Airmad¶

Installation¶

Airmad can be installed by using the Automad dashboard. However in case you would like to install the package by using Composer, just run the following command on your command line:

$ composer require airmad/airmad

Configuration¶

Airtable requires an API token to authenticate when accessing bases using their REST API. In case you don’t have one, you can easily create one on your Airtable profile page. After successfully creating such token, it has to be added to Automad’s config/config.php file. That can be done by navigating to System Settings > More > Edit Configuration File in the Automad dashboard as demonstrated below. Aside from the authentictaion, there you can also configure the Airtable cache lifetime in seconds.

{
  "AIRMAD_TOKEN": "keyXXXXXXXXXXXXXX",
  "AIRMAD_CACHE_LIFETIME": 43200,
  ...
}

Options¶

The example above shows a typical use case of an Airtable integration. Find below a list of all availabe options.

Runtime Variables¶

Aside from the output, Airmad provides more variables as shown in the table below.

Multiple Instances¶

As soon as you want to use filters and select dropdowns to let a user control the displayed set of records on a page, you will have to use multiple instances of Airmad on one page. For example one instance request all records of a fictional table called Type to generate a list of all existing product types in your database, while another one gets the actual products for example from a table called Products. To avoid overwriting the output the first table with the output of the second one, the generated runtime variables need to have a unique prefix that can be defined in the options by using the prefix parameter.

 <@ Airmad/Airmad {
     base: 'appXXXXXXXXXXXXXX',
     table: 'Type',
     view: 'Grid view',
     template: '<option value="{{ Name }}">',
     prefix: ':type'
 } @>
 @{ :typeOutput }

 <@ Airmad/Airmad {
     base: 'appXXXXXXXXXXXXXX',
     table: 'Products',
     view: 'Grid view',
     template: '<option value="{{ Name }}">',
     prefix: ':products'
 } @>
 @{ :productsOutput }

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. 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%}}

If Equals¶

In case you quickly want to compare a field value with any string or number you can use the if== helper:

{{#if== field, value}} ... {{/if==}}

If Not Equals¶

The counterpart to if== helper is the if!= helper that lets you check for inequality:

{{#if!= field, value}} ... {{/if!=}}

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.

{{ _ID }}

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 }}

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.

Example¶

A very simple example for a pagination within an Automad snippet could look as follows:

<ul class="uk-pagination">

    <@ if @{ ?Page } > 1 @>
        <li><a href="?<@ queryStringMerge { Page: @{ ?Page | -1 } } @>">←</a></li>
    <@ end @>

    <@ for @{ :airmadPage | -3 } to @{ :airmadPage | +3 } @>
        <@ if @{ :i } > 0 and @{ :i } <= @{ :airmadPages } @>
            <li>
                <a
                href="?<@ queryStringMerge { Page: @{ :i } } @>"
                <@ if @{ ?Page | def(1) } = @{ :i } @>class="uk-active"<@ end @>
                >
                    @{:i}
                </a>
            </li>
        <@ end @>
    <@ end @>

    <@ if @{ ?Page } < @{ :airmadPages } @>
        <li><a href="?<@ queryStringMerge { Page: @{ ?Page | +1 } } @>">→</a></li>
    <@ end @>

</ul>

You can simply copy and paste this into a snippet block after creating an Airmad instance. The classes in use will work out of the box with the Standard and Adam themes.

Autocompletion¶

To enhance the user experience for your visitors, you might want to provide an autocompletion list of Type names for the second input field. You can simply use a second Airmad instance to pull all type names from the Type table and populate such a list with the Name field of each record. In the following example we use a datalist for such purpose.

 <form action="">
     <input type="text" name="Name" value="@{ ?Name }">
     <input type="text" list="types" name="Type" value="@{ ?Type }">
     <@ Airmad/Airmad {
         base: 'appXXXXXXXXXXXXXX',
         table: 'Types',
         view: 'Grid view',
         template: '<option value="{{ Name }}">',
         prefix: ':type'
     } @>
     <datalist id="types">
         @{ :typeOutput }
     </datalist>
 </form>
 <ul>
 <@ Airmad/Airmad {
     base: 'appXXXXXXXXXXXXXX',
     table: 'Products',
     view: 'Grid view',
     linked: 'Type => Types',
     template: '<li>{{ Name }}</li>',
     filters: 'Name, Type',
     limit: 20,
     page: @{ ?Page | def(1) }
 } @>
 </ul>

Filters¶

The first part is creating the filter menu. Note that the naming of the input fields is essential here! In our example we want to filter the records by the Client field that is linked to the Clients table (note the “s” in the table name).

<form action="">
    <input type="text" name="Name" value="@{ ?Name }">
    <input type="text" list="clients" name="Client" value="@{ ?Client }">
    <@ Airmad/Airmad {
        base: 'appXXXXXXXXXXXXXX',
        table: 'Clients',
        view: 'All clients',
        template: '<option value="{{ Name }}">',
        prefix: ':clients'
    } @>
    <datalist id="clients">
        @{ :clientsOutput }
    </datalist>
    <button type="submit">Filter</button>
</form>

Listing Records¶

The second part is building the actual list of record. Again, the mapping of linked tables is important here! The code below will generate a grid of record including a little slider to be used with with the Standard theme.

<@ Airmad/Airmad {
    base: 'appXXXXXXXXXXXXXX',
    table: 'Design projects',
    view: 'All projects',
    linked: 'Client => Clients',
    template: '
        <div class="card">
            <div class="card-content uk-panel uk-panel-box">
                <div class="uk-panel-teaser">
                    {{#slider Project images 75%}}
                </div>
                <div class="uk-panel-title">
                    {{ Name }}
                </div>
                <p>
                    {{# Client }}
                        <b>{{ Name }}</b>
                    {{/ Client }}
                </p>
            </div>
        </div>
    ',
    filters: 'Name, Client',
    limit: 8,
    page: @{ ?Page | def(1) }
} @>

<div class="cards grid am-stretched">
    @{ :airmadOutput }
</div>

Pagination¶

The last part will create the pagination navigation. Again the generated markup will work out of the box with the Standard theme.

<ul class="uk-pagination">
    <@ if @{ ?Page } > 1 @>
        <li><a href="?<@ queryStringMerge { Page: @{ ?Page | -1 } } @>">←</a></li>
    <@ end @>
    <@ for @{ :airmadPage | -3 } to @{ :airmadPage | +3 } @>
        <@ if @{ :i } > 0 and @{ :i } <= @{ :airmadPages } @>
            <li><a href="?<@ queryStringMerge { Page: @{ :i } } @>" <@ if @{ ?Page | def(1) } = @{ :i } @>
                class="uk-active"
            <@ end @>>@{:i}</a></li>
        <@ end @>
    <@ end @>
    <@ if @{ ?Page } < @{ :airmadPages } @>
        <li><a href="?<@ queryStringMerge { Page: @{ ?Page | +1 } } @>">→</a></li>
    <@ end @>
</ul>