Events

The back-office of Novius OS is one “big HTML page”. Actions performed in one tab can affect other tabs (ex: adding, modifying or deleting an item).

An event system has been established to enable the various interface elements to communicate with each other.

On the one side, the interface elements are listening to events (by binding callbacks functions) by connecting to dispatchers.
On the other side, the different actions trigger events, usually returned by AJAX requests (see $container.nosAjax()), which are then dispatched to all interface elements via dispatchers.

Dispatched events are executed immediately on the current active tab or popup (the one which has focus). For other tabs (or popups), they are executed only when the tab or popup becomes active / focused.

dispatcher
A DOM element that receives system events. The child elements of the dispatcher can listen for events by connecting to it.
Each tab and popup have a dispatcher.

Structure of an event

Event
Event.name
string
Required
Event name. For events on a Model, the name is the Model name, including its PHP namespace.
Event.id
int or [int]
For events on a Model, ID(s) of the item to which they relate.
Event.action
string
Name of the action item that triggered the event. Ex: insert, update or delete.
Event.context
string or [string]
Context of the item that triggered the event. See Multi-Contexts.

nosListenEvent

$container.nosListenEvent(event, callback[, caller])
Listen one (or many) event(s), i.e. register a callback function to be called when the event occurs.
Listening will be on current dispatcher (closest relatives in the DOM element in jQuery container).

For the callback function to be triggered, listened and triggered events should not match exactly. The listened event can just match one property of the triggered event.

Arguments:
  • event (mixed) – {} or [{}]. Required. JSON event to listen.
  • callback (function) – Required. The callback function to execute when the event occurs. The function takes as parameter the triggered event.
  • caller (string) – Caller name. If set, can stop listening to specific listener. See $container.nosUnlistenEvent().
// Listen all events with name 'Nos\Model_Page'
$(domContext).nosListenEvent({
        name: 'Nos\Model_Page'
}, function(event) {
        // ...
}, 'caller');

// Listen all events with the 'Nos\Model_Page' name and 'insert' or 'delete' actions
$(domContext).nosListenEvent({
                name: 'Nos\Model_Page',
                action: ['insert', 'delete']
        },
        function(event) {
                // ...
        });

// Listen all events with the 'Nos\Model_Page' name and 'insert' or 'delete' actions,
// or events with the 'Nos\Model_Page' name and the 'main::en_GB' context
$(domContext).nosListenEvent([
        {
                name: 'Nos\Model_Page',
                action: ['insert', 'delete']
        },
        {
                name; 'Nos\Model_Page',
                context; 'main::en_GB'
        }
], function(event) {
        // ...
});

nosUnlistenEvent

$container.nosUnlistenEvent(caller)

Stop listening events for a specific caller. See caller param of nosListenEvent.

Arguments:
  • caller (string) – Caller name.
$(domContext).nosUnlistenEvent('caller');

nosDispatchEvent

$.nosDispatchEvent(event)

Dispatches an event to all available dispatchers.

Arguments:
  • event (JSON) – See Event.
// Dispatch event, page with ID 4 has been create with 'main::en_GB' context
$.nosDispatchEvent({
        name: 'Nos\Model_Page',
        action: 'insert',
        id: 4,
        context: 'main::en_GB',
});