https://github.com/netzstrategen/twig_fractal

Reuse Fractal components in your Twig or Drupal projects without duplicating component code.
https://github.com/netzstrategen/twig_fractal

adapter component-library drupal fractal twig

Last synced: 6 days ago
JSON representation

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

• Host: GitHub
• URL: https://github.com/netzstrategen/twig_fractal
• Owner: netzstrategen
• Created: 2017-08-17T12:49:47.000Z (about 7 years ago)
• Default Branch: master
• Last Pushed: 2023-10-10T14:16:05.000Z (about 1 year ago)
• Last Synced: 2023-10-10T17:33:37.138Z (about 1 year ago)
• Topics: adapter, component-library, drupal, fractal, twig
• Language: PHP
• Homepage:
• Size: 55.7 KB
• Stars: 4
• Watchers: 16
• Forks: 3
• Open Issues: 1
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

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

    ```twig

    {% 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.

    ```yml

    context:

      attributes:

        class: article--teaser

      title: Dummy article title

      title_attributes:

        class: article__heading

    ```

    ```twig

    

      
{{ title }}

    

    ```


3. Variance: Modifiers. Multiple modifiers.

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

    component name:

    ```twig

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

    ```

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

    'button' atom:

    ```yml

    context:

      attributes:

        class: button

    variants:

      - modifier: primary

        context:

          label: Save

          attributes:

            class: button--primary

    ```

    Components may appear in multiple variations and states.

    ```twig

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

    ```

## Installation

Add the following in your project `composer.json` file:

```sh

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: 

    ```sh

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