Blog

One of the great additions to Drupal 8 theming is the layouts file. Previously adding layout options to a Drupal 7 site required the Display Suite module, creating folders for each layout then creating 2-3 files per template option/folder. Now the DS module is still required, however the templating control is all within the theme, specifically the theme.layouts.yml file.

Each layout requires a minimum of 6 items:

1. layout machine name
2. layout ui label
3. category template
4. location
5. css
6. available regions:
   1. region machine name
   2. region ui label 

bootstrap_full_width: [ layout machine name ]
  label: Full Width [ layout ui label ]
  category: Paragraphs [ category]
  template: templates/ds/bootstrap_full_width [ template location ]
  css: stylesheets/sapan.css [ css file ]
  regions: [ available regions ]
    main: [ region machine name ]
    label: Main content [ region ui label ]

layout machine name

The layout machine name is the name of your template. Since it's the "machine name" remember to use lower case letters and underscores.

layout ui label

This is the "friendly" label users will see in the Drupal UI.

category

I am SO happy they added this to the options. If you're going to need multiple layouts for multiple content types utilize this handy item! Some categories we've been using include blocks, blogs, articles, basic pages and homepage.

template location

Simply the location of the template file within the theme folder. I would suggest creating a "templates" folder within the theme directory (themes/[theme]/templates) and house them in subfolder there. Organization is the key.

css

While this is required you don't need to create one custom css file per template. You can opt to create one for all, or simply integrate the styles into your main css file. We use scss/sass and I have the layout styles within a partial.scss file integrated into the main css file. Every layout then has the same css file listed.

available regions

This is very similar to the way you'll add regions to the page template files. It contains to 2 items: the machine name and label. The theme.layouts file will contain all the layout options used on the site. Grouping them in some sort of manner will help you keep your sanity, such as alphabetically or by category. If you're going to use a module like paragraphs you'll end up with a larger number of layouts (think 12+). Before you start creating the layouts just figure out a plan for organizing the file, as well as the .html.twig template files. The template files can be very minimal. Looking at the sample layout above for the full width display, the template file may look like:

<div class="full-home"> {{ content.main }} </div>

When working in the layout templates you'll always start with the double brackets and "content.[region_machine_name]" within to call the region. Once the files are added to the site along with Display Suite, simply clear the cache, enable the module, navigate to the "manage display" tab of the content you want to update and select your newly added layout. You'll need to click save for it to register in the system, then drag the fields into the appropriate sections.

Organization is the key so you don't pull your hair out down the line. Utilize the categories, develop a naming convention and create meaningful directories within the themes/[theme]/templates folder.