Here is the short version of what work we are trying to do. This will be updated and elaborated as we have time. Please feel free to leave comments/questions as we refine it.
First, check the Work in Progress page to select a group of files that are not currently being worked on. You will need to get the files for your chosen directory from the sandbox, ideally doing a CVS checkout. For each directory listed there, this is the routine:
- Create a template.php for your directory.
- Create phptemplate_* functions for every tpl.php file in your directory using _phptemplate_callback. (See http://drupal.org/node/11811 for an overview)
- This is where the creative work comes in - you need to analyze your tpl.php files and try to determine what is logic. Try to move the logic into the template.php function and reduce the tpl.php to just prints. (For tpl.phps that have loops, you might need to create a separate template. One for what goes outside the loop and one that is called for each iteration through the loop.)
If you have a CVS account, make sure you checkout the sandbox with your account, not anonymous, so you can commit back. Sandboxes are open so you do not need special rights to be able to commit to it. If you do not have a CVS account, please attach your file(s) to the Work in Progress page and someone with an account will add your changes.
Comments
Commenting the code
Should we be commenting the code and if so then we should keep the comments consistent across all of the files. So should we have "instructions" in each file or would that be covered in a Themer Pack README? Also the Bryght tpl files all have a
//WARNING: make sure to return after the print, this is a return replacementcomment in them, should we remove it or perhaps put a more helpful warning for themers who may not know what that means, and therefor get a little freaked?Learn Drupal online at Drupalize.me
I'm all in favor of
I'm all in favor of commenting the code. Keeping the comments consistent will be difficult since the work is being done by multiple people, but that can be dealt with some in the review process.
I think an overall README will provide basic instructions, but a README per system might provide more specific instructions if you think they are needed. For example, a human readable overview of what all the theming functions in that category do are very sensible.
Using this method, there shouldn't need to be a return, so remove that warning.
Checking in
Hey all,
Just wanted to check in and say that I hadn't dropped off the face of the earth. I'm still hoping to give a helping hand sometime sooner or later. Besides being crazily busy, I've been tracking the conversations of add1sun, dvessel, and merlinofchaos about the callbacks/functions/theme.php stuff trying to get a grip on it. Most of my themeing for Drupal, I've either done with css or a hacked a file or two (looks down in shame), so I just need to sit down and study/tinker a bit to absorb the ins and outs...
Cheers.
naming conventions?
On point #3, when we have to break off into another .tpl.php file for a loop or anything else, how should we name it?
1.) Just give it a descriptive name? 2.) Prepend the original function name, making it super long? 3.) Make another sub directory and group it in there? 4.) Or how about prepending it with an underscore to make it obvious that it's not a core theme function?
I know I got some bad ideas but I'm leaning towards 1 & 4. For example:
block_admin_display.tpl.php
_block_region_highlight.tpl.php
The region highlighting is part of a loop. It looks obvious on what it does and we don't confuse it as a themable function. Any thoughts?
Ok, I like prepending with
Ok, I like prepending with an _ -- we didn't do that with the user_profile .tpl.phps but I think we can easily change that. So that's a good idea.
I would say this:
o Prepend it with a _
o Use the exact theming function it comes from
o And then append something descriptive.
So: _block_admin_display_region
Hmm. However, I just realized a problem with that: Doing it this way will cause the files to NOT be logically grouped to gether in the directory. So let's append it with a _. Like so:
block_admin_display_region_.tpl.php
That way in a dir listing it'll appear with block_admin_display.tpl.php (and logically after) and there is a clear visual indicator that it's one of our files.
Any thoughts?
Prepending the original
Prepending the original function name leaves little room for being descriptive imo. And some of these names can be very long.. After experimenting with the custom callback, I like having them in their own directory with the name of the parent function as the folder name. Seems to be nice and neat and everything groups well together.
But first, I'd like to hear your thoughts on a custom callback.