drupal-docs

good one

Aside from the bit mentioning Javascript, CSS, XHTML PHP etc (which should be moved to the About Theming page?), I think the "Learning to theme the Drupal way" section should be shelved.

Agreed. Done.

A couple of points. This page *desperately* needs an introduction that orients a novice reader. Just a sentence or two would be enough, something along the lines of "Adding JavaScript and jQuery to your theme allows you to ... ". Maybe a few examples too. As it reads now, I've no idea whether this is something I need to read and understand, and what it would do for me if I did.

Actually this page should probably be moved to the JavaScript and JQuery section of the Developer Guide. Or else that part of the dev guide should be moved here to the theme guide. If it's the same subject it shouldn't be fragmented over two locations. We can also put a newbie friendly page here which directs people to the dev guide if they need it.

This page "Basic theme help" clearly didn't belong under Troubleshoot your theme. This should be moved up- and merged possibly with Introduction to themeing or theming overview.

yeah i think go ahead and make the changes, and leave comments here for anyone who joined the sub-team!

This is post by Keiran Lal (amazon) and I think this page has been very well-thought out, and backed by user research. I think we should keep it here as a guide, and also begin to link off of it, and use it for placement/navigation of content.

I think merging with the current top would be great, but those bits that are placeholders for future structure should be all together at the bottom and marked as such.

I actually don't quite see the point of this page. It promises to help with some theme development goals, then notes that some tasks are easy and some are hard, but it doesn't getting arount to actually showing how to do anything. Am I missing something?

IMO it was intended as an intro/overview, and does contain some good "meta" structure ideas, possibly placeholders for future writing that never happened? and bit & pieces of useful content.

Sorry, I completely don't get it and I can't see that it's really based on research (other than acknowledging that many people think theming is difficult). The first set of bullets doesn't belong here at all. The second set of bullets (make small design changes etc.) is very promising and worth building on, and the bit about Firebug is good for CSS themers. Removing everything else would improve the page tremendously and give it a clear scope and focus.

Keep in mind that this page was written in 2005. I agree with Lee that we can lose a lot of fluff and noise and get the page to focus things that people making a theme realy need/want to know.

This clearly has to go up to the top.- or get merged.

Finally, I see where this doc came from- it's interesting that it is based on User research, and posted by Amazon, I would have alot of trust that this was very well thought-out. I think we should use this as a guide for placement and navigation.

"Changing the labels and the ordering of fields in content types created with the Content Creation Kit. For more information, see the CCK documentation."

I would say that this is part of theming, maybe using color module too, but they're not to be included because they are topics specific to contrib-modules, which belong with the module's docs. We can of course link to them when appropriate, and I think CCK is so widely used these kinds of issues need to be at least mentioned as part of template.php/page/node template-specific pages.

Also re Views, a lot of what people use Views for can be done through theming, so again, links when appropriate, enough information to inform them in making the choice.

I've updated this page as per Hans' comments although that bit has now been moved to the About this Guide child page. (Sorry)

See Jeff Eaton's Template of Doom article http://www.lullabot.com/articles/overriding-theme-functions-in-modules

dvessel wrote in the sidebar:
Actually, the "Clearing the theme cache" should be in this main page. The cache is always a hinderance for those that don't know how it behaves. It should be very visible.
---
me - absolutely - I have the menu item from Devel module on every site's custom nav that shows up for any user role=admin, this (or an equivalently easy method) should be part of any "introduction to customizing a theme". Not with the background details about the registry etc, perhaps a "here's why" link to that information.

