Confirm and Elaborate Information on Custom Theming Strategies for Infographic Design

I'm the author of the theming chapters you mention, and it seems like you've grasped the concepts of each pretty well. I think it's awesome that you are looking to create an infographic on this stuff. We could all benefit from such a document.

My only issue after studying the material within the book, which I admit might be more of a personal issue than something everybody experiences, especially given that each exercise implies to a varying extent the particular purpose of each theming technique, is an all-inclusive comparative analysis or custom site build demonstration that reveals the logic of using one theming technique over another in different areas throughout an entire site build process.

I've seen similar feedback in reviews of the book, so I'd like to take this opportunity to explain some of this.

1. First of all, to have an all-inclusive comparative analysis would require an entire book dedicated to the topic of theming. I tried to squeeze as much of the really important concepts in as possible, because it's the information that I would have loved to know when starting out. That obviously means some trade-offs, so I don't think it's a personal issue. :)
2. We did provide code for demonstration purposes. The entire site build of the definitivedrupal.org site and the theme which includes examples is available for download here: https://github.com/definitivedrupal/dgd7. I can't speak for the other chapters, but I tried really hard to get as many examples as possible in a real theme here: https://github.com/jacine/dgd7 (Note: this is also in the main repo linked previously). It's not perfect, but the point of it is to demonstrate the techniques covered in practice.

I'm a little overwhelmed by all the options and I have been trying to look for or develop the logic for using one strategy over another in the different areas of the site build process.

This is actually a problem with Drupal theming itself, and a very common complaint. There are WAY too many options and unfortunately there is no hard and fast rule for when to use one technique over another. The inconsistencies make things hard and this is an area where most of us really want to see changes in Drupal core. The choice for which technique to implement lies in the hands of module developers 90% of the time, so knowing how something is being built is the main key to changing it. This is why being able to identify the technique used and knowing the foundation of each is critical.

I am a designer and a newcomer to Drupal who is interested in learning custom themes from scratch and possibly creating an infographic that summarizes the logic of the various custom theming strategies in Drupal for a typical site build process.

Like I said, I think you got quite a bit out of the chapters, and would love to see what you come up with. I think it's a very worthwhile cause, and can help us identify concrete areas to improve in Drupal 8.

A consequence of open source is that some features come into existence piece-wise and evolve over time without original comprehensive plans or constitution. Some APIs are useful, but others sometimes just feel like responses to old workarounds.

As Jacine mentioned, this has resulted in a raffish cornucopia of theming APIs that are confusing not just for beginners but for seasoned vetrans as well. Drupal 7 theming is much more difficult than Drupal 6. I experience much more iteration and debate of technique.

Personally, I think we need better tools and fewer gagets. Themers want a chef's knife and we given them a Slap Chop.

What's good is that we're talking about it. What's better is that this is open source. We can fix it. If you have ideas, please contribute to discussion on g.d.o and other channels. Whether newcomer or vetran, we're all authors of the future of Drupal theming.

Hello there, Brandon!

I am also a huge fan of that huge book :) I'm writing training materials on this very topic right now, I would love to see an infographic to direct learners to.

I wonder about your target audience.
Group A. You say they are designers? That is, visual designers who need to understand Drupal to create visual mockups for it?
Group B. Or are they coding designer/developers who are interpreting a visual design in Drupal?

For both groups who are NEW to Drupal, I would caution against bringing them to the VIP template.php room first, doing lines of PHP, and getting lost in preprocessing, and overriding theme functions.

The best practice is to take a "configuration before coding" approach. They should look closely at configuring Views to get the markup you want, configuring content types and field display, and configuring any other contrib modules. That is, before making theme-specific alterations. This configuration before coding approach is one our professional services team at work promote to our clients time and time again. With that, they see less errors and less trouble.

A good method is to "theme with the markup you have, not the markup you wish you had". (- Laura Scott) If you are talking to markup purists about Drupal, they will be quickly frustrated at this stage. There is quite a lot you can do with CSS overrides.

Best practice with module development implies that module developers should output template suggestions and theme template files. This allows themers to override markup by duplicating the file in their own theme folder. This is the ideal situation. Yet of course, you want to avoid template-itis.

Template files should manipulate markup on a macro scale, and preprocess functions should alter smaller chunks of content, such as overriding the output of a variable.

Common pitfalls include:
- Creating preprocess functions for something which can be configured in the UI, or using String overrides, etc.
- Template-itis, making themes with many many .tpl.php file overrides, with often just slight alterations.
- Manipulating content layout in the theme layer, when there are superior modules such as display suite, panels/context or others.

For Group A- They may be used to being able to design every last element of the site. Especially if they are new to CMSs. Drupal comes with quite a bit out of the box. Error messages, tabs, user registration pages, which designers often forget. Try the Style guide module to show what you may have forgotten. http://drupal.org/project/styleguide

For Group B- they may be used to tag based template systems like EE and WP. They can create their perfect markup and pop in their "tags" which output results from their CMS. Drupal is the furthest you can get from that. I think a better metaphor would be an "extruder". You have these patterns and shapes and your site is extruded through it.

The difference with Drupal is what I call the "markup middle man". The historical aim of Drupal is to put powerful tools like content type creation and query building (Views) in the hands of trusted line managers and site builders. Whereas in other systems you actually have to get at the templating layer to alter queries (give me X posts of Y category), in Drupal, we use Views (in most situations).

Recapping:
- Configuration before coding
- Theme with the markup you have
- Less is better, more maintainable and sustainable.

I do believe a little bit of knowledge is dangerous. Inexperienced developers can do some damage, but experienced PHP developers can do the worst damage when they are just getting to know Drupal. They can engineer entire parts of Drupal on top of Drupal. Always emphasize they should learn site building first and coding later.

I also recommend looking at this presentation by Tim Cosgrove from Treehouse Agency:
http://treehouseagency.com/blog/tim-cosgrove/2011/10/22/modern-theming-b...

And watch the recorded presentation from BadCamp
http://treehouseagency.com/blog/taran-rampersad/2011/12/06/badcamp-video...

It's sort of cut off, so you can watch it along the same time.

Here is the content that I've gathered on Custom Theming using drupal.org and the books "The Definitive Guide to Drupal 7," by Melancon et al and to a lesser extent, "Beginning Drupal 7" by Todd Tomlinson. As I said before I'm still learning Drupal and began compiling this information as a study guide rather than as an knowledgeable expert in the field. I'm really hoping that the drupal community will help to evaluate and elaborate on the information, particularly in the examples of common/useful/practical applications of each theming technique, right now the examples are "limited" by what was covered in the books.

I've ordered the list and list items from basic theming strategies to major/advanced theming strategies. Starting with Basic Page and Article following the advice that Heather offered concerning the need for an awareness of the potentials of font-end configuration. However, even though I did watch the link to Tim Cosgrove's BadCamp presentation that Heather recommended, and was really impressed and excited, as a newbie that tends to become easily perplexed, I still don't quite understand the theming strategies that were discussed in the presentation so there is nothing here on the Bean, Fieldgroup, or Display Suite modules. Maybe someone could point me to a link or book that offers a real simple and straightforward explanation of those modules and/or add them in this list format:

Modifying Contents, Structure, and Placement of Elements

• The Basic page content type provides you with a text field for entering the title of the content item, and a body text area. The body field is flexible and can contain whatever the author feels like writing about.
  • Write an entire book in the body field, including HTML markup (headings, tables, CSS, and so on).
  • Insert pictures.
  • Write a single sentence.
• An article is identical to a basic page with the single exception that an article has an image upload feature and an additional field where the author can enter what are called tags. Tags are simply words that help classify, organize, and search for related content on your site.
• Custom Content Typesare good when you want to:
  • Require that certain information is entered before the author submits the content item for publishing; for example the start date and time for an event, the address of the venue where the event is being held, and a link to the event on a Google map.
  • Have the ability to perform calculations based on the information that is captured in a content item.
  • Have the ability to sort content items by specific “fields.”
  • Have the ability to “filter” or restrict which content items are displayed on a page based on a value in a field.
  • Enforce the structure of how a piece of content is rendered on a page; for example, you may want to display information about a book and want the title to be followed by the author, followed by the ISBN, followed by the price, followed by the description of the book.
• A block is a generic term that is applied to any self-contained piece of content, menu, or code. Standard blocks that come with Drupal include the login block, the search block, the “who’s online” block, the “who’s new” block, the latest blog postings block, and more. There are also blocks that come with contributed modules, such as blocks that share the latest weather report, your recent Twitter posts, or your current Facebook status. As a site administrator, you can construct your own custom blocks.
• Views provides an easy-to-use tool for selecting and displaying lists of content on your website. It is essentially a smart query builder that can build the proper query, execute it, and display the results. Examples of how you might use Views include:
  • Displaying the most recent news articles posted to your website, sorted in descending order by the date of posting.
  • Displaying a list of company locations as a table that is sortable by clicking on the titles for the location name, city, state, and country.
  • Displaying a list of blog postings that is filterable by subject.
  • Creating an RSS feed that lists the most recent content posted on your website.
  • Displaying just about any kind of list that you can think of, created from the content that is stored on your website, as a list, table, or RSS feed.
• Panels are useful when you want to divide a region into multiple “mini-regions” called panel panes. *
• Alter Hooks (p 323), ex: dynamically add HTML for new small bit of content into a region, moving content from one region to another based on certain circumstances, and changing the contents of tabs based on certain circumstances. **
• render(), hide(), and show() (p 327), selectively renders bits of content, such as fields, inside theme functions, templates and pre/process functions. Ex: render() is essentially an implementation of a render array **, hiding part or all of a render element to allow them to be placed outside of a div, hiding content based on certain circumstances, show() reverts a previously applied hide(), render() can be used multiple times. ***

*Views can be used with panel panes to define what content should be rendered, how many items should be included in the list, and how those items should be rendered. Using Taxonomy, content authors select the appropriate taxonomy term that is associated with each panel pane, and the content automatically appears in the right spot on the right page.

**Render Arrays are structered arrays that contain nested data and other information that drupal uses to render HTML (p 321) they are similar to theme hooks in that they use template and theme functions but they are modified using alter hooks (323).

***It’s best to do these operations in preprocess or process functions in order to keep your templates clean and more manageable (329).

Styling

• Define Stylesheets via the .info file (p 343), to be loaded for all pages.
• drupal_add_css() to conditionally load stylesheets (p 344), ex: to dynamically print as an “inline” block of css code within the tag, stylesheets for single pages, specifying the weight of a file to control the order that it loads, conditional stylesheets that target specific browsers, loading external stylesheets, excluding a CSS file from the aggregation and compression process. *
• hook_css_alter() to remove or override CSS files provided by modules and core (p 345).

*Enabling aggregation and compression for CSS files (admin/config/development/performance) on all live sites is highly recommended, as it will speed up page loads quite a bit (341).

Adding, Removing and Modifying Variables

• Preprocess Functions (p 314) are normally used to add or tweak variables* available inside template files, for example to provide the $subject variable in block.tpl.php. Ex: dynamically adding CSS classes to variables (such as regions) as opposed to overriding a template, hiding links in certain situations, modifying the portion of content that is to be viewed in certain situations, and to create a custom variable to input a link for a type of user (318). **
• Process Functions (p 314) ex: adding, removing, hiding, and modifying variables in certain circumstances “later in the processing cycle.” **

*use devel module’s dpm() function to determine all the available variables to work within each theme hook p.311

** These functions are run prior to the template being displayed, thereby allowing you to manipulate the variables for use in the templates themselves.

Modifying HTML Markup

• Theme Hook Suggestions p.305 – progressively traverse drupal’s template/theme function/block specificity to target a specific template/theme function/block
• Theme Functions* p.301 – small, but site-wide, changes to form elements, fields, menu items, and adding/modifying content to blocks (p301) See: http://api.drupal.org/api/group/themeable/7
• Template** Overrides p.293 – major site-wide changes to structure of a page, nodes, blocks, or to add/remove regions*** (291)

*These are theme specific, meaning if the site employs more than one theme it will not apply.
** The block.tpl.php file, for example, is used when a block is being rendered. Template files can be overridden by copying them into your own theme. It is also possible to make specific overrides with naming conventions, such as block–user.tpl.php.

*** Regions play a large part in defining the high-level structure of HTML markup. Typical regions include the header, footer, sidebars, and content, most of a site’s content is output inside these regions.