Working With Twig and Patternlab

The Waiter generates the pages of a publication by combining the JSON returned by the cook with Twig templates and CSS styles. The default location of those styles and templates is the CUE Front templates folder. The contents of this folder is monitored by a synchronization process, so any changes you make to templates or SCSS files in this folder are immediately copied into the Waiter's Docker container and result in corresponding changes to your web site. These templates, however, not only drive the actual web site - they also drive a Patternweb style guide, which you can use to view static examples of all the templates that make up your publication.

Open your browser and point it at http://localhost:8103/. You should see the demo publication's style guide, displayed using the Patternlab web application:

Using this application you can explore all the Atomic Design patterns from which the demo application is constructed – each pattern being a Twig template fragment.

You will see that Patternlab's menu bar contains menus called TOKENS, ATOMS, MOLECULES, ORGANISMS and PAGES. These menus represent different types of patterns. The PAGES menu contains the names of the page patterns used for the demo publication: Atomic Frontpage is the name of the pattern used for the publication's section pages, and Article Page is the name of the pattern used for story pages. The ORGANISMS menu contains re-usable patterns that may appear several places in a page pattern, or in several different page patterns, such as the Five Story Section component. The MOLECULES menu contains smaller patterns that may appear several places in different organisms or directly in page patterns, and the ATOMS menu contains even smaller patterns that may be re-used in molecules, organisms or pages. Finally, the TOKENS menu contains variables defining the colors, fonts, icons and so on that form the basis of the design.

When you select a pattern from one of the menus, the template is processed using Twig and the results are displayed in Patternlab. In order to be able to display the patterns, Patternlab has access to some sample JSON data for merging with the templates.

Besides allowing you to browse the patterns from which a design is constructed, Patternlab offers a number of other functions. The most useful are:

• You can display a pattern's template code plus a description of the pattern by selecting Show Pattern Info from the Tools menu at the right hand end of the toolbar.

• You can see what each pattern looks like on different size screens by selecting a size option from the right hand end of the menu bar: Small, Medium, Large or Full (the default).

Patternlab requires the templates that make up a pattern library to be stored in a known location, in accordance with specific naming conventions. The demo publication's patterns are stored in cue-front/templates/_patterns. In cue-front/templates/_patterns/10-pages, for example, you will find all the templates that appear in Patternlab's PAGES menu.

Patternlab is a very useful review tool for designers: you can work directly on the patterns in the library, and use Patternlab to review the results of the changes in a variety of contexts. If you make a change to an atom template, for example, then you can use Patternlab to see what the change looks like in a variety of contexts:

• The atom in isolation

• The various molecules, organisms and pages in which the atom appears

• At different screen sizes

In addition, since Patternlab uses locally stored static data files for display purposes, you are not dependent on access to a working site for the design work. If you want to export the Patternlab style guide to work with it on a different machine, you can do so by entering:

make dist-style-guide

in the cue-front folder. This will create a zip file containing the style guide in the cue-front/dist folder.

Patternlab supports the concept of pattern states such as in progress, in review, unplugged and complete to help you organize your workflow. Pattern states are represented by coloured dots displayed before the pattern names in Patternlab menus, and the states are "inherited". That is, if an atom is in progress, then all other patterns that include that atom will also be displayed as in progress by Patternlab.

Pattern states are implemented by means of a naming convention. To put a pattern in the unplugged state, you simply append @unplugged to the end of its file name: rename 00-header.twig to 00-header.twig@unplugged, for example.

A good deal of Patternlab functionality is governed by naming conventions. For a brief introduction to these conventions, see Patternlab Conventions. For more detailed information about Patternlab, see the Patternlab documentation.