Guides

Templating

AMPize uses Mustache templates to display content from your data sources. Every query-based component (list, detail, carousel) uses them.

Together with the CSS code fields in page and site settings they are the main tools to customize the design of your AMPize website.

Overview

Mustache templates are simple and easy to use. Being logic-less, they don't have any advanced features such as conditionals and yet they can cover the vast majority of use cases.

AMPize automatically generates basic templates for every use case directly in the query builder so you never need to start from scratch. This makes templating productive as most of the time you can either leave the auto-generated templates as they are or do some minor tinkering.

You can also save your templates and reuse them in other components of the same type and perform centralized updates.

Template management

Using templates in components

Whenever you use the query builder, the last stage is always a preview of the resulting html. By default, the query builder automatically generates a template adapted to your use case (list, detail or carousel) and uses it to render the preview. This default template lists all the fields from your query in their order of definition. While it may do the job for simple lists of titles or basic content details it might need some tinkering if you want to change the order in which fields are displayed or modify their layout.

Clicking on the pencil-shaped edit button will split the query builder window into two panels : the code editor and the preview. In order to help you code, every change you make in the editor immediately affects the preview. We will cover the details of editing in the next section of this guide.

If at some point during your editing you realize that a field is useless or that you need other fields that aren't in the query you can always go back to the first stage and make the necessary changes. The template will not be re-generated as you return to the last stage unless you click the corresponding button in the second stage.

Once you are satisfied with the template clicking the "SAVE" button in the bottom-right side of the screen will save your changes and close the editor. You can always return and edit the template either by re-opening the query builder ("data" button on the current component toolbar) or going directly to the template editor ("template" button on the current component toolbar).

Reusable templates and centralized updates

In many use cases different components can use the same template and it would be unnecessarily tedious to have to maintain the all separately. This is why templates can be saved and reused in other components. In order to do this simply configure a new component (or edit an existing one) and click the floppy-disk-shaped icon right beneath the code editor. This will display a form which you can use to name and save your template.

Once the template is saved, it can no longer be edited directly from the component. This means that the last stage of the query builder wil no longer display the edit button and code editor and that the "template" button is no longer available on the toolbar of that component. The template can only be edited from the centralized template editing interface.

To access this interface simply click the "Templates" button in the site menu. Reusable templates are scoped by site and are separated into categories depending on what components can use them. Here you can edit or delete the templates. Any changes made to a template in this interface is automatically applied to any components that use it.

In order to use an existing template in a component simply create a new component (or edit an existing one) and select that template in the second stage of the query builder. Keep in mind that this discards the components current custom template (if it has one).

If you don't want a component to use a saved template anymore you can always select another one or "custom template" in the second stage of the query builder. If you select "custom template" you can either re-generate the template automatically by clicking the corresponding button or use the code of the previously selected template as a basis for the code editor.

Template code

This is a basic list template auto-generated by the query builder.

{{#capitalList}}
 <div>
{{title}}
<a class="ampize-primary-color" href="{{ampizeDetailUrl}}">Read more</a>
<hr></div>
 {{/capitalList}}
 {{#ampizePaging}}
<div class="flex justify-center ampize-paging">
{{#prevPage}}<button class="ampize-btn ampize-btn-secondary"><a href="{{url}}"><<</a></button> {{/prevPage}}
 <span class="ampize-paging-current-page">{{currentPage}}</span>
{{#nextPage}} <button class="ampize-btn ampize-btn-secondary"><a href="{{url}}">>></a></button>{{/nextPage}}
</div>
{{/ampizePaging}}

It displays the title followed by a "read more" link for each item in the list. As you can see it's just HTML enriched with some Moustache code in order to repeat the div for each item and output the data.

The first part of the code between {{#capitalList}} and {{/capitalList}} is specific to the data and is repeated for each item (capitalList is the internal name of the query). The second part between {{#ampizePaging}} and {{/ampizePaging}} is component-specific code : in this case the paging links that will be displayed under the list if you activate paging in the component settings.

Data output

AMPize automatically generates templates that display all the fields in your query. This means that all of the Mustache code required to display data is already in the template. Nevertheless it can be very useful to know how Mustache code works.

The Mustache doc is a a very quick read (shorter than this templating guide) and will teach you all you need to know about outputting data in templates. We recommend that you read it before proceeding.

Now that you know what {{#capitalList}} means you're probably wondering where the name came from. It's the internal name of the query (in this case the name of the multiEndpoint of the "capital" model) that serves as a root for the Mustache repetition (top section). You don't have to worry about guessing its name since AMPize will auto-generate it with the first custom template for this component. The fields of your query will be within this initial section.

The key to customising templates efficiently resides in the effective use of sections. They can display arrays ir single items or act as a form of conditional (if the value is empty everything with the section is hidden) with the same syntax. This is why list templates and detail templates are almost identical (except for the "read more" link and the paging).

Another important fact is that Mustache tags are independent from your HTML. This means that you can add any HTML you want (as long as it's valid AMP HTML of course) between the tags. Here's a simple example :

{{#capitalList}}
 <div>
<h2>{{title}}
<a class="ampize-primary-color" href="{{ampizeDetailUrl}}">Read more</a>
<hr></div>
 {{/capitalList}}
 {{#ampizePaging}}
<div class="flex justify-center ampize-paging">
{{#prevPage}}<button class="ampize-btn ampize-btn-secondary"><a href="{{url}}"><<</a></button> {{/prevPage}}
 <span class="ampize-paging-current-page">{{currentPage}}</span>
{{#nextPage}} <button class="ampize-btn ampize-btn-secondary"><a href="{{url}}">>></a></button>{{/nextPage}}
</div>
{{/ampizePaging}}

This template works just like the first one but adds a HTML tag (h2) around the title.

In addition to the fields from your query that can be outputted using {{field}} tags, component variables(variables set in JSON in the "variables" tool of the current component and GET params of the current page can be displayed with the same syntax.

One thing that is not very clear in the docs is how to output a non-associative array. The answer is pretty simple : {{#property}} {{.}} {{/property}}. The {{.}} tag designates the root value of the current section.

Component-specific elements

Depending on what type of component your template is used in, certain special elements can be used. In our list template those would be the detail link and the pager.

In all list templates a field called "ampizeDetailUrl" is injected at the root of every result item. It is automatically field with the detail URL of that item (if a detail page is configured in the component settings).You should remove the entire <a class="ampize-primary-color" href="{{ampizeDetailUrl}}">Read more</a> link if you don't want this behaviour (otherwise you just get empty links).

The entire "ampizePaging" section is used for paging and will only be displayed if paging is activated in the component settings. Please note the use of the "prevPage" section as a form of conditional display: if it is not defined the "previous page" link is not rendered.