How MODx Plugins Work
Plugins are custom code that is inserted at specified points in the various processes of the core of MODx. They make use of event functions that are sprinkled throughout the parser and the other processing scripts, such as displaying the forms for creating or editing documents, saving documents, snippets, etc. and at various points during user logins. In this manner it is possible to customize the core behavior of MODx without changing the core scripts.
Plugins are created in the same manner as most other MODx content; there is a form with a few fields for its name, a description, and a textarea field for the plugin code. The key to using a plugin is the System Events tab. This tab contains checkboxes enabling the plugin to "listen" as it were for whatever events are checked. The code in the plugin is executed at the point in the MODx script where that event function is specified.
Third-party snippets can also use this "event" model to allow customization without actually hacking the original script. One such snippet is the WebLogin snippet. Another snippet is the TreasureChest e-commerce snippet. These snippets make use of plugins by inserting their event names into the system_eventnames table in the MODx database on installation, and calling the invokeEvent function.
Creating a Plugin
To create a plugin, go to Resources, Manage Resources in the main manager menu.
- Select the Plugins tab, and click on the New Plugin link.
- Give the plugin a name, and a description.
- The next checkbox will enable or disable the plugin. A disabled plugin won't run.
- The next checkbox is to prevent users who have not been assigned the Administrator role from editing or deleting the plugin.
- Enter the php code for the plugin in the Plugin code textarea field.
The Configuration tab has four fields:
- Existing category or New category - This has no effect on the plugin's behavior; it's strictly for organizing your plugins. Either select an existing category from the drop-down list, or enter a new category.
- Import module shared parameters - If the plugin works with a module, you can share the module's parameters. The module has to be configured to share its parameters with your plugin, then the module or modules will be available for selection in the drop-down.
- Plugin configuration - any global configuration settings for your plugin. These settings will be available as ordinary PHP variables to your plugin code. A common configuration might be the path to the plugin's include or other support files.
The System Events tab is where you select the event or events you want your code to intercept.
Standard plugin code
While you can just have your plugin's code in the plugin itself, it is often better to use external .php files and have your plugin code include the external file:
include '../assets/plugins/myPlugin/myPlugin.php';
While you can code a function any way you are comfortable, it is a good idea to use the Event object so that you can take advantage of the features of the Event object. If you will be using more than one event in your plugin, then a switch statement will let you catch which one is being triggered.
// Get a reference to the event
$e = & $modx->Event;
switch ($e->name) {
case "OnDocFormRender":
include $path.'docform.inc.php'; //$path is from configuration
break;
}
If your code includes function definitions, you need to declare the $modx object global at the beginning of your function definition in order for all of the API functions to be available.
function myFunction() {
global $modx;
...
}
If you wish your plugin to display something on the finished page, load the output into a variable such as $output, then use the Event class function $e->output($output). The plugin processing code will return the variable's content, adding it to the content of whatever you are modifying. An example of this can be seen in the Bottom Button Bar plugin, which adds the Save/Duplicate/Delete/Cancel buttons at the bottom of most of the Manager resource editing pages.
// Add the new bar to the output $e->output($output);
There are several plugins included with the default MODx installation, so you can open them for editing and look at the code to get examples and ideas. They were all written by different people, so they often have different structures. You can choose a structure that suits your coding style best; they all work just the same.
Plugin code is processed using the PHP eval() function.
Available Data
It is important to be aware of what data is available at various events. For example, the OnPageUnauthorized event is invoked just before the $modx->documentObject array is created. This makes sense, because if the viewer doesn't have permission to view the page and is being sent to the unauthorized page, there's no need to further process the document. So while the $modx->documentIdentifier is available, a plugin using this event would need to do its own database query to get any further information about this document. However, the core arrays and objects, such as the $modx object, the $modx->db object and the $modx->config[] array are available.
The PHP system arrays are always available, such as $_POST, $_COOKIE and $_SESSION.
Comment On This Article
Do you find something unclear? Did I miss something or get something wrong? What do you like or not like about this chapter? Please do not ask for help here; use the forums if you need help.
