pixo/labcoat

Development tools for Twig

Labcoat: Pattern Lab for Production

Labcoat is a library for using Pattern Lab content in live site environments. It provides the ability to:, _(*1)

• Render pattern templates
• Generate style guides using the Pattern Lab UI
• Validate template content

Labcoat places the following restrictions on Pattern Lab installations:, _(*2)

• Twig is the only supported templating language
• Patterns can only be referenced by partial and path syntax
• Layouts, macros, and other advanced Twig features are not supported

Labcoat was created by Pixo, and released under the NCSA license., _(*3)

Pattern Lab was created by Brad Frost and Dave Olsen, and released under the MIT license., _(*4)

Basic usage

Include the Labcoat library using Composer:, _(*5)

{
  "require": {
    "pixo/labcoat": "^1.0.0"
  }
}

The PatternLab class represents a Pattern Lab installation. For Standard Edition installations, Labcoat needs the path to the installation root (containing config and source directories):, _(*6)

$labcoat = Labcoat\PatternLab::loadStandardEdition('/path/to/patternlab');

For an installation that uses Labcoat's default structure:, _(*7)

$labcoat = Labcoat\PatternLab::load('/path/to/patternlab');

For custom configurations, create a new Configuration object and use it as a constructor argument:, _(*8)

$config = new Labcoat\Configuration\Configuration();
$config->setPatternsPath('/path/to/pattern/templates');
$labcoat = new Labcoat\PatternLab($config);

• More about Labcoat configuration

Rendering pattern templates

Labcoat contains a Twig loader class for using pattern templates in other applications., _(*9)

$loader = new Labcoat\Twig\Loader($labcoat);
$twig = new Twig_Environment($loader, ['cache' => '/path/to/twig/cache']);

The loader supports two methods of including patterns:, _(*10)

• Partial syntax, i.e. type-name. Fuzzy matching is not supported.
• Path, relative to the patterns directory. The file extension and any ordering digits are ignored.

# These will all render the template "00-atoms/01-icons/email.twig"
print $twig->render('atoms-email');
print $twig->render('atoms/icons/email');
print $twig->render('00-atoms/01-icons/email');
print $twig->render('00-atoms/01-icons/email.twig');
print $twig->render('123-atoms/456-icons/email.twig');

# Fuzzy matching isn't supported, so this won't work
print $twig->render('atoms-em');

Caching the loader

Once created, the loader class can be stored in a cache to save time during the next request. If Memcache is available:, _(*11)

$makeLoaderIfNotInCache = function ($cache, $key, &$loader) {
  $labcoat = Labcoat\PatternLab::load('/path/to/patternlab');
  $loader = new Labcoat\Twig\Loader($labcoat);
};
$loader = $memcache->get('labcoat_loader', $makeLoaderIfNotInCache);
$twig = new Twig_Environment($loader);

If Stash is being used:, _(*12)

$item = $stash->getItem('labcoat/loader');
$loader = $item->get();
if ($item->isMiss()) {
  $item->lock();
  $labcoat = Labcoat\PatternLab::load('/path/to/patternlab');
  $loader = new Labcoat\Twig\Loader($labcoat);
  $item->set($loader);
}
$twig = new Twig_Environment($loader);

Combining with other loaders

The Labcoat loader can be chained with other loaders:, _(*13)

$loader = new Twig_Loader_Chain([
  new Labcoat\Twig\Loader($labcoat),
  new Twig_Loader_Filesystem('/path/to/more/templates'),
]);
$twig = new Twig_Environment($loader);

Creating HTML documents

The Document class makes full HTML pages from patterns:, _(*14)

$doc = new Labcoat\Html\Document($twig->render('pages-about'));
$doc->setTitle('About Us');
$doc->includeStylesheet('/css/styles.min.css');
$doc->includeScript('/js/script.min.js');
print $doc;

Generating style guides

Labcoat can generate style guides that use the Pattern Lab interface, _(*15)

$labcoat = new Labcoat\PatternLab('/path/to/patternlab');
$styleguide = new Labcoat\Styleguide\Styleguide($labcoat);
$styleguide->generate('/path/to/styleguide');

Use PHP's built-in webserver to browse the style guide locally (at http://localhost:8080, in this example):, _(*16)

php -S 0.0.0.0:8080 -t /path/to/styleguide

Reporting

The generate() method returns a report object, which can be printed to obtain a summary of the generation process:, _(*17)

print $styleguide->generate('/path/to/styleguide');

Which produces something like:, _(*18)

443 files updated, 0 skipped, 0 removed
Generated in 1.432264 seconds

To get a full report of style guide file changes, use the verbose() method of the report:, _(*19)

print $styleguide->generate('/path/to/styleguide')->verbose();

...
index.html
  Updated (0.60 ms)
styleguide/data/patternlab-data.js
  Updated (1.41 ms)
annotations/annotations.js
  Updated (0.52 ms)
latest-change.txt
  Updated (0.18 ms)

443 files updated, 0 skipped, 0 removed
Generated in 1.432264 seconds

Validating template content

Labcoat can use pattern data files to validate classes that will represent live content in production environments., _(*20)

For example, a template named molecules-event could have the following data file:, _(*21)

{
  "event": {
    "name": "Company picnic",
    "date": "August 25",
    "time": "1:00pm",
    "private": true
  }
}

In production, the event variable will be an instance of the Event class. This class has properties and methods that Twig will treat like attributes of the variable., _(*22)

class Event {
  public $name;
  public function getDate() ...
  public function isPrivate() ...
}

Labcoat provides test methods to ensure that the Event class has all the attributes of event which are present in the data file., _(*23)

class EventTest extends Labcoat\Testing\TestCase {
  public function testEvent() {
    $labcoat = new Labcoat\PatternLab("/path/to/patternlab");
    $this->assertPatternData($labcoat, "molecules-event#event", "Event");
  }
}

When this test is run, the output will be something like this:, _(*24)

There was 1 failure:

1) EventTest::testEvent
Failed asserting that the data classes contain the required pattern variables.

molecules-event#event.name
  FOUND: Event::$name
molecules-event#event.date
  FOUND: Event::getDate(), line 15
molecules-event#event.time
  NOT FOUND
molecules-event#event.private
  FOUND: Event::isPrivate(), line 22