Theming for module developers example

yes, that is a good one. I'm not the best one to make this example, but I can do a sample theme and expect to be improved by others (just learnt themeing because of a very few demands).

but a theme is a project, and I think it has room in this examples project (an install profile is not so close to a 'project', but I agree it also fits here).

rfay, what about merging the rendering stuff in this 'theme' project? or this could be too complex?

Not sure if this is what you are after, but here is a patch on form_example.
It demonstrates how to embed forms in a page and how to theme a form.

Not sure why the patch in #5 failed, made on current cvs and it patches fine for me

~/sandboxes/drupal-dev/contrib-7.x-1.x/modules/examples/form_example # patch -p0 < form_example_page-951340-4.patch
patching file form_example.module
patching file form_example_tutorial.inc

What am I doing wrong?

Ahh, OK here it is, see if this works.

Good idea, I'll be happy to chip in. Perhaps someone with a greater familiarity with the formal layout of an example project could get the ball rolling.

Hutch, sorry for the late reply. Will you take the lead in this? or are you still waiting to have a code base start point.

"waiting to have a code base start point" puts it very succinctly ;-)

Also, what would be the best order of work, start in HEAD and branch to DRUPAL-6--1 once there is something worth looking at or start in DRUPAL-6--1 and skip HEAD altogether. Then once D6 is coherent port to D7 (not too hard)

Another consideration, who commits? I have a CVS account and am happy to manage commits, review patches etc but I would need perms I guess.

(sub) Module name:
theme_example
with files:
theme_example.info
theme_example.module
theme_example.tpl.php
(for a start)

tests is an area I have little experience and no luck (so far) but if anyone with more knowledge can chip in there it would help.

rfay suggested a TODO list in #13, looks OK to me.

I'll fish around in the other examples and build up a start, any pointers welcome!

OK, I'll start with D7 and get something posted here soon.

Please, hutch, if you really really want to comaintain any of the sub modules of examples, rfay oppened an issue for that ;)

Attached is a tarball to get things rolling

What does the TODO list in the .module file mean? I'm confused, there is already theme functions, and a template file. Is that todo outdated?

The TODO list was pasted from #13 to remind me what to do, so if that has all been covered in can come out

Ok, so, main quick overall review (no code key points).

The code in the module to me appears just another Drupal module, I mean, for sure it is functional, but is not as descriptive as required to be an example for now. I'm not talking about coding standards in this case, I mean, the code is not a guided introduction for people not versed at all in theming.

During all the time I've been coding in this sanct project what I've learn in the end is that each file must be considered a TXT in its most basic essence, starting from the top and and reading through to bottom. We must be sure each function in the file has a meaning, a purpose and conditions about when is it going to be fired, and when not!, and we must turn this into comments.

Question I often do right now about each different function in module:
- When do we need this hook.
- What are the alternatives.
- What conditions are met before using the hook.
- What implications do have changing things in that hook.
- What does the documentation says about it, is it accurate?
- How much variations of the hook should we put in the module? (when change, add, remove things)
-...

And what is most important for people that has not ever touch Drupal before, a description about the overall usage of the module at the begining is required, just a summary, but required. So we are going to have 1 or 2 forms doing this, this will be themed this not, this can be changed if you modify this template file (come on, do that change and - empty the cache first - update) and so on.

I'll be reviewing and working on this example too, I'm very interested in having such an example module, but also I'm pretty sure I'll learn things about theming I don't know at all.

Said this, looks like a good start, but requires a lot of work, so IMO we need first that summary of 'what this module does' so we can split taks and assign resources :)

Good work and thanks for taking the ball rolling!!

I realise that the docs side of things is still very lean, I was mainly concerned to produce some simple examples that work in the hope that others with more experience with writeups could expand on that.

Setting version.

I was just looking for an example of hook_theme() in D7, as my implementation isn't working, and rfay pointed me to #20. At first I thought it was an example of what I'm trying to do, but it's not. What I'm doing is defining a new theme callback with new variables and assigning that a template. The only example here using templates, theming_example_text_form, attaches the template to an existing render element rather than new variables. I don't know how generally useful it would be, but I'd at least love to see an example of a template with variables.

In the tarball in #20, there is function template_preprocess_theming_example_text_form() in theming_example.module
If you want to create more variables you can add them in your preprocessing function, so
$variables['mystuff'] = 'Hello World';
Would be accessed in the template file with
print $mystuff

Hope this helps.

My problem turned out to be two parts, neither of which had anything to do with the variable/render different. First, I had assumed template file names were matched against the 'template' value of an item returned in hook_theme(), but they're actually matched against the array key of each item the hook name. The 'template' value appears to be used to load the template file from the module directory, though, so if you use two different values for the hook name vs. the template name, you need to have a different file name when you do an override in the theme.

My second problem was that hook is further converted from "_" to "-" when matching file names, so if you do what I did and name the hook after your module, with a name like "theming_example", the actual file name needs to look like "theming-example--".

I guess it would be good to explain these in the example, but I haven't yet found any documentation on why either of these work like this. Both seem very counter-intuitive to me.

Just mentioning another new module developer who is interested in a good example of how to create a new display page that is controlled by a template.

page_example got me started with at least being able to display my variables via a pre-defined list, but that method doesn't seem to lead to anything that could work with a custom template.

While of course I would love an example with massive detail in the documentation comments, even just a good working example with the basics could help people get started and provide a base for a good doc writer.

