Change record status: 
Introduced in branch: 
Introduced in version: 

Note: This change notice is no longer applicable to Drupal 8, because the Layout module was removed from core. Its evolution will happen in the contributed project

Page layouts in Drupal 7 were defined in themes as page.tpl.php files, and they had page title, breadcrumbs, etc. hardwired as template variables $title, $breadcrumbs, etc. Alternate page layouts used the theme suggestions mechanism, such as page-node.tpl.php and page-admin.tpl.php, etc. It was/is not possible for users to pick page layouts on the user interface and themes cannot independently define layouts for such use. Panels worked around this limitations skipping these templates.

We are working in Drupal 8 to introduce generic layouts that can accommodate blocks as the sole source of display output. The first step in this process is the introduction of layouts as a separate piece from page templates. As it stands at the time of this writing, the layouts cannot be used for any practical purposes, further work is going on at #1787634: [META] Decouple layouts from themes and sub-issues to make them meaningful.

However, the defined layout format is as follows:

  • Drupal core only supports so-called static layouts. There are potentially other layout types supported with contributed modules. The static layout means that layouts are defined with concrete templates and CSS/JS files (the layouts themselves are not editable). Static does not relate to what kind of content it can hold (which is fully dynamic).
  • Place a static layout under a module or theme under the layouts/static subdirectory. Eg. if your theme defines a layout called 'page', place it in themename/layouts/static/page. You can define any number of static layouts in parallel subdirectories.
  • A layout is defined with a meta-information file in YAML format. Use the same name for the file as for the directory, so place a page.yml in themename/layouts/static/page. This file should contain the human-friendly name of the layout, list any CSS/JS files associated as well as admin backend CSS/JS files needed when the layout is displayed in an admin environment. All the regions supported by the layout should also be listed. Even though this file is in YAML format, it is not managed by the configuration management system in Drupal 8. An example of this file is:
    title: Two column
    category: Columns: 2
    template: two-col
      - two-col.css
      left: 'Left side'
      right: 'Right side'

    Layout meta-information can contain a list of "stylesheets", "scripts", "admin stylesheets" and "admin scripts" respectively. Regions is a list of key-value pairs, keys corresponding to the region variable names in the template, values corresponding to the region label displayed on the admin interface.

  • The template key on the .yml file provides the filename for the template to use to render the layout. It should refer to the regions with the keys provided, such as in the above example, two-col.tpl.php would refer to $left and $right in the template.
  • The layouts are obviously free to use any wrapping markup and styling, componentize to several CSS/JS files or wrap up all CSS/JS in one file each as required. No CSS or JS is required to expose a layout (such as for a one column layout, simple wrapper markup might be enough).

Changes in a graphical format:

For examples, see a one column test layout at (defined under a theme) and a two column test layout at (defined under a theme). None of the layouts at the time of this writing are exposed by non-test modules/themes, help is welcome to define sensible markup / CSS structure for layouts and more work is needed to make use of layouts so they can replace page templates, see #1787634: [META] Decouple layouts from themes and sub-issues for help.

Module developers
Updates Done (doc team, etc.)
Online documentation: 
Not done
Theming guide: 
Not done
Module developer documentation: 
Not done
Examples project: 
Not done
Coder Review: 
Not done
Coder Upgrade: 
Not done
Other updates done


podarok’s picture

Andrii Podanenko
web(uk, en)
personal blog(uk)