Twig and the new theme layer in Drupal 8

Shortcuts:

• Regular meetings
• Essential Resources
• Roadmap
• Issue tags & Documentation
• Code sprints
• Principles: Waypoints to guide us
• Tell your friends

Regular meetings

We are organizing our effort via several channels:

• Weekly Google hangout: Thursdays at 11:30AM PT (2:30PM ET, 20:30 CET). We'll post an agenda and talk about progress and next steps.
• Chat:#drupal-twig on Freenode. Come join the discussion to ask questions. We hold regular office hours here on Thursdays before and after the call.

Essential Resources

Here are some essential resources for helping us with the move to Twig:

• Core template conversion issues
• Core theme function conversion issues
• Core markup cleanup issues
• Current Twig TODO list
• New to Twig? For a brief introduction to Drupal and Twig, please read this blog post by Anthony Ringoet.

Roadmap

Current plan for cleaning up the theme system.

1. Update core to use two different theme engines, & fallback to PHPTemplate:
   • #1696786: Integrate Twig into core: Implementation issue
2. Add simple example of Twig to core:
   • #1696786: Integrate Twig into core: Implementation issue
3. Convert PHPtemplate files to Twig & use Twig as the default:
   • #1987510: [meta] Convert all core *.tpl.php templates to Twig as singular patch
   • #1806478: Make twig the default engine once all modules templates are converted from .tpl.php to .html.twig

4. Must-have's for Drupal 8

   • Variables in templates must be drillable NO MATTER WHAT
     • #2008450: Provide for a drillable variable structure in Twig templates
   • Solve template suggestion problems
     • #2004872: [meta] Theme system architecture changes
     • #1886448: Rewrite the theme registry into a proper service
   • Remove the process layer (also performance enhancement)
     • #1843650: [meta] Remove the process layer
   • Translation (and format_plural)
     • #1927584: Handle trans block as Twig extensionAssigned to: geoffreyr
   • A secure theme system
     • #1825952: Rely on Twig auto-escape, don't prepare wasted variables in preprocess
     • #1818266: [meta] A secure theme system (with twig)

5. Nice-to-have for Drupal 8

   • Consolidate template files (also performance enhancement)
     • #1804614: [meta] Consolidate theme functions and properly use theme suggestions in core
   • Convert theme functions to Twig & benchmark:
     • #1876712: [meta] Convert form tables in core to new #type 'table'
     • #1757550: [meta] Convert core PHPTemplate files and theme functions to Twig
   • Rewrite the theme registry as a service
     • #1886448: Rewrite the theme registry into a proper service
   • Add a theme component library:
     • #1804488: [meta] Introduce a Theme Component Library
   • Refactor the Render API
     • #1843798: [meta] Refactor Render API

6. Allowed after code freeze (Jul 1)

   • #type = 'table' acts weird - bugfix
     • @todo - create an issue
   • Replace Drupal's crappy markup with our Dream Markup(tm)
     • #1980004: [meta] Creating Dream Markup

Issue tags & Documentation

See the following tags for core issues related to Twig and revising Drupal's theme system.

• Queue Search: Twig
• Queue Search: Twig engine
• Queue Search: dreammarkup
• Queue Search: Theme system cleanup
• Queue Search: Theme system consistency
• Twig documentation on drupal.org
• Twig documentation on Sensio labs
• DrupalTwig folder in Google Docs
• Google Doc: Conversion instructions
• Drupal Twig (Sandbox -> Core) Conversion Instructions
• Google Doc: Conversion worksheet
• Google Doc: Consolidation opportunities
• A 10 minute overview of working with this sandbox
• [meta] New theme system

Code sprints

Principles: Waypoints to guide us

At the BADCamp 2012 theme sprint, we outlined some core principles to guide our work for the D8 theme layer.

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 common theme functions that modules leverage (i.e. a Theme Component Library).

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.

Tell your friends

Send people to this page using this link: http://lb.cm/twig

• Regular meetings
• Essential Resources
• Roadmap
• Issue tags & Documentation
• Code sprints
• Principles: Waypoints to guide us
• Tell your friends