Pepper Event Handlers and Methods

This article is part of a series on developing Pepper for Mint introduced here.

Now that we’ve gotten the Pepper properties out of the way, let’s take a look at the default methods and event handlers:

  • onPepperLoad()
  • onUpdate()
  • update()
  • isCompatible()
  • onInstall()
  • onJavaScript()
  • onRecord()
  • onDisplaySupplemental()
  • onDisplay()
  • onAfterDisplay()
  • onDisplayPreferences()
  • onSavePreferences()
  • onCustom()
  • onUninstall()

These default functions will be called directly by Mint in response to a particular event. Let’s go right down the list, in the order they are likely to be called.

onPepperLoad()

The optional onPepperLoad() event handler fires immediately after the $Mint object is created as Mint loads all installed Pepper. It serves as a replacement for individual Pepper constructors. Because Mint manages loading Pepper data and preferences, and information about the Pepper and its panes are now inherited properties of the parent Pepper class, there’s not much left for this handler to do. May be useful down the road.

onUpdate()

The onUpdate() event handler fires when Mint is being updated. Could be used to allow a Pepper to support multiple versions of Mint with different feature sets.

update()

The update() method is called when Mint detects that the hard-coded version of a Pepper is greater than Mint’s internal version for a Pepper. Use to update existing Pepper preferences or data to be compatible with the current Mint and Pepper version. Return true on success

isCompatible()

It is each Pepper’s responsibility to check compatibility with the server software and the installed version of Mint. This method should return an associative array. The first index, isCompatible, should be a boolean indicating whether this Pepper is compatible or not. The second, optional index explanation provides an upgrade or helpful message specific to the server software or current version of Mint as a formatted HTML string. Use HERE doc syntax for complex messages. (Please provide a helpful explanation with upgrade info if your Pepper is not compatible.)

onInstall()

The onInstall() method is called once immediately after the Pepper has been installed. It is useful for notifying existing Pepper of the new Pepper’s presence—this method is not intended for adding columns or tables to the Mint database. Please use the $manifest and $moderate properties of the Pepper class to add columns or custom tables to the Mint Database.

onJavaScript()

The onJavaScript() event handler fires when the Mint JavaScript include is generated. This function should directly output (not return) any JavaScript required by the Pepper. This can by done a number of ways including echoing a string or HERE doc, or including an external file (use the js extension to retain your editor’s JavaScript syntax coloring) as in the sample below.

function onJavaScript() 
{
    $js = "pepper/developer-name/pepper-name/script.js";
    if (file_exists($js))
    {
        include_once($js);
    }
}

We’ll cover coding conventions and requirements for the Mint JavaScript include later, when we build our own Pepper.

onRecord()

The onRecord() event handler fires after the Mint JavaScript include has validated the hit and the Mint record method is called. It operates on existing $_GET values, values generated as a result of the Pepper’s optional JavaScript output or existing $_SERVER variables. Any changes made to the Pepper’s data array in this event handler will be saved automatically. Values meant for the Mint visit table should be returned as an associative array with each column name as an index with the corresponding the value to be stored in that column as the value. This handler must return an array—even if it is just an empty array.

onDisplaySupplemental()

The onDisplaySupplemental() method is used to output any additional CSS or JavaScript required by a pane and is called before the onDisplay() method. CSS should be included either via the <link> tag or inline in a <style> tag. JavaScript should be enclosed in a <script> tag.

onDisplay()

The onDisplay() event handler fires when Mint generates the display view or when an individual tab is loaded or refreshed. It should return the HTML contents of an individual tab. This handler is often a traffic handler, consisting of nested switch statements that pass the HTML generation off to functions specific to each tab. While there is no requirement for this, these functions usually conform to the following naming convention, getHTML_<PaneName><TabName>. This function may be omitted for pane-less Pepper.

onAfterDisplay()

The onAfterDisplay() method gives Pepper the ability to write display-side Javascript to manipulate the Mint interface in new ways. While the onDisplaySupplemental() method provides a hook for pane-specific CSS or JavaScript additions, onAfterDisplay() doesn’t even require a paned Pepper. JavaScript should be enclosed in its own <script> tag and is output after all panes but before the footer.

onDisplayPreferences()

The onDisplayPreferences() event handler fires when Mint generates the Preferences view. This handler should return an assoicative array (indexed by pane name) that contains the HTML contents of that pane’s preference. Preferences used by all panes in this Pepper should be indexed as Global and appear first in the array. This function may be omitted if the Pepper doesn’t utilize preferences.

onSavePreferences()

The onSavePreferences() event handler fires after clicking the Done button in the Preferences view. This handler should validate any user input requested by the onDisplayPreferences() handler and assign the validated input to the $prefs property. This function may be omitted if the Pepper doesn’t utilize references.

onCustom()

The optional onCustom() event handler fires when the custom argument appears in the query string of a request or a form is posted with MintPath set to “Custom”. The Pepper is responsible for providing additional variables and logic to handle those variables. The function can return anything or nothing—whatever is appropriate for its use. The $prefs and $data properties are automatically saved to the database by Mint after this handler is called.

onUninstall()

The onUninstall() method is a Pepper’s dying breath. Use it to notify other Pepper that it is being uninstalled (most useful for tandem preferences). Mint still handles uninstallation so database manipulation is unnecessary; use only for notification.

That covers the basics. Next we’ll walk through building a simple Pepper. Questions? Visit the Mint Forum.

Previous
Pepper Properties
Next
Example Pepper: Window Width
Author
Shaun Inman
Posted
October 21st, 2005 at 2:11 pm
Categories
PHP
Mint
Web