Template Language
Automad's template language provides a flexible and safe way to render content dynamically. In contrast to other generic template engines, the Automad core functions are integrated into the engine. That includes such things as image processing as well as a the access to an even wider range of methods through PHP extensions. Due to its close relation to the core, the template engine's syntax is clean and intuitive and reduces overhead to a minimum.
Introduction
Please check out the Cheat Sheets and the theme skeleton to get started.
Automad's template language consists out of several different components. Those components can be split in two main groups - content and statements. As with other template languages, content and statements can be simply mixed with the template's HTML markup.
<html>
<head>...</head>
<body>
<@ header.php @>
<# Some comment. #>
<div class="nav"><@ navTop @></div>
<h1>@{ title }</h1>
<p>@{ text | markdown }</p>
<@ footer.php @>
</body>
</html>
Content
All variables you define for a page as well as shared and runtime variables are considered content. A value of such a variable can be used in a template like this:
@{ variable }
A variable's value can also be modified by some functions or basic mathematical operations using the pipe syntax:
@{ variable | function }
@{ variable | +5 }
Statements
The group of available statements includes function calls, extension methods, control structures, snippet definitions and includes of other files. The basic statement syntax works as follows:
<@ function { key: 'Value' } @>
<@ snippet @>
<@ file.php @>
However, some statements like control structures or snippet definitions can also wrap a block of code:
<@ foreach in pagelist @>
...
<@ end @>
Note the pagelist object in the example above. There are several types of objects which can be accessed by control structure during runtime.
Context
The context defines the page associated with a variable within the template. The default context is always the currently requested page reflected by the URL. It is possible to change that context using a foreach loops or a with statement.
<# By default the current context is the requested page (URL) #>
<@ with '/some-page' @>
<# Within this block the context has changed to the page with the URL '/some-page' #>
<h2>@{ title }</h2>
<@ end @>
Extending Templates
Themes in most cases constist of multiple templates that share a lot of redundant code and only differ in minor details. To reduce such redundancy, it is recommended to extend one master template and just override those elements that have to be different. Using inheritance in order to follow the DRY principle will lead to much cleaner code and better organization of a project.
Stripping Whitespace
When building complex template structure, it can happen that actually generated output of a template contains a lot of unnecessary whitespace. That can for example also affect the functionality of a generated JSON response. Therefore Automad's template language allows for stripping unwanted whitespace as follows:
<# Removing all whitespace before a statement. #>
<@~ statement @>
<# Removing all whitespace after a statement. #>
<@ statement ~@>
Commenting Things
As with other languages, commenting your code is always a good practice. Comments are removed from the markup during rendering and can be used as follows:
<# Some comment #>