dvessel - I've proposed a convention for our using Diigo's many different types of "spoor" - Discussion threads in sticky notes, text-specific comments in highlights, as these show on the page without having to browse with the sidebar open. Bookmarks for tagging (because that's the only way to get tags; currently just tagging for D5/6 applicability), don't use Page Comments at all.

What do you think of this idea?

The content here should allow me to at least have a chance of understanding the node that follows, or maybe intervening nodes need to be inserted, huge jump from this to the coding stuff that follows.

Looked at it again, and still can't get my head around it. Needs re-working for different skill/experience level: 1 extract what's relevant for Joe noob tweaking Zen, without him having to learn how it actually works. 2 extract what's only relevant to developers. 3 teach Joe how to understand what's left, and sequence, insert flow/connecting transitions and references to other relevant nodes. e.g. what is a hook? how do you "implement a hook as a template", and what are the other ways to do it, differences?

OK, summarizing - first impression from many was this is way-deep module-developer's stuff and it should be moved to the developer's guide, perhaps http://drupal.org/node/165706.

dvessel and addi strongly differed, so we're leaving it here. However IMO the idea of preprocess functions needs to be introduced from a more-noob POV with relevant mainstream examples, with the more-advanced stuff moved to a clearly labeled section or sub-page. Plus the whole idea is D6-specific, except for Zen, right?

Past comments:

Hans
Move (most of this?) to the Developer's guide, relevant to creating modules, not end-user theming. Although there should be docs here on how to override using preprocess - applies to D5 using Zen and some others, otherwise just D6.

Lee
Yes, most of this, maybe all, should be moved. If we're leaving some of this here, there should be a clearer introductory sentence. Something like "If you are developing your own module, you can make it easy for others to theme your content." (I don't know if that's what this page is about, but something like that would allow someone like me to say "Ok this page is something I don't need to read")

Shai
+1. As evidence that this is the right move, there is a comment on that developer page asking, "Where is the documentation on preprocess functions?" -- and then another comment referring to this page.

heather
I think also the inclusion of Lee's suggested Intro sentence and help divert anyone off this page to save them some time- no matter where this page ends up. "If you are developing your own module, you can make it easy for others to theme your content."

dvessel
This is very specific to *theming* so it should stay in the theming handbook. Let's not dumb this down. It's a very important topic to grasp for themers.

Addi
Whoa, I agree with dvessel here. This is *theming* info that a themer needs to know if they want to implement in their template.php. The devs have their own guide from the module side already. Removing this from the theme guide would be a *horrible* decision. Yes, we can change the text to orient people more, but srsly, this *is* for themes, not modules.

dvessel - re dumbing it down - agree, but IMO the main "spine" needs to be accessible to people that are brand new users of Drupal, otherwise they won't even try to climb that steep learning curve and bail out of Drupal. We need to make the docs complete, but anyone who's capable of understanding this page as it stands now ain't finding his way by clicking through the nav hierarchy, she already knows google's site:drupal.org :)

Re: searching through google.. I don't buy it. It can be changed so it's more accessible but all the information should be there in full. I've seen many situations where someone has no clue as to where a piece of information comes from. It's the theming layer and they should be aware of the underlying function to solve their problems.

Common question.. How do I change $primary_links? If they knew that "template_preprocess_page" pulls all the page template data then it would be easier to track down.

So yeah, change the text so it's easier to understand but let's not remove it preventing others from learning.

From dvessel 's page-level comment (only visible from the sidebar - I reckon it's easier to see things all together in a sticky)
Re: searching through google.. I don't buy it. It can be changed so it's more accessible but all the information should be there in full. I've seen many situations where someone has no clue as to where a piece of information comes from. It's the theming layer and they should be aware of the underlying function to solve their problems.

Common question.. How do I change $primary_links? If they knew that "template_preprocess_page" pulls all the page template data then it would be easier to track down.

So yeah, change the text so it's easier to understand but let's not remove it preventing others from learning.

Can we please standardize on floating sticky's except when commenting on specific text? If I have time, I'll summarize and start a new one when a threads gotten too long, but I can't actually delete it until everyone deleted their old posts (after they've been summarized)

