Variables are the content of your templates. The actual value of a variable depends on the current context, which in most cases is the currently requested page. In case a variable is not defined in the data of a page, the value of the shared data is used as a fallback. Besides content that is defined in the dashboard, Automad also provides variables that are generated during runtime as well as access to parameters of the URL's query string and the session data.
@{ variable }Page Variables
Page variables represent the data that belongs to a page. By default, the context is the page that is reflected by the URL. However, within loops the context automatically switches to other pages while iterating, so that the same variable returns the value of the page in the current iteration.
<h1>@{ title }</h1>
<@ foreach in pagelist @>
<# Here, the title of each page in the pagelist is used. #>
<a href="@{ url }">@{ title }</a>
<@ end @>Discovering Fields
There is no need to register variables anywhere. Automad scans the selected template and all of its included files for variables and automatically adds an input field to the page settings in the dashboard for each variable that is found. Variables that are only used indirectly, for example in a template that is loaded by a custom function, can be made visible to the dashboard by simply mentioning them inside a comment:
<# @{ imagePagelist } @{ +pageNotFoundContent } #>Naming
The name of a variable also determines the type of its input field in the dashboard. Depending on its prefix, a matching field type is chosen by the following patterns:
| Prefix | Field | Example |
|---|---|---|
+ | Block editor — read more about blocks | +main |
checkbox | Toggle — in page settings, a toggle can also fall back to the shared default | checkboxHideTitle |
color | Color picker | colorBackground |
date | Date and time picker | dateEvent |
image | Image picker | imageLogo |
number | Number input | numberMaxItems |
select | Dropdown with options that are defined in the theme.json | selectLayout |
text | Markdown editor | textTeaser |
url | Link field with page autocompletion | urlContext |
All other variables are represented by a simple text area.
Shared Variables
Conceptually, shared variables can be considered global defaults for page variables. They are stored together with the shared data of a site. When a variable is used in a template, Automad first checks whether that variable is defined in the data of the page. If not, a possibly existing value in the shared data is used instead. Shared variables can also be defined during runtime by using the set function.
<@ set { variable: 'Some text ...' } @>
@{ variable }Blocks
Compared to all other variables, block variables stand out in the way their data is stored. Instead of plain text, blocks are saved in a structured JSON format. The actual HTML is only rendered when the template is rendered. In templates, block variables can be used like any other variable:
<main>@{ +main }</main>There is no need to process block variables using the markdown filter, since blocks are rendered automatically by the template engine. However, there are some details to be considered in order to fully support all layout features. You can also learn more about customizing the look and feel of rendered blocks in your theme.
Query String Parameters
Any query string parameter of the current URL can be accessed by preceding its name with a ?. For example, the filter parameter of the URL below can be used as follows:
<# https://yoursite.com/page?filter=all #>
@{ ?filter }It is good practice to define default values for query string parameters in case a parameter is not defined or the query string is empty:
@{ ?sort | def ('date desc') }Query string parameters are a great way to dynamically configure a pagelist, for example for filtering, searching or pagination. Take a look at the examples of the newPagelist function for more details.
Session Variables
Session variables persist across multiple requests and are therefore a good option to store settings that a visitor has chosen. The names of session variables always start with a %. The set function can be used to define them.
<@ set { %variable: 'value' } @>
@{ %variable }Runtime Variables
Runtime variables are generated by Automad during rendering. They can be used like any other variable in templates and their names always start with a :. Find a list of all runtime variables here.
@{ :parent }Reserved Variables
Some variables have reserved names and are managed by Automad, but can be overridden in the page or shared data. You can find a list of all reserved variables here.