Picture
Phil Boden Drupal Developer and Themer
June 14, 2021

What are Layout Paragraphs?

According to their project page, Layout Paragraphs provides an intuitive drag-and-drop experience for building flexible layouts with paragraphs. Paragraphs are the preferred method of dealing with complex content structures inside of Drupal, and Layout Paragraphs are for dealing with complex layout structures in those paragraphs. 

Layout paragraphs are meant to help separate the content and structural needs of site builders and content editors. The concept of Layout paragraphs is not really a new idea. It builds upon a long history of layout systems including panels, display suite, blocks and panelizer, but utilizes more core API's like Entity API and Layout Builder API.

When using paragraphs in the past, extra paragraphs, or multiple versions of the same paragraphs, were needed in order to provide different layouts and styles for content creators. With a very plain editing experience, it could be very difficult for content creators to get an idea of how their page will look on the front end. Layout paragraphs are here to help simplify what content paragraphs are needed, and provide a better idea of what the page will look like when editing.

With some practice and refining of the steps below, it is possible to create and replicate a powerful layout and content system that your clients will love using. So let's get to it.

Setup steps

  1. Install modules and themes.
  2. Setup the main settings for layouts and paragraphs.
    • Visit the "Layout Paragraph Labels" settings page - admin/config/content/layout_paragraphs/labels.
      • Select Show paragraph labels.
      • Deselect Show layout labels (I find this not needed, if layouts are easily distinguishable from each other).

  3. Setup a paragraph to use as the Layout source.

    This is known as a layout paragraph.

    • Call it Layout (or whatever helps you to know this is layout related) You can have multiple paragraphs that handle layouts (like one for large complex layouts and one for simple layouts inside of a layout), but best to keep simple.
    • In Behaviors, Set to Layout paragraph.
    • Select the layouts that you want to have available. You will have to come back to this as you create/update/delete layouts
      • Default core layouts are available.
      • Easy to create custom layouts using Core layout API.
    • No other fields are required on this paragraph, and nothing needed in the form display or display settings.
      • Text fields for headings and select fields with options for setting classes are things you can try to work in here, but really no other fields are needed.

  4. Setup some paragraph types that will be used in the layouts.

    These are known as content paragraphs. This part is up to you and your needs for the site.

    • Good recommendation for content paragraphs are just simple paragraphs. Some examples include:
      • One with just a WYSIWYG body field. 
      • One with an unlimited link field.
      • One for with an unlimited media field to post single images or multiple image slideshows.

  5. Setup a layout field on a content type of your choice.

    For this I prefer to keep it simple. I will have just the title field, the layout/content field, and then rename the body field to something like "teaser/summary" and set that up to only be used in teasers and meta tag descriptions.

    • Create a field of paragraph type. I usually call it field_content of field_paragraphs.
      • Set the field settings to Unlimited.
      • Include/exclude the paragraphs that you want available in your layouts. This is something you will probably have to come back to as you add new paragraph types to the site.
      • Must include the paragraph that is acting as the Layout paragraph.
    • Set the Form display.
      • Set Widget to Layout Paragraphs.
      • Set view mode to Preview. 
      • Set 0 nesting depth (prevent layouts in layouts. I like to keep it simple, but it will come down to your needs and desired user experience.).
      • Set require paragraphs to be added inside a layout (a layout must be chosen first before a content paragraph can be set).
    • Set the Display.
      • Set the label to Hidden.
      • Set to format to Layout paragraphs.
      • Set rendered as Default. 

  6. Place stuff in your new layouts.

    • Create a new page of the content type with your layout field.
    • When you hover over the field, an add icon will appear. Click on it and you will be able to add a layout type paragraph.
    • When you add a layout, a modal will popup where you can set the desired layout style as well as any other options that are available (this is based on what contrib you have installed or if you have any fields on your layout paragraphs).
    • Select a layout style, like One Column, and select accept.
    • You will see a "block" representing your new layout. Hover over and you will see an add icon appear at the top and bottom of the area.
    • Click on one of those icons, and you will have the option to set one of the Content paragraphs you've made available. 
    • The paragraph fields will display in a popup. Add your content accordingly and press accept.
    • Repeat with a couple more content paragraphs.
    • Make sure to add the node title, and press save.
    • Review your new node. Things may look slightly off (or wildly off). It's based on how the CSS is working in your theme. But rest assured, all the pieces of the puzzle are in place for you to work your magic.

 

You can change the layout and move content around.

 

Conclusion

Many of these steps are customizable based on your needs and your Drupal development skills. I've used select fields and view mode selection fields inside of the layout paragraphs and content paragraphs to allow content creators to get creative and apply different prebuilt styles. I've played around with preprocessing, twig templates, and extra fields to build complex displays, but still allowed for a simple user interface. The possibilities are up to you.

Drupal 9