In the last post, we introduced Emulsify and spoke a little about the history that went into its creation. In this post, we will walk through the basics of Emulsify to get you building lovely, organized components automatically added to Pattern Lab.
Emulsify is at it's most basic level a prototyping tool. Assuming you've met the requirements and have installed Emulsify, running the tool is as simple as navigating to the directory and running npm start. This task takes care of building your Pattern Lab website, compiling Sass to minified CSS, linting and minifying Javascript, even creating an SVG sprite from SVGs in the images/icons/src/ directory. Also, this single command will start a watch task and open your Pattern Lab instance automatically in a browser. So now when you save a file, it will run the appropriate task and refresh the browser to show your latest changes. In other words, it is an end-to-end prototyping tool meant to allow a developer to start creating components quickly with a solid backbone of automation.
Emulsify, like Pattern Lab, expects the developer to use a component-based building approach. This approach is elegantly simple - write your DRY components, including your Sass and Javascript, in a single directory. Automation takes care of the Sass compilation to a single CSS file and Javascript to a single Javascript file for viewing functionality in Pattern Lab. Because it leverages the Twig templating engine, you can build each component HTML(Twig) file and then use the Twig functions include, embed and extends to combine components into full-scale layouts. Sound confusing? No need to worry - there are multiple examples pre-built in Emulsify. Let's take a look at one below.
Below is a simple but common user experience - the accordion. Let's look at the markup for a single FAQ accordion item component:
<dt class="accordion-item__term">What is Emulsify?</dt>
<dd class="accordion-item__def">A Pattern Lab prototyping tool and Drupal 8 base theme.</dd>
If you look in the components/_patterns/02-molecules/accordion-item directory, you'll find this Twig file as well as the CSS and Javascript files that provide the default styling and open/close functionality respectively. (You'll also see a YAML file, which is used to provide data for the component in Pattern Lab.).
But an accordion typically has multiple items and HTML definitions should have a <dl> wrapper, right? Let's take a look at the emulsify/components/_patterns/03-organisms/accordion/accordion.twig markup:
<dl class="accordion-item">
{% for listItem in listItems.four %}
{% include "@molecules/accordion-item/accordion-item.twig"
with {
"accordion_item": listItem.headline.short,
"accordion_def": listItem.excerpt.long
}
%}
{% endfor %}
</dl>
Here you can see the only HTML added is the dl wrapper. Inside of that, we have a Twig for loop that will loop through our list items and for each one include our single accordion item component above. The rest of the component syntax is Pattern Lab specific (e.g., listItems, headline.short, excerpt.long). Pattern Lab provides some helpful default data syntax. For example, {% for listItem in listItems.four %} is a special syntax you can use in Pattern Lab to quickly stub out list data.
If you are following along in your own local Emulsify installation, you can view this accordion in action inside your Pattern Lab installation. With this example, we've introduced not only the basics of component-based theming, but we've also seen an example of inheriting templates using the Twig include function. Using this example as well as the other pre-built components in Emulsify, we have what we need to start prototyping! In the next article, we'll dive into how to implement Emulsify as a Drupal 8 theme and start building a component-based Drupal 8 project.