• ♡ Sponsor

    Variables

    #Blocks #Context #Session #Variable

    The actual value of a variable is depending on the current context. In most cases the context is the currently requested page. However, control structures can change the context to any other page during runtime, for example when iterating over a list of pages. In case a variable is not defined in a page's data set, a possibly existing value within the shared data will be used as fallback. Note that also information created by Automad during runtime and parameters of the URL's query string can be used in templates. In case variables have to persist across multiple requests, they can be stored in the session data array.

    Page Variables

    Page variables reflect the data associated with pages. As mentioned above, the default context is reflected by the URL. However, within loops the context will switch automatically to other pages while iterating. Check out this template of the theme skeleton package for more information. The syntax for outputting variable values within the markup looks like this:

    @{ text }
    

    Naming

    The name of a variable also determines its input field style in the dashboard. Depending on the start of the name, a corresponding input type is chosen by the following patterns:

    • +*: Blocks, like +main — read more here
    • checkbox*: Toggle
    • color*: Color picker
    • date*: Date and time picker
    • image*: Image picker — note that images* will be ignored
    • text*: Markdown editor
    • url*: Link dialog with autocomplete for pages

    All other variables a represented by just a simple text area.

    Note that variable names can only contain the characters "a-z", "A-Z", "0-9", "-" and "_". The "+" can only be used to indicate a block variable and must be used as the first character in the variable name.

    Shared Variables

    Conceptually shared variables can be considered as global fallbacks for page variables. They are stored with the shared settings and data. As soon as a variable is used in a template, first it is checked whether that variable is defined in the page's data. If not, Automad will try to use a possibly existing value in the shared data. Shared variables can also be defined during runtime be using the set function.

    <@ set { variable: 'Some text ...' } @>
    @{ variable }
    

    Note that you can mask variables in either the shared or page settings to have a nice and tidy dashboard with only relevant options and information. Take a look at the masks field in the theme.json documentation to understand how masking works.

    Blocks

    Compared to all other variable types, block editor variables stand out in the way they stored data. Unlike all other variables, blocks are saved in a structured JSON format. The actual HTML is only rendered when the containing template is rendered. Therefore the block editor doesn't consist of a single textarea only but instead adds a flexible amount of different input fields when needed. In templates, block variables can be used like all other variables too.

    @{ +blocks }
    

    It is not required to process the variable content using the markdown pipe function — the blocks are automatically rendered by the template engine. Most of the generated HTML consists of pure HTML tags. However there are some CSS custom properties to control the look of the rendered blocks.

    Check out this guide about customizing the look and feel of rendered blocks in your theme.

    You can read more about using blocks here.

    Query String Parameters

    You can access any query string parameter of the current URL by preceding its name with a ?. For example the filter parameter of the URL below can be used as follows:

    <# http://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') }
    

    Again, this template is a very good example of how to use query string parameters to modify the configuration of a pagelist.

    Session Variables

    Session variables persit across multiple requests and are therefore a good option to store settings like for example the selected language on a website with multilingual content. Session variable names always start with a %.

    @{ %variable }
    

    The set function can be used to define session variables. The multilingual content template is a good example for using session variables.

    Runtime Variables

    Runtime variables are generated by Automad during rendering. They can be used like normal variables in templates. Their name always starts with a :. More here.

    @{ :parent }
    

    Reserved Variables

    Some variables are always defined by Automad, but can be overriden. You can find a list of all reserved variables here.


    More in Variables

    • Reserved Variables
    • Runtime Variables

    Related

    User Guide  ⁄
    Using Blocks — User Guide

    Blocks are little pieces of content like a text paragraph, a header, a gallery, a slideshow or many others. You can even add dynamic content like pagelists, filelists or custom snippets. The block editor provides an intuitive editing experience and enables users to freely compose ...

    Variables  ⁄
    Reserved Variables — Variables

    Some variables have reserved names and are always defined. They can be found on top of the page/shared data section in the dashboard. Reseverd variables can be used like normal page variables.

    Variables  ⁄
    Runtime Variables — Variables

    There are some variables defined by Automad during runtime. The names of those runtime variables are always preceded with a colon as follows: @{ :basename } Runtime variables can be subdivided into two types - context related variables and variables created within control ...

    Template Language  ⁄
    Pipe — Template Language

    A pipe | allows for using the value of a variable to be the input value for a function. It is also possible to chain multiple functions together, so that the output of one function is used as input for the next one. Therefore a pipe can be used to modify the value of a variable ...

    Toolbox  ⁄
    queryStringMerge — Toolbox

    Creates a query string containing the specified paramters as key/value pairs merged with the existing query string of the current URL. This method can be used to create links for adding or replacing some parameters of the query string without touching the other ones. A standard ...

    Toolbox  ⁄
    set — Toolbox

    Sets shared, session or runtime variables by passing key/value pairs as option array.

    Template Language  ⁄
    Control Structures — Template Language

    As in other languages, control structures in Automad are statements that dynamically determine the flow of an application or website based on evaluating content or variables. Automad knows four different statements to control the flow of the application: for, foreach, if and ...

    Control Structures  ⁄
    foreach — Control Structures

    The foreach loop iterates over objects. Depending of the type of the object in use, Automad provides different runtime variables within the code block of the loop to refer to items of the object. The :i variable refers to the index of the current iteration in the loop.

    Control Structures  ⁄
    with — Control Structures

    The with statement allows for processing code associated with a given page or file. When using a page's URL or one of the keywords prev and next as an argument, the context within the block of code changes to that page. When using a file path, it is possible to access related ...

    Template Language  ⁄
    Multilingual Content — Template Language

    In case you want to provide your content in multiple languages, it is important that once a user has selected a language, the selection persits across multiple pages. Automad provides an easy way to store such data in the session data array. The saved selection will then be used ...

    Building Themes  ⁄
    Block Layouts — Building Themes

    Aside from just stacking blocks on top of each other, Automad's block editor provides some handy features to create flexible layout directly in the block editor. It is possible to stretch a block to the full with of the parent container to make it stand out as well as to arrange ...

    Building Themes  ⁄
    Customizing Blocks — Building Themes

    Most of the blocks only consist of pure HTML tags without classes and just inherit theme styles when being displayed. However the default styling of more complex blocks like the mail form or the gallery block might not be matching a theme out of the box. You can use CSS custom ...

    • Automad
    • Developer Guide
    • Building Themes
    • Template Language
    • Variables
    Discuss
    Packages
    Release Notes
    Support
    Terms of Use
      Become a Sponsor
      GitHub
      Twitter
      Facebook
      Instagram
      2013-2022 by Marc Anton Dahmen
    Released under the MIT license

    A faceless machine, creating one's portrait in the internet.
  • Automad
  • Getting Started
  • System
  • User Guide
  • Developer Guide
  • Headless Mode
  • Discuss
  • Packages
  • Developer Guide ←
  • Building Themes ←
  • Template Language ←
  • Variables
  • Reserved Variables
  • Runtime Variables