• ♡ Sponsor

    Generic Extensions

    #Composer #Extension #PHP #Package

    In case you are missing any advanced feature while developing themes using Automad's template language, you are able to implement that functionality as a generic extension written in plain PHP.

    Package Structure

    Like themes, generic extensions have to be added to an Automad installation in form of a package. There are two types of generic extension packages: local packages and Composer packages. The main difference between them is the way autoloading PHP classes is handled.

    Local Packages

    The minimal structure of a generic extension package is basically just a directory for your namespace under packages including a directory for your extension sharing the same name as the PHP file inside. Note that all file and directory names must be lowercase.

    packages/
      yournamespace/
        yourextension/
          yourextension.php
    

    According to the directory structure above, the extension's PHP file will look like this:

    <?php
    // Namespace corresponding to your directory structure.
    namespace YourNamespace;
    // Prevent direct access to the extension to enhance security.
    defined('AUTOMAD') or die();
    // The class name corresponds to the extension directory and file name.
    class YourExtension {
        // The main method of your extension. 
        // Note that the method name must be the same as the class name.
        public function YourExtension($options, $Automad) {
            // Your extension code goes here.
        }
    }
    ?>
    

    Now your extension can be used in templates as follows:

    <@ yournamespace/yourextension { key: "Value", ... } @>
    

    Composer Packages

    In contrast to local packages, the autoloading of PHP classes is handled differently in Composer packages. Since Composer registeres all used classes in file called autoload.php on installation, you are more flexible with the file structure of your package. The only important convention to follow is that the main function has the same name as the class itself. A good example for such a package is the MetaTags extension. Note that extensions using the Composer autoloader can be called in templates by using a combination of their namespace and their class name.

    <@ Automad/MetaTags { key: "Value", ... } @>
    

    To make sure your extension is autoloaded correctly by Composer, you will have to add a composer.json file with the following content to the root of your package:

    {
        "name": "vendor/extension-name",
        "description": "The extension description ...",
        "type": "automad-package",
        "keywords": ["extension"],
        "license": "MIT",
        "require": {
          "automad/package-installer": "^1.1"
        },
        "autoload": {
            "classmap": [""]
        }
    }
    

    Find more information about publishing extensions here.

    Options

    When the extension is called by a template, two parameters get always passed automatically by the template engine to the main method:

    1. An associative array of $options
    2. The Automad object

    The MetaTags extension shipped with Automad provides a good example of how to use options!

    Return Values

    The main job of an extension is to generate some kind of markup. The template parser will insert the extension's return value into the template's HTML. Therefore all extensions should generally end with a return statement.

    Autoloading Assets

    In case your extension requires Javascript or CSS files to be loaded, Automad takes care of that. All .js and .css files within an extension's directory - no subdirectory - get automatically appended to your template's <head> section when needed. To prevent loading these files automatically, you can place your .css and .js files in a subdirectory.

    Minified Files

    In case you have as well compressed versions of your files ending with .min.js and .min.css stored along with the uncompressed files, Automad will only load the compressed ones and skip the uncompressed files to avoid conflicts due to loading assets twice.


    Related

    System  ⁄
    Installing Packages — System

    Automad can be easily extended by installing custom packages. A package can be a theme or a PHP extension or a combination of both. The easiest way to install packages is to use the Packages section on the Automad dashboard. It also helps you to get an overview about available ...

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

    Template Language  ⁄
    Using Extensions — Template Language

    Extensions provide a convenient way of turning custom PHP code into Automad statements. Besides the fact that extensions have to be called by their names including their namespace, the syntax is the same as for Toolbox or pipe functions.

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

    Developer Guide  ⁄
    Developing Extensions — Developer Guide

    The extension interface provides a convenient way of extending Automad's core functionality with custom PHP code while still offering Automad's template syntax. There are basically two types of template language extensions: generic extensions and custom pipe functions. Check out ...

    Developing Extensions  ⁄
    Custom Pipe Functions — Developing Extensions

    Automad provides already some basic string manipulation functions to be used with the pipe operator. However, in some cases it my be necessary to use a custom function to modify the content of a variable. Custom pipe functions can be written in plain PHP. Thier basic setup is ...

    Developer Guide  ⁄
    Publishing Packages — Developer Guide

    Automad uses Composer as dependency manager. Therefore packages can be made public by submitting them as Composer packages to the Packagist website. Published Automad packages also automatically appear in the package browser. The process of releasing a package is basically the ...

    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 theme skeleton package available to help you getting started.

    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.

    Packages

    Browse free Composer packages and install themes and extensions for your Automad site.

    • Automad
    • Developer Guide
    • Developing Extensions
    • Generic Extensions
    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 ←
  • Developing Extensions
  • Generic Extensions
  • Custom Pipe Functions