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.
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", ... } @>
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.