Bootstrap Paragraphs

Texas Camp 2017

Bootstrap Paragraphs Module

The Bootstrap Paragraphs module provides a suite of content and layout Paragraph bundles made with the Bootstrap front-end framework.

Demo Site

Boostrap Paragraphs Demo

Already using Paragraphs?

How many times have you built...

  • Three Column Paragraph
  • Text and Image Paragraph
  • Slideshow Paragraph
  • Simple HTML Paragraph

How many times have you built it just a little bit different???

Cat Gif

If you're not using Paragraphs yet

Install this module on a test site and start exploring all the possibilities Paragraphs offers.

Rainbow Cat Gif

Module Strategy

  • Create a module that would make the basic paragraphs needed for every site.
  • Create base templates & CSS that could be used with any theme that includes Bootstrap.
  • Harness the power of Entity Reference Revisions fields to nest Paragraphs.
  • Have global width & background color options.

Drupal Paragraphs

Paragraphs is a contrib module for Drupal that allows creation, administration, and display of customizable content components.

Why we use Paragraphs

  • Different widths for different content elements
    • Better typography - Best readability at 60 to 70 characters wide
    • But wanting Images and Videos wider
  • Structured content
    • Frustrated with Rich Text Editors since '97
    • WYSIWYG integration with Media, was buggy at best
    • Ability to add semantic markup, Schema.org, JSON-LD
  • Easy to administer layouts
    • Multiple columns
    • Quickly restructuring rows
    • Heros, Slideshows and more!

Bootstrap Framework

Bootstrap is the most popular HTML, CSS, and JS framework for developing responsive, mobile first projects on the web.

Why we use Bootstrap

  • Core functionality
    • Responsive Grid Markup and CSS
    • Themable Content and Javascript Components
    • Readable Typography base
  • Documentation
    • Standardization helps teams become more productive
    • Onboarding new developers is quicker
  • Customizable
    • Completely customizable for large projects
    • Mixins for adding existing styles to semantic html
  • Best practices for small/low budget projects
  • Open Source - MIT License

Inspiration

Thanks to Les Lim and David Needham's great presentation Using Paragraphs to Weave a Beautiful Content Tapestry, I learned the idea of separating paragraph bundles into Content, Layout and Ponies categories.

This idea helped me solidify the structure of this module.

Content bundles

Common semantically organized fields, and reference fields to common entities.

  • Simple HTML
  • Image
  • Blank
  • Contact Form
  • Drupal Blocks
  • Views
  • Media (Coming soon to a core near you!)

Layout bundles

Entity Reference Revisions fields to other Paragraphs.

  • Columns
  • Carousel
  • Accordion
  • Modal
  • Tabs

Paragraph Bundle Types

Simple

This Paragraphs type has a formatted long text field, which we configured to use the Full HTML text format during installation. This is essentially what you would expect from a normal body field.

Bootstrap Paragraphs - Simple

Image

This Paragraphs type has an Image reference field, and a Link field if you want to link the image. Because this uses Drupal core's Image module, we get to set the default field attributes, and require an ALT tag, which is required for proper accessibility.

Bootstrap Paragraphs - Image

Blank

The Blank Paragraphs type is perfect for less restrictive HTML and JavaScript.  I use these paragraphs for things like scripts from external services like Mailchimp, Pardot, Eloqua, Marketo; and adding page specific JSON-LD for SEO.

Bootstrap Paragraphs - Blank

Contact Form

The Bootstrap Paragraphs Contact Form type allows you to embed one of Drupal 8 core's Contact Forms anywhere you need it, including inside of Accordions, Carousels, Columns, Modals, and Tabs. This is possible thanks to the Contact Formatter module.

Add Inline Entity Form to allow your administrators to add new, or select existing Contact Forms.

Bootstrap Paragraphs - Contact Form

Drupal Blocks

The Drupal Block Paragraphs type has a reference field to Drupal core, System, and Menus blocks for easy inclusion in your content.

You can also use this type as an example for creating a Paragraphs type for your custom blocks.

Bootstrap Paragraphs - Drupal Block

Some Drupal blocks do not render.  Here is the list of working/not working blocks as of April, 2017.

Working

  • Footer menu
  • Main navigation
  • Powered by Drupal
  • Site branding
  • Status messages
  • Tabs

