Available in Ariadne > 2.7.3.

ar\events

This module allows you to fire events and listen to them. This is a very powerful way to create re-usable modules with a simple mechanism to extend their functionality.

The event system is modelled on the W3C DOM event system. This means that there is a capture and a bubble phase and that you can cancel the event cascade and prevent a default action seperately. Events are fired on a path, by default the path of the current object. Events start off in the capture phase, starting at the root node - '/' , and moves to the object where it was fired. If it isn't cancelled by then, the event enters the bubble phase, starting at the current object and moving back to the root node.

If multiple event handlers are added at the same node, they will be handled in the order in which they were added.

Firing an event:

<pinp>
// do something
$result = ar('events')->fire( 'myEvent', $myData );
if ($result) {
$myData = $result;
}
// do something else
</pinp>

Handling an event (myhandler.html):

<pinp>
$event = ar('events')->event();
$event->data['test'] = 'Some value';
if ($preventDefault) { // just an example
$event->preventDefault();
}
if ($cancel) { // just an example
return false;
}
</pinp>

Adding a listener:

<pinp>
ar('events')->listen( 'myEvent' )->call(
'myhandler.html',
array( 'argument1' => 'a value' )
);
</pinp>

An event listener must be defined before the corresponding event is fired. You can do this in any template, but often the config.ini template is the best fit. This template is always called when an object is first loaded from the store.

methods

(object)callRegister a template to be called whenever the listener is triggered.
(object) capture Create a new event handler in the capture phase.
(object) event Returns the current event or null.
(mixed) fire Fires a new event.
(object) get Changes the path on which to listen or fire events.
(object) listen Create a new event handler in the bubble phase.
(void)removeRemoves a registered listener.

call

(object) $eventsInstance->call( $template, $args = array() )

(mixed)$templateEither a string with the name of the template to call, or a callable function, e.g. created with mod_util::create_function()
(array)$argsArguments that will be passed to the called template. If the template is a callable function, these will be passed as the arguments to that function.

Call creates a new event listener and registers it. It returns a listener object of type ar_eventsListener.

<pinp>
$listener = ar('events')->listen( 'myEvent' )->call( 'mytemplate.html', $args );
</pinp>

The listener can be removed - unregistered - by calling its remove() method. 

<pinp>
$listener->remove();
</pinp>

capture

(object) ar('events')->capture( $eventName, $objectType = null )

(string) $eventName The name of the event to capture.
(string) $objectType The object type to capture events on.

With this method you can create an event listener which listens in the capture phase.

<pinp>
ar('events')->capture( 'myEvent' )->call( 'mytemplate.html', $args );
</pinp>

Whenever a template fires the 'myEvent' event, your template 'mytemplate.html' will be called. If that template returns false, no other event handlers, either in the capture or bubble phase, will be called.

event

(object) ar('events')->event()

Returns the current event object, if any. Any additional data sent with the event when fired is accessible as $event->data. Any changes made will be passed on to any other event handler and ultimately returned to the template that fired the event.

<pinp>
$event = ar('events')->event();
$event->data['test'] = 'I was here';
</pinp>

The event object has one method, preventDefault:

(bool) $event->preventDefault()

If this method is called while handling an event, the ar_events::fire() method that created the event will return false.

fire

(mixed) ar('events')->fire( $eventName, $eventData = array(), $objectType = null ) 

(string) $eventName The name of the event to fire.
(mixed) $eventData Optional additional data for the event.
(string) $objectType The object type to fire an event on. Defaults to the type of the current object. Set this to false to prevent this.

Fires an event. Any listeners listening to this event will be called, in order. If no handler calls preventDefault() on the event object, this method will return $eventData, incorporating any changes made by event handlers on the way. If preventDefault() is called, this method will return false.

<pinp>
$result = ar('events')->fire(
'myEvent',
array( 'test' => 'Is someone here?' )
);
if ($result) {
// do your thing
} else {
// default action prevented
}
</pinp>

get

(object) ar('events')->get( $path )

(string) $path The path to change to, to then add a listener or fire an event.

