MODx From the Inside

System Events

For the most part, the events' naming convention makes it pretty clear at what point they are invoked. However, the events used in the parser itself are worth taking a closer look at.

• OnWebPageInit - This is the first event to be invoked when generating a page. The parser has used the HTML string (alias or id) to determine which document has been requested. The document's ID is loaded into the documentIdentifier variable. These arrays and variables are available:
  • $modx->config[]
  • $modx->documentIdentifier
  A documentMethod variable is also available, to indicate whether it's by ID or by alias, but this is only for internal parser use.
• OnLogPageHit - as soon as it's determined which document this is, immediately after the onWebPageInit event, a check is made whether or not the document's 'track_visitors' field is set to 1; if it is, this event is made available.
• OnPageNotFound - Actually, this event is invoked in more than one situation. Of course one would expect it to be invoked if the document requested is not found, and it is. But it is also invoked if the page is unpublished and the user is not logged in as a Manager user, or if the Manager user does not have permissions to view unpublished documents. It is also invoked if the document is tagged for deletion. Since it is invoked immediately before redirecting the visitor to the "Not Found" error page, it would be a good place to customize your 404 pages. Available arrays and variables:
  • $modx->config[]
  • $modx->documentIdentifier
• OnLoadWebPageCache - this event is called if the page is being loaded from cache rather than being generated. The document's properties were serialized and included in the cache file; this is now unserialized and loaded into the documentObject array. The content from the page's cache file is loaded into the documentContent. Any document groups the document belonged to are checked against the user's SESSION to make sure the user has permission to view the page. These arrays and variables are available:
  • $modx->config[]
  • $modx->documentIdentifier
  • $modx->documentObject[]
  • $modx->documentContent
  The documentContent will contain any snippet tags that were originally called uncached; the processing that generated the cached page has already converted the [! ... !] tags to ordinary [[ ... ]] snippet tags. The uncached snippets will now get processed and their output inserted into the page before the page is served. The documentContent, therefor, will not necessarily be the same later in the parsing process.
• OnPageUnauthorized - This event is invoked if the user does not have permission to access the page, before the user is redirected to the site's "Unauthorized" page. The variables and arrays available depend on whether or not the document was cached. If the document was not cached, the document's document groups are retrieved and the user's SESSION is checked to make sure he has permission to access the page. This is done before the documentObject is loaded from the database. These arrays and variables are available:
  • $modx->config[]
  • $modx->documentIdentifier
  If the document is cached, since its properties are recovered from the cache file and the documentObject is rebuilt and used for checking the user's web groups against the document's document groups, these variables and arrays are available:
  • $modx->config[]
  • $modx->documentIdentifier
  • $modx->documentObject[]
  • $modx->documentContent
  Note that if the site cache has been cleared and this is the first time this document has been requested since then, there won't be a cache file, and the document will be generated from scratch. The documentObject array and the documentContent won't be available. That being the case, it would not be a good idea to depend on these values being available to your plugin code.
• OnLoadWebDocument - this event is invoked when the document's template (or its content, if it uses a blank template) is loaded, before any parsing is begun. At this point, these variables and arrays are available:
  • $modx->config[]
  • $modx->documentIdentifier
  • $modx->documentObject[]
  • $mdox->documentName
  • $modx->documentContent
  The documentObject array contains the fields from the site_content table of the database for this document. The documentContent variable contains the raw unparsed HTML of the template (or content).
• OnParseDocument - After the OnLoadWebDocument event, the raw documentContent is passed to the ParseDocumentSource() function. The documentContent is loaded into an internal $source variable, which is in turn loaded into the documentOutput, then this event is invoked. So we now have the following variables and arrays available:
  • $modx->config[]
  • $modx->documentIdentifier
  • $modx->documentName
  • $modx->documentObject[]
  • $modx->documentContent
  • $modx->documentOutput
  After the event is processed, the documentOutput is again loaded into the internal $source variable so that any changes our plugin may have made to the documentOutput will be used in the rest of the processing.
• OnBeforeWebSaveCache - this event is invoked immediately before the document is cached. The documentObject array has the document's assigned document groups (if any) added to it, then the array is serialized. This and the documentContent are written to the cache file for this document.
• OnWebPageComplete - The page content has been parsed (or loaded from cache), but there still may be more passes through the parser. Uncached snippets may still need to be processed, and chunks and TVs may have had MODx tags in them that need another pass through the parser. These variables and arrays are available:
  • $mdox->config[]
  • $modx->documentIdentifier
  • $modx->documentName
  • $modx->documentObject[]
  • $modx->documentContent
  • $modx->documentOutput
• onWebPagePrerender - this is the last event of the document parsing process, immediately before the finished document is sent to the server. This event is probably the one most commonly used; since the entire document is available in the documentOutput variable, additional parsing and modifications to the finished document can be added here. For example, the email obfuscation plugins use this event to modify all links that are mailto: links.

System events are registered with the system_eventnames table. A developer creating a module or snippet that uses events can add its events to the database, providing users with checkboxes along with the rest of the registered System Events so they can use your events in a plugin. An example of this would be the WebLogin snippet.

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.

Security Code:

Articles

• How MODx Works
• How MODx Templates Work
  • Using Chunks
• How Template Variables Work
  • Using TV Input Types
  • Using TV Output Widgets
  • Using TV Bindings
• How Snippets Work
  • Creating Snippets
• How Plugins Work
  • System Events

• Back to sottwell.com

© 2008 - 2010 sottwell.com