Not Working

  • Administration menu
  • Breadcrumbs
  • Main page Content
  • Page title
  • Primary admin actions
  • Syndicate
  • Tools
  • User account menu
  • User login

Views

The Bootstrap Paragraphs Views type allows you to easily embed a View in and around your other Paragraphs using a Views Reference Field.

Bootstrap Paragraphs - Views

Columns

The three Bootstrap Paragraphs Column types allow content creators to add column structure into their content using a Column Content field.

The field allows for multiple values, so columns can be easily reordered by drag and drop in the admin UI.

Columns

  • Columns (Equal) - allows for up to 6 references, and distributes the content evenly, up to 6 columns
  • 3 and 2 Column Uneven - allow for 3 and 2 items respectively, and have an additional Column Style option to choose the layout of the grid.

Equal Columns

Bootstrap Paragraphs - Columns

Two Uneven Columns

Bootstrap Paragraphs - Two Columns

Three Uneven Columns

Bootstrap Paragraphs - Three Columns

Column Wrapper

Texas Camp

New for Texas Camp!

Allows you to add multiple Paragraphs in a column. Basically, it is another level of nesting, if you need to add an image and a simple to a column.

Works in all three column types.

Column Wrapper

Bootstrap Paragraphs - Column Wrapper Example - Equal Columns

Column Wrapper

Bootstrap Paragraphs - Column Wrapper Example - Two Uneven Columns

Carousel

The Bootstrap Paragraphs Carousel allows for other Paragraph entities to be loaded in the Slide Content field. Cycle through images, simples, or multi-column pieces of content. The Carousel also has a Slide Interval speed option.

Bootstrap Paragraphs - Views

Accordion

The Bootstrap Paragraphs Accordion implements the Bootstrap Collapse Javascript to create an accordion with the panel/card component. The Accordion references the Accordion Section Paragraph Type which has a title and a Paragraph reference section for the accordion body.

Bootstrap Paragraphs - Accordion

Modal

The Bootstrap Paragraphs Modal allows for content creators to easily add modals to the site.

The bundle has 4 fields:

  • Modal Button Text - the trigger that launches the modal
  • Modal Title - the title of the modal
  • Modal Body - Paragraph reference field
  • Modal Footer - Paragraph reference field

Modal

Bootstrap Paragraphs - Modal

Tabs

The Bootstrap Paragraphs Tabs lets you put Paragraph entities in different tabs using the Tab Section bundle.

Bootstrap Paragraphs - Tabs

Those are the basic Paragraph Types

Dancing Cat

Global Settings

Every paragraph, whether content or layout has the option to set background color and one of five widths, from narrow to full using List/Text Select fields.

Widths

Each Paragraph has an option where you can set one of 5 widths. As the width gets narrower, the content becomes centered using Bootstraps offset classes. The widths are:

  • Tiny: col-4, offset-4
  • Narrow: col-6, offset-3
  • Medium: col-8, offset-2
  • Wide: col-10, offset-1
  • Full: col-12

Widths

Bootstrap Paragraphs - Widths

Background Colors

Each Paragraph has a background color option. Included are over 50 background colors and five empty background classes for you to customize in your own theme.

Empty classes follow the Bootstrap nomenclature:

  • .paragraph--color--primary
  • .paragraph--color--secondary
  • .paragraph--color--success
  • .paragraph--color--info
  • .paragraph--color--warning
  • .paragraph--color--danger

Background Colors

Bootstrap Paragraphs - Colors

Template & Markup Strategy

Markup - div.paragraph


 
  • We apply the Bootstrap .row rules
  • Stretches to the edge in a .container or .container-fluid
  • Also works if nested in another column

Markup - div.paragraph Modifiers


 
  • Type: .paragraph-type--type
  • View Mode: .paragraph--view-mode--default
  • Widths: .paragraph--width--name
  • Colors: .paragraph--color
    .paragraph--color--color-name

Markup - div.paragraph__column


 

We apply the appropriate Bootstrap widths here.

Markup - The Content


 
{{ content|without('bp_width', 'bp_background') }}

The content is added without the background color and width fields.

Twig - Width example

Twig markup for Width Field

Drupal Asset libraries

In our Paragraphs templates we use a library to load our two CSS files only on pages that need it.

{{ attach_library('bootstrap_paragraphs/bootstrap-paragraphs') }}

