Customizing Blocks

    #Blocks #Theme

    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 properties to style the rendered blocks to match your theme. Some block types — pagelist and filelist blocks — also support custom templates to be used for rendering content.

    Take a look a the custom block templates shipped with the Standard theme to get started quickly.

    Styling Blocks

    To customize the look of rendered blocks, Automad provides a couple of custom properties which can be overriden in .css, .less or .sass files of a theme. You can find a collection of all available custom properties in the variables.less file which is shipped with Automad.

    automad/blocks/less/variables.less
    

    To change for example the styling of the buttons block, you can define the following custom properties in your stylesheets:

    :root {
        --am-button-margin: 5px;
        --am-button-padding: 0 1.5rem;
        --am-button-font-size: 1.15rem;
        --am-button-height: 2.75rem;
        --am-button-lineheight: 2.75rem;
        ...
    }
    

    Custom Templates

    The pagelist and the filelist blocks support the use of custom templates. Conceptionally those templates are just normal snippet files containing a foreach loop — either iterating a pagelist or a filelist object.

    Pagelist Block Templates

    Creating a custom pagelist block template is pretty straight forward. To be available in the block editor, a .php file including a foreach loop has to be placed within a blocks/pagelist directory somewhere in a package. So its path basically has to match /packages/**/blocks/pagelist/*.php like for example the custom templates of the Standard themes shipped with Automad:

    /packages/standard/templates/blocks/pagelist/simple.php
    

    The actual pagelist configuration is handled by the block editor user interface and therefore the content of such a template file is not more than just a foreach loop snippet:

    <?php defined('AUTOMAD') or die('Direct access not permitted!'); ?>
    <section>
        <@ foreach in pagelist @>
            <p>
                <a href="@{ url }"><b>@{ title }</b></a>
                <br>
                @{ tags }
            </p>
        <@ end @>
    </section>
    

    Filelist Block Templates

    Custom block templates for filelists work exactly the same as for pagelist blocks. They only differ in their location and in the type of object to be iterated. Their path has to match /packages/**/blocks/filelist/*.php like:

    /packages/vendor/name/blocks/filelist/simple.php
    

    Also here the configuration of the filelist is handled by the block editor user interface. Again, the content of the template is just a foreach loop iterating a filelist object.

    <?php defined('AUTOMAD') or die('Direct access not permitted!'); ?>
    <section>
        <ul>
            <@ foreach in filelist @>
                <li>
                    <a href="@{ :file }">@{ :basename }</a>
                </li>
            <@ end @>
        </ul>
    </section>
    

    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 a post from several ...

    Developer Guide  ⁄
    Building Themes — Developer Guide

    Themes are an essential part of a content management system. They define the way your content is presented to the visitors of your website. Automad's flexible and intuitive template language enables also inexperienced developers or beginners to create themes and templates on their own. In case you ...

    Building Themes  ⁄
    theme.json — Building Themes

    Every theme needs a theme.json to work. As mentioned before, all subdirectories of the packages directory containing a theme.json side by side with at least one template are to be considered as valid themes. Please see the list below for all required fields.

    Building Themes  ⁄
    Template Language — Building Themes

    Automad's template language provides a flexible and safe way to render content dynamically. In contrast to other generic template engines, the Automad core functions are integrated into the engine. That includes such things as image processing as well as a the access to an even wider range of ...

    Template Language  ⁄
    Variables — Template Language

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

    Building Themes  ⁄
    Plain PHP — Building Themes

    Automad supports plain PHP in template files. However, variables used in plain PHP blocks will not show up automatically in the dashboard and mixing PHP with Automad's template engine should be done carefully. Therefore it is not recommended to use plain PHP in normal templates. Missing ...

    Developer Guide  ⁄
    Cheat Sheets — Developer Guide

    In case you prefer to start developing a theme or extension without reading the full documention, the cheat sheets below are a good point to start. In addition to this page there is also the tutorial theme included in your Automad installation to help you getting started.

    Cheat Sheets  ⁄
    Useful Template Snippets — Cheat Sheets

    Find below a collection of useful snippets for common tasks using Automad's template language.

    Cheat Sheets  ⁄
    Plain PHP Snippets — Cheat Sheets

    In case you want to develop a new extension or use PHP in your templates, the collection of common code snippets below might help you getting started quickly.

    Cheat Sheets  ⁄
    Creating Theme Packages — Cheat Sheets

    This guide describes step by step the workflow of setting up and publish a new theme. It assumes you're familiar with Visual Code Studio and working on a system with a Bash shell or similar — like macOS or Linux.

    • Automad
    • Developer Guide
    • Building Themes
    • Customizing Blocks
    Discuss
    Packages
    Release Notes
    Support
    Terms of Use
      GitHub
      Twitter
      Facebook
      Instagram
      2013-2021 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
  • theme.json
  • Template Language
  • Customizing Blocks
  • Plain PHP