After a vendor recently delivered a site to us built in Panels that I found to be unbelievably confusing to try to work with, I went off searching once again for the Holy Grail of Drupal - a module that can actually make it easy for a non-technical content manager to create and maintain moderately fancy page layouts. Fortunately, I didn't have to look far, as a former co-worker pointed me to a wonderful little diamond in the rough called Paragraphs. This module doesn't look like much at first, but it really has some nice power under the hood once you figure it out. I guess it's just par for the course that a module like this one would have the same steep learning curve as Drupal itself. So, in today's blog post, I'll try to unravel the mysteries of this marvelous module and provide a quick tutorial to get you started.
What Does Paragraphs Do?
Paragraphs is a user-friendly way to create a collection (bundle) of fields and reuse that collection in multiple ways. The power of Paragraphs is that the placement of these bundles can be done by a content manager on a per-page basis, thanks to a custom 'Paragraphs' field type provided by the module. Thus, you don't have to create a different content type for each kind of page layout that you want in your site -- you just create a single content type that allows any number of Paragraphs bundles to be embedded into it, and then your content manager can simply build layouts on the fly as s/he is populating the website with content.
Paragraphs can also be used to enhance custom form content types that gather information from users. As an example, you could configure a form content type to let the user add any number of 'Author' bundle instances to their submission, where each Author instance has fields for the Author's name, contact details, etc.
About the only thing not to like about Paragraphs is that it doesn't come with any pre-defined bundles, so on first installing the module it's hard to tell what it can really do. This is why the first time that I installed it for testing some months ago, I rather quickly abandoned it due to a lack of time to dig in and figure it out.
How Do I Get Started?
Download and install the module and enable it on your Modules page. Once it is active, you should have a new Paragraph Bundles option on the Structure sub-menu of the Admin menu. Go to this option and select Add Paragraph Bundle to get started. I recommend creating a very standard bundle first -- I called mine 'Standard Section', and gave it the following fields:
- Section Title (Text)
- Main Image (Image)
- Section Body (Long text and summary)
If you're using the third-party Link module, then you might also want to add a 'More Information' link field at the bottom. Either way, configure each field to your personal tastes, and don't forget to configure the Display settings for each field as well (you'll likely want to hide the labels, which Drupal defaults to showing for each new field). While you're on the Manage Display tab, it's useful to open up the Custom Display Settings section and uncheck Paragraphs Editor Preview so that this view mode will use the default display settings.
Eventually you'll want to create more bundles, but one is enough to get started and test that everything works properly. The next step is to create a content type that contains a Paragraphs field. You could make these changes to the Basic page type, but it's best to leave that type alone so that it's always available for simple interior site pages. For my sites, I create a content type called Landing Page and configure it with the following fields:
- Title [Standard field]
- Body (Long text and summary)
- Body Sections (Paragraphs)
- Attachments (File)
Once again, configure each field to your personal tastes and don't forget to configure the Display settings as well.
The important field, of course, is the Paragraphs field, which lets you embed one or more Paragraphs bundles. When configuring it, you can use the Allowed Paragraph bundes setting to control which bundles you want to allow to be embedded. This is very useful when you want to create a more complex page with bundles that can only be used in specfic parts of the page. As an example, I created a special bundle for an image and text header to show at the top of the page, and then added a Paragraphs field at the top of my Landing Page that only accepts this one bundle type. Thus, I know that the site's content manager can only place this type of heading at the top of a page and not attempt to insert something that wouldn't look right up there.
With the Item Title and Plural Item Title settings, you can customize the information text that your content manager will see, so that inserting and managing bundles will make as much sense as possible.
For the Default edit mode setting, I prefer to set this to Preview, which causes each bundle to show in preview mode when you first open the page for editing. This gives the content manager a visual reference for quickly finding the section s/he wants to update, and limits the number of active input fields initially displayed (the default option is to render every bundle as 'Open' for editing, which on a complex page can result in a lot of active input fields.)
Finally, for my 'Body Sections' Paragraphs field, I set Number of values to 'Unlimited', so that the content manager can add any number of bundles s/he wants to a page.
Testing Out Your Configuration
Once you've saved all of your settings, you can create a test page of your new content type. When you get down on the editor page to where you placed your Paragraphs field, you'll see the title you gave it (in my example, 'Body Sections'), along with the message "No Body Sections added yet. Select a Body Section type and press the button below to add one." Use the drop-down selection box directly below that message to select an available bundle type and then select the 'Add new Body Section' button.
The page will do an in-place AJAX-based update to show an editor for the newly created section. On the left-hand side of this section, you'll notice the standard cross-arrow symbol, which means that once you've added multiple bundles / sections, you can reorder them by just click-dragging the cross arrow symbol. To remove a bundle / section, just look for the Remove button at the bottom of the section. The Collapse button next to the Remove button will simply close the editing interface for that section, returning it to preview mode, which will reflect any changes you made. However, as the warning indicates, those changes are not permanently saved until you save the entire page.
Okay, This Looks Nice, But There Has to be More, Right?
The real power of Paragraphs (in my opinion) is the fact that you can put a Paragraphs field into a bundle, creating nested layers of bundles. Thus, you can create a wrapper that accepts some number of sub-bundles, and then add custom CSS to your site theme to format the sub-bundles based on the wrapper that contains them. The simplest example is using a wrapper to format two sub-bundles as side-by-side columns of specific widths: 50/50, 1/3-2/3, or 2/3-1/3 widths. While such an effect be achieved in some WYSIWYG editors (e.g. CKEditor with custom widgets), using the Paragraphs bundle-based approach creates a true separation between columns, giving you more control and flexibility, and reducing the chance that editing one column will accidentally mess up other columns. The sub-bundle itself doesn't have to be a custom bundle -- you can easily reuse your 'Standard Section' bundle as the allowed bundle for each column, keeping the number of bundles you have to define down to a minimum.
The key to creating these interesting layouts is the custom CSS, which is most easily added to your theme or sub-theme, though you could also create a custom module to contain this CSS, which would be useful should you ever want to share that CSS with others. To formulate your CSS, you'll need to use the machine name of each bundle, with a few programatic changes: a machine name of standard_section becomes a CSS class name of paragraphs-items-standard-section. This kind of CSS development isn't necessarily for the feint of heart, and I don't have time and space here to explain all the details, but learning how to do it is critical to getting the most benefit out of the Paragraphs module.
Can I Reuse My Bundle Designs?
In theory, yes. The module provides an export option that works with the Features module, but that's another somewhat steep learning curve if you've never used Features before.
There may be other workable methods as well, but I haven't explored anything in this area yet. So far, most of my Paragraphs work has been on one Drupal site, with some testing and development work on a second site. I definitely want to find a way to bring my bundle designs over to other sites, but at the moment I don't have any good answers for how to do this.
Of course, keep in mind that you not only have to bring over your bundle configurations, but you'd also need to bring over the custom CSS you've created to format different bundles in specific ways (like the multi-column example I gave above). A good way of dealing with this would be to create a custom module that implements a bundle and it's needed CSS code. There's an example pack out there called Paragraphs Pack that I think would provide a foundation for creating these modules.
Do You Have Any Examples?
Not yet, but I hope to make an example site available for public viewing in the next few weeks. In the meantime, there's an example website available from a company that has built some add-ons for Paragraphs.