Bonus Round

Cat typing GIF

Page Template Suggestions

For Full Width Colors, add a new Region into your page.html.twig


 {% if page.structured_content %}
   {% block structured_content %}
     
{{ page.structured_content }}
{% endblock %} {% endif %}

And add the following CSS to your theme.


 /* Adds full width, margin-less and padding-less container for Paragraphs. */
 /* This is so colors go full width.  Padding is on interior elements. */
 .structured-content.container {
   padding-left: 0;
   padding-right: 0;
   width: 100%;
 }
						

Block Layout Screen

Block Layout

Overriding

Customize Bootstrap Paragraphs in your own theme after you've installed.

Bundles and Fields

After installation, Paragraph Bundles and Fields are kept in your database and in your configuration.

Any changes you make will be yours.

CSS & Templates

Your theme has a higher priority than this module. Move the template files, and Overwrite the CSS from your theme if desired.

Uninstall this module!

In fact, you can uninstall this module after installation and still keep all the functionality.

  • Move the templates to your theme, and remove the attach_library call.
  • Move the CSS files to your theme and call them from your theme's library file.

Play us off keyboard cat

Keyboard Cat

Extending Bootstrap Paragraphs

Create a new "Custom Block" Paragraphs Bundle Type

Use the Drupal Block Paragraph to provide the example.

Screenshot of Custom Block

Custom Block

Add a new Paragraph Type.

Screenshot of Custom Block 1

Custom Block

Add the existing Background field.

Screenshot of Custom Block 2

Custom Block

Add the existing Width field.

Screenshot of Custom Block 3

Custom Block

Add a new Reference Revisions field, select Other for type.

Screenshot of Custom Block 4

Custom Block

Select Custom Block in the Reference Revisions field settings.

Screenshot of Custom Block 5

Custom Block

Select which Custom Block Type Bundles.

Screenshot of Custom Block 6

Custom Block

Manage Display

Screenshot of Custom Block 7

Up next, the hero

Cat in a box GIF

Hero

Here is a more complex example for a Hero Paragraph bundle which has:

  • Paragraph Reference field for content
  • Background Image
  • Parallax Option
  • Image Overlay Option
  • Image Overlay Invert Option
  • Zoom/Ken Burns Effect Option

Hero

Hero Paragraph

Hero - Fields

Hero Paragraph Fields

Hero - Display

Hero Paragraph Displays

Hero - Overlay

Hero Paragraph Template

Hero - Parallax

Hero Paragraph Template

Hero - Invert

Hero Paragraph Template

Hero - Zoom

Hero Paragraph Template

Hero - Putting it all together

Up next, working globally

Cat GIF

Building a module using config

Building a module using config

Create Once, Reuse Everywhere!

Build a custom module to install a Paragraph bundle.

  • Create bundle structure in a blank Drupal install
  • Create module structure
  • Add Templates, CSS, and JS
  • Add Function to override Template
  • Export Config, delete UUIDs, Name space/change file names

Create bundle structure in a blank Drupal install

Spin up a sandbox on your favorite hosting platform or on your local dev environment and build your bundle.

Create module structure

Hero Paragraph Module Structure

Add Templates, CSS, and JS

  • Copy and rename the default template from the Bootstrap Paragraphs module.
  • Add a CSS file.
  • Add a JS file if needed.
  • Configure them in the module's .libraries file.

Add Function to override Template in .module file

Hero Paragraph Function

Export Config, delete UUIDs, Name space/change file names

Hero Paragraph Config

Install, Test, & Share the finished product

This example can be found at Xeno Hero on Github.

Xeno Hero on Github

Let's finish up!

Cat at a Computer Keyboard

To Sum Up

Using frameworks benefits productivity (Drupal, Bootstrap, Paragraphs). That is what I was trying to achieve by building this module.

You can also use this approach with other front end frameworks and scripts -- Singularity, Foundation, Slick, etc...

Many thanks to:

Xeno Media

Xeno Media, Inc. is a Chicago-based agency providing Drupal Development, Web Consulting and Design to the world's greatest clients.

Many thanks to:

  • All my amazing co-workers and clients at Xeno Media.
  • Albert Jankowski (albertski) for helping me develop this module and always helping me debug all the Drupal 8 things!

The End

Continuing the conversation: