Paragraphs is a Drupal module that allows for flexible content structures through reusable "paragraph" blocks. It can go wrong through poor planning, overly complex implementations, or mixing content and presentation. Key tips for success include carefully planning paragraph types, separating structure and presentation, and designing paragraph editing experiences with author usability in mind.
12. What is Paragraphs?
● An entity type designed to be created and embedded
inside other entities
● Like constructing content from building blocks
13. 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
16. 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
17. 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
24. 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
25. You can choose how Paragraphs will be labelled in the editing interface!
26. 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.
28. Creating a new Paragraph type
whenever you need one
Paragraphs 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
29. 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”
31. 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
32. 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”
41. 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
43. Possibilities for excessive
complexity
● Too many similar paragraph bundles (already discussed)
● Too many levels of nesting (Paragraphs within
Paragraphs within Paragraphs)