I have a hard time wrapping my mind around the structure of the current theming guide. This makes it difficult to work on the guide or update it for D7. I'd like to talk about what an ideal theme guide might look like, as something to move towards.

This is a rough idea of how the Theming Drupal 6 and 7 guide might be re-structured. This outline assumes that readers know intermediate-level HTML and CSS, but may have little to no knowledge of PHP.

Audience: designers and front-end developers

Theming Drupal 6 and 7

  • Anatomy of a Theme

      • .info file (defines theme files)
      • tpl.php files (markup)
      • css files - (presentation)
      • template.php (logic)
    • Building a basic theme
      • .info file
      • page template
      • style.css
    • Customizing template files to control your markup
      • page.tpl.php in-depth
        • variables in page.tpl.php
        • creating regions
        • digging through arrays
          • using devel_themer
      • node.tpl.php in-depth
        • understanding the $content variable
      • How to add more template files
        • Theming specific content types with templates
        • Theming specific nodes with templates
    • Default markup and styles
      • How modules add HTML and CSS
        • Why there are many stylesheets
        • Why and where templates are created
      • Core templates
        • D7 template suggestions
        • D6 template suggestions
      • Standard core styles and classes
      • Viewing default markup with Stark
    • Subtheming
      • How subtheming works
      • Starting with a base theme
        • comparison chart of starter theme features
    • Caching
      • clearing the theme registry
      • clearing the cache
      • css and js aggregation
  • Advanced theming

    • Theming Views
      • Semantic Views
    • Theming Panels
    • Theming Fields
    • Theming Forms
      • Altering Forms with the FAPI
        • example: changing the search button text
    • Javascript and Jquery
    • Creating advanced theme settings
    • Creating UI settings with Skinr
    • Theming for different devices
      • Mobile themes
      • Targeting devices with Mobile tools
      • Targeting browsers
        • e.g. adding ie7 fixes
      • print stylesheets
      • rtf languages
  • Custom Theming with PHP Functions
    • resources for learning PHP
    • Intro to the Drupal API
      • theme functions in modules
      • the theme() function
        • inheritance of functions
        • theme() function vs. template files
      • t(), drupal_get_path, etc.
    • A few theme examples with extensive commentary
      • Creating new variables
        • example: for a page
        • example: for a block
    • More PHP functions
  • Best Practices

    • Where to put theme files
      • sites/all/themes, etc.
    • Security in the theme
    • Keep logic in template.php
    • Theming methodology
      • Sustainable theming
      • Limiting template files

    Comments

    Carolyn’s picture

    Issue tags: +Sprint: May 2011

    tags

    rootwork’s picture

    This seems like a great outline! Thanks for all of this work. In general this makes a lot of sense to me.

    I have some very minor quibbles with a couple of the positions of things, notably:

    - I think subtheming should go up higher, or at least teased somehow, because if people are really theming beginners (and if they're coming looking for a theming guide on d.o then they're really beginners!) I think it really makes sense to point them toward subtheming first. Or else when they create their "custom" theme they're going to try to start by ripping apart Garland or something.

    - I would put theming fields first, since fields are in core, and views and panels, as popular as they are, are not.

    But overall I think this would be a great way to proceed.

    arianek’s picture

    I reviewed this last week on IRC with carolynk, and also thought it looked great and sensible. I can get on board with rootwork's rational for moving sub-themes up in the outline as well.

    arianek’s picture

    Status: Active » Needs review
    sylvain_a’s picture

    Hello,
    Sounds interesting indeed. Finally a guide that doesn't start with a developer-oriented "how does the theming layer works!" ; )
    I would adopt the bulk of it. Hope i can help you as much as possible implement a version of this.

    Personally, i would make it just a tad more systematic, so people can wrap their head around it. Understanding the scope of theming in four steps could help people through the not-so-obvious process:
    a) Definitions in .info,
    b) templates with .tpl.php,
    c) styles in CSS, and
    d) logic in template.php, that seems to be a good starting point.

    Definitions, templates, styles, logic. Could be a good idea to reuse these coherently through the guide, and within your structure.

    For example:
    - "Customizing template files to control your markup" expanding the markup/templates point.

    - "Default markup and styles" expanding the presentation/style point.

    - Following this idea, I would put section "Custom Theming with PHP Functions" first in advanced theming, to expand template.php and the "logic" part of theming.

    - This would leave all the other unrelated subtopics following in "Advanced Theming" (as panels, views, etc. I would also put subtheming and caching within the advanced section, but this is highly debatable.)

    - Finally, in "Building a basic theme" on top, add a little demonstation of what template.php can do (changing a "more link" or whatever element in the page systematically in the site, or add a simple custom variable, as an example of the possibilities of template.php).

    What do you think about it?
    I will try to add more ideas when I start mixing the new structure with the actual existing content.

    technicalknockout’s picture

    Hello,

    I like the "Ideal" theme guide structure, but I have a couple of suggestion for general pages I don't see listed:

    1) 'intro to drupal terminology'. The structure above seems to stem from being very familiar with the terminology already. I know I will find it useful since I often go back and review very specific issues. For example, I usually will know if I need to theme a field vs editing a page.tpl.php file. For those new to drupal, it might be helpful to have a glossary page that indexes all the concept terms and links to the pages within the documentation for the details.

    2) 'front-end debugging' or 'common themeing pitfalls'- When I started working with drupal, I found it tricky to figure out how/where specific markup is created. Also, when I go around the theme help forum, most people get started looking to customize one particular thing. If we had entry points into the documentation that addressed user stories of specific issues, it could ease the entry path for new themers. Ideally we could do a quick survey of what some of the more popular issues (maybe just roughly looking at the theme forum) and go step-by-step through a user story. Then where appropriate link back to the more in-depth documentation pages.

    technicalknockout’s picture

    In reply to my own points above...
    1) Looking around I see there is a glossary outside of the Theming Drupal 6 and 7 section. Might be good just to reference it and api.drupal.org in the Other Places to Explore section of the http://drupal.org/documentation/theme page.
    2) There is already a similar section at http://drupal.org/node/45471 . However it is at the bottom of the theming guide structure, seemingly outside of the scope of drupal 6 & 7. Would it make sense to have a similar section within Theming Drupal 6 and 7?

    RKS’s picture

    I know one of the things I was looking for a few months back was breaking apart $links or $content.

    Many modules do not include/know their own snippets for embeding their modules on a .tpl.php and so if you've customized your theme and haven't included $links or $content, those modules will not appear on the node at all.

    If you include $links or $content you don't have the control you'd like over the placement. So an ideal theme guide to me should take users through a first step of discovering exactly what is on the node and included within $links and $content so when it comes time to theme they can use different methods of outputting their modules.

    An example would be to print $links but hide components within $links because you have them printed already elsewhere on the page. I really think teaching people how to see everything on their node before they start themeing would be good practice so that when they theme they better understand what they're wanting to do and how to do it.

    [EDIT] I see I skipped over the section you added in the outline for understanding $content. That's what I was talking about. I think understanding $links should be included as well.

    fejn’s picture

    I've found the Andromeda Handbook quite useful when trying to figure out how to adjust a theme. The outline presented above is great; it includes lots of important information: I'd like to see a template that individual themes could use to present technical information (e.g., how to configure a slideshow within the theme) for special features that their theme offers for a separate document. That would separate the general from the specific issues.

    (Note: I'm pretty new at documentation; I've been around Drupal for a while, though).

    goldhat’s picture

    Does the current navigation in Drupal.org support this kind of "tree outline" approach which might be very useful for documentation? I've found often when I'm looking at a certain page of documentation here, I still have to search to find the next page. Often the next page in the list or shown nearby in the tree is quite different in topic or nature.

    I think that is one of the keys of good documentation, is not just to have good individual pages but that there is a really simple way to navigate through or see it as an overview. My all-time favorite for documentation approaches so far is from Code Igniter help guide. It provides an at a glance overview of the entire help guide and once you become familiar with that, you know exactly where to go each time you are searching. This is quite different from the Drupal.org experience, where the navigation is constantly changing depending on where you might currently be. Options come and go too often.

    jhodgdon’s picture

    Issue tags: -Sprint: May 2011 +valid issue

    Using a new issue tag...

    fejn’s picture

    Component: Placement/Navigation/Structure » Correction/Clarification

    The thing I found most difficult as a Drupal n00b was to figure out what I should ask, which might be hard to serve up in documentation.

    dkre’s picture

    I've come to this issue from the contribute doc page so I'm not 100% if this is still the best place to post this, but this is definitely on topic.

    I started building sites with drupal as a designer with limited experience. My background was purely design but over the last year I've climbed the drupal learning curve and now am absolutely passionate about the system and it's success. So I think I have a fairly good perspective.

    The biggest issue I see overall with the documentation is that it isn't branched according to version. This is a wider documentation issue rather than specific to the theming guide but it is a lot more important in this case because as mentioned this sections audience will be: designers and front-end developers.

    Furthermore a site can be built with the core modules if the site is rather simple but the design and look of the site is only going to be able to be achieved with understanding of how themes work in drupal.

    The documentation must be branched
    I stopped reading any documentation on drupal.org very early on. Why? Because I found the vast majority of the documentation to be irrelevant because you don't know an article, which according to the title is exactly what you need to know, is for 4.7 until you visit the page.

    Grouping 6 & 7 together makes sense in some ways given that the fundamentals are much the same but it breaks down quickly given that drupal 7 is so very different once you deal with the templates and preprocess which is the majority of what is and needs to be documented.

    Where this breaks down even further is when you look at overall theming guide documentation (root) with snippets, howtos and most of the other root menu links being obsolete for anyone developing with drupal 7 - or more importantly someone starting out with drupal right now.

    The root menu should reflect what is current
    I was originally looking for a place to post a snippet which solved an issue posted a couple of times in the core issue > support request queue and in the forums. Then found that theming guide > code snippets (theme snippets) were so random the way they were organised I didn't see the point. Like myself people will find (by search) my posts (to be posted at the time of writing) in the forums/issues rather than the documentation.

    LeeHunter’s picture

    I think everyone agrees that the reader should be able to view version-specific guides but unfortunately this doesn't seem practical right now because the current setup of d.o. is fairly primitive and doesn't allow content to be single-sourced (i.e. there's no way to have the same instance of a chunk of content appear in two different guides). Without that capability, we'd have to create separate instances of whatever information is common to both guides which would instantly into a horror show because edits don't get made to each version.

    humberto.sachs’s picture

    There are two aspects of documentation: specifications and user manual. Unfortunately, Drupal mix then, as other open technology organizations do, starting with Linux; the result is inevitable: the task becomes a giant accumulation of valuable data in a format that cannot satisfy the expert nor the user. In the process, important little details get lost, valuable time is wasted, and good software is often misused.
    I have 40 years experience mentoring and training professionals and proved my theory for Knowledge Transference in the Space Station Project in 1990-1993 time frame. Lack of open source basic tools did not allow the successful prototype to become production. No one could afford the cost of starting from scratch. Now we are reviving this technology within Txgroup and I would be glad to help Drupal implement it.

    batigolix’s picture

    Humberto: this is an ancient thread you're commeting on, so do not expect a lot of reactions.

    There are many ideas and proposals regarding the improvement of Drupal documentation, many of them can be found here: https://drupal.org/project/issues/documentation?text=&status=Open&priori...

    Your views and opinions could be very valuable in this subject.

    Keep an eye on active discussions and share your thoughts there. Join our efforts to improve Drupal's documentation to get an idea of the challenges we are facing.

    batigolix’s picture

    Issue summary: View changes

    Added subitems for using themes to target specific content.

    krina.addweb’s picture

    Issue summary: View changes
    krina.addweb’s picture

    Issue summary: View changes