The Drupal Paragraphs is a very popular module for handling content in Drupal 8. Paragraphs work in a similar way to content fields, but also provides a wide range of options for the design, layout and grouping of your content. This article provides a detailed guide on the use of Paragraphs and following it diligently, you will be able to use Paragraphs for all your Drpal sites.
You may also want to read:
Drupal Website Maintenance tutorial
Drupal Website Security Tutorial
How to Speed Up Your Drupal Website
Why use the Drupal Paragraphs module?
Paragraph Types can be anything from a simple text block or image to a complex and configurable slideshow.
Instead of putting all their content in one WYSIWYG body field, end-users can choose on-the-fly between pre-defined Paragraph Types. You can create multiple advanced features and end-users can choose which one they want to use.
This makes it much easier for users to add advanced content. For example, users might understand how to add a pull quote into a content body, but it might not end up centered or formatted quite correctly. They may also want to do something more complex such as include an call-out box inside an article, but have no idea how to add the required styles.
The Drupal Paragraphs module can make processes like these much more manageable for non-technical users while also giving developers the ability to control the formatting and appearance of such specially formatted elements at the theme level.
Paragraphs allows users to insert elements much like content fields, but instead of adding these around the body of any given piece of content, they are effectually inserted throughout the body.
For this guide, we’ll imagine we are creating a website called “test,” which offers informational content in the form of articles. You can follow along on any other development website if you wish, making minor adjustments as necessary.
You will also want to read:
Drupal Website Maintenance tutorial
Drupal Website Security Tutorial
How to Speed Up Your Drupal Website
How to address "failed Drupal Clean url Test"
Installing the Drupal Paragraphs Module
We recommend using a blank Drupal 8 test site for this project.
Click here to download the Paragaphs module.
Paragraphs also requires the Entity Reference Revisions module.
Once you have downloaded these two modules and placed them in your /modules directory, install them for your site.
Creating Your First Paragraphs
Paragraphs works by allowing us to create what are called “Paragraphs types”. It will collectively replace the Body field of any given content type with which we want to use these Paragraphs types.
In order to begin taking advantage of Paragraphs, you must first create at least one Paragraphs type, and then you have to add that Paragraphs type to a content type. This process can seem confusing at first, but it is easy to become familiar with once you set up one or two Paragraphs types.
In our case we’ll replace the Body field of the default Article content type with a handful of Paragraphs types.
Important: If you are testing this on a site that already has content of type Article, do not delete the Article content type’s Body field as we are about to do in this demonstration. If you do, you will lose the body of all Articles on your website. If you are working on a site in which the Article content type has already been used, you should create a new content type on which to test out the Paragraphs module.
On our "test" site, we will begin configuring Paragraphs by editing the Article content type.
Go to Structure > Content types.
Click the “Manage fields” button in the Article row.
You will now be on the “Manage fields” page for the Article content type. On this page, click the dropdown arrow next to the “Edit” button on the Body row, and click Delete.
Confirm deletion on the next page.
delete row for use with the Drupal Paragaphs Module
Now we will create our first Paragraphs type.
Navigate to Structure > Paragraphs types.
Click “Add paragraphs type.”
On the next page, we need to provide a label for this paragraphs type. For our test case, we’ll call this one “Body text,” since we are going to use it as the body of our content.
Click “Save and manage fields.”
On this “Manage fields” page, click “Add field.”
In the following “Add a new field” dropdown list, scroll down, and under “Text,” select “Text (formatted, long, with summary)”. This is similar to the default Body field that the Article content type often uses—a long-form text area with a WYSIWYG editor.
On the following “Add field” page, we’ll label this particular field “Body text” as well.
Click “Save and continue.”
Next we are taken to this field’s “Field settings” tab. For any of these fields, we may specify an allowed number of values. It can be useful to allow more than 1 value for some fields—particularly those that accept individual discreet pieces of information, such as dates, image files, or short-form text fields for information such as names—but for long-form text areas, it is often unnecessary to provide additional values since paragraphs can simply be placed one after the other in a single text area. Leave the default settings at “Limited” and 1.
Click “Save field settings.”
On the following “Body text settings for Body text” page, we can keep all of the defaults. Notice that users will still have all of the formatting options that they normally would with the text area’s WYSIWYG editor. We are not taking anything away from them. What we’ll be doing instead is giving them an additional, improved method of adding certain types of elements to their content.
Click “Save settings.”
You'll now see your new fields inside your new Paragraph Type:
On this next page, click the “Manage display” tab.
Currently this Paragraphs type has only one field—the Body text field. We don’t want a label to appear along with the text from this field, so select “Hidden” under the Label column for this field. Format should stay as Default.
Click “Save.”
Now we need to add this Paragraphs type to the Article content type in order for that content type to be able to use it. Here's how we do that:
Navigate to Structure > Content types.
Click “Manage fields” for the Article content type.
Click “Add field.”
To use our new Paragraphs type with this field, open the “Select a field type” dropdown list and select “Paragraph” under “Reference revisions.”
After selecting “Paragraph,” provide the label “Body” because this is what we are using as the body of our content.
Click “Save and continue.”
On the next page, “Type of item to reference” should be set to “Paragraph".
“Allowed number of values should be “Unlimited.” By selecting “Unlimited,” we can insert this special field provided by our configured Paragraphs types as many times as we want. This will become helpful when we begin inserting other things besides text into the body of the content.
Click “Save field settings.”
On the following “Body text settings for Article” page, we need to make our previously created Paragraphs type available to this field. To do this, check the box next to “Body text” under “Type,” near the bottom of the page. This is how to make that particular Paragraphs type available in this field. You can add more Paragraphs types to your site, we can come back and make those available to this field as well.
Click “Save settings,” and the site should take you back to the “Manage fields” page for the content type.
Now we’ve finished replacing the previous (default) Body field with our new Body field, which utilizes Paragraphs, and specifically the “Body text” Paragraphs type that we created. Now we’ll configure a few more settings so that it appears the way we want.
To start, we’ll click the “Manage form display” tab so that we can place the new Body field in a prominent location on the content creation page for Articles.
On this page, scroll down to find our new Body field, and drag it near the top of the list, just below Title.
Click “Save.”
Now you need to make sure the new Paragraph Type is available in the proper place for site visitors.
Click "Manage form display".
Again you’ll find Body at the bottom. Drag this near the top, just below Image. We’ll treat that image field as a large sort of introductory or lead-in image for our Articles and not part of the content itself.
Click “Save.”
Drupal Paragraphs Module field
At this point, we have completed the setup for our Article content type using this new Paragraphs field. Now it’s time to create some content to test it out.
Go to your site’s Content page, and click “Add content".
Click "Article".
You can enter any title for your article. For this example, let’s call our article “How to Make 100 Friends”.
Now, down to the Body field, you may have noticed that it looks slightly different, though it still uses the same long-form field with a WYSIWYG editor just like before. The difference now is that we have an encompassing Body field that currently contains one Body text field. Just below the Body text field, you should see an “Add Body text” button, which allows us to add multiple fields. At this point, that would be unnecessary because the long text field currently in use is perfectly suited for inputting long, multi-paragraph text, so we wouldn’t need to add an additional field when we could just add more text in the same field. Later, though, we’ll see that it becomes very useful to be able to add additional Paragraphs fields when you have implemented multiple Paragraphs types on your site. For now, just enter a paragraph or two of text into your Body text field.
Save your article and view the page as any visitor would see it.
At this point, the new Body using Paragraphs looks no different from an article using the default Body field. With Paragraphs in place, though, we will soon be able to allow our content creators to add additional elements to the content without having to know how to style it properly.
You will also want to read:
Installing a new Drupal website
A Basic Guide to Drupal Website Management
How to address "failed Drupal Clean url Test"
Installing a new Drupal website
Adding Your CSS to Paragraphs
A big part of what makes Paragraphs so useful is that we can write CSS for specific in-content elements so that content creators don’t have to try manually styling as many of these elements themselves using the WYSIWYG editor or inline CSS. This means we’ll be customizing our site’s theme to make these elements appear exactly as we want.
In many cases, you’ll likely be working with a custom theme or subtheme of your own, in which case you may edit it freely. For this tutorial, you can choose to create a quick and easy subtheme of the default Bartik theme so that we can follow best practices and add our own CSS without editing the Bartik them itself. (We avoid editing Bartik—or any other core or contributed theme—directly because if we do so and then later apply a released update to that theme, our own modifications will be lost.) If you are unfamiliar with creating subthemes, that’s ok. We recommend instead that you create a direct copy of the theme, to which we will then apply some slight alterations. This is an easy process.
To create a subtheme, you first need to access the server on which your site is hosted, and navigate to your site’s root directory.
Once there, open the “themes” directory. This is where all custom and contributed themes and subthemes are placed. In this “themes” directory, create a new folder called “custombartik,” and navigate into this new directory.
Now we need to add a couple files to this new directory. The first will be the theme’s info file. Open up whatever code editing software you use for web development. These info files require several pieces of information: the name of the project (the name of our theme), the type of project (“theme” in this case), the machine name of the base theme if this is a subtheme (as ours is), a short description, and the major version of Drupal (7.x, 8.x, etc.) for which the theme is built. We will enter this information in the following form (type everything exactly as you see it):
name: Custom Bartik
type: theme
base theme: bartik
description: A custom theme based on the core Bartik theme
core: 8.x
Make sure the base theme name “bartik” remains un-capitalized—it is the case-sensitive machine-readable name that we need. With this information entered, save the file as “custombartik.info.yml”. It is important that you save it with exactly the same name as the folder you created followed by “.info.yml”.
Now we need to create our theme’s libraries file, where we will tell Drupal where to find the theme’s CSS and what version of the theme this is. More information can be provided, but this is all we need for our purposes.
Open a new file. In this file, pay close attention to the indentations here. Each indentation should be a two-space tab.
Enter the following information exactly as it appears:
global-css:
version: 0.1
css:
theme:
css/style.css: {}
Save this file as “custombartik.libraries.yml”. This file essentially tells the website that this is version 0.1 of the theme (we could have given this any version number) and that there will be a stylesheet located inside our theme directory (“custombartik”) at css/style.css.
Now we need to go back to our info file to tell Drupal to use the information under the “global-css” container to find our stylesheet.
Open your custombartik.info.yml file, add a blank line under your “core: 8.x” line, and then add the following line of information, again keeping the indentation exactly as it appears below:
libraries:
- custombartik/global-css
The whole file should now look like this:
name: Custom Bartik
type: theme
base theme: bartik
description: A custom theme based on the core Bartik theme.
core: 8.x
libraries:
- custombartik/global-css
At this point, we are ready to add these two files to our theme.
Upload or copy your custombartik.info.yml and custombartik.libraries.yml files into your custombartik folder.
Now add a folder called “css” inside your custombartik folder.
Go ahead and create a blank file called “style.css” and upload it to this directory. This will be our stylesheet.
Before we create our stylesheet, however, navigate to your website’s “Appearance” page.
Scroll to the bottom of the page, and under the “Uninstalled theme” section, you should see your Custom Bartik theme. If you do not see it, make sure that your custombartik folder and all of its files are present in the themes folder of your site’s file system.
Click “Install and set as default” under your custom theme so that your site will begin using your theme.
Once this is done, navigate to your homepage, and it should look almost exactly like Drupal’s default Bartik theme, with the exception that you will probably see a broken image icon in place of the Drupal logo. The theme looks just like Bartik because what we have created is a subtheme of Bartik with no customization yet in place. If your site does not look like Bartik, and especially if it looks like plain HTML with no CSS styling, go back to your two .yml files and make sure they look exactly as printed above.
Finally, to fix the broken logo image, we’ll copy the logo straight from Bartik into our subtheme. This is OK because we aren’t actually changing anything in Bartik.
Navigate to your site’s root directory, and go to core/themes/bartik. In here, you’ll see a file called “logo.svg”.
Copy this file into your subtheme (the “custombartik” directory).
On your website, navigate to Configuration > Performance, and click “Clear all caches.” Now the logo should appear on your site.
Styling Your Paragaphs Fields
Now that we have a subtheme that we can safely edit, we can begin setting styling rules for the elements of our content controlled by Paragraphs. Before we do so, we should create a new Paragraphs type that requires special styling rules. We’ll follow our example of having a field that inserts a centered image in the midst of an article.
Navigate to Structure > Paragraphs types.
Click “Add paragraphs type.”
We’ll set the label for this one as “Centered image.”
Click “Save and manage fields.”
On the next page, click “Add field,” and select “Image” under “Add a new field.”
We’ll label this field “Centered image” as well.
Click “Save and continue.”
On the next page, we can retain all default values, so click “Save field settings.”
Then, on the “Centered image settings for Centered image” page, we’ll add a few simple restrictions. Set the Maximum image resolution to 650x450 and the minimum resolution to 50x50. Set the maximum upload size to 1 MB, and click “Save settings.” These specific settings are not necessary for the Paragraphs type to work properly; we are including them simply to mimic a real-world scenario.
Drupal paragraphs centered images
Now click on the “Manage display” tab, set the Centered image label as “Hidden,” and click “Save.”
At this point, we need to add this Paragraphs type to the Paragraphs field we have in our Article content type.
Go to Structure > Content types.
Click “Manage fields” next to “Article.”
You may be tempted to click “Add field” here for our new “Centered image” Paragraphs type, but remember, this is going to be intermingled with our custom Body field. So, instead, we will add Centered image to the Body field we created.
Click “Edit” next to “Body,” and scroll to the bottom of the page.
Here you’ll see “Centered image” available beneath our “Body text” Paragraphs type.
Check the box next to “Centered image” to make it available to this field, and save your settings.
Now we’ll add an image using this field.
Navigate to your Content page, and edit your “How to Make 100 Friends” article.
Let’s imagine we want to add a centered image somewhere in the middle of our article. Beneath the Body text field, you’ll again see the “Add Body text” button to add another Body text field within this Body field. However, if you click the dropdown arrow next to this button, you’ll see that “Centered image” is now also available. Click this button, and choose some image file to upload here. Then provide some alternative text, since that is required.
Now we’ve added the image to our content, but currently it is placed below all of the text. This is where we will make use of an additional Body text field.
Click “Add Body text.” Now we have, top-to-bottom, a field of body text, a centered image, and another field of Body text. Note that, though you shouldn’t need to do so at this point, you can freely move these around via the drag-and-drop arrows on the top left of the individual Paragraphs fields. To have the centered image appear sandwiched between article text, simply go to the first Body text field, select whatever text you would like to appear after the image, and cut that text from the field. Then scroll down and paste that cut text into the second Body text field (after your image).
Click “Save.”
When you view your article now, it will still not look quite correct. Since we have not yet added any styling rules to our theme, the image is likely to be floated left (as it is by default), rather than centered. However, it should appear after the text of the first Body text field and before the text of the second Body text field. Now we have an article on which we can test some custom styling rules.
Controlling Paragraphs with CSS
We’ll go to our custom subtheme now to begin styling the output of the Paragraphs fields we’ve created. For now, we’ll target the “Centered image” field specifically, rather than the encompassing Paragraphs field from the content type. We’re doing this because we will want this field to be centered anytime, regardless of where it is. Thus, by setting rules directly for “Centered image,” we avoid setting unnecessary multiple rules for multiple contexts.
We do need to target the “node” class, however, because there will be, by default, some styling for this field targeted under the “node” class. Thus, we have to override those rules.
Open your “custombartik” subtheme’s stylesheet at custombartik/css/style.css.
The file should still be empty, but now we will begin adding rules to it. We’ll keep things simple for now. Add the following lines of code to your stylesheet:
.node .field--name-field-centered-image {
float: none;
text-align: center;
}
.node .field--name-field-centered-image img {
max-width: 100%;
max-height: 450px;
}
With the first set of rules, we are simply centering the image horizontally within its field class and making sure no text or anything else floats next to it. The second set of rules is not strictly necessary, but is some common code to make sure images don’t end up larger than they should be in relation to the content area.
Once you’ve added this to your style.css file, save your changes (from here forward, any reference to saving changes in your subtheme also assumes uploading or otherwise copying the files to your server if you are not editing directly on the server on which your test site is located).
Then on your site, navigate to Configuration > Performance, and click “Clear all caches” to load the theme changes on your site.
Navigate back to the article on which you added the image to be centered (or refresh the page if you already have it open).
The image placed through the “Centered image” Paragraphs type should now be centered with no text floated to either side of it. There may be further styling we’d like to add, but for the purpose of this tutorial, we’ve done what we want to do at this time—make sure that the output of this field is strictly controlled by CSS so that users adding content do not have to style anything themselves using the WYSIWYG editor or other inline styling methods.
Paragraphs With Multiple Fields
We can also create Paragraphs types that themselves consist of multiple fields.
For example, instead of a “Centered image” type, we can create a “Centered image with caption” type, which would consist of an image upload field and an accompanying text field for any single element of that type. This, too, helps us remove the burden of layout from those adding content to the site so that we can control content display at the theme level.
Let’s create this “Centered image with caption” type to practice the process of creating a multi-field Paragraphs type. As you might expect, this process is going to be similar to that of creating a single-field type.
Navigate to Structure > Paragraphs types, and click “Add paragraphs type.”
Label this type “Centered image with caption,” and click “Save and manage fields.”
Click “Add field.”
Since our previously created “Centered image” field is exactly what we want for the image portion of our new Paragraphs type, instead of creating a new field, we can reuse the previous one. So, do not select anything under “Add a new field” on the “Add field” page.
Under “Re-use an existing field,” select “Image: field_centered_image”.
Keep the “Centered image” label, and click “Save and continue.”
We do need to configure our settings for the image’s size bounds on the next page. Let’s once again enter a maximum image resolution of 650x450 pixels, and a minimum of 50x50 pixels. Set the maximum upload size to 1 MB.
Click “Save settings.”
Now we’ll add another field. Keep in mind we are still inside the settings for our new Paragraphs type, so once we add this second field, “Centered image with caption” will be one type with two fields.
Click “Add field,” and add a new field of type “Text (plain)”.
Label this field “Caption".
Click “Save and continue.”
Some longer captions might need to exceed the default 255-character limit, so change the maximum length for this field to 500. Keep the allowed number of values at “Limited” and 1, and save the settings.
The following caption settings defaults are all fine, so save the settings on that page as well.
Now our new Paragraphs type has all of the fields it needs, so let's control the display.
Click the “Manage display” tab so that we can remove the field labels, which are unnecessary in this case.
Select “Hidden” under the “Label” column for both fields, and click “Save.”
If the two fields were out of order, we would rearrange them so that the caption field comes after the image field, but since we added the caption field last, it should already be positioned after the image field, just as we want it to be.
Now we’ll add the new type to our Article content type.
Navigate to Structure > Content types, and click “Manage fields” for Article. As was the case when we added our first “Centered image” Paragraphs type to the content type, we will add this new Paragraphs type within our custom Body field rather than adding a new field altogether.
On the “Manage fields” page for Article, click “Edit” for Body.
Scroll to the bottom of the page, and check the box next to “Centered image with caption” to make that type available within this Body field.
Click “Save settings.”
Now this new Paragraphs type will be available for those who are adding Articles to the site.
Let’s go ahead and create a new article using this field, and then we’ll add our styling to control its display.
Navigate to the Content page, click “Add content,” and click “Article.”
Let’s call this article “Learning to Play an Instrument May Improve Your Life.”
Click “Add Body text” to begin adding some text to the article. Enter a paragraph or two of text into this field.
Then, below the Body text field, click the dropdown arrow next to “Add Body text,” and select the newly available “Add Centered image with caption” option. Notice that we are now presented with two fields for data input, as we should expect—the “Centered image” and “Caption” fields that belong to this Paragraphs type.
Upload any image into the image field and provide some alternative text.
Then type, “The Les Paul is one of the most legendary guitars in rock and roll.”
Now we’ll add some of the rest of the article’s text after the image and caption.
Beneath the image and caption Paragraphs type, click “Add Body text” once again.
Add another paragraph or two of text.
Finally, click “Save and publish.”
Currently, the display of our “Centered image and caption” should be half correct. Since we reused the previous “Centered image” field, the image itself should already be centered just as it was for the previous field that consisted solely of an image to be centered. The caption text, of course, does not have any CSS rules yet, so it will appear left-aligned and look just liken the text of the rest of the article. So, we need to add some rules to our theme to style this caption text.
multiple field drupal paragraphs
This time, when writing our CSS, we will target the entire “Centered image with caption” Paragraphs type and then drill down to the caption field within that class, rather than targeting the caption text independent of its container, as we previously did with the centered image. We’ll take this approach because we might want to reuse this caption text field elsewhere, and it is likely that in some cases we will want it styled differently (such as being aligned left or right rather than centered) from how it is in this particular Paragraphs type.
We’ll center our caption text because its corresponding image is centered, and to provide a visual differentiation between this text and the text of the article, we’ll make it bold (italics would also provide that effect).
Add the following lines of code to your stylesheet, and save your changes:
{codecitation}.paragraph--type--centered-image-with-caption .field--name-field-caption { font-weight: bold; text-align: center; }{codecitation}
Then, to see our changes on the site, navigate to Configuration > Performance, and clear all caches.
Go back and refresh the recently created article, and you should see the new styling rules in effect. The caption text should now be bold and centered below the image.
We can of course apply some styling to this Paragraphs type as a whole. One reason to do this would be to separate the image/caption element from the surrounding text and to make it visually clear that it should be viewed as a single unit.
Add the following code to your stylesheet, and save your changes:
{codecitation}.paragraph--type--centered-image-with-caption { border: 2px gray solid; margin: 4px 0; padding: 4px; }
Now clear your site’s cache once again, and refresh the article page. The image and caption should look mostly the same; however, now the entire image/caption unit is surrounded by a gray border and has small margins around the top and bottom. We could do more to improve the aesthetics here (and the border is likely not necessary), but this demonstrates our ability to provide styling for individual components of Paragraphs types as well as Paragraphs types as a whole.
multiple field drupal paragraphs with css
Now if a non-technical user is adding content to the site and wants to include a large, centered image with a caption, all they have to do is select this Paragraphs field while editing the article, upload an image, and enter the text into the caption field. The formatting will be automatically applied.
Using Entire Nodes in Paragraphs
At this point, we’ve seen some examples of the basic uses of Paragraphs. Now we’ll tackle a slightly more advanced example: using Paragraphs to place an entire node inside the body of a piece of content. One use case for this would be to place a related but standalone piece of supplementary information inside one of your articles (similar to something like a “Did You Know?” section that you might see accompanying a magazine article).
For our example, we’ll imagine we want to have the option to add what we’ll call “Info boxes” to our articles, and we’ll do so by placing a short piece of content entitled “A Short History of the Harp” within our previously created article about learning to play an instrument.
First, we need to create a content type for these “info boxes.”
Navigate to Structure > Content types, and click “Add content type.”
We’ll give this content type the name “Info box.”
For the description, write “Short pieces of information used to supplement articles.”
Click the “Display settings” tab, and uncheck “Display author and date information” because we don’t want author and date information showing up within our Info box content.
All of the rest of the default settings on this page should be fine. Click “Save and manage fields.”
On the “Manage fields” page, we already have a basic long-form “Body” field, and this is all we want for this content type, since all pieces of content of this type should be short and simple. No changes are therefore necessary here. Click “Add field.”
Now that our content type has been created, we need to create the Paragraphs type that will reference it.
Navigate to Structure > Paragraphs types, and click “Add paragraphs type.”
Give this type the label “Info box.”
On the “Manage fields” page, click “Add field".
Beneath “Add a new field,” select “Content,” found under the “Reference” header.
For the label, write “Info box,” and save.
All defaults are fine on the next page, so click “Save field settings” there.
On the next settings page, scroll down until you see the “Reference type” settings.
Since we want to use this Paragraphs type to reference and display Info box nodes, check the box next to “Info box” beneath the “Content types” header. You can leave “Sort by” set to “None” because the field will autofill based on what we type and is not a list of all content of this type. Click “Save settings.”
Back on the “Manage fields” page, click the “Manage display” tab.
As we’ve been doing so far, we’ll remove the label, so select “Hidden” under the label column for the Info box field.
Then, because we want to display the entire Info box node whenever we choose to include an Info box in one of our articles, we need to select “Rendered entity” in the column labeled “Format.”
Click “Save.”
It’s time to make this Paragraphs type available to our Article content type.
Navigate to Structure > Content types, and click the “Manage fields” button for the Article content type.
As we’ve been doing, click “Edit” for the Body field.
Scroll down and check the box next to “Info box” under the “Paragraph types” header.
Save your settings.
With the structure side of this implementation complete, we’ll now create some content to test it out. We’ll start by adding our site’s first “Info box.”
Navigate to the “Content” page, and click “Add content.”
Choose Info box.
For the title, enter “A Short History of the Harp.”
Enter two or three paragraphs of text into the Body field, and click “Save and publish.”
At this point we will divert briefly from Paragraphs. Currently the home page of our site lists all of our articles and info boxes, but we don’t want the latter to appear on the homepage; we want them only placed within other articles. So, let’s quickly edit the view for our homepage to exclude these pieces of content.
You can either click the “Edit view” icon (which is displayed as a pencil icon) on the top right corner of the view area of the homepage.
Navigate to Structure > Views, and edit the “Frontpage” view.
On the view’s settings page, next to the “Filter criteria” header, click “Add.”
Select “Content type,” and then click “Apply (all displays).”
For the filter criterion, select “Is not one of” under “Operator,” and under “Content types,” check “Info box.” Then click “Apply (all displays).” This, as you probably know, will exclude all content of type “Info box” from the Frontpage view.
Back at the view’s settings page, click “Save.”
Now when you view the homepage of your site, you will no longer see the “A Short History of the Harp” info box.
Now we’ll add our Info box to the “Learning to Play an Instrument” article.
Scroll down to the bottom of the Body Paragraphs field (the larger field encompassing all individual Paragraphs fields).
Click the dropdown arrow next to “Add Body text,” and select “Add Info box.” You can type in any piece of the title of your “A Short History of the Harp” Info box node into the autofill field, and that Info box should then be displayed as an option.
Select it to include that Info box in the body of this article.
adding info box paragraphs
With the Info box now included in our Body, we need to place it where we want it.
Drag and place it after the first Body text field and before the Centered image field.
With this new organization, we should probably have some text between the Info box and the Centered image. To simulate doing this in a real-world scenario, we’ll cut some of our current text and paste it into a new Body text field, as opposed to arbitrarily adding text to the article.
So that we have a field to paste our new text in, go ahead and click the “Add Body text” button beneath all of the Paragraphs fields.
Then scroll to the first Body text field and select and cut one or two paragraphs of text from the field (making sure to leave at least some text in the field).
Paste the cut text into the newly created (currently empty) Body text field.
Once this is done, drag the new Body text field, and place it after the Info box field and before the Centered image field.
Click “Save and keep published”.
Upon viewing the article, you’ll see that the referenced Info box node is displayed in its entirety within the larger article. (If all you see is the title of the Info box node, that means you forgot to select “Rendered entity” in the Format column Paragraph type’s “Manage Display” page.) As it currently is, the lack of styling on the referenced Info box is likely to be confusing to most viewers. We won’t go through the task of applying additional CSS to these Info box references because we already now how to do that, but it is important to note that, in practice, these references should be styled to appear significantly different from the containing article. It should be made extremely clear—through the use of some combination of background color, borders, text size, and font family—that the information contained in the Info box is not part of containing article and is simply supplementary information.
Using Field Layout with Paragraphs
Just as the Field Layout module can be used to control the layout of nodes, it can also be used to control the layout of individual Paragraphs types. In some cases, this can be a viable alternative to controlling the layout via CSS, depending on the situation and on the developer’s (your) preference.
Important: As of this writing, Field Layout is an experimental module. As such, any implementation of Field Layout should be considered a risk. If you do decide to use the module during its experimental phase, it should be tested extremely thoroughly on a development site before being used on a production site. Otherwise, play it safe by considering this information useful for future situations after the module has graduated into non-experimental core.
Because Field Layout is a core module, it does not need to be downloaded.
Begin by navigating to your site’s Extend page.
Select the Field Layout and Layout Discovery (a dependency) modules, and click “Install.”
Then, if prompted, click “Continue.”
Let’s use Field Layout to control the layout of a new Paragraphs type in which we create a two-column unit of “Pros and cons” information.
Navigate to Structure > Paragraphs types, and add a new Paragraphs type.
Give it the label “Pros and cons,” and add a field.
For this field, select “Text (formatted, long),” and give this first field the label “Pros”.
Save and continue, and keep all of the default settings through the next two pages.
You are back at the “Manage fields” page. Add another field with a Text (formatted, long) input type, and label this one “Cons”.
Save, and continue through the subsequent settings pages, once again keeping all default settings.
Once you’re back at the “Manage fields” page, click the “Manage display” tab. This time we will keep the label (positioned above, as is default) for each field so that when visitors are reading them, they know that we are listing pros and cons accordingly.
If we look below the listed fields, we will see a new group of settings called “Layout settings.” This is made available by the Field Layout module. Click to expand these settings.
We have a handful of options here, and for our Pros and cons lists, we’ll select “Two column.”
Then click “Save,” and you’ll be taken back to the “Manage display” page.
Now we have additional layout areas to place our fields in for this Paragraphs type. In total, we have “Top” for the area spanning the width of the content space above our columns, “First” for the left column, “Second” for the right column, “Bottom” for the area spanning the width of our content space below the columns, and “Disabled” for fields we do not want to display.
Drag-and-drop your Pros and Cons fields so that Pros is in the “First” column and Cons is in the “Second” column, and save.
Now, as usual, we need to add the new Paragraphs type to our Article content type.
Navigate to Structure > Content types, and click “Manage fields” for Article.
Edit the Body field, scroll to the bottom of that field’s settings.
Check the box next to “Pros and cons” to add that Paragraphs type to this custom Body field. Then save.
Now we’re ready to begin using this “Pros and cons” Paragraphs type. Let’s use it in a new article.
Create a new article called “Swimming Is a Great Way to Stay in Shape.”
Add two or so paragraphs of Body text to this article.
Click the dropdown arrow next to the “Add Body text” button, and select “Add Pros and cons.” Notice that this Paragraphs type has two long-form text areas to fill in, one labeled “Pros” and the other labeled “Cons.”
Enter text for five or so pros, each separated by a simple line break (in other words, separated by pressing the Enter key). If you’d like, you can alternatively make these 5 bullet points. Do the same in the Cons field.
If you’d like to fill out this article a bit more, you can then add another field of Body text below the Pros and cons field.
Click “Save and publish.”
Viewing the article, you’ll see your comparison of pros and cons listed, with the pros listed in a left-hand column and the cons listed next to them in a right-hand column. You should also see your “Pros” and “Cons” labels above each list.
drupal paragraphs layout
In most cases you would likely want to apply some CSS to these elements via your stylesheet. Again, we won’t take the time do so here because you have seen how that works. Some styling suggestions might be to add a vertical border between the lists of pros and cons (and potentially borders surrounding the entire Paragraphs type) and to make the “Pros” and “Cons” labels more prominent. Additionally, you may consider going back and editing the Pros and cons Paragraphs type to add a title field which can be displayed in the “Top” area above both columns. In this case, such a field might read, “Some Pros and Cons of Swimming for Exercise.”
Permissions for the Paragraphs Module
At this point, we’ve set up all of our Drupal Paragraphs types and integrated them the way we want, aside from some styling we would need to apply to the Info box and Pros and cons types. However, we have not yet configured any permissions pertaining to Paragraphs. This is an important step. Currently, if an anonymous visitor were to view our site, they would not be able to see any of the content entered via Paragraphs types (which is all of the content we have entered in this tutorial) because by default, only administrators have permission to view such content. You can see this for yourself by logging out of the site in its current state and trying to view the content. You will see the titles of articles but none of the body content.
Additionally, we want to have a “Content creator” (or similar) role on the site so that not everyone adding content has full access to all administrative configuration on the site. These users need permission not only to view Paragraphs content but to create, edit, and delete it.
We’ll start by giving everyone permission to view Paragraphs content.
Navigate to your site’s People page, and click on the “Permissions” tab.
Scroll down until you see the “Paragraphs Type Permissions” section. Beneath this header, find “Body text: View content,” and check the boxes for Anonymous User and Authenticated User.
Do the same for the “View content” permission of all the rest of the Paragraphs types we created: Centered image, Centered image with caption, Info box, and Pros and cons.
Click “Save permissions”.
At this point, all users can view all Paragraphs content. Feel free to log out and view the site as an anonymous visitor to confirm.
Now to create a new role for those who will be adding and editing content on our site.
Navigate to People, click the “Roles” tab, and click “Add role.”
Call this role “Content creator.”
Back on the Roles page, click the dropdown arrow next to the Content creator role, and select “Edit permissions.”
There are quite a few permissions we will need to give users of this role. Some of these are unrelated to Paragraphs, but we’re including them anyway to mimic a real-world scenario. Additionally, it will be difficult to test the new role reliably if it does not have all the permissions it would have in practice. Note also that we’re granting these permissions assuming that our content creators are all working in-house. That is, we don’t have large numbers of technically authenticated but still pseudo-anonymous users creating content on our site, so we do feel we can safely grant these users permission to do things like use the Full HTML text format, which in other cases would cause some security concerns.
