How To Create a Paragraph Template within Drupal 8

When designing a Drupal website, it’s not uncommon to see pages that share similar components. From the content creator’s perspective, it might be tedious to reproduce the same layout in a WYSIWYG editor each time a new page has to be made. The process of manually creating something that should be consistent across the website also introduces the chance of human error.

Paragraphs is a Drupal module that allows you to break down any content type into reusable components. It allows us to group relevant data fields into paragraphs and associate an HTML template to it so the content creators do not need to worry about the layout.

Prerequisites

For this tutorial, you will need the following on hand:

1. Drupal Console
2. A fresh Drupal installation
3. Some HTML and CSS know-how
4. Around 1 hour of your time

Breaking down your page into paragraphs

In this tutorial we will create two pages with the following layouts:

Page 1:

Page 2:

Before we start making the actual paragraphs, we need to identify the sections of the pages that can be reused. Those will be made into paragraphs.

In our two-page example, there are three unique components that occasionally appear.

They are:

• The hero image (Hero Image)

• The image pair (Image Pair)

• The image with a text article to its right (Image with text)

Create the paragraphs in your admin panel

As I mentioned earlier, paragraphs are essentially groupings of fields that we can assign a template to. We need to determine which fields belong to each paragraph that we will make.

If you’re not familiar with the concept of fields (documentation here), it is imperative that you spend some time studying them because they play a big role when managing content in Drupal 8.

The hero image is pretty simple. We only need an image field to upload what we want to display. The Image pair consists of two image fields, and the image with a text article consists of an image field and a long text field.

To create a paragraph, log into the admin panel and go to Structure > Paragraph Types.

You will have to repeat the following process for each of the three paragraph types

1. Click Add paragraph type and give it a label. Labels should be self-descriptive because you’ll use them to reference that certain template for the perpetuity of the project. For the hero image, I used “Hero Image” and so forth.
2. Click Save and manage fields to select the fields you want to bundle together in that paragraph. You’ll have to add each field one-by one.
3. First, they ask you the type (similar to data type in other programming languages) and a unique label which we will use later.
4. Second, they ask you the number of values of that field type that paragraph will have. For all of the paragraphs we will make, you need to limit this to one. The way it works is when creating a new paragraph, if a field is set to unlimited, the content creator can add an unlimited number of those fields. I recommend checking it out in your free time.

After making all three paragraphs, we end up with something like this:

The fields I made were as follows:

Hero Image

Image Pair

Image with text fields

Aside: Here’s an excellent tutorial that includes more details about using paragraphs as the admin.

Create the pages using the paragraphs we made

Attaching our new paragraphs to the Basic Page

In order to use your new paragraphs, you have to attach it to a content-type. Since we want to make pages with our paragraphs, we have to attach them to the Basic Page content-type, which was already made for you when you installed Drupal.

To do this, navigate to Structure > Content Types > Basic page in the admin panel and add a field of type Paragraph.

Since you want your user to add paragraphs without any constraints, make sure that the allowed number of values is set to Unlimited. Select Save field settings.

You will be shown a screen that will allow you to set the reference type of the paragraph you have newly created. This allows you to select which paragraphs a content creator can add to the Basic page. In our case, we want our content creators to use all the paragraphs we had just created.

At this point, we are ready to use the paragraphs we had just made. First, let’s tidy up the basic page.

Go to Manage form display and set it up like so:

We are disabling the body tag because we don’t need it in any of our pages (kindly refer to our wire-frames).

Go to Manage Display and disable the Body and Links fields like so:

Creating the actual pages

To create a new page, click Content > Add Content in the admin navigation bar and select Basic Page. Add the paragraphs needed to make page 1 and page 2.

For page 1 it should look something like this:

Regardless of your base theme, when you’re done, your pages will look something like this:

All the elements are stacked on top of each other because the default template that drupal uses simply dumps everything to your screen. To fix this, we need to override the default template.

Note: At this point, it is probably a good idea to activate developers mode to make twig debugging easier.

Creating the HTML templates

It is a good idea to identify which template renders each section on your page. We do this by opening the developer’s console in your browser after activating developers mode.

Look at the “BEGIN OUTPUT from" comment

We can observe a couple things from this snippet:

1. Each paragraph gets rendered in a default template (paragraph.html.twig)
2. Drupal is kind enough to recommend the names we need to use when overriding the default template. The naming conventions used are documented here.

In your theme, make a sub-folder called paragraphs (the name of our module) and within it, a folder called templates. If you do not have a theme yet, read this article about how it works. The easiest way to make a sub-theme is to generate one with Drupal Console! In this example, I made a sub-theme of the bootstrap theme.

The file naming convention for paragraph templates are paragraph — <paragraph label>[…mode].html.twig. I find that replacing the hyphen in the paragraph label portion with an underscore makes it work.

For each paragraph, copy the default template (from modules/contrib/paragraphs/templates/paragraph.html.twig), put it in the templates folder and rename them to their recommended filenames. Our file structure should look like this:

After this, clear your Drupal cache and reload your page. Check your developer’s console to determine which template generates your code. Right now, it should be the new templates you just made.

Aside: It does not actually matter which sub-folder you put your .html.twig files in your theme — as long as they are inside the templates sub-folder. Drupal will always find your templates because it looks for them by name.

Modifying the HTML templates

At this point, you can edit your html templates. You also want to add custom css and js to your sub-theme. Here’s another guide for doing so.

It is obviously important to have access to the data you’ve set up in the admin panel earlier so you can use them. The idea is you are given a content object in the template and you can access the attributes using the machine name of the property you want. If you want to review the properties available to you, go to the admin panel and click manage fields. Here’s the documentation for that.

In this paragraph, you can use {{ content.field_image }} and {{ content.field_image_text }} in your template

I’ve done some crude theme-ing just to get the layout correctly and hid the blocks with css for this example (since we are focused on making templates for the paragraphs module itself). In an actual site, you might want to do this the proper way.

The code

Comparing the end result

Here’s the original side-by-side layout for the pages we wanted to make:

And here’s the side-by side result of our code:

It’s not 100% exact, but you can tweak the css more (or change the image dimensions) to get the layout exactly as you wish.

Next steps

Since a paragraph is just a collection of fields that we can attach to a content type as another field, it makes sense that we can also add a paragraph to a paragraph.

Can you imagine use cases for these?

Conclusion

Once properly implemented in your site, paragraphs will save you and your team countless templating hours in the long term.

I hope that this article helped you realize how a purportedly complex CMS like Drupal can be made simple for content creators and developers alike.