Templates¶
As mentioned earlier, Airmad uses Handlebars to render table data. Basically all model data is structured in a multi-dimensional array and can be accessed in a template. You can see the actual data while developing your templates by enabling debugging.
Model¶
The model contains seven main elements — records
, filters
, filteredFilters
, query
,
count
, pages
and automad
. A typical structure looks as follows:
records
record
id
fields
column
column
...
record
id
fields
column
column
...
filters
...
filteredFilters
...
query
...
count
pages
automad
title
date
...
Name |
Description |
---|---|
|
The records element basically contains all rows in the given table |
|
A collection of items of columns specified in the filters option |
|
The |
|
The query element contains all parameters of the query string |
|
The count of records in filtered the model |
|
The number of pages needed to display all records in the model |
|
A bridge to a merged array of shared and page data. |
In a template you can therefore iterate all records using the Handlebars syntax as demonstarted below.
Note that column
just represents any column name in your table.
{{#records}}
{{#fields}}
{{column}}
{{/fields}}
{{/records}}
Attention
Airtable provides some example bases when setting up an account. The Airmad repository includes some example snipptes that are made to work with the Project tracker example base of Airtable. Take a look at the example template on GitHub.
Query String Parameters¶
To access a parameter in a query string like for example https://domain.com?parameter=value
you can simply use:
{{query.parameter}}
Automad Data¶
You can also access Automad’s page and shared data as follows as shown below. For example to get the title of the current page within a template you can simply use:
{{automad.title}}
Record ID¶
Since the actual record ID is by default not a field, Airmad provides the dedicated _ID
field
that contains the actual record ID.
{{#records}}
{{ _ID }}
{{/records}}
Linked Tables¶
In case you have fields that actually link to other tables in your base, the content of such a field is just a
bunch of record IDs. In most cases you would want to be able to actually get the values of the one or more
fields of that record. Fortunately Airmad automatically looks up the linked fields for you and replaces the ID string
with an array of the actual fields. The replaced ID is then moved to the _ID
field of the record’s array.
Let’s assume you have a Type
table and you want to access the Name
of each type linked to your product.
The data returned by the Airtable API looks for example as follows:
{
"fields": {
"Type": [
"recmD5WiE2GeV3ZIW",
"recuBUENcDgqnzSww",
"recj0zpg9qo8M7SeM"
]
}
}
Airmad will look up all contained fields automatically and expose the following data to the render engine:
{
"fields": {
"Type": [
{
"Name": "Chair",
"Product": ["recUtSDeLJ4HQI0uD", "recJcjDC9IN8Vws16"],
"_ID": "recmD5WiE2GeV3ZIW"
},
{
"Name": "Table",
"Product": ["recUtSDeLJ4HQI0uD"],
"_ID": "recuBUENcDgqnzSww"
},
{
"Name": "Carpet",
"Product": ["recJcjDC9IN8Vws16"],
"_ID": "recj0zpg9qo8M7SeM"
}
]
}
}
In a template you can therefore simple loop over the types and get the Name
as follows:
{{#Type}}
{{Name}}
{{/Type}}
Debugging¶
To quickly understand the actual structure of the model returned by the Airtable API, you can enable the
Debug Mode in Automad and then take a look at the browser console.
Since there will be a lot of output, you can then simply filter the console by Airmad->Airmad
.
Helpers¶
While there are all official Handlebars helpers available in templates, Airmad also provides some additional useful helpers as listed here below.
Image Sliders¶
In case your table has an attachement field, you can use the {{#slider images}}
or
{{#sliderLarge images}}
helper functions to create an image slider containing all
provided images as that are listed in a field called images
in the field context of a record.
By default the slide will have an aspect ratio of 1:1 — in other words a height of 100% relative to the width.
You can pass an optional second argument to the helper to define a custom height as follows:
{{#slider images 75%}}
The normal slider uses resized thumbnails as source files. It is also possible to get the original image in a slider as follows:
{{#sliderLarge images 75%}}
Sanitize Values¶
In order to use values in a query string, it is good practice to sanitize those before as follows:
{{#sanitize field}}
Regex Search and Replace¶
The replace
helper can be used to search and replace within a field value using Regex:
{{#replace "/regex/", "replace", field}}
JSON Output¶
To get the actual context data instead of a rendered HTML output, you can render JSON output instead. To get all data simply use this as your template:
{{#json this}}
To just get the records for example, you can use:
{{#json records}}
Markdown¶
Rich text content in Airtable fields is returned from the Airtable API in the Markdown format. In order to convert such content to actual HTML, the markdown helper can be used as follows:
{{#markdown field}}
If Equals¶
In case you quickly want to compare a field value with any other value or string you can use the if==
helper:
{{#if== field, "value"}} ... {{/if==}}
{{#if== field, otherField}} ... {{/if==}}
Note that it might sometimes be required to compare sanitized values. This can be done as follows as well:
{{#ifsan== field, "value"}} ... {{/ifsan==}}
{{#ifsan== field, query.field}} ... {{/ifsan==}}
If Not Equals¶
The counterpart to if==
helper is the if!=
helper that lets you check for inequality:
{{#if!= field, "value"}} ... {{/if!=}}
{{#if!= field, otherField}} ... {{/if!=}}
To compare sanitized values, please use:
{{#ifsan!= field, "value"}} ... {{/ifsan!=}}
{{#ifsan!= field, query.field}} ... {{/ifsan!=}}
Each Loops¶
Handlebars provides a great feature to enhance the use of lists. While it is possible to simply loop over items like:
{{#Type}}
{{Name}}
{{/Type}}
You can alternatively use the {{#each Type}} ... {{/each}}
helper to get more access to
built-in data variables like @first
, @last
and @index
. This is for example very
useful in case you need to concatenate a list of items with a comma:
{{#each Type}}
<i>{{Name}}</i>{{#unless @last}},{{/unless}}
{{/each}}
You can find more about the use of data variables in here.
Sorted Loops¶
The sorted
loop works exactly like a normal each
loop except the fact that all items
are sorted.
{{#sorted Category}}
{{this}}
{{/sorted}}
As a second argument, a key can be specified in order to sort an array of objects by the value for the given key.
{{#sorted Type, "Name"}}
<i>{{Name}}</i>{{#unless @last}},{{/unless}}
{{/sorted}}
Unique Loops¶
The unique
loop works exactly like a normal each
loop except the fact that duplicate items are ignored.
{{#unique Type}}
<i>{{Name}}</i>{{#unless @last}},{{/unless}}
{{/unique}}
More Handlebars Helpers¶
Aside from the examples above, Handlebars offers even more helpers that can be used in templates
such as with
, if
, unless
and others.
You can find the documentation
of those features as well on GitHub.
Partials¶
In order to use Handlebars partials, you have to define an absolute path in relation to your Automad directory
as the value for the partials
parameter when creating a new Airmad instance. All *.handlbars
files in that
directory can be used as partials as follows:
{{> myPartial }}