Twig and the new theme layer in Drupal 8

Regular meetings

We are organizing our effort via several channels:

• Google hangout every 2 weeks: We'll put together an agenda and talk about progress and next steps. For the dates and times see the Google calendar (below) or check the topic in #drupal-twig on IRC.
• Drupal Twig calendar: For Google hangout times, upcoming sprints, etc.: Subscribe to iCalendar feed or add ubk01l2m902412nhi4ef2hjn20@group.calendar.google.com to Google Calendar

• Chat: #drupal-twig on Freenode. Come join the discussion to collaborate or ask questions. We hold unofficial office hours here on Thursdays before and after the call.

  If you'd like to get involved but aren't sure where to start, attending core mentoring is a great first step. Talk to a mentor and mention that you want to help with Twig and the theme layer in Drupal 8.

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

   • Theme System/Architectural Issues
     • #2004872: [meta] Theme system architecture changes
     • #1843650: Remove the process layer (hook_process and hook_process_HOOK)
     • #1751194: Introduce hook_theme_suggestions[_HOOK]() and hook_theme_suggestions[_HOOK]_alter()
     • #2035055: Introduce hook_theme_prepare[_alter]() and remove hook_preprocess_HOOK()
     • #1886448: Rewrite the theme registry into a proper service
     • #2029819: Implement a ThemeHandler to manage themes (@see ModuleHandler)
     • #2060767: Replace Drupal::moduleHandler()->themeInvoke() with Drupal::themeHandler()->invoke()
     • #2060773: [META] Migrate hook_preprocess() functions to template plugin prepare() methods
     • #2060783: Remove the preprocess layer.
   • Multilingual
     • #1927584: Add support for the Twig {% trans %} tag extension Assigned to: markhalliwell
     • #2049241: Add support for language options to the Twig {% trans %} tag extension Assigned to: markhalliwell
   • Variables in templates must be drillable
     • #2008450: Provide for a drillable variable structure in Twig templates
     • #2047263: Provide inline_template tag within Twig that inlines a template for usage with a render array
   • Security
     • #1825952: Turn on twig autoescape by default
     • #1818266: [meta] A secure theme system (with twig) Assigned to: Fabianx

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 all tables in core to new #type 'table'
     • #1757550: [Meta] Convert core theme functions to Twig templates
   • Replace Drupal's crappy markup with our Dream Markup(tm)
     • #1980004: [meta] Creating Dream Markup
   • Add a theme component library:
     • #1804488: [meta] Introduce a Theme Component Library

6. Drupal 8 - NEW markup "nice-to-haves" (lowest priority)

   • Icon: #1849712: Add theming template and prepare logic for rendering icons

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 the old 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