Portal Registration Hook Reference

The following is a reference for all registration hooks offered within the portal’s core code. This reference presumes you are familiar with how registration hooks work and that you understand the terminology in use. For more information on these topics, please review section 3 of the portal developer’s guide: Understanding and using registration hooks.


INIT

Description: Arbitrary functions to be executed each time the application is accessed. The functions will be executed after the session has been loaded but before any other other actions are taken (such as form handling or routing).

Trigger: Unused except for logging.

Args:

  • callbackstring – (required) A fully qualified and namespaced function name without arguments or parentheses.
  • argsarray – Arguments to be passed to the function specified in the callback.

Example:

__register('INIT', 'demo', ['callback' => '\Papal\Log::write', 'args' => ['Demo']]);

PERM

Description: Defines a slug to appear as a permission which can be assigned to various user roles. The slug itself has no value in and of itself; rather it’s up to the developer to make use of the slug when implementing permissions-related functionality in their modules.

Trigger: The slug to be defined as the permission. Please use a proper slug beginning with a lowercase letter and consisting of lowercase alphanumeric characters and hyphens.

Args: Unused.

Examples:

__register('PERM', 'search');
__register('PERM', 'system-alerts');

FORM

Description: Defines a handler for form submissions. The portal will look for a POST data key that matches the trigger and will execute the specified function. Arguments may optionally be passed to the function by specifying an array of addtional POST data keys from which the values will be taken.

Trigger: The POST data key that the portal is to look for.

Args:

  • callback  – string – (required) A fully qualified and namespaced function name without arguments or parentheses.
  • argsarray – POST data keys from which to use the values for as arguments to be passed to the function specified in the callback.
  • requiresstring | array – Permission triggers required by the user submitting the form.
  • requiresComparestring – Accepts the literal values ‘AND’ and ‘OR’. If the ‘requires’ parameter is an array, pass AND to require all permissions or pass OR to require any one of the specified permissions.

Example:

__register('FORM', 'testForm', ['callback' => '\Papal\Log::write', 'args' => ['content']]);

The above presumes a $_POST variable with structure similar to the following:

array(2) {
  ["testForm"]=>
  int(1)
  ["content"]=>
  string(4) "Test form content."
}

Additionally you could specify that the user submitting the form be required to have both the search and system-alerts permissions:

__register('FORM', 'testForm', ['callback' => '\Papal\Log::write', 'args' => ['content'], 'requires' => ['search', 'system-alerts'], 'requiresCompare' => 'AND']);

VIEW

Description: Associates a URL with a function that outputs content, such as HTML or JSON. This can also assign a context to the session which can be used by other parts of the application to determine things such as conditional menu display.

Trigger: A string containing the URL to route to the view with optionally embedded regular expressions for pattern matching. An array of each URL component is passed as an argument to the specified callback.

Args:

  • callbackstring – (required) A fully qualified and namespaced function name without arguments or parentheses. Preferably one that outputs content usable by something like a browser or cURL.
  • contextstring – The context of the view.

Examples:

__register('VIEW', "/admin", ['callback' => '\Papal\View\Admin::display', 'context' => 'admin']);
__register('VIEW', "/admin/users/[0-9]+", ['callback' => '\Papal\View\UserEdit::display', 'context' => 'admin']);

CRON

Description: Functions to be executed whenever the cron.php file is executed. This is similar to the INIT registration hook, however a cron job should be set up on a reasonable schedule to ensure the regular execution of these functions. In the future, scheduling will occur via arguments passed to the registration hook. For now it executes the function with every execution of the cron script.

Trigger: Unused except for logging.

Args:

  • callbackstring – (required) A fully qualified and namespaced function name without arguments or parentheses.
  • args  – array – Arguments to be passed to the function specified in the callback.

Example:

__register('CRON', 'sessionClean', ['callback' => '\Papal\Session::clean']);

MENU

Description: Adds an entry to the menu.

Trigger: The menu link destination. Relative URL paths can be used, but should be used with caution. It’s preferable to link URLs within the application by using their path relative to the base URL. If you’re using a URL for a page outside of the application, perhaps ask yourself why that item needs to be in the menu in the first place.

Args:

  • menustring – (required) Which menu to include the item in. The portal includes three default options (‘main’, ‘sub’, and ‘user’) however developers are free to implement their own menus either in the sidebar or in other parts of the application.
  • labelstring – The text to appear as/with the menu item (if applicable).
  • altstring – The HTML alt text for the menu item.
  • iconstring – The icon to appear as/with the menu item (if applicable). By default the portal uses the free, solid icon set from FontAwesome.
  • priorityint – Where in the menu order the item should appear. Low numbers are placed first whereas high numbers are placed last.
  • permsarray – If the user isn’t capable of any of the permissions listed here, the menu item will not display.
  • contextarray – Only display the menu item if an item in this array matches the context of the current view.

Example:

__register('MENU', "/infrastructure/datacenters", ['menu' => 'sub', 'label' => "Datacenters", 'alt' => "Datacenters", 'icon' => "hotel", 'priority' => 10, 'perms' => ['manage-infrastructure'], 'context' => ['infrastructure']]);