I'm going to DL the file in #20 to see if it can help get me started.

OK I've done a bit of experimenting so far, and I've gotten confused. Either this doesn't do what I thought it might or I'm missing something someplace.

First I tried to borrow some of the code to allow me to update my module to allow me to output some variables into a template. (see http://drupal.org/node/1256038 for more background about what I want to do). I couldn't get it to use the template so I thought I'd take a step back and verify my assumptions.

So I D/Led the tarball in #20 and installed it. I got the URLs from the module and tried the pages, and they come up. OK so the first step worked. So I thought I'd make some updates to the templates and see how they interacted with the module. I did reset the cache, but couldn't seem to get any of my updates to actually show in the displayed page. I just got the original untouched display.

The "theming_example.tpl.php" file is actually empty. And while "theming_example_text_form.tpl.php" didn't have much in it, it did have what appeared to be a valid template. I looked for the class from the DIV "container-inline" to verify that it showed up in the output page, and it did. I made some changes. added another class + changed the spelling. But neither showed up.

I then went back to the module and searched for the class from the DIV "container-inline" and found it. I made modifications to that, and THAT did show up in my page's HTML.

So from the testing I've done so far, I'm not sure if either of the supplied templates are actually used anyplace. If I am wrong and missing something (probably obvious) could someone enlighten me?

Unfortunately I'm doing this the week where many folks are hiding at DrupalCon in London. :-) Not good timing for me, but hopefully they are learning a lot. I can't wait for the videos to be put up. Not the same as being there, but still a great resource.

Any help is appreciated.

It's ages since I looked at this, I will be back later today with some explanation of how this works and how to apply it to a theme

back soon....

Ok, let's start from the top.

You have installed theming_example module and can see the link in 'Navigation'.

Open theming_example.module in a text editor

The link in 'Navigation' is created in function theming_example_menu()

We'll start with 'Theming Examples' as defined in this menu function snippet:

  $items['examples/theming_example'] = array(
    'title' => 'Theming Examples',
    'description' => 'Some theming examples.',
    'page callback' => 'theming_example_page',
    'access callback' => TRUE,
    'access arguments' => array('access content'),
  );

The page callback is function theming_example_page on line 64.
This function creates an array '$content' with some links.
This is fed through a theme 'theming_example_page' which is registered in
function theming_example_theme() (line 134) and expressed in function theme_theming_example_page() (line 163)
which loops over the array and does stuff to it, eg makes the first one bold and wraps them all in para tags.

Now let's assume you have a theme 'mytheme'.
To theme the above page you would copy function 'theme_theming_example_page' to your theme's template.php and rename it to 'mytheme_theming_example_page'

To test that it is working put a html comment in it, eg

// now in template.php
function mytheme_theming_example_page($variables) {

  $content = $variables['content'];
  $output = '';
  $output .= '<!-- mytheme_theming_example_page -->';
  foreach ($content AS $count => $para) {
    if (! $count) {
      // first one
      $output .= '<p><b>' . $para . '</b></p>';
    }
    else {
      $output .= '<p>' . $para . '</p>';
    }
  }
  $output .= '<!-- /mytheme_theming_example_page -->';
  return $output;
}

When you flush cache and refresh the page look in the source html in your browser and you should see the comments.

You can apply the same method to function 'theming_example_list_page'.
Copy function theme_theming_example_list_page() to function mytheme_theming_example_list_page() in template.php and mess around with it in there.

The third example is a form which is also themed in a function.
function theming_example_order_form defines a form as an array (line 90)
This is themed in theme_theming_example_order_form on line 220 and can be copied to template.php as above.

The fourth example is incorrect, although function template_preprocess_theming_example_text_form() works it will be run again (not instead) if copied over to template.php

Here is the fix:
Rename template_preprocess_theming_example_text_form() (line 237) to theme_preprocess_theming_example_text_form()

If you want to alter which $variables are passed to the template copy
theme_preprocess_theming_example_text_form() to mytheme_preprocess_theming_example_text_form() in template.php
and play with things there

The fourth example uses a file template 'theming_example_text_form.tpl.php'. To use this in a theme copy it into your theme folder.
With zen for instance this is in a subfolder 'templates', no need to rename.

See how you get on.

Edit: the fourth example is still wrong, very exasperating but I will figure it out. more later....

@hutch Thank you for the detailed response. Especially during DrupalCon.

I'll start walking thru the steps you mention and let you know how it goes.

Thanks again,

Thanks for that, I will knock up a README based on #32
I had hoped to find a way to override template_preprocess_theming_example_text_form but have not found a way, I can add to it but not override. Oh well.

In my case I'm doing a rather simple use case. I just need to place 4 variables inside the template in their correct places.

I'd consider building the HTML inside the module from scratch, but I want to keep things separate so someone else can come back later and change the design of the page without having to go neck deep in my code :-) Plus there is a lot of HTML/CSS/graphics and such in the page, so that would look like a real mess.

Thanks again

Attached is the same patch as in #33 with a README.txt added

Well, there are some very interesting concepts and methods explained here. I would say go for it.

Not sure what caused the test fail, but it could be file theming_example.test, line 33

    $this->assertRaw('<p><a href="/examples/theming_example/theming_example_order_form">Simple form 1</a>');

should be

    $this->assertRaw('<p><a href="/examples/theming_example/theming_example_order_form">Simple form 1</a></p>');