Themable function guidelines and documentation
public
group: Theme development
Neil Drumm - Fri, 2006-06-09 05:02
We have a great theme system, but we don't always make full and proper use of it from the developer side and the themer side is underdocumented. I propose we improve this situation by writing guidelines:
- When to use themable functions; building on How to write themable modules.
- What PHP is allowed in a themable function and what is not. Somewhere between
print $fooanddb_query()there is a hard line to be drawn. - Notes on accessibility
- What HTML is best, including
- Needs to be valid
- What is semantic HTML and why should we care?
- Some design patterns (for example, Microformats when appropriate)
- What CSS is best (current convention: as little as possible, but usable without extra CSS)
For every themable function, document:
- What the function does
- What variables go in
- What the expected output should contain, including required and recommended classes and ids for HTML elements
- When it will be used and in what context (for example- block or inline in HTML)
Using these guidelines and documentation we can attack theming annoyances at the root cause and fix the bugs in the default themable functions in Drupal core and contributed modules.
Worth doing.
Your idea knocked loose one of the two suggestions that have ever occurred to me, and since I forgot the other one, this seems like a good time to bring up the one I didn't.
Would it make sense to add some kind of tagging mechanism that would allow one to, say, click a link in the admin section and be given a watchdog-like list of which modules contained themeable functions and what they were via the tags? It probably would be more efficient to simply provide that info in the documentation, but it seems like this might be simple enough that it'd require less writing for everyone over all, besides possibly fending off a few support questions about how to do X with a .CSS file for the developers that would be better routed to the forums or something.
Doh!
While I'd looked up a couple of articles about the semantic web, they didn't click at all. But having nailed down the idea from your link as well as microformats, I see that you've already factored in a way of addressing all of the points I brought up with the added bonus of not requiring any additional code at all.
Between this, Adrian talking about making gd lib available via a project he's working on and the fact that I've been hearing a lot of positive buzz from people using Yahoo's grids.css as an easy, hack-free layout solution for their themes, its clear that there's a conversion of really cool ideas moving towards 4.8 that might warrant a small summit for the purpose of giving the theming community a preview of what's down the road.
Definitely, guidelines would
Definitely, guidelines would be helpful.
I have come across a lot of theme functions which do too much processing. Inputs should be passed in as strings, or at most arrays of pre-filled data. There's no way a so-called theme function should be calling external functions or loading anything from the database, in my opinion.
Proper guidelines would facilitate Adrian's initiative to split out .tpl.php files as well.
yup
we've had this conversation before.
until we sit down and systematically tackle it. nothing will happen though =(
--
The future is so Bryght, I have to wear shades
or else do it the Drupal
or else do it the Drupal way. Put on your "eye flaps" and tackle one function at the time.
Seriously, taking this on in one huge task is undoable. one function in one patch Is, I am afraid, the only practical way to get this done.
oh. and regarding what should be in a theme function ...
we need to decide whether some things really are theme functions.
such as theme_table, for instance.
that thing is one of the most complex functions in drupal, and supposedly it's designer friendly?
i don't think so
--
The future is so Bryght, I have to wear shades.
yep, and there is a bunch of
yep, and there is a bunch of other similar functions in core, no idea abou contrib. I think the splitting of the theme_xxx functions ouside of code proper will at least help us identify these preoblems. Something for the future will probably be to unnoodle all the theme code. It is no intuitive at all what is the invokation order, for example.
one a time: here is one
http://drupal.org/node/73996 simplify the status_message theme function. That is one hell of a complex one ATM. Are there other patches yet where I can look at?