Generic Extensions
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:
- An associative array of
$options - 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.