Layouts

Layouts are templates that wrap around your content. They allow you to have the source code for your template in one place so you don’t have to repeat things like your navigation and footer on every page.

By default, layout files are loaded from the /layouts directory.

Table of Contents

• Frontmatter
• Inheritance

Frontmatter

The page frontmatter layout property specifies what layout is used for the page and contains the relative path to the layout. If no layout is defined, the built-in default layout is loaded.

For example:

----
layout: default
name: Page
title: The title of the page
summary: A super duper summary for this page.
---

Layout Frontmatter

A layout can in itself also have a frontmatter, like with pages, layout properties are defined in the front matter using YAML. All properties are lowercase and are accessible in the page templates using $[property].

Setting layout properties

It's possible to define the layout frontmatter through the page frontmatter. In that case, an array needs to be used to specify the layout, an additional path property defines the layout path, the other properties are overrides for layout frontmatter properties.

For example:

----
layout:
    path: default
    header:
        image: path/to/image.jpg
        class: header
name: Page
title: The title of the page
summary: A super duper summary for this page.
---

In this example, we are loading the default layout and setting the header layout properties through the page frontmatter.

Dynamically changing layout properties

In some cases you want to be able to change layout properties dynamically, this example shows how you can change a layout property dynamically:

<? page()->layout->header->image = "path/to/page.jpg ?>

Inheritance

When a layout specifies another layout, it means the content of the first layout will be injected into the <ktml:content> tag of the second layout. As an analogy, think of Russian dolls that fit into each other.

At the same time, the frontmatter of the layouts will be merged. If an inner layout specifies the same variable as an outer layout, the outer layout will receive the value defined in the inner layout. This allows you to use the frontmatter to dynamically adjust the behaviour of the outer layout.

Layout inheritance is useful when you want to add something to an existing layout for a portion of pages on your site. A common example of this is articles, you might want an article to display the date and author but otherwise be identical to your default layout.

To achieve this you need to create another layout which specifies your original layout in frontmatter. For example, this layout will live at /layouts/article.html.php:

---
layout: default
---
<p><?= Written by page()->author on date(page()->date)</p>

<ktml:content>

<ktml:content> gets the currently rendered content from the template object. It allows the current layout to decorate that content, and replace it back into the template object.

Note: You can also add the page content to the layout using page()->content. The result will be the same as using <ktml:content>, which gets the currently rendered content from the template object.