Contents of a layout template
A layout template is comprised of a single layout directory containing several files. Core layout template 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.pngDetails 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.
The template file should be named: layout--YOUR-LAYOUT-NAME.tpl.php (where YOUR-LAYOUT-NAME is the machine name of your layout with underscores (_) changed to hyphens (-)).
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 = contentContents
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.