Plugins
Last edited by Susan Ottwell on Aug 10, 2014.
What is a Plugin?
Plugins are similar to Snippets in that they are bits of PHP code that have access to the MODx API. The big difference, however, is in when the code executes. You put Snippets inside of a page or inside a template and they run when the page is viewed, whereas Plugins are set to execute during certain system events, e.g. saving a Chunk, or emptying the cache. So when a given event "fires", any Plugin "listening" for that event is executed. Once the Plugin's code has executed, control returns to the point after the spot where the System Event was triggered.
Every CMS uses some concept of "plugin", but the exact nomenclature may differ. In WordPress, for example, plugins are "hooked" to events called "actions" or "filters".
Since they execute during various events, Plugins aren't limited to front-end processing. Many events are triggered by events that take place only within the MODx Manager. There is a list of MODx System Events here.
The Event Model
MODx invokes System Events across its code processes to allow you to modify core functionality without hacking the core. These System Events can have any number of Plugins attached to them, and will execute each Plugin in rank according to its priority (lowest numbers first).
Handling an Event
In your Plugin, how you handle the output depends on the System Event you are in. For some system events, you return a value from the Plugin. For others, you access the output by reference and modify it.
If you need to know which event triggered your plugin (say, for a plugin that listens to more than one event), you can access the Event's name like so:
$eventName = $modx->event->name;
The code for a Plugin listening to more than one event looks like this:
$eventName = $modx->event->name; switch($eventName) { case 'OnWebPageInit': /* do something */ break; case 'OnWebPagePrerender': /* do something else */ break; }
Plugin Examples
Plugins can be used for a variety of different applications, below are a couple of examples:
Message the User:
Description: Send a custom message to the user as they create/edit a page... a custom header.
System Events: OnDocFormPrerender
$modx->event->output('Hi there user!');
Custom Validation
Description: Do some custom validation on saving a page resource
System Events: OnBeforeDocFormSave
// Do some logical stuff.... if validation failed: $modx->event->output('Something did not validate!'); return "This goes to the logs";
The trick here is that what you want to message the user has to be passed to the $modx->event->output() function; any text you want to write to the logs can simply be returned by the plugin. If you pass validation, simply return null.
The output you set in $modx->event->output() must not contain any HTML! Use plain text only! This is because the message is passed to the user via a Javascript modal window.
Return value must be a string. If your return value will be a number, concatenate it with an empty string.
Word Filter
Description: Filter words from a document before it's displayed on the web
System Events: OnWebPagePrerender
$words = array("snippet", "template"); // words to filter $output = &$modx->resource->_output; // get a reference to the output $output = str_replace($words,"<b>[filtered]</b>",$output);
Page-Not-Found Redirector:
Description: Redirects a user to selected document and sends a message
System Events: OnPageNotFound
System Settings:
- pnf.page: Error Resource ID
- pnf.mailto: Mail To Address
- pnf.mailfrom: Mail From Address
if ($modx->event->name == 'OnPageNotFound') { $errorPage = $modx->getOption('pnf.page'); if (empty($errorPage)) { $modx->sendErrorPage(); } else { $mailto = $modx->getOption('pnf.mailto'); if (!empty($mailto)) { // send a message to a local account $resourceId = $modx->resource->get('id'); $subject = 'Page not found'; $body = 'Someone tried to access document id '.$resourceId; $modx->getService('mail', 'mail.modPHPMailer'); $modx->mail->set(modMail::MAIL_BODY, $body); $modx->mail->set(modMail::MAIL_FROM, '$modx->getOption('pnf.mailfrom')); $modx->mail->set(modMail::MAIL_FROM_NAME, 'MODx'); $modx->mail->set(modMail::MAIL_SENDER, 'MODx'); $modx->mail->set(modMail::MAIL_SUBJECT, $subject); $modx->mail->address('to',$mailto); $modx->mail->setHTML(true); $modx->mail->send(); } $url = $this->makeUrl($scriptProperties['page']); $modx->sendRedirect($url, 1); exit; } }
See Also
- System Events
- OnBeforeCacheUpdate
- OnBeforeChunkFormDelete
- OnBeforeChunkFormSave
- OnBeforeDocFormDelete
- OnBeforeDocFormSave
- OnBeforeManagerLogout
- OnBeforeSaveWebPageCache
- OnBeforeWebLogout
- OnCacheUpdate
- OnChunkFormDelete
- OnChunkFormPrerender
- OnChunkFormRender
- OnChunkFormSave
- OnDocFormDelete
- OnDocFormPrerender
- OnDocFormRender
- OnDocFormSave
- OnDocPublished
- OnDocUnPublished
- OnLoadWebPageCache
- OnManagerLogin
- OnManagerLogout
- OnSiteRefresh
- OnUserChangePassword
- OnWebLogin
- OnWebLogout
- OnWebPagePrerender
- OnManagerPageBeforeRender
- OnTemplateVarBeforeSave
- OnTemplateVarSave
- OnTemplateVarBeforeRemove
- OnTemplateVarRemove
- OnBeforeEmptyTrash
- OnBeforeManagerLogin
- OnBeforeManagerPageInit
- OnBeforePluginFormDelete
- OnBeforePluginFormSave
- OnBeforeSnipFormDelete
- OnBeforeSnipFormSave
- OnBeforeTempFormDelete
- OnBeforeTempFormSave
- OnBeforeTVFormDelete
- OnBeforeTVFormSave
- OnBeforeUserActivate
- OnBeforeUserFormDelete
- OnBeforeUserFormSave
- OnBeforeWebLogin
- OnCategoryBeforeRemove
- OnCategoryBeforeSave
- OnCategoryRemove
- OnCategorySave
- OnChunkBeforeRemove
- OnChunkBeforeSave
- OnChunkRemove
- OnChunkSave
- OnContextBeforeRemove
- OnContextBeforeSave
- OnContextFormPrerender
- OnContextFormRender
- OnContextRemove
- OnContextSave
- OnEmptyTrash
- OnFileManagerUpload
- OnHandleRequest
- OnInitCulture
- OnLoadWebDocument
- OnManagerAuthentication
- OnManagerLoginFormPrerender
- OnManagerLoginFormRender
- OnManagerPageAfterRender
- OnManagerPageInit
- OnPageNotFound
- OnPageUnauthorized
- OnParseDocument
- OnPluginBeforeRemove
- OnPluginBeforeSave
- OnPluginEventRemove
- OnPluginFormDelete
- OnPluginFormPrerender
- OnPluginFormRender
- OnPluginFormSave
- OnPluginRemove
- OnPluginSave
- OnPropertySetBeforeRemove
- OnPropertySetBeforeSave
- OnPropertySetRemove
- OnPropertySetSave
- OnResourceGroupBeforeRemove
- OnResourceGroupBeforeSave
- OnResourceGroupRemove
- OnResourceGroupSave
- OnRichTextBrowserInit
- OnRichTextEditorInit
- OnRichTextEditorRegister
- OnSiteSettingsRender
- OnUserActivate
- OnUserBeforeRemove
- OnUserBeforeSave
- OnUserFormDelete
- OnUserFormSave
- OnUserNotFound
- OnUserRemove
- OnUserSave
- OnWebAuthentication
- OnWebPageComplete
- OnWebPageInit
Suggest an edit to this page on GitHub (Requires GitHub account. Opens a new window/tab).