D6 theming - Template suggestions page

For those shrugging at "What's Diigo"?... it's a web tool that a drupal docs subcommittee is using to upgrade, help organized the Drupal theming manual. If you want to help... contact HansBKK? --- but I may be talking out of turn.

To HansBKK: You've been a great policeman at defining precisely what Diigo is for and what it is not for in this context. I think you have it perfect. Keep up the good work.

As for the content discussion on how to name the Template Suggestions page or describe the custom templating system... thanks for the directed search idea to garner background to the topic. And also thanks for the encouragement in true "Wiki" culture to be empowered to make edits.

Since I'm working on the Getting Started guide and some CVS docs pages right now... I think I'll back off on this issue for now. I was curious about Diigo --- and I've got a big "mouth" AND I'm a generalist (I can have opinions about things I know little about :) --- hence my jumping in. I'll keep an eye on this but don't expect to be too active.

Thanks for the great leadership on this.

Shai

OK, so I saw the dupe of this first and posted a comment there, which I see has largely been addressed, but I'l copy my comment here anyway:

just FYI, "suggestions" is what it is referred to in the code and how I have always heard them referred to. i.e. it is a common term for many people already familiar. Candidate was a new term added by theme dev module and not one that have ever used myself, nor is it used from within Drupal anywhere. I don't say this to say "you have to use suggestions" but just to point out that for people already familiar with that term from theming for several versions of Drupal or who are looking at the code, candidate may mean absolutely nothing to them. So, please be clear that what you (or theme devel) call "candidate" is actually called $suggestions in the code (in theme.inc). (The term coming from this thinking, "Get suggestions for alternate templates...," taken from the comments in theme.inc.)

So how about Creating Alternative Template Files for Theme Customization?

so... i don't really understand what diigo is, but it would appear it is no longer being used (the fact that i haven't heard of it, makes me suspicious!)

as far as the original issue - can anyone provide an update?

We experimented with Diigo for a while, mostly to gather suggestions for reworking the theming guide. It's a web service that allows you to share comments on any web page with other logged in Diigo members. It was interesting to have a private editorial discussion right on the page. The major downside, in my mind, was that there didn't seem to be a way to remove or expire comments that were no longer relevant.

Re. the template suggestion page, I still find the introductory paragraph to be rather vague and unhelpful. "Template suggestions are alternate templates based on existing .tpl.php files. These suggestions are used when a specific condition is met and a matching file exists. All layers from core, modules, theme engines and themes can provide the suggestions. You can think of them as naming hints telling the system to pick and choose based on the right circumstances. The idea is simple but it is a powerful feature providing another layer of customization."

Perhaps it's perfectly clear to an experience themer but it means nothing to me. It would be really helpful if this started with a standard "You can ..." or perhaps something like this: "Using template suggestions you can display a page in different ways, depending on conditions that you specify. A template suggestion is an alternative template file that exists in your theme folder[[is that right?]]. The conditions that trigger use of the alternative template are specified in a preprocess function. "

I would also drop the bit about thinking of them as "naming hints". The idea of "hints" totally confuses me (I'm already confused by the ambiguity of "suggestion")

I'd rewrite this myself but, like I said, I'm not sure that I understand what's happening here.

Thanks for all the info - that totally makes sense. Does sound like we need a themer type to go through and make this stuff easier to follow.

Have removed the reference to diigo from the issue title, leaving open.

Just some minor corrections to this page:

"This example add suggestions..."
Change to:
"This example adds suggestions..."

This code should be in php tags, not code tags:

function my_theme_preprocess_page(&$variables) {
  if ($variables['node']->type != "") {
    $variables['template_files'][] = "page-node-" . $variables['node']->type;
  }
}

and use drop as prefix, as in the previous example, because the code is an improvement of the previous code.

Looks like this page is good enough now.

#10 is still not dealt with. The code example is still not in PHP tags and named my_theme_*. It's a quick fix :)

I've made the changes. Relying on the folks upthread who said this was good to go, I've also removed the "needs technical review" status.

Oops. Meant to mark this fixed.