The Layout module creates pages and wraps existing pages in layouts.

Backdrop's primary tool for positioning content is through layouts and blocks. A "layout" is the template that defines regions in which pieces of content may be placed. Each piece of content in this case is called a "block". Blocks may be placed multiple times in a single layout, and each block maintains separate settings. Each layout created saves to a configuration file, including all the settings for the blocks contained within it.

Layout module provides two distinct ways of rendering pages. It is capable of creating a stand-alone page that is created at any custom path specified by the user, and it can also "wrap" the content of any path provided by a module. In the case where a custom path is created, Layout module registers the path in the menu system through hook_menu(). For wrapping module-provided pages, Layout module declares itself as the system-wide "route handler", as checked in menu_execute_active_handler(). Layout module then becomes responsible for calling the module-provided content as a block, and positions other blocks around the existing content.

Contents of a layout

Layouts are comprised of a layout directory, usually named after the layout, containing files and directories. Core layout directories are found in the BACKDROP_ROOT/core/layouts directory; contributed layouts in the BACKDROP_ROOT/layouts directory. A layout directory may have the following example structure (although not all of these are required, as explained below):

BACKDROP_ROOT/layouts
    my_layout
        my_layout.info
        layout--my-layout.tpl.php
        my_layout.php
        my_layout.css
        preview.png

Details of these components follow.

The layout .info file (required)
This file is required for Backdrop to see your layout. Should the layout require them, style sheets, block regions and more can be defined here.

The template file (.tpl.php)
This template provides the (x)HTML markup and PHP variables which build the page. For example, the core layout--three-three-four-column.tpl.php layout reproduces the regions and appearance of the legacy Bartik theme. This file is optional, and if none exists in your layout it will fall back to the default layout.tpl.php file. Refrain from having complex logic in these files. In most cases, it should be straight (x)HTML tags and PHP variables. Copying a core layout to your layout folder will force Backdrop to read your version, but this is not recommended.

Additional .php processing files
If a layout template requires additional conditional logic and data processing of the output, a template processing file should be included rather than performing complex logic in the .tpl.php files. This generally means it is used to hold preprocessors for generating variables before they are merged with the markup inside the layout .tpl.php file. Custom functions, overriding layout functions or any other customization of the raw output should also be done here.

The preview.png file
An image representing the appearance of this layout.

Additional .css files
To supply CSS necessary for the layout, specific .css files can be used. Note however that the site theme is responsible for styling of page elements; the layout CSS file should only include markup essential for architecture.

Writing layout .info files

The .info file is a static text file for defining and configuring a layout. Each line in the .info file is a key-value pair with the key on the left and the value on the right, with an "equals sign" between them (e.g. name = my_layout). Semicolons are used to comment out a line. Even though the .info file extension is not natively opened by an Application, you can use TextEdit on a Mac or Notepad on a Windows computer in order to view, edit, and save your changes.

The following example shows the .info file for the 3/3/4 columns layout:

name = 3/3/4 columns
version = BACKDROP_VERSION
backdrop = 1.x
type = layout

; Include file for special preprocessing of this layout's variables.
file = three_three_four_column.php

; Specify regions for this layout.
regions[header] = Header
regions[top] = Top
regions[content] = Content
... (additional regions definitions)

; Content is the default region by default, but specify it for clarity.
default region = content

Contents

Backdrop understands the .info file keys listed below. Backdrop will use default values for the optional keys not present in the .info file.

name (required)
name = 3/3/4 columns

The human readable name.

layout version
version = 1.0

You can give your layout whatever version string makes sense. If you publish your project in the Backdrop Contributed Projects group, a version line will automatically be added to your .info file when the project is packaged by BackdropCMS.org.

backdrop version (required)
backdrop = 1.x

All .info files for modules and layouts must indicate what major version of Backdrop core they are compatible with. The value set here is compared with the BACKDROP_CORE_COMPATIBILITY constant. If it does not match, the layout will be disabled.

type (required)
type = layout

The type of project. For a layout, this will always be "layout". Other available types are "module" or "theme". Although this property is not required to use the layout, it is required to properly package the layout on BackdropCMS.org and thus should always be included.

file
file = three_three_four_column.php

The name of a PHP file to be included prior to any rendering of this layout. This may be used to provide preprocess functions to prepare variables for the use of the layout.

regions
regions[header] = Header
regions[top] = Top

A list of regions this layout provides, keyed by a machine name with a human label value.

default region
default region = content

Determines which region will hold the main page content block by default. Defaults to 'content' if not specified.

stylesheet
stylesheets[all][] = my_layout.css

An array of CSS file used whenever this layout is presented. If left empty, "my_layout.css" will be used for all media types.

preview
preview = preview.png

Optional. An image representing the appearance of this layout. If left empty, "preview.png" will be used.

Assigning content to regions

Regions are defined, as described above, by including these regions in the .info file. Layout module then provides these regions as template variables to be inserted into the layout template (.tpl.php) file.

Example: the variables available to the layout--three-three-four-column.tpl.php template:

$content['header']
$content['top']
$content['content']
$content['sidebar_first']
...

Regions being rendered in the page:

  <?php if ($content['top']): ?>
    <div id="top"><div class="section clearfix">
      <?php print $content['top']; ?>
    </div></div> <!-- /.section, /#featured -->
  <?php endif; ?>

Layout module administrative pages provide the drag and drop interface for adding content to regions defined in a layout. The end user with appropriate permissions is able to select from a list of blocks available to Backdrop and insert these blocks into any region. Blocks can be inserted into multiple regions.

Therefore, certain typically included page components are not explicitly provided by either the theme or the Layout. Navigation menus, logo items and site descriptions are provided as blocks and can be dragged and rearranged into any region using the Layout administrative interface.