Automad's template language provides a flexible and safe way to render content dynamically. In contrast to generic template engines, Automad's core features are integrated directly into the engine. That includes things like image processing, collections of pages and files, as well as access to an even wider range of functionality through custom functions and extensions. Due to its close relation to the core, the syntax is clean and intuitive and reduces overhead to a minimum.
Syntax
The template language consists of two main groups of components — content and statements. As with other template languages, both can simply be mixed with the HTML markup of a template.
<!DOCTYPE html>
<html lang="en">
<head>...</head>
<body>
<@ header.php @>
<# Some comment. #>
<nav><@ navTop @></nav>
<h1>@{ title }</h1>
<main>@{ +main }</main>
<@ footer.php @>
</body>
</html>Content
All variables that are defined for a page as well as shared, runtime, session and query string variables are considered content. The value of a variable can be used in a template like this:
@{ variable }The value of a variable can also be modified in place by chaining filters or basic mathematical operations using the | operator:
@{ variable | filter }
@{ variable | +5 }Statements
Statements include function calls, custom functions, extensions, control structures, snippet definitions and includes of other template files. The basic statement syntax looks as follows:
<@ function { key: 'value' } @>
<@ snippet @>
<@ file.php @>Some statements, like control structures and snippet definitions, wrap a block of code that is closed by an end statement:
<@ foreach in pagelist @>
<a href="@{ url }">@{ title }</a>
<@ end @>Note the pagelist in the example above. There are several types of collections that can be iterated by control structures during runtime.
Context
The context defines the page that a variable belongs to. The default context is always the currently requested page that is reflected by the URL. The context can be changed temporarily using a foreach loop or a with statement.
<# By default the context is the requested page. #>
<@ with '/some-page' @>
<# Inside this block, the context is the page with the URL "/some-page". #>
<h2>@{ title }</h2>
<@ end @>Extending Templates
In most cases, themes consist of multiple templates that share a lot of redundant code and only differ in minor details. In order to reduce such redundancy, it is recommended to extend a common base template and only override the snippets that have to be different. Following the DRY principle leads to much cleaner code and a better organization of your project.
Stripping Whitespace
When building complex template structures, the generated output can contain a lot of unnecessary whitespace. That can, for example, also break a generated JSON response. A ~ character next to a statement delimiter removes all whitespace before or after that statement.
<# Remove all whitespace before a statement. #>
<@~ statement @>
<# Remove all whitespace after a statement. #>
<@ statement ~@>
<# Remove whitespace on both sides. #>
<@~ statement ~@>Comments
As with any other language, commenting your code is always good practice. Comments are removed from the markup during rendering and therefore never show up in the source of the rendered page.
<# Some comment #>Mixing with PHP
Since templates are regular .php files, the template language can also be mixed with plain PHP if needed. Learn more about using inline PHP in templates.