Fractal integration for Twig projects

This module enables you to build a living style guide based on Fractal components using the Twig templating language. It can either be used as a Drupal module or as a standalone Twig extension.

Features

Consistency: Respect component definitions.

The default variables of a component are read from its component definition file (usually *.config.yml).

The class name of a component (or a variant of it) is not manually passed to the template each time it is used. Instead, every usage of the component ensures that that at least the component's class names are output (which should follow BEM).
```
{% render '@atoms/button.twig' with { name: 'submit' } %}

{% render '@atoms/button--primary.twig' with { label: 'Save' } %}

{% render [
  '@pages/section--trythis.twig',
  '@pages/section--alternative.twig',
  '@pages/section.twig',
] %} 
```
By design, the class name of a component or variant cannot be removed, it may only be amended.

Structure: Drupal Attributes.

Any template context variable with "attributes" in its name is treated as a Drupal Attributes object. Use them intuitively in your Fractal components.

context:
  attributes:
    class: article--teaser
  title: Dummy article title
  title_attributes:
    class: article__heading

<article{{ attributes }}>
  <h1{{ title_attributes }}>{{ title }}</h1>
</article>

Variance: Modifiers. Multiple modifiers.

A variant is identified by its modifier name, as specified in the referenced component name:

{% render '@atoms/button--primary.twig' %}

This will look up the variant identified by modifier 'primary' in the 'button' atom:

context:
  attributes:
    class: button

variants:
  - modifier: primary
    context:
      label: Save
      attributes:
        class: button--primary

Components may appear in multiple variations and states.

{% render '@atoms/button--primary--disabled.twig' with { label: 'Save' } %}

Installation

Add the following in your project composer.json file:

composer config repositories.twig_fractal git https://github.com/netzstrategen/twig_fractal.git

composer require drupal/twig_fractal:dev-master

Standalone

Drupal Core did not split its components into separate repositories yet, so the files need to be retrieved manually from the main repository. As soon as separate repositories for Drupal Components and Core become available, you can try to use them instead.

As the extension relies on some Drupal functionalities we need to grab the necessary files and autoload them:

composer config repositories.drupal-attributes git https://github.com/netzstrategen/drupal-attributes.git

composer require netzstrategen/drupal-attributes:dev-master

// Add 'render' tag for pattern library components.
$twig->addExtension(new \Drupal\twig_fractal\TwigFractal());

Recommended packages

https://github.com/netzstrategen/twig_fractal (this package) adds support for the {% render %} tag to the Twig environment in PHP (of your application).

https://github.com/netzstrategen/fractal-twig adds support for the {% render %} tag to the Twig environment in JavaScript (of the Fractal UI).