Skip to content

Reuse Fractal components in your Twig or Drupal projects without duplicating component code.

Notifications You must be signed in to change notification settings

netzstrategen/twig_fractal

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

36 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

  1. 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.

  2. 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>
  3. 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.

  1. 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
  2. Register the Twig extension in your project:

    // 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).

About

Reuse Fractal components in your Twig or Drupal projects without duplicating component code.

Topics

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages