Upgrade Your Drupal Skills

We trained 1,000+ Drupal Developers over the last decade.

See Advanced Courses NAH, I know Enough
Jun 14 2021
Jun 14

What are Layout Paragraphs?

According to their project page, Layout Paragraphs provides an intuitive drag-and-drop experience for building flexible layouts with paragraphs. Paragraphs are the preferred method of dealing with complex content structures inside of Drupal, and Layout Paragraphs are for dealing with complex layout structures in those paragraphs. 

Layout paragraphs are meant to help separate the content and structural needs of site builders and content editors. The concept of Layout paragraphs is not really a new idea. It builds upon a long history of layout systems including panels, display suite, blocks and panelizer, but utilizes more core API's like Entity API and Layout Builder API.

When using paragraphs in the past, extra paragraphs, or multiple versions of the same paragraphs, were needed in order to provide different layouts and styles for content creators. With a very plain editing experience, it could be very difficult for content creators to get an idea of how their page will look on the front end. Layout paragraphs are here to help simplify what content paragraphs are needed, and provide a better idea of what the page will look like when editing.

With some practice and refining of the steps below, it is possible to create and replicate a powerful layout and content system that your clients will love using. So let's get to it.

Setup steps

  1. Install modules and themes.
    • Modules required: 
    • Optional:
      • gin (recommended admin theme. Claro and some others work well too.)
      • gin_toolbar (recommended if using gin for your admin theme.)
  2. Setup the main settings for layouts and paragraphs.
    • Visit the "Layout Paragraph Labels" settings page - admin/config/content/layout_paragraphs/labels.
      • Select Show paragraph labels.
      • Deselect Show layout labels (I find this not needed, if layouts are easily distinguishable from each other).
  3. Setup a paragraph to use as the Layout source.

    This is known as a layout paragraph.

    • Call it Layout (or whatever helps you to know this is layout related) You can have multiple paragraphs that handle layouts (like one for large complex layouts and one for simple layouts inside of a layout), but best to keep simple.
    • In Behaviors, Set to Layout paragraph.
    • Select the layouts that you want to have available. You will have to come back to this as you create/update/delete layouts
      • Default core layouts are available.
      • Easy to create custom layouts using Core layout API.
    • No other fields are required on this paragraph, and nothing needed in the form display or display settings.
      • Text fields for headings and select fields with options for setting classes are things you can try to work in here, but really no other fields are needed.
  4. Setup some paragraph types that will be used in the layouts.

    These are known as content paragraphs. This part is up to you and your needs for the site.

    • Good recommendation for content paragraphs are just simple paragraphs. Some examples include:
      • One with just a WYSIWYG body field. 
      • One with an unlimited link field.
      • One for with an unlimited media field to post single images or multiple image slideshows.
  5. Setup a layout field on a content type of your choice.

    For this I prefer to keep it simple. I will have just the title field, the layout/content field, and then rename the body field to something like "teaser/summary" and set that up to only be used in teasers and meta tag descriptions.

    • Create a field of paragraph type. I usually call it field_content of field_paragraphs.
      • Set the field settings to Unlimited.
      • Include/exclude the paragraphs that you want available in your layouts. This is something you will probably have to come back to as you add new paragraph types to the site.
      • Must include the paragraph that is acting as the Layout paragraph.
    • Set the Form display.
      • Set Widget to Layout Paragraphs.
      • Set view mode to Preview. 
      • Set 0 nesting depth (prevent layouts in layouts. I like to keep it simple, but it will come down to your needs and desired user experience.).
      • Set require paragraphs to be added inside a layout (a layout must be chosen first before a content paragraph can be set).
    • Set the Display.
      • Set the label to Hidden.
      • Set to format to Layout paragraphs.
      • Set rendered as Default
  6. Place stuff in your new layouts.

    • Create a new page of the content type with your layout field.
    • When you hover over the field, an add icon will appear. Click on it and you will be able to add a layout type paragraph.
    • When you add a layout, a modal will popup where you can set the desired layout style as well as any other options that are available (this is based on what contrib you have installed or if you have any fields on your layout paragraphs).
    • Select a layout style, like One Column, and select accept.
    • You will see a "block" representing your new layout. Hover over and you will see an add icon appear at the top and bottom of the area.
    • Click on one of those icons, and you will have the option to set one of the Content paragraphs you've made available. 
    • The paragraph fields will display in a popup. Add your content accordingly and press accept.
    • Repeat with a couple more content paragraphs.
    • Make sure to add the node title, and press save.
    • Review your new node. Things may look slightly off (or wildly off). It's based on how the CSS is working in your theme. But rest assured, all the pieces of the puzzle are in place for you to work your magic.

You can change the layout and move content around.


Many of these steps are customizable based on your needs and your Drupal development skills. I've used select fields and view mode selection fields inside of the layout paragraphs and content paragraphs to allow content creators to get creative and apply different prebuilt styles. I've played around with preprocessing, twig templates, and extra fields to build complex displays, but still allowed for a simple user interface. The possibilities are up to you.

May 03 2021
May 03

SIREN (Social Interventions Research and Evaluation Network) at UCSF has a mission to, “Improve health and health equity by advancing high quality research on health care sector strategies to improve social conditions". This research initiative, supported by Kaiser Permanente and the Robert Wood Johnson Foundation, is a leader in the creation, curation and dissemination of research that explores the intersection between health and social determinants that often play a critical role in the health outcomes of individuals and communities. 

Chapter Three was recently brought in to help the SIREN team make improvements to their old Drupal 7 site, the most extensive technical work since the original site was built. Over the last several years, SIREN's research and publication efforts grew; they needed a refresh, both to modernize the look and feel and to streamline the user experience. Importantly, they also needed to migrate from Drupal 7 to Drupal 8. We managed to achieve all of these with an approach tailored to their needs and budget.

Outcomes: A Small Sites Approach for Migration and Redesign


Most of the content on the SIREN website is relatively straightforward and didn’t require major restructuring. By taking a simplified approach that emphasized changes to several key pages and incorporating new design elements, we gave the site a more modern and updated look and feel without requiring a wholesale rethink of every page type. For smaller sites like this one, this approach can work wonders!

By focusing on the home page, resource library, (new) Coffee & Science podcast, and the News section, we were able to give SIREN a lot of value for the money. For page templates that weren't redesigned, the addition of new iconography, updates to the color scheme and other styles gave those pages a refresh without impacting the budget.

Figure: Old SIREN homepage with three separate "resource" headings
Old Homepage of SIREN at UCSF
Figure: New SIREN site with updates to imagery, featured content, and simplified navigation
New Homepage of SIREN at UCSF


User Experience

As the SIREN Network initiative grew, so did content and navigation, which had expanded out of a desire to expose more of that content directly through major navigation headings. This redesign presented an ideal opportunity to streamline the information architecture while still emphasizing access to SIREN’s priority content. We did this by providing strong design cues and prominent imagery for featured content and thereby reducing the need to have the navigation take on all the work of exposing content that might be nested as a subpage.

Figure: Old resource page with multiple "resource" navigation labels; where should users go?
Old Resource Library of SIREN at UCSF
Figure: New Resource Library provides updated visual treatment to better direct users to key content. All interaction with resources are done via the single Evidence & Resource Library heading.
New Resource Library for SIREN at UCSF


SIREN at UCSF has now migrated to Drupal 8 with a new design and UX that emphasized changes to priority content areas and streamlined navigation. The project approach is especially suited to smaller sites that are in need of a rethink; sites that have grown organically but now need a modest restructuring of content and design.

The team at Chapter Three is proud of our partnership with SIREN and their new site. Please have a look and get in touch with any questions.

Mar 10 2021
Mar 10

California's court system is the largest in the nation and serves a population of more than 39.5 million people — about 12 percent of the total U.S. population. 

Every year, thousands of Californians seek support for legal claims as self-represented litigants, or SRLs. This self-help system is managed by the Judicial Council of California, the administrative body for California’s courts; it offers legal assistance resources on a variety of topics such family law, civil proceedings and a variety of other issues. Every year, more and more Californians choose to represent themselves before the courts, a trend that the State has sought to address with new investments in technology and content.

Ensuring Equitable Legal Services in California

Government websites are often internally-focused, byzantine places that focus on how the government understands itself rather than how citizens need to interact with it. That gap between how the organization presents itself and how users approach it can seem overwhelming; now imagine the average citizen navigating the largest court system in the country. In 2017, the Futures Commission of the California Courts submitted a report to the Chief Justice that included a variety of recommendations to improve the public's access to the legal system. These recommendations included making investments in technology to ensure that self-help resources are easier to use, especially in family law and civil proceedings. Self-represented litigants, and the organizations that assist them, have often struggled with inconsistent information, forms, and services scattered throughout the California Courts system.

The Self-Represented Litigants Portal: A Service-First Strategy

The Judicial Council of California is now in the process of reinventing their SRL portal to be a service-first, approachable, and useful information hub, making often complex legal processes simpler to engage with. The long-term vision for the portal, or Self-Help Guide, is to replace duplicative and outdated information on trial court websites and make the court system much more accessible to the general public.

Figure: California SRL Portal Homepage

California Self-Help Portal Homepage


California’s new SRL Portal organizes around a set of services that has been informed by extensive user and background research on the tasks, case types, legal workflows and frustrations that have typically plagued users. The SRL Portal starts with a straightforward, friendly question: What Would You Like to Do? Users then scan a series of action-oriented responses to find the services and information they need.  

Figure: Rather than burying content in complex navigation, the action-oriented homepage provides direct paths to key services and information based on user research conducted by the JCC

California Self-Help Dropdowns from Homepage

Clicking on Small Claims takes users to a landing page where the initial content is straightforward. It notes the basics about what Small Claims is, the fees associated with filing a claim, and links to specific scenarios that help people decide what to do next (button labeled “Go to the steps”). 

Figure: Small Claims Landing Page

California Self Help Small Claims Page

Once the user navigates to the "Process" or "Steps" page, easy to understand language coupled with typical decision workflows allow users to access the legal system in a more intuitive way. 

Figure: Small Claims “Steps” page with dropdowns to allow scenario-based exploration of the phases of a case

California SRL Small Claims Process Page


JCC: Partners With Drupal and Chapter Three

Delivering services and managing content across an enterprise of sites can be difficult and time-consuming. This is especially true with decentralized systems and staffing which can lead to off-brand variations in how sites look, feel, and operate, confusing and frustrating users.

We understand these challenges. For JCC’s new SRL Portal, Chapter Three tamed this problem by focusing on structure, separating content and administration from presentation. This means site administrators and content creators can work faster and with less friction. A library of design components integrated into a Drupal-powered content platform provides a content entry experience that’s missing all the frustration of fighting with formatting and layout. Enter some content and let the system make it look great, every time, on every page.

The flexible design system provides highly refined components as building blocks for content creation, including body content, headings and containers for "steps" and other content elements. This allows for variation in structure from page to page while ensuring a high quality look and feel that’s consistent with the organization's design standards. The component library stands alone. It can be incorporated into other platforms or projects easily, bringing the same level of polish and simplicity to all of the organization’s digital assets, from microsites to intranets and web applications. For the JCC, these components help easily build informational, “step” or other pages with predictable, clean layouts governed by the pattern library’s tight integration with Drupal.

Drupal's Flexibility Powers Change in the Public Sector

The SRL Portal is one example of a growing pivot towards service-oriented content and infrastructure. For government agencies seeking to rethink and revamp how to deliver services online, the combination of Drupal, pattern libraries and a services-first content approach can make dramatic improvements in citizen engagement and resource management for the public sector. Making websites easier to administer allows your content strategy to focus on the customer and the services most important to them, whether searching for legal advice, paying a fee, submitting a building permit, or any of hundreds of other essential interactions between government and citizenry.

Finally, creating information workflows more intuitive for your customers can help reduce the amount of time staff need to spend answering phone calls or responding to in-person queries, making other public interactions more productive and satisfying for both staff and customers.

Interested in learning more about the project and approach we took? Contact us! We'd love to discuss the problems you're trying to solve and how our insights can benefit your organization.

Jan 14 2021
Jan 14

I once sat on a mountain and deeply contemplated the mysteries of Drupal development. Actually, I live on a mountain, so I do this every day, and the title of this post isn't a Zen revelation, I stole that from Elon Musk.

I'm not trying to build rockets and send humans to Mars, and I don't want to draw too many parallels between what I do and the complexity of that enterprise, but we do solve some complex problems of critical importance to our clients. Every efficiency we can gain improves outcomes.

The Challenge: Theming Efficiently

When I work on a project, or a problem, I try to distil it down to it's most important elements, and ruthlessly eliminate that which is not efficient, or providing real value. As we trend more towards Javascript front ends and I've had more opportunity to get deeply back into that side of Drupal development, I find myself being more critical of inefficiency, over-engineering, bloat and unnecessary "features". I believe the Developer Experience (DX) is as important as the User Experience (UX). Happy, efficient devs, make quality software.

To that end, I want to simplify and reduce the friction in my workflow. My particular goal for this post is to make a theme cleaner, easier to build and maintain, and perhaps get even better performance.

I'm afraid this might be controversial for some reason, but I've dropped the compiler and task runner from my themes. Every theme I've encountered since I can't remember when, has used SCSS and an often unnecessary JS Compiler. Why run simple jQuery based behaviors through a compiler?

There was a time when I was excited about this approach and could see the benefits of SCSS. Today, I'm not so sure it's necessary. As for Javascript, if you're just doing simple Drupal behaviors, and you're not into Typescript or something, you don't need a compiler for that. Why not avoid the complexity and drop it all from the theme? Of course, decoupled front ends or other advanced Javascript requirements is a different story.

What was great about SASS/SCSS, but maybe isn't so much any more?

  • It's CSS Syntax friendly so you already know how to get started with it.
    • CSS is CSS Syntax friendly too. :p
  • Variables
    • CSS has that now, and it's "catching up" in other ways.
  • Nested Syntax
    • I often see this causing bloat and hard to read code. While they say it's "easier to read/write", I'd say this is only true when there's a disciplined hand crafting well structured SCSS. This is true for CSS as well, and I don't see the advantage of nested syntax.
  • Mixins
    • Component driven Atomic Design reduces the value of this, and new features of CSS reduce it even further.
  • Modularity via @import compiling down to a single file.
    • Again I'll mention Component based Atomic Design, as well as Drupal's Aggregation and libraries.yml.
  • Popularity and a large SASS Community
    • Literally every front end dev uses CSS. ;)

