Twig Sprint Summary, BADCamp 2012

UPDATE: Looking to help with Twig tasks?

Please see the Twig sandbox for all information about the roadmap, current tasks, related issues, and more.

We're sprinting on Twig, the new theme layer for Drupal 8 that was just committed yesterday! In attendance, are moretendk, JohnAlbin, jenlampton, c4rl, ry5n, snugug, dnotes, philosurfer, mikestewart, laura s, eojthebrave, eatings, chrisshattuck, dboeger, ceagans, steveoliver, starryeyez024, and others.

We decided to work on several different things today: we have one group of people converting theme functions to template files, and we have a larger group discussing HTML patterns in core, and coming up with our component library, based on Jacine's Blog post and her code example.

Most of the sprint was a discussion about our approach and principles to guide the ongoing Twig tasks.

Approach: A new theme in core

The first question I asked was if it was "okay" to break all the CSS and JS in core by reworking markup, and this brought up two points of view.

• Core default markup in D7 is bloated: We should strip it down entirely.
• Core default markup in D7 contains some useful things (classes, IDs, wrappers) that certain themers might still want to keep. We should just move it someplace else.

As we discussed why people wanted option (1) (minimal markup and CSS in core default templates), we all started to agree that this would be a very attractive thing for front-end developers, but that we still need option (2) to demonstrate some useful markup and classes for people to use who were CSS savvy.

It became apparent that Stark in D7 does two things: It represents a window into core default markup. But the result of this markup currently has some feasibly beneficial classes and IDs for people to use as a potential base theme. Our proposition for Drupal 8 is that these should be separated. Core default markup would be essentially "naked" so that no extraneous markup exists in the templates and there exists an optional core theme that provides the possibly-useful classes and IDs (for example, .node, .block, .front, etc).

The working title for this new theme as conceived in the sprint is "Lush." It is possible that it is simply a refactored Bartik.

Drupal 7

Drupal 8

*Possibly a refactored Bartik.

We didn't get into the specifics of how JavaScript would work, so that is a discussion yet to happen.

With this approach we wish to appeal to two personae:

Persona A: Front-end expert (Stark)

The goal of Stark in D8 retains a focus on minimal output. Front-end experts who prefer very clean semantic markup will prefer these templates as a base for a custom theme. This way, they don't have to work backwards. This could improve Drupal's reputation among front-end experts outside of the community. Stark is not born out of practicality in a real-world use case, but rather to provide a clean, semantic slate.

Persona B: CSS-driven (Codename "Lush")

Some folks don't mind having some useful classes provided for them, and are likely to add only a style sheet that adds or changes CSS from core. These themers would use Codename "Lush" as a base theme. This would preserve some purpose and utility of long-standing class and markup conventions in Drupal.

Given the existing prospect of implementing a Theme Component Library (TBD – #1804488), our hope is core modules will not need to provide their own markup, they can use the components from core (mostly). Those components can be overridden in the Lush theme to add useful divs, IDs or classes.

What about module preprocess functions that add classes?

Certain modules provide preprocessors to provide classes for the markup that they define in hook_theme(). An example of this is template_preprocess_node() in node.module. Classes like .promoted, .sticky, .unpublished, and others are added to the template wrapper.

These are definitely not mandatory from a functionality standpoint, they are just nice-to-haves for themes. Removing these classes doesn't break anything critical (that is, removing .unpublished doesn't affect node_access), but they can be useful to have and there are definite general use cases where they apply.

We came to the conclusion that many of these can remain as-is, and that the majority of clean-up should consist of cleaning up extraneous markup and classes in the templates themselves (as these get the biggest gripes from front-end experts).

Based on the principle of "Build from use cases," we want to accommodate 90% of what people will use and provide tools for the remaining 10% of use cases.

So, consider the following example. Suppose our Codename "Lush" theme is being used as a base theme, and the .sticky class is added by the base template_preprocess_node() function and node.html.twig that starts something like this:

So, the "sticky" class lives in attributes.class (added by the preprocessor). It seems useful here to make the distinction that sticky is a property that any node may have and that the appearance of a sticky node being different than a non-sticky node is a general use case whereas the appearance of .node-article vs .node-page may not. (@todo Consider whether we could explore the distinction of "functional" classes vs "appearance" classes, or use data- attributes for things like sticky/published/etc).

Suppose someone uses the template as a base for their theme and wants to clean-up classes. At minimum, they could do the following:

So, .sticky being a functional HTML class added by the preprocessor remains since it is part of the attributes object. We believe this covers the 90% of use cases.

