Plugin Introduction & Primary Plugin Class

Extend and add functionality to Enact using the powerful, but streamlined plugin process.

Building plugins is a more involved task than just writing/designing Twig template or HTML. You will need to understand PHP (including objected oriented programming and name spaces), JavaScript (including some React), potentially SQL, and some basic understanding of how the Disco PHP Framework operates.

In a way plugins are like mini-applications, potentially having their own database tables, REST-ful routes, templates and template functionality, custom fields and so on.

Plugin Strucuture#

All plugins live in the enact/plugin/ folder and each plugin lives within a self contained all lower-case directory, typically named after the plugin.

Every plugin at a minimum must contain at least one file, the Plugin.php file. This file informs Enact of some basic details about the plugin and contains the methods for extending, adding, and hooking functionality across the CMS. In some cases this may be the only PHP necessary to achieve your goals, but more in-depth plugins will typically consist of other files.

You can generate a barebones plugin and directory structure using the CLI tools:

php public/index.php createPlugin 'MyPluginName'

This will generate you a directory structure in enact/plugin/ like so:

  • mypluginname/

    • app/

      • config/

      • controller/

      • model/

      • record/

      • router/

      • template/

    • composer.json

    • Plugin.php

    • resource/

Primary Plugin Class#

<?php
namespace MyPluginName;

class Plugin extends \Enact\Plugin {

    function name(){
        return 'MyPluginName';
    }

    function version(){
        return '1.0.0';
    }

}

return new \MyPluginName\Plugin;

Above is the absolute minimum required for Enact to recognize your plugin and make it installable via the Plugin management screen in the CMS.

Notice that you MUST return a new instance of the primary plugin class from the Plugin.php file.

You can access your primary plugin class at any time by calling:

enact()->with('Plugin')->getPlugin('YourPluginName');

or

\YourPluginNamespace\PluginName::instance();

Methods#

name() :

Return a string name of your plugin with only alpha characters.

displayName() :

Return a string name of your plugin as presented to end users, can contain any characters.

version() :

Return the current version of your plugin. Your plugin versions should be supplied using semantic verisioning and only contain numbers and periods.

creator() :

Return a string with the creators company, organization, or personal name.

website() :

Return a FQDN string to the creators website.

gitHubLink() :

Return a FQDN string with the link to the github repo for this plugin. It's important that you provide this if you want users to easily be able to download and install updates for your plugin as you release them. Learn more on the migrations & updates page.

onInstall() :

Execute the logic necessary to install your plugin. This will most likely include creating any database tables used by your plugin.

onUnInstall() :

Execute the logic necessary to un-install your plugin. This will most likely involve removing any database tables used by your plugin and cleaning up any temporary files.

onUpdate() :

Execute the logic necessary to update your plugin to a new version level.

configUri() :

If your plugin has a page which provides configuration controls return the URI/slug from this function. Users will be directed here after install if it exists. Use the enact_cpSlug() function to generate your URI/slug when returning it, which you pass a string and returns you a slug appropriate to the current control panel slug as configured by the site administrator. By default the control panel area of Enact is located within /admin/ but it can be changed at anytime by the site owner, so creating slugs with the default string hard encoded is considered a very bad practice.

onBoot() :

Perform the necessary bootstrapping for your plugin. This is called on eachh request into the application.

You should perform these tasks in this function:

  • Include your autoloader or require any classes your plugin uses if not using a autoloader. Its highly recommended you use a autoloader, such as composer. You will notice if you used the CLI to generate your plugin structure a composer.json file is made ready for your to run composer update and be off to the races.

  • Event hooks.

  • Define any constants.

template() :

Return an instance of the class that represents your plugin in the Twig template, accessed via enact.plugin.MyPluginName.

See Plugin Templating for more information.

templatePath() :

Return the path relative to your plugin directory where your templates are stored.

See Plugin Templating for more information.

fields() :

Return an array containing the fields your plugin provides.

See Plugin Fields for more information.

richTextFieldExtensions() :

Return an array of resources that extend the functionality of the Rich Text Editor.

See Extending The Rich Text Editor for more information.

menuItem() :

Return an array containing menu items provided by your plugin.

See Plugin Navigation for more information.

menuSettingItems() :

Return an array of arrays containing menu setting items provided by your plugin.

See Plugin Navigation for more information.

menuUserItems() :

Return an array of arrays containing menu user items provided by your plugin.

See Plugin Navigation for more information.

permissions() :

Return an array of permissions specific to your plugin.

See Plugin Permissions for more information.

privateRoutes() :

Set up any private (user session authenticated) routes your plugin provides.

See Plugin Routing & Controllers for more information.

publicRoutes() :

Set up any public routes your plugin provides.

See Plugin Routing & Controllers for more information.