modRequest

A module request (aka "modRequest") is a specialized event dispatching utility designed to send data to many modules, and receive responses from each recipient module (when applicable). All server side modRequests are executed synchronously.

Example

Where is a modRequest applicable?

Consider the page editor, provides a list of widgets that can be embedded into a content page. The page editor module needs a way to collect all the registered widgets from other modules. On the other hand, modules should be able to register a widget without assuming the page editor is even installed.

The page editor can execute a modRequest called page_editor_get_widgets. Other modules can register listeners for that modRequest, and define a callback for when it is executed. See creating a modRequest listener and executing a modRequest.

Creating a ModRequest Listener

Register the listener

ModRequest listeners are registered inside the init() method of a module's {module}Config.php file. The first parameter of modRequest::listen() is the name of the request. The second parameter is the controller and method to be executed: {controller}@{method}.

<?php
use sa\application\modRequest;
​
class MemberConfig extends moduleConfig {
    public static function init() {
        modRequest::listen('page_editor.get_widgets', 'MemberModRequestController@getMemberListWidget');
    }
}

Listener Callback

A module's modRequest listeners are generally grouped up in a dedicated modRequest controller. Notice the controller does not extend sa\application\controller. This special controller type does not respond to HTTP requests, so it does not need the methods offered by the base controller class.

The getMemberListWidget() method is our listener. It receives 1 parameter $data, which holds all the content returned by other listeners. The method simply appends its content to the array and returns the bundle. It's usually bad practice to modify the content already existing inside of $data.

<?php
class MemberModRequestController {
    public function getMemberListWidget(array $data) {
        $data[] = array(
            'name' => 'Member List',
            'html' => '...'
        );
        
        return $data;
    }
}

Parameters

Parameter	Type	Required	Default	Description
$event	string	yes		A unique label for the event. By convention, should only contain underscores and alphabetic characters, and be prefixed with module name.
$action	string	yes		The controller and method to be executed, delimited by the @ symbol. (e.g PayPalModRequestController@getPaymentProcessor)
$priority	int	no	1	A numeric weight which sets the order of which the listeners should be executed. Listeners with higher priority value will be executed first.
$name	string	no	null	A unique name for the specific listener. By convention, base SiteAdmin modules should give this field a value to all the listener to be overwritten by child modules.
$allow_js	boolean	no	false	If true, this modRequest will be executable from the browser via the modRequest JS API.
$is_protected	boolean		false	If true, a user must be logged in to execute the modRequest.

Executing a modRequest

<?php
use sa\application\modRequest;
​
$pageEditorWidgets = modRequest::request('page_editor.get_widgets');

Parameters

Event	Type	Required	Default	Description
$event	string	yes		A unique label for the event. By convention, should only contain underscores and alphabetic characters, and be prefixed with module name.
$default	mixed	no	null	The default data returned by the modRequest, if no listeners respond.
$data	mixed	no	null	The default values to be sent to each listener. This value will be modified by each listener, then returned.
$is_js_request	boolean	no	false	Flag to identify if the modRequest is being sent from the browser client, or server.

Conventions

ModRequests

The event label for a modRequest should adhere to the format {module}.{action} or {module}.{domain}.{action}. The label should be composed of lower case alphabetic characters. Module and action names should be delimited by underscores.

// {module}.{action} example
modRequest::listen('page_editor.get_widgets')
​
// {module}.{domain}.{action} example
modRequest::listen('page_editor.navigation.get_nav_items')

Listeners

ModRequest listeners should exist in a dedicated controller, which does not extend any other class. Modules with many listeners may use many modRequest controllers to organize concerns, but most modules will use a single controller. The controller name should follow the format {domain}ModRequestController.

// Example of a generic modRequest controller
class PaymentsModRequestController {}

// Examples of specific modRequest controllers (for larger modules)
class OrdersModRequestController {}
class CustomersModRequestController {}
class ProductsModRequestController {}