Ariadne

• Programmers Ref…»
• Ariadne General…»
• events»

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

call

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

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

capture

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

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 ) 

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 )

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 )

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.

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:

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:

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.

• FAQ
• Installation
• User Manual
• Tutorials
• Programmers Reference
  • architecture
  • classes
  • Ariadne General API
    • Cache
    • Content
    • connect
    • CSS
    • error
    • events
    • HTML
    • HTTP
    • loader
    • PINP
    • store
    • URL
    • XML
  • modules
  • Templates
• Installation Requirements
• Examples