This method allows you to fire events or add listeners on another path than that of the current object.

<pinp>
ar('events')->get('/')->capture( 'myEvent' )->call( 'myTemplate.html' );
</pinp>
<pinp>
ar('events')->get('/a/path/')->fire( 'someEvent' );
</pinp>

listen

(object) ar('events')->listen( $eventName, $objectType = null )

(string) $eventName The name of the event to listen for.
(string) $objectType The object type to listen on.

With this method you can create an event listener which listens in the bubble phase.

<pinp>
ar('events')->listen( 'myEvent' )->call( 'mytemplate.html', $args );
</pinp>

Whenever a template fires the 'myEvent' event, your template 'mytemplate.html' will be called.  If that template returns false, no other event handlers in the bubble phase will be called.

remove

(void) $eventsListener->remove()

This unregisters a previously created event listener.

<pinp>
  $listener = ar('events')->listen( 'myEvent' )
    ->call( 'mytemplate.html', $args );
  // do some stuff that may trigger the event
  ...
  $listener->remove();
</pinp>

System Events

Available in Ariadne > 2.7.5

The following events are fired by Ariadne automatically. The events fired before an action takes place can prevent the default action using the preventDefault method.

onaccessdenied Fired when the login is unknown, the password is incorrect or the user has insufficient grants. Fired before the login screen is shown.
onbeforecall Ariadne 9.0: Fired just before a template is called.
onbeforecopy Fired just before an object is copied.
onbeforedelete Fired just before an object is deleted.
onbeforemove Fired just before an object is moved.
onbeforesave Fired just before an object is saved.
onbeforeview Fired just before the first template of the current HTTP request is shown. Warning: up to and including Ariadne 2.7.6 this event is broken and may break your Ariadne install when used.
oncall Ariadne 9.0: Fired immediately after a template is called.
oncopy Fired immediately after an object is copied, on the original object.
ondelete Fired immediately after an object is deleted from the store. It is still available in memory.
onlanguagenotfound Fired when the first template called in the current HTTP request is not available in the requested language. Fired before a language select dialog is shown.
onmove Fired immediately after an object is moved.
onnotfound Fired when a requested path doesn't exist in the store. It is fired on the nearest parent object, before the default not found screen is shown.
onsave Fired immediately after an object is saved.
onview Fired immediately after the main template called in the current HTTP request is done.

The Event object

An event handle template can retrieve an event object which contains information about the event that triggered it. This object has the following methods and properties:

(string) name The name of the event, e.g. 'onbeforesave'.
(object) data Data specific to thievent.
(string) path Ariadne 9.0: The path where the event was fired.
(object) target Ariadne 9.0: The object where the event was fired, if available.
(bool) preventDefault() Prevents the default action for this event from occuring, if possible. It does not prevent other event handlers from being called. It has no arguments and always returns false.

The event object has a name containing the type of event that triggered it, e.g. 'onbeforeview' and it has a data object that contains extra information specific for this event. The following data is available in the system events:

(array) arCallArgs The list of arguments passed to the template that triggered this event.
Set by: all system events.
(string) arCallFunction The name of the template that triggered this event.
Set by: all system events.
(string) arCallPath The original path as requested.
Set by: onaccessdenied, onnotfound.
(bool) arIsNewObject Whether or not the object on which the on(before)save event fired is a new object.
Set by: onbeforesave, onsave.
(string) arLoginMessage The message to display.
Set by: onaccessdenied.
(array) arProperties The list of properties to be saved.
Set by: onbeforesave, onsave.
(string) arReason Contains a language independant string with the reason the onaccessdenied event was triggered. Can be one of 'access timeout', 'access denied' or 'password expired'.
Set by: onaccessdenied.
(string) arRequestedNLS The NLS code as set in the HTTP request.
Set by: onlanguagenotfound.
(string) arTarget The target of the copy or move command.
Set by: onbeforecopy, onbeforemove, oncopy, onmove.

Any changes made in the event data object is passed on to the next event handler called for this event. In the case of onbeforeX and onX data changes made in the onbeforeX data are passed on to the onX data.