The constant struggle between content editors and web developers:

• Content editors want to embed rich media, callouts, and references to related content anywhere within their WYSIWYG.  They love the Body field and want more buttons added to the WYSIWYG.
• Web developers want to add additional fields for media, attachments, related content to support rich content relationships and access control.  Web developers hate the Body field and wish they didn’t need a WYSIWYG.

In the latest 2.30 version of Open Atrium, we attempt to help both content editors and web developers with a new approach to building rich story content using the Paragraphs module.  Rather than having a single WYSIWYG body, content editors can build their story using multiple paragraphs of different types and layouts. The order of these paragraphs can be rearranged via drag and drop to create long-form content.

Site builders can add their own custom paragraph types to their sites, but Open Atrium comes with four powerful paragraph types “out of the box”:

(1) Text Paragraphs

The simplest paragraph type is the “Text” paragraph.  It works just like the normal Body field with it’s own WYSIWYG editor.  But an additional Layout field is added to control how the text is rendered.  There are options for multiple columns of wrapping text within the paragraph (something nearly impossible to do with the normal Body field), as well as options for left or right floating “callouts” of text.

(2) Media Gallery

The “Media Gallery” paragraph handles all of the images and videos you want to add to your story.  It can replace the normal Attachments field previously used to add media to a document.  Each Media paragraph can contain one or more images, videos, or files.  The Layout field controls how that media is displayed, providing options for left or right floating regions, or a grid-like gallery of media.  Videos can be embedded as preview images or full video players.

When floating media to the left or right, the text from other paragraphs will flow around it, just as if the media had been embedded into the WYSIWYG.  To move the images to a different part of the story, just drag the media paragraph to a new position in the story.

In Open Atrium, images directly embedded into the Body WYSIWYG field becomes Public, bypassing the normal OA access control rules.  However, anything added to a Media paragraph works more like the Attachment field and properly inherits the access permission of the story document being created.  Thus, the Media paragraph provides a way to embed Media within your story while retraining proper privacy permissions.

(3) Snippets

The “Snippet” paragraph type allows you to embed text from any other content on your site.  You can specify whether the Summary, Body, or full Node is embedded and also control the Layout the same as with Text paragraphs.  You can also either display the Title of the referenced content or hide the title, or override the title with your own text.

One of the best features of Snippets is the ability to lock which revision you want to display.  For example, imagine you want to embed a standard operating procedure (SOP) within your story document.  You create a Snippet paragraph that points to the SOP.  However, if the related SOP node is updated in the future, you don’t want your old document to change.  For compliance purposes it still needs to contain the original SOP text.  By “locking” the snippet to the old revision, the old document will continue to display the original SOP even if the SOP is updated later.  If you “unlock” the snippet, then it will display the latest version of the related SOP.

Open Atrium access controls are also respected when displaying snippets.  If you reference content that the user doesn’t have permission to view, that snippet will be removed from the displayed text.  Users still only see the content they are allowed.  This provides a very powerful way to create rich documents that contain different snippets of reusable content for different user roles and permissions.  Similar to adding additional fields with Field Permissions, but much more flexible and easy to use.

(4) Related Content

The “Related Content” paragraph type is similar to Snippets, but displays the Summary or Full rendered node of the related content.  Like the Media paragraph, the Related Content can contain one or more references to other content on the site.  The Layout provides options for displaying the content as a table of files, or a list of node summaries (teasers), or as full node content.  When full node content is used, any paragraphs used in the related content will also being displayed (paragraph “inception”!).  In addition, any special fields from the full related node can be shown.  For example, a Related Event will show the map of the event location.  A Related Discussion will show all of the discussion replies and even provide the Reply Form, allowing you to reply to a related discussion directly from the story document itself!

Related Content is also a bi-directional link.  When you view the related content node, a sidebar widget called “Referenced From” will show all of the stories that reference the node being viewed.

A Real World Example

To pull all of this together with a real-world example, imagine that you are scheduling a Meeting.  You want to create an Agenda for that meeting and allow your team to discuss and edit the agenda before the meeting.  In Open Atrium you can now do this all from a single document:

1. Create the Event for the Meeting, adding your team to the Notifications
2. Add a Related Content paragraph for the meeting Agenda document
3. Add a Related Content paragraph for the agenda Discussion

Open Atrium is smart about where this related content is created.  If you already have a section for documents, the Agenda will be created within that section.  If you already have a section for discussions, the related discussion will be placed there.  You can change these locations if you wish, but the default behavior reflects the most common information architecture.

When your team members receive the email notification about the meeting and click the link, they will be taken to your Event and will see the agenda document and discussion as if they were a normal part of the event body.  They can view the agenda content directly and can post replies directly into the discussion reply field.  They don’t need to go to separate places on the site to see the document or discussion.  If you *do* view the document or discussion nodes directly, such as from a search results page, you’ll see a link back to the meeting event in the References From list in the sidebar.

Conclusion

Not only do the Paragraph features help content editors build rich stories quickly and easily, they allow web developers to create related documents, linked content, better search results, better data structures.  It’s still not a magical unicorn wysiwig of content editor’s dreams, but it’s a significant step for Open Atrium and Drupal. It opens a whole new world of collaboration where all related content can be viewed together.

Looking for more information about Open Atrium? Sign up to receive Open Atrium newsletters and updates! Don’t miss our winter release webinar on Wednesday, January 28th, at 11am EST!