Theme Layouts

What are Layouts?

Theme layouts determine how content is organized within your page.

For example, you might have a 3 Column Layout, a 2 Column Layout, and a Single Column layout. Any layout that you create becomes available within the Page Settings options on your site. You can create multiple layouts and apply different layouts to different pages.

Heres an example of a theme with a few different layout files created:

These layouts would then appear within your Page Settings for the pages on your site:

Creating a Layout

To create a new layout for your theme, simply create any new file with the ending .tmpl.php within your themes layout directory. For example Column1.tmpl.php

Within your template file you will create the layout of your page any way that you want. You will have several template variables passed to your layout file that will contain page content.

$header - Contains rendered html from the Header.tmpl.php file for your theme
$footer - Contains rendered html from the Footer.tmpl.php file for your them
$links - These are the page management links, such as the link to edit the page or to to the Control Panel
array $area1 - (Left of Page) Contains an array of html for AREA 1 of your page.
array $area2 - (Center of Page) Contains an array of html for AREA 2 of your page.
array $area3 - (Right of Page) Contains an array of html for AREA 3 of your page.
array $area4 - (Top of Page) Contains an array of html for AREA 4 of your page.
array $area5 - (Bottom of Page) Contains an array of html for AREA 5 of your page.

$area1-5 are special template variables that each contain an array of HTML strings. Each entry is a different rendered part or CodeBehind View Handler that has been rendered.

Your layouts do NOT need to display each area, and generally, they will only use a few. Usually areas are rendered in the same general area between layouts (marked in bold above) - this helps keep some consistency when switching between themes. This, however, is only a suggestion and you are free to place areas how you would like.

Usually you will provide CSS in your Style Sheet file to control each layout.

Sample Single Column

Heres an example of what a Single Column template might look like:



Columns1.tmpl.php
=========================
<?=$header?>
<div id="container" class="Columns1">
        <div id="contents">
            <?=implode($area2)?>
        </div>
        <div class="clear"></div>
    </div>
</div>
<?=$footer?>
<?=$links?>

Style.css
=========================
...
#container {
    text-align: left;
    padding-left: 120px;
    padding-right: 120px;
    }
...
/* Layout: Columns1 */
.Columns1 #contents {
    margin-left: 17px;
    margin-right: 17px;
    line-height: 2em;
}
...

Note that since the $area1 variable is an array of HTML, this template uses implode to combine them into a single string: <?=implode($area2)?>.

Sample Double Column

Heres an exmaple of what a 2 Column template might look like:



Columns2.tmpl.php
=========================
<?=$header?>
<div id="container" class="Columns2">
        <div id="leftbar" >
            <?=implode($area1)?>
        </div>
        <div id="contents">
            <?=implode($area2)?>
        </div>
        <div class="clear"></div>
    </div>
</div>
<?=$footer?>
<?=$links?>

Style.css
=========================
...
#container {
    text-align: left;
    padding-left: 120px;
    padding-right: 120px;
    }
...
/* Layout: Columns2 */
.Columns2 #leftbar{
    float: left;
    width: 300px;
    min-height: 100px;
    }

.Columns2 #contents{
    margin-left: 330px;
    line-height: 2em;
    }
...

Preview Images

Preview Images are the small thumbnails shown next to your layout name under Page Settings.

To create a preview image, create a GIF file in your themes layout\samples directory. You should name your GIF the exact same name as the template file that you want it to preview.