Usage¶
Airmad can either be used in template files as part of a theme or, as recommended, in a snippet block. The latter one allows for integrating Airmad into any existing theme that supports Automad’s block editor. The markup looks as follows:
Attention
You can simply paste an Airmad snippet directly into a code field of the new Template Snippet block on any page in the Automad dashboard.
<@ Airmad/Airmad {
base: 'appXXXXXXXXXXXXXX',
table: 'Design projects',
view: 'All projects',
fields: 'Name, Client',
filters: 'Client, Category',
formula: 'SEARCH(LOWER("@{ ?search }"), LOWER({Name}))',
linked: 'Client => Clients[Name Address]',
prefix: ':example',
template: '
{{#records}}
{{#fields}}
<div class="card">
<h3>{{Name}}</h3>
<p>
{{#Client}}
{{Name}}
{{/Client}}
</p>
</div>
{{/fields}}
{{/records}}
',
partials: '/packages/some/partials',
limit: 20,
page: @{ ?Page | def(1) }
} @>
The code above doesn’t produce any output. Instead it populates some Runtime
variables that can be used in the
Automad template at any point after the Airmad instance above. Note the prefix
parameter. The prefix is required to make sure that all runtime variables have unique names.
To display the generated output, the :exampleOutput
variable can be used in a
template for example as follows.
<div class="cards">
@{ :exampleOutput }
</div>
Attention
In case you want to use multiple Airmad instances on your site, you will have to define unique prefixes for each one in order to avoid conflicts between them.
Options¶
The example above shows a typical use case of an Airtable integration. Find below a list of all availabe options.
Name |
Description |
---|---|
|
The Airtable base ID |
|
The main table to be used to pull records from |
|
The view of the main table to be used |
|
A comma separated list of fields that should be included in the records, leave empty to get all fields |
|
A required prefix for the generated runtime variables — prefixes have to be unique, in case more than one Airmad instance is used on the site |
|
A comma separated list of tables that are linked to a field
of the main table records — note that it is only required to list linked tables
here that include information that you want to display.
In case the field name differs from the actual table name to be linked,
it is also possible to pass a list of strings like
|
|
The Handlebar template to be used to render the model (the collection of records) — can be either a string, a variable containing a string or a file path |
|
You can optionally specify a path to a directory containing partials. That path must be
an absolute path in relation to your Automad installation directory, like
for example |
|
A comma separated list of fields that can be used to filter the records by — check out the examples below for more information about filtering |
|
A formula
to be used to for the |
|
The maximum number of records to be displayed on a page |
|
The current page of records (pagination) |
Runtime Variables¶
Aside from the output, Airmad provides more variables as shown in the table below. Note that :prefix
can be
replaced with any other valid string and is just used for demonstration here.
Name |
Description |
---|---|
|
The rendered output of the table records |
|
The number of found records |
|
The current page number — this has to be seen in context to
the |
|
The amount of pages the records are spread over,
also related to the |
|
The max memory used by Automad in bytes |
Attention
Note that you must define an unique prefix to be used instead of :prefix*
in the
Airmad options when creating a new instance.
Filters and Formula¶
Airmad offers two ways of searching an Airtable base — filters and formulas. While filters are very easy to use and allow for automatic filtering of records whenever there is a query string parameter with a column name present, formulas are way more flexible and powerful. In contrast to filters, formulas allow for searching across multiple fields by a custom formula. Take a look at the official formula documentation provided by Airtable for a full list of available options and examples.
<@ Airmad/Airmad {
base: 'appXXXXXXXXXXXXXX',
table: 'Design projects',
view: 'All projects',
formula: 'SEARCH(LOWER("@{ ?search }"), LOWER(CONCATENATE({Name}, {Client})))',
prefix: ':example',
template: '
{{#records}}
{{#fields}}
<h3>{{Name}}</h3>
{{/fields}}
{{/records}}
'
} @>
The example above will demonstrates how you can implement searching the Name
and the Client
fields of records
at the same time by only a single search parameter in the query string.