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', '[email protected]');
}
}

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 [email protected])

$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 {}