Exercise 1

Building the Heading pattern

The first exercise of this training consist of building a basic heading pattern. The pattern is a single field pattern and will be used to print the hero title in our final product.

We will build the Heading pattern using the file structure in the previous chapter.

Heading Data

Let's start by building the data that will populate the Heading pattern. This data is provided in .yml format.

Inside src/components/ create a new folder called heading
Inside the heading folder, create a new file called heading.ui_patterns.yml
Copy the snippet below inside heading.ui_patterns.yml (indentation is important)

heading:
  label: Heading
  description: Basic heading pattern
  fields:
    title:
      type: text
      label: Heading
      description: Title field for heading pattern
      preview: The Beautiful Scape

Let's take a moment to describe each of the pieces involved in the snippet above for better understanding.

heading: This is the pattern name and ID. This is required.

label: Normally the name of the pattern for pattern overview purposes. This is required.

description: A description for the pattern. Optional.

fields: Hash defining of the pattern fields. Each field must have the following properties defined below.

type: Field type, can be text, numeric, etc. at the moment only used for documentation purposes.

label: Field label, used on pattern overview page.

description: Field description, used on pattern overview page.

preview: Preview content, used on pattern overview page. It can be either a string or a Drupal render array, in which case we can use keys like type: processed_textor theme: image.

NOTE: Depending on the field type, their properties will vary.

Heading Markup

Now that the data source for the heading pattern is ready, we can create the markup which will print the heading to the screen. The markup for a pattern is written in combination of HTML and Twig. This makes creating patterns extremely efficient and powerful as twig offers so many advantages over plain html.

Inside the heading directory create a new file called pattern-heading.html.twig
Paste the snippet below into the new file

<h1 class="heading">{{ title }}</h1>

From the markup example above, we are passing the title field from the .yml file as a twig variable ( ), then we are wrapping the title variable in a h1 tag.

Heading Styles

It is recommended to create each pattern's styles as individual stylesheets so we can ensure the styles only address the target pattern. This can save from styles leaking or regressions.

Inside the heading folder create a new file called heading.css
Copy the snippet below into the new file

heading.css

.heading {
  font-size: 2.5rem;
  font-weight: bold;
  line-height: 1;
  margin: 0 0 12px;
}

@media screen and (min-width: 768px) {

  .heading {
    font-size: 4rem;
    margin: 0 0 20px;
  }
}

Drupal Libraries

Currently if we were to use the heading pattern in Drupal, the pattern would not look styled because Drupal would not know where to get the styles from. To solve this, we need to create a new library and then attach that library to the pattern. The library will include any css and/or javascript the pattern needs.

In Drupal 8, the recommended way for adding CSS and Javascript to a page or a pattern is by using Libraries. Typically you would create your pattern's libraries inside theme-name.libraries.yml, however, UI Patterns offers a great way to declare your pattern's libraries directly in the pattern itself. This makes your patterns more flexible and portable because every time a pattern is called, its library automatically comes with it.

Open the heading.ui_patterns.yml file and override its content with the code snippet below.

heading:
  label: Heading
  description: A simple heading pattern
  fields:
    title:
      type: text
      label: Title field
      description: Title field for heading pattern
      preview: The Beautiful Scape
  libraries:
    - heading:
        css:
          component:
            heading.css: {}

Notice the new section libraries?

Here we are declaring a new Drupal library called heading in which we are adding the heading.css file we created earlier.

If we needed to create additional libraries for this pattern, we could do so by adding another section at the same level as - heading: and repeat the process of adding css or js based on our needs.

Attaching the library

If the heading library had been created inside theme-name.libraries.yml, we would have had to attach that library to our pattern's twig file for the styles and javascript (if any), to be inherited by the pattern. However, since we declared the library in the component's .yml file, the library is automatically attached to the pattern.

Previewing your patterns

UI Patterns provides a patterns preview page where you can take a look at your patterns as you build them. This is the equivalent of a styleguide.

Before previewing your patterns, you need to clear your site's cache
On your site, navigate to /patterns
You will see a menu that includes all the patterns you have built. Each pattern shows the metadata we added to the pattern's .yml file.
To view a pattern on its own for proper testing and preview, you can click the link just below the pattern and you will be directed to a separate page where you will only see that pattern.

Build the Heading pattern