@dvessel - sorry if I'm not being clear, no one's saying move it out anywhere, in fact we're bringing *everything* relating to a topic together as it hasn't been before. It's just that there should be intro/overview pages that are "parents" to the more advanced ones (eg talk about coding), which should help frame the topic for the non-coders, rather than them being thrown right into the deep end without a clue. The complex content will be right there e.g. intro "about pre-process functions", containing info as to how a noob could use them e.g. Zen theme's template.php. This would be a parent of: "details on pre-process functions" and "example pre-process snippets" and "module development and pre-process functions" and a series of step-by-step HowTos on pre-process functions and links to API docs, etc etc.
Bringing it all together so it's easy to find via the navigation for everyone, setting the tone of the intro/overview nodes so they are accessible, give the noob a chance to get up to speed.

Great example here http://drupal.org/node/295346

http://drupal.org/node/201587

D5 specific to come here

I think moving it into a sub-page is fine. At first the discussion was about moving it completely out of the theming handbook and that's a bad idea.

Sorry about not posting into the right section. This diigo is new to me. Not completely sure how to use it. :)

NP devessel, we're all Diigo noobs, that's why we'll need to define practices as we go. I think these stickies work well, basically a topic thread, start a new one for a different topic or when the old one's got too long, summarizing the old one at the top of the new, along with decisions. D* versioning group tags coming soon.

Yes, most of this, maybe all, should be moved. If we're leaving some of this here, there should be a clearer introductory sentence. Something like "If you are developing your own module, you can make it easy for others to theme your content." (I don't know if that's what this page is about, but something like that would allow someone like me to say "Ok this page is something I don't need to read")

we need more pictures within the documentation. (without losing any content ofcourse.)

pictures are a great addition.

I agree. Clear illustrations for the visually oriented.

this is probaly too far on the bottom of the page.

Even more so, I think an early branch should distinguish between what a learning end-user cares about. First comes 1 selecting, 2 download/installing and 3 configuring an existing theme, then comes 4 customizing/sub-themes. Both of these items belong with that content. I think much of the existing content here is aimed at 5 those who might want to create their own theme from scratch, and IMO that should be marked out explicitly. What a theme comprises is good background information for an intial overview, but the procedural details for how to proceed with 1-4 IMO should as a whole be earlier in the tree.

to D5-specific preprocess section

Great example of a "walk-through" with appropriate tone/level. The wizardly stuff could be below here (NOT buried), and the noob isn't scared away.

This seems to need an example or a better description. I understand what it's saying (I think) but I don't understand how it's used. I'm also confused by screen capture from the devel module. Is a "candidate" the same thing as a suggestion? What is the signifigance of the three candidate files? Why would I choose one and not the other?

There's a specific-is-higher priority scheme for the override taking effect on any given page load. In this case, when node 297 loads, tne leftmost will take precedence over the more general ones, if it doesn't exist, then the one specific for full-node displays, and if that doesn't exist then the general page template (and if that doesn't exist then core's?)

Woop breaking my own guideline for using Diigo. Since this is a substantive content question, I think this would be better posted to the doc issues queue with a link.

That will keep the Diigo comments focussed on tagging and navigation placement as I intend. I don't want people saying this medium is splitting dialog flow that should be on d.o.

Plus you'll get better responses there, more actual theming experts there :)

What do you think?

There is definitely a fine line/grey area here that is hard to figure out regarding what level of writing this group is tasked to do.

I don't think this group is simply tasked with organization. I think the, marked paragraph on this page is incomprehensible! Of course, this stuff is indeed hard to describe.From what I remember, Ric Shreves did a good job of describing this concept in "Drupal 5 Themes" (we, of course need to be careful about plagiarism -- but nothing wrong in looking at a good model).

Since when do we have the terminology "template suggestions." I prefer "candidate" over "suggestion".

How about changing the title of the page to, "Creating Template Files for Theme Customization" or "Creating Derivative Template Files for Theme Customization". The latter is better, but I don't know if the word "derivative" reminds people too much of calculus :)

Transferred this discussion to the issue queue as per Diigo usage guidelines for the group:

http://drupal.org/node/337235#comment-1119122

Please don't post to this sticky note any more, create a new comment if it relates to navigation or topic/status tags