Integrating Components with Drupal 8 - Part 1

Meeting our Component

 Let’s meet the component we will be building in this series. The name of the component is Card and here are the various elements that make it up as well as how the end product will look:

• Photo

• Name

• Label (Follow on)

• Social Media icons

• Biography

The idea is to be able to place this component on any page in our site and have it look and behave the same. The View full biography link will toggle a drawer/accordion behavior allowing us to open/close the drawer to read the full biography of the person.

Building the Component with Twig:

There are several ways or tools for building components intended for Drupal. Two of the most popular ones I know of are Pattern Lab and KSS Node. At Mediacurrent we use KSS Node but this blog series is tool agnostic so you can apply it to your existing workflow.

The way we build components is grouping all the pieces that make up a component in folders.  This includes markup (HTML), Sass, JavaScript and assets (if any). Our card component structure would look like this: 

/card
  /assets
  card.js
  card.json
  card.scss
  card.twig

• /card = The folder that contains everything about our component.

• /assets = Folder where we place images, icons, etc. related to this one component.

• card.js = JavaScript needed for component’s behavior (open/close in this example).

• card.json = Provides object which defines all variables and stock content for component.

• card.twig = Consumes content of card.json wrapped into component’s markup.

The above describes how most components will be organized. Some may or may not need Javascript or assets, but just about all of them will need styles, markup and some stock/dummy content in .json format.

It’s important to note that the component described above is only intended for the living styleguide that KSS Node provides. At this point, Drupal is unaware this component even exists.

Next I will break down the code used in each of the files above and explain how everything ties in together.

card.twig (github gist):

<div class="card">
  <div class="card__image">{{ image }}</div>
  <h2 class="card__name">{{ name }}</h2>
  <div class="card__social-media">
    <div class="card__social-media--label">Follow on:</div>
    <ul class="menu card__menu--social">
      {% for item in socialLinks %}
        <li class="card__menu--social--item">
          <a href="{{ item.url }}" class="icon-{{ item.icon|lower|clean_class }}">
            {{ icons.get(item.icon) }}<span>{{ item.icon }}</span>
          </a>
        </li>
      {% endfor %}
    </ul>
  </div>
  <button class="card__view-bio">{{ showBio }}</button>
    <div class="card__bio">{{ bio }}</div>
</div>

The .JSON file defines an object where we have a collection of variables and values which we are passing to our twig file.  Within the json file we can create arrays of information that we can loop through in twig.  Example of array above is the socialLinks info.

Although we can technically create our twig template anticipating drupal's content variables, there may be times when Drupal is not quite ready for us to use its content.  This is where .JSON comes in handy as it gives us a way to populate our component with stock content.

card.js (Github gist):

(function ($) {
  'use strict';


  Drupal.behaviors.card = {
    attach: function (context, settings) {
      var $bioButton = $('.card__view-bio', context);
      var $bioDrawer = $('.card__bio', context);
      var showBio = 'View full biography';
      var hideBio = 'Hide biography';


      $bioButton.on('click', function() {
        $bioDrawer.toggleClass('is-open');
        $bioButton.toggleClass('flip-carat');
        if ($bioDrawer.hasClass('is-open')) {
          $bioButton.text(hideBio);
          $bioButton.toggleClass('is-open');
        }
        else {
          $bioButton.text(showBio);
          $bioButton.removeClass('is-open');
        }
      });
    }
  };
})(jQuery);