Want to learn more about Paragraphs? Then check out our online video course called “Build Edge-to-edge Sites using Paragraphs in Drupal 8“.
Over the last couple of years edge-to-edge, or fluid looking websites, have become popular. You just have to look at a few digital agency websites and you’ll notice the common pattern.
With this design, the page is broken out into separate components. A component could be something as simple as a single text field, or something complex like an image gallery. You may also see scrolling animation on these components. As a user scrolls the text could zoom in from the right and an image could fade in from the left.
How would you build this type of website in Drupal?
Let me introduce you to Paragraphs.
The module allows you to build Paragraph types which an editor can then add to a page using a Paragraph field.
On a decent size website, you could have a few paragraph types: one for entering in text and another to display content in a grid, or another which displays a video.
In this tutorial, you’ll learn the basics of Paragraphs and we’ll setup a simple paragraph type for adding basic text.
In future tutorials, we’ll look at using Paragraphs to manage a dynamic sidebar and how to create an image gallery.
We have a lot to do, so let’s jump right in.
$ drush dl paragraphs entity_reference_revisions $ drush en paragraphs
$ drupal module:download paragraphs 8.x-1.0-rc4 $ drupal module:download entity_reference_revisions 8.x-1.0-rc4 $ drupal module:install paragraphs
Creating Paragraph Type
When creating a paragraph-powered website the first thing you need to do is look at the designs and look out for common patterns.
For example, there may be a need to display an image and text side-by-side in a grid, or testimonials may need to be displayed. These two examples are perfect candidates for their own paragraph type.
For this tutorial, we’ll create a basic Content paragraph type which’ll have just two fields: Title (text field) and Content (textarea).
1. On the navigation bar click on Structure and “Paragraphs types”.
From this page you can create new paragraph types and you’ll be able to manage existing ones. Currently, there are none, so you can’t see any.
2. Click on “Add a Paragraphs type”.
3. Enter Content into the Label and make sure the machine name is
content. Then click on Save.
4. Now you should be back on the “Paragraphs types” page and you should see the new Content paragraph type which we just created.
If you click on the Edit button down arrow, in the Operations column, you should see a bunch of options such as “Manage fields” and “Manage displays”.
If you know how to add fields to content types or other entities than this should look familiar. Managing fields on a paragraph type is the same as on content types and other entities.
Adding Fields to Paragraph Type
I mentioned earlier that the Content paragraph type will have two fields: Title and Content. Let’s now create those fields.
1. From the Edit drop-down click on “Manage fields”.
2. Click on “Add field”, select “Text (plain)” from the “Add a new field” drop-down and enter in Title into the Label field.
Then click on “Save and continue”.
3. Leave the next page, “Field settings” as is and click on “Save field settings”.
4. Leave the Edit page as is as well and click on “Save settings”.
5. Now, let’s create the Content field. Click on “Add field”, select “Text (formatted, long)” from the “Add a new field” drop-down and enter in Content into the Label field.
Then click on “Save and continue”.
6. Same as when creating the Title field, leave the “Field settings” and Edit page as is and simply create the field.
Once the field has been created you should see both of them on the “Manage fields” page.
Manage Field Widgets
The astute learner among us may notice that we haven’t configured any widgets yet. We’ve created the fields but we haven’t modified the widgets.
In Drupal 8, the field type and field widgets have been separated between two pages. On the “Manage fields” you simply create the field. On the “Manage form display” you get to configure the field widget.
I talk about “Form displays” in the “Build a Blog in Drupal 8: Content types and Fields” tutorial. I won’t repeat it here so if you want to learn more about it go to the tutorial.
1. Click on “Manage form display” and you should see the two fields we created. The Title widget should be Textfield and for Content it should be “Text area (multiple rows)”. If you like, you can reorder the widgets and configure their settings by clicking on the cogwheel.
Once you’ve configured the widgets make sure you click on Save at the bottom of the page.
Manage Field Display
Let’s now configure how the paragraph will be displayed. We do this via the “Manage display” page. If you’ve used Drupal 7 then you should be familiar with this page.
1. Click on the “Manage display” tab.
2. The only thing we’ll do is hide the labels. From the Label drop-down select
- Hidden - for both fields then click Save.
At this point we’ve completed the following:
- Created a paragraph type.
- Added custom fields to paragraph type.
- Configured widgets and formatters on fields.
Add Paragraph Field
When building a paragraph-powered site, you need to setup two things. First, you need to create some paragraph types, which we’ve already done. Second, you need to add a Paragraph field to a content type.
Now let’s add a Paragraph field to the Article content type and start building paragraphs.
1. On the navigation bar click on Structure and “Content types”.
2. Click on “Manage fields” on the Article row. Then click on “Add field”.
3. Select Paragraphs from the “Add a new field” drop-down. Enter in Paragraphs into the Label field. Then click on “Save and continue”.
4. Leave the “Field settings” as is and click on “Save field settings”.
5. We’ll also leave the “Edit” as default and click on “Save settings”.
Configure Field Widget
With the field created let’s now configure the widget.
1. Click on the “Manage form display” tab.
2. Drag the Paragraphs field so it sits below the Body field. Then click on Save.
The widget settings for a paragraph field let’s you configure a few things. Let’s take a look at the options. Click on the cogwheel on the field row.
Paragraph Title and Plural Paragraph Title
This allows you to change the label on the field. Often the word “Paragraph” could confuse users. So you could change the terminology to “Module” or “Component”.
Edit modes allow you to control how the paragraph will be displayed on the node edit form.
When using the Open edit mode, the fields on the paragraph type are editable. This is great because you can edit the field easily. However, once you have more than a few paragraph items it can be difficult to reorder them if they’re all opened.
The Closed edit mode collapses all paragraph items. This makes it easy to reorder them. But to modify the paragraph you must first click the Edit button which can be a pain if you’re trying to find a particular paragraph.
The Preview edit mode, similar to the Closed mode, collapses the paragraph item. But the edit mode renders the collapsed paragraph item using a custom view mode called Preview. You can configure how the preview will be displayed by modifying the Preview view mode.
The Add mode option lets you configure how new paragraph items will be selected.
You have the three following options. They’re pretty self-explanatory once you see them.
Form display mode
The Form display mode option lets you select a different form display mode. This is something new in Drupal 8. Form display modes are similar to view modes but they let you control field widgets instead of formatters.
On most websites you’ll leave this as default.
Once you’ve finished configuring the widget settings, click on Update, then Save at the bottom of the page.
Configure Field Formatter
The final bit of configuration we need to do is reorder the field formatter.
1. Click on the “Manage display” tab.
2. Reorder the Paragraph field so it sits under Body and select the Label to
- Hidden -.
Scroll to the bottom and click on Save.
We’ve finally configured everything. Let’s now go and create an Article with a Paragraph.
Create Article with Paragraphs.
1. Go to Content, “Add content” and click on Article.
2. Enter “Test article” in the Title and scroll down to the Paragraphs field.
3. Click on the “Add Content” and enter in “Paragraph title” in the Title field and “Paragraph content.” into Content.
4. Scroll to the bottom and click on “Save and publish”.
You should see the paragraph being displayed after the Body field.
When building a paragraph-powered website, you must visualize the content as reusable components instead of creating custom fields on content types.
In the next tutorial, we’ll use Display Suite and add sidebar paragraphs to the Article content type.