Paragraphs without pain

Angus GordonWeave (weaveweb.com.au)

This talk

● What is Paragraphs, and what is it good for?● What are the ways Paragraphs can go wrong, and how

can I avoid them?

What is Paragraphs and what is it good for?

Traditional content modelling in Drupal

● Content types● Fields● Taxonomy● Entity references● Views

This is great for capturing content that follows set patterns.

But not all content does that:

Landing pagesHome pagesLongform articlesMultipart content

Typical Drupal solutions

● Layout in the Body field● Big bunch o’ blocks● Panels

...but none of them are good solutions for flexible structures like these

Enter Paragraphsdrupal.org/project/paragraphs

What is Paragraphs?

● An entity type designed to be created and embedded inside other entities

● Like constructing content from building blocks

Basic Paragraphs implementation

● Create “Paragraph types” (“Paragraph bundles” in earlier versions) for each type of building block you need (equivalent to content types)

● Add a Paragraphs field to your “host” entity● Make it a multi-value field so authors can add any

number of Paragraphs, of any type, in any order

Examples

http://paragraphs.site-showcase.com/ (Morpht)

https://www.communications.gov.au/ (Acquia/PNX)

https://www.ewov.com.au/reports/res-online/201609 (Weave)

Alternatives?

Inline Entity Form + Nodes or custom entities● See

https://www.chapterthree.com/blog/paragraphs-vs-eck-drupal-8

● This is the approach to go for if you need your individual entities to be reusable or to exist independently of the “host” entity

● Advantages of Paragraphs: lightweight, works out of the box, ecosystem

WYSIWYG Fields or Entity Embed

● https://www.drupal.org/project/wysiwyg_fields● https://www.drupal.org/project/entity_embed ● Both ways of inserting a component (either a field or an

entity) into a Body field using WYSIWYG● Great for particular use cases (e.g. longform articles with

rich media)● Both can be used in conjunction with Paragraphs

Ways Paragraphs can go wrong...and how to avoid

them?

Drupal people have learned how to do content modelling for content types.

Do we have to re-learn these principles for Paragraphs?

Ways Paragraphs can go wrong

● Poor naming● Lack of planning● Mixing content and presentation● Editing interface issues● Excessive complexity

Poor naming

The name “Paragraphs”

● Let’s be honest, it’s a terrible name● We already have 2 things called paragraphs: an HTML

element and a unit of language● If we can’t change the name of the module, let’s at least

hide it from authors

You can choose how Paragraphs will be labelled in the editing interface!

Naming of Paragraph types

● Confusing● Ad hoc● Coupled to presentation

These problems are related to other issues: lack of planning and mixing content and presentation.

Lack of planning

Creating a new Paragraph type whenever you need oneParagraphs seems to invite this ad hoc approach

This can lead to

● Too many types invented for a single use case● Too many similar-sounding names● Lack of discipline● Complexity

Solution: plan that shit

● Plan Paragraphs bundles the same way you plan content types

● You do plan content types, right?● Include Paragraphs requirements in content audit and

content model● Put some guidelines in place for creating new Paragraphs

types: make them “earn their place”

Mixing content and presentation

Entities are not pages

● Basic content modelling concept: separate content from presentation

● Becomes more urgent as we move towards decoupled / headless sites

● If we take this principle seriously, we will think of Paragraph types as semantic structures not mini-layouts

Solution: think decoupled

● Avoid presentational logic when naming Paragraphs bundles and fields

● “Three column promo grid” => “Three item promo section”

● “Text beneath image” => “Text associated with image”● “Blue background text box” => “Highlighted text box”

Editing interface issues

You can choose how Paragraphs will be displayed in the editing interface

This is “Open”.

This is “Closed”.

This is “Preview”. Nifty! But how…?

Custom view mode for each Paragraph type

Choose the field you want to display in the editing interface.

Enable “Preview” Edit mode

Is Paragraphs even the right tool?

● Paragraphs works well where content is intrinsically chunky

● What about long form articles that are “punctuated” by rich media?

● This is a single narrative (“body”) with interruptions, not a series of discrete chunks

● WYSIWYG Fields or Entity Embed might be the solution: perhaps in combination with Paragraphs

Excessive complexity

Possibilities for excessive complexity

● Too many similar paragraph bundles (already discussed)● Too many levels of nesting (Paragraphs within

Paragraphs within Paragraphs)

LImit Paragraph types allowed to avoid infinite nesting

The Drupal community is taking author experience seriously.

Let’s make Paragraphs part of that.

Thank you!

@angusgmelb@WeAreWeave