note: 6 of the 7 benefits of SASS over CSS from this 2018 post.

Another thing we got from the compiler was code linting which can be done at some or all of three other points in the development/delivery pipeline; in the editor, in a git pre-commit hook or in automated test runs. There are even CSS linters written in php we can include in the composer.json we're using anyway.

Now that all that's out of the way...

How I Built My Last Project

  • Atomic Design
  • Components
  • Drupal libraries
  • Drupal CSS/JS Aggregation

Every front end Drupal developer is probably fully aware of these things. We're doing component based front ends already. I won't belabor each of these points. I'll just share a few thoughts about why I think this is often enough to make fast, reliable and robust front ends, and eliminate some cruft from the process.

Atomic Design

A quick book to read online

Breaking our user interfaces down into clearly defined patterns gives us consistency, re-usability and a clear hierarchy of components. I kind of assume everyone has encountered this, or some similar methodology, but if not, I highly recommend this book.

Identifying these clear and reusable patterns in our UI allows us to build each one out as a discrete and self contained component that can be pieced together to make more complex features on a page.


Building these Atomic patterns into usable templates creates our components. The self contained components include the twig template and the CSS specific to that component. If there's some discrete JS functionality that goes along with it, it can be include here as well.

 - my_theme
   - components
     - hero
       - paragraphs--hero.html.twig
       - hero.css
     - card
       - paragraphs--card.html.twig
       - card.css
     - ...

We can install the components contrib module to allow our theme templates to be discovered somewhere other than the /templates directory.

My preference for this project was to use the paragraphs module to create "stackable" components for node content, but you can create or use components in node templates, for blocks, header, nav, etc.

You might even abstract your components out to something more like a pattern library, allowing you to include them in different drupal templates, i.e., in my paragraph--hero.html.twig file:

{% include "@my-pattern-library/hero/hero.twig" with { ...

In my case I have a set of components I reuse across multiple projects which are defined in a custom module. The component module allows me to access them as components in this way from my theme templates.

In the theme or module's info.yml file:

      - components

Makes the components in this project's components path available to include with @my-components/....

You can use this with something like Pattern Lab too, and seamlessly integrate components from another resource. If your project is at a level where it needs something like that, then keeping the compilation tooling in a separate pattern library project process still allows us to run without it in the Drupal theme.

Drupal Libraries

Now in our component template files, we can directly attach the library we want associated with the component.

/* Optionally include the custom module's default component styles. */
{{ attach_library('my_component_module/hero') }}
/* Optionally include this theme's component styles, if any. */
{{ attach_library('my_theme/hero') }}

{% include "@my_component_module/hero/hero.twig" with {
  'image': content.field_background_image,
  'heading': content.field_heading,
  'text': content.field_text,
  'link': content.field_link

These libraries are, of course, defined in their respective module's or theme's libraries.yml file.

By attaching them to the component's templates we allow Drupal to only load them when that particular component is used on a page, instead of one huge compiled CSS or JS file for everything.

Drupal CSS/JS Aggregation

Now when we turn on Aggregation, any libraries loaded with components are pulled together by Drupal and cached as needed. Each page's aggregated CSS is only the size it needs to be to deliver it's components.

Using the Advanced CSS/JS Aggregation contrib module can give us additional improvements, including minifiy which is something we would actually lose without a processor in the development pipeline.

Back to My Mountain Meditation

The component approach gives us an innate modularity to our CSS which vastly improves maintainability and suppresses the opportunity for bloat. The clear structure makes the CSS understandable.

Removing compilation means we can forget maintaining another package list, and github telling us we have vulnerabilities in our package.json all the time. We don't need watchers and browser sync and we can avoid any debate on whether to include compiled assets in the working repo! (hint...you should not.) ;)

We've also just sped up our CI build/test and removed more than one potential point of failure in that process.

I'll be pushing and testing the limits of performance, scalability and maintainability of this project as I prepare it for the wild and help it grow. If I find I've made a terrible mistake, I'll be sure to report back here. But right now, it feels like spring cleaning on the mountain.

"Code like nobody is watching... but then refactor. ;)"

About Drupal Sun

Drupal Sun is an Evolving Web project. It allows you to:

  • Do full-text search on all the articles in Drupal Planet (thanks to Apache Solr)
  • Facet based on tags, author, or feed
  • Flip through articles quickly (with j/k or arrow keys) to find what you're interested in
  • View the entire article text inline, or in the context of the site where it was created

See the blog post at Evolving Web

Evolving Web