Based on the principle of "Provide tools," in the event that someone really wants to remove this class, they have options. They can remove all classes in their custom preprocessor function, or simply unset the class variable in the twig template (See http://drupal.org/node/1696912#comment-6704868, syntax uncertain. @todo provide updated syntax)

What about contrib?

Contrib modules must provide certain default styling to be functional for site builders that want to download the module and use it right away. Consider the fivestar module: the styling and graphics must work out of the box. So, contrib modules should, minimally, always provide appropriate markup, IDs, classes, CSS and JS. This assures the least sophisticated Drupal user can install a module and get functionality out of the box, and Persona B can leverage existing markup.

For Persona A, we want to provide a mechanism in a custom theme to disable the CSS files and JS files added by contrib modules (some sort of simple asset management). This makes overriding contrib styling easier: instead of copying an entire CSS file and then changing all the properties, we can simply exclude the file from being included in the first place and write our own CSS.

For example, a custom theme could implement the following syntax in the .info file. These are examples in order from most granular to least granular (Arguably, the latter examples may be overkill).

Issue: http://drupal.org/node/1833896

Principles: Waypoints to guide us

After we established this approach, we decided to focus on defining some core principles to guide the work necessary to convert and revise existing theme templates and functions to D8.

Start with nothing

Core default markup should strive for semantic simplicity, with few HTML elements, added only as needed

Build from use cases

Don't assume you know what people want or add features based on "What-if?" Think about the 90% of use cases.

Provide tools

Give front-end experts a way to achieve specific goals; goals that apply to the remaining 10% of use cases. Keep in mind that complex problems may require complex solutions.

Consolidate

"Your markup is not special." Don't make something new. Work toward a Theme Component Library that modules leverage.

Visibility

You should be able to see what's going on in a template without reading docs. Twig provides a lot of this by virtue of its syntax (it looks like HTML). Form follows function.

Consistency

Do the same things everywhere, follow patterns. Use similar variable names across templates if they represent similar things.

Don't dumb it down

Complexity should be reduced but not obscured. Themers *can* understand template logic and loops. When complexity does happen, use comments to explain why.

Organization should be driven by meaning and semantics over technical convenience

Consider what an element means rather than how it structurally appears. For example: theme_item_list() came about from a developer's perspective: OL and UL markup is nearly structurally the same, so providing a single function with the type argument came about from a code efficiency standpoint. However, from a semantic HTML perspective, we do not use a singular 'list' element with an attribute to indicate whether it is ordered or unordered, we have two different elements. Semantically, OL and UL represent different information. Therefore, we should provide a separate templates for OL and UL, even though they contain nearly identical markup.

Related to this principle (and the principle of Visibility), names and locations of templates should be self-evident. Consider where a newcomer might expect to override markup. Example: Someone looking to override a menu isn't going to look for a item_list template, even if a menu is structurally identical. So we should not simply have a menu use an item list, nor should we simply include an item list from a menu template. Themers want to see markup in templates, not abstraction.

Markup

After establishing these principles, we proceeded to look at some template examples and work on rewriting them according to the principles. Some of the above principles were added and revised during this process. We mainly focused on basic examples toward the pursuit of creating theme components.

We worked quite a bit on item-list.html.twig, adding ol.html.twig and ul.html.twig, then looked at menu.html.twig. These patches are currently on jenlampton's local machine, but we'll be looking to get these posted into the existing issues. (@todo get jenlamptons patches)

It was an enriching process to have many voices and perspectives in the room when writing template code.

Revised APIs

We didn't get much into revised PHP tooling. Much of this is TBD.

Markup utility functions: theme-less markup

jenlampton and c4rl made an important realization at the end of the sprint. Certain existing theme functions simply output a single element. Some of these looked like this:

As we looked at these, they were suspiciously similar and simple. We began to question the use and purpose of these:

• How are these useful to themers? Are they at all?
• Why do they go through the theme layer? What was the origin of this?
• What is a use case where a themer would have to override every image tag, or every link? Keep in mind we're designing for majority use cases.
• Why do we have theme_link and theme_image when we don't have theme_paragraph, theme_blockquote, theme_heading, etc?
• What can we learn from l(), a function that produces markup that doesn't go through the theme layer?

Functions like l(), theme_image(), and theme_image_style() are used because they are shortcuts to write tags. They offer developers more benefit than themers as they are a shortcut to write common markup.

The only point of sending markup through the theme layer is for themers to override that markup. After the sprint, effulgentsia mentioned that something like theme_link() was added out of a blanket policy that "All markup should go through the theme layer." Given that we were questioning many things at the sprint, we asked "Is this policy is too general?"

We couldn't think of a general use case where overriding every single link tag or every single image tag would be useful. Generally speaking, we believe if the markup of a specific link or image tag needs to be customized, that element is part of a larger structure (such as a pager or a menu) and the specifics of that link can be addressed via the parent template.

So, an issue was proposed to as "What if we had some markup bypass the theme layer?" (see http://drupal.org/node/1833920). UPDATE: After much discussion, some great realizations were made about the purpose and utility of things like theme_link() and l(), but the need for addressability (via array structure), and the prospect of a link being actually a Theme Component (say, a simplified button design pattern) clarified the necessity. Please see the linked issue for the full discussion.

JavaScript class selectors overlapping with CSS

We want to remove some markup and classes, but not that which would affect functionality via JavaScript too terribly. There's a lot of gray area here, but some solutions could be class namespacing or usage of data- attributes.

Issue: http://drupal.org/node/1833912

Next steps

@todo Figure out which templates that have already been converted to Twig simply "work" in twig, or if they have to be refactored, i.e. where a theme_foo() is renamed to template_preprocess_foo() and we have an empty template with {{ content }}
@todo Consider whether we should setup gatekeepers for the patches
@todo How do HTML5 semantics affect Stark?