The extension interface provides a convenient way of extending Automad's core functionality with custom PHP code while still offering Automad's template syntax. Extensions can be used like normal Toolbox methods. Check out the source of the Mail extension shipped with Automad to quickly get started with a simple example.
There are two types of extensions: local extensions and Composer extensions. The main difference between them is the way autoloading PHP classes is handled.
The easiest structure for an Automad extension is basically just a PHP file in a directory of the same name under packages. While it is not required, it is recommended to create a unique directory as your namespace and place your extension in there. 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", ... } @>
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", ... } @>
Find more information about publishing extensions here.
When the extension is called by a template, two parameters get always passed automatically by the template engine to the main method:
$optionsThe Mail extension shipped with Automad provides a good example of how to use options!
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.
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.
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.