Drupal Usage

Including Components in Drupal

From your Drupal Twig templates in templates/ you can use Twig's {% include %}, {% extends %}, and {% embed %} statements to include your Pattern Lab Twig template files. Each of the top level folders has a Twig Namespace like @organisms (see emulsify.info.yml for the namespace conventions) and then you append the path down to the file like below.

{% include "@organisms/path/to/file.twig" %}

Atomic Design Structure

As a Drupal developer, it may be helpful to think of the Atomic Design structure (atoms, molecules, etc.) in terms of Drupal output. In general, fields can be thought of as atoms, nodes as molecules and views, paragraphs or other listings as organisms. Component organization is really left to logic and will sometimes defy these conventions, but these principles apply as a general rule.

Passing Variables

One of the biggest benefits of this component system is being able to give concise, logical names to your variables. However, Drupal has it's own variable syntax that you will need to leverage to pass data. Below is an example from the page title template (templates/page-title.html.twig) of how to pass that data using Twig's {% include %} statement. Notice that the component uses a {{ heading_1 }} variable but the Drupal template uses {{ title }}. Simply pass the Drupal variable to the component variable as follows:

{% include "@atoms/02-text/00-headings/_heading.twig" with {
    "heading_level": 1,
    "heading": title,
  } %}

Below are more complex examples:

{% include "@molecules/info-box/info-box.twig"
  with {
    "infobox_title": content.field_paragraph_info_box_label,
    "infobox_text": content.field_paragraph_info_box_text,
    "infobox_link": content.field_paragraph_info_box_link.0['#url']
  }
%}

or

{% embed "@molecules/card/01-card.twig"
  with {
    "card_title": label,
    "card_body": body,
    "card_link_text": content.field_link.0['#title'],
    "card_link_url": content.field_link.0['#url'],
  }
%}
  {% block card_img %}
    {{ content.field_image }}
  {% endblock %}
{% endembed %}

Drupal-specific functions, filters and tags

Drupal has specific Twig functions, filters, tags, etc. that it uses that Pattern Lab is not aware of. Pattern Lab has an easy way to add those though, which is in components/_twig-components/. There are examples of filters and functions already in there (e.g., t(), without(), kint() functions). Documentation on how to add these can be found here.

JavaScript in Drupal

• Component-specific javascript should be written inside each component alongside the HTML/Twig and CSS. From there, add it as a library in the theme and use Drupal's attach_library function inside your component Twig file (e.g., {{ attach_library('YOUR_THEME/LIBRARY_NAME') }}). We use a modified version of the attach_library function in Emulsify, and using this will ensure your library is added in both Pattern Lab and Drupal.
• You can use Drupal.behaviors inside pattern lab, but you will need to follow the instructions for symlinking the correct files and uncommenting some lines in components/_meta/_01-head.twig. See components/_patterns/02-molecules/accordion-item/accordion-item.js for an example usage.

Resources

Component-Driven Development in Drupal