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.

1. Paragraphs
without pain
Angus Gordon
Weave (weaveweb.com.au)

2. 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?

3. What is Paragraphs and
what is it good for?

4. Traditional content modelling in
Drupal
● Content types
● Fields
● Taxonomy
● Entity references
● Views

5. This is great for
capturing content
that follows set
patterns.

6. But not all content
does that:

7. Landing pages
Home pages
Longform articles
Multipart content

8. Typical Drupal solutions
● Layout in the Body field
● Big bunch o’ blocks
● Panels

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

11. Enter Paragraphs
drupal.org/project/paragraphs

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

14. Examples
http://paragraphs.site-showcase.com/ (Morpht)
https://www.communications.gov.au/ (Acquia/PNX)
https://www.ewov.com.au/reports/res-online/201609
(Weave)

15. Alternatives?

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

18. Ways Paragraphs can go
wrong...and how to avoid
them?

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

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

22. Ways Paragraphs can go wrong
● Poor naming
● Lack of planning
● Mixing content and presentation
● Editing interface issues
● Excessive complexity

23. Poor naming

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.

27. Lack of planning

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”

30. Mixing content and
presentation

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”

33. Editing interface
issues

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

35. This is “Open”.

36. This is “Closed”.

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

38. Custom view mode for each Paragraph type

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

40. Enable “Preview” Edit mode

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

42. Excessive
complexity

43. Possibilities for excessive
complexity
● Too many similar paragraph bundles (already discussed)
● Too many levels of nesting (Paragraphs within
Paragraphs within Paragraphs)

46. LImit Paragraph types allowed to avoid infinite nesting

47. The Drupal
community is taking
author experience
seriously.

49. Let’s make
Paragraphs part of
that.

50. Thank you!
@angusgmelb
@WeAreWeave