Event Handlers

Handling component events

The Event Management System

The event management system is one of the most important pieces within the component model since is the one in charge of performing the following tasks:

To notify to the server all the events raised in the client (i.e. a click on a button or a text control change)
To synchronize the component status between the client and the server (i.e. update the component text property once it has been changed in the client)

From the server point of view, it's transparent the fact that an event has been raised from the client side.

Life-cycle of the event management system

The following figure ilustrates the life-cycle of the event management system:

When an event is raised from a component in the client-side, it is sent to the server (usually via AJAX).
Once the request is received, the Front Controller delegates to the associated Event Handler, a subclass of __EventHandler which executes some logic associated to the given event.
Finally, components are updated in the client-side according to the server status after the event has been handled.

The communication process between client and server is performed usually via Ajax plus JSON.
However, this communication is handled entirely by the framework, so we don't need to care about low-level details regarding how this process is being done.

The Event Handler

The way that lion proposes to handle client events is by defining Event Handlers associated to views. An event handler is a class in charge of events management for concrete views.

We just need to define subclasses of __EventHandler and follow a naming convention for methods.

Naming convention and location

Lion is enough flexible to allow whatever name and location for your event handlers. There are not restrictions in that sense.
However there are some naming conventions and predefined locations that ease the definition and enablement of event handlers:

Use the view code plus the suffix 'EventHandler' to define an event handler associated to a concrete view.
Define each event handler in a single file with the same name of the event handler class followed by the suffix '.class.php'
Place your event handlers in the /libs/eventhandlers directory

Associating an event handler to a view

First thing that we need to know in order to define event handlers is the fact that each event handle need to be associated to a view at least.

We can do it declarativelly in the view-definitions configuration section by defining the eventHandlerClass view property.

i.e.

<?xml version = "1.0" standalone="yes"?>
 
<configuration>
 
  <view-definitions>
  
    <view code="fooBarView" class="__SmartyView">
      <property name="template" value="fooBar.tpl"/>
      <property name="eventHandlerClass" value="FooBarEventHandler"/> 
    </view>
  
  </view-definitions>
  
</configuration>

In this example, we are associating the class FooBarEventHandler to the view identified by the code fooBar.

However, there is a rule in the views.xml by default that simplifies this task by just following a naming convention:

<?xml version = "1.0" standalone="yes"?>
 
<configuration>
 
  <view-definitions>
  
    <view code="*" class="__SmartyView">
      <property name="template" value="*.tpl"/>
      <property name="eventHandlerClass" value="*EventHandler"/> 
    </view>
  
  </view-definitions>
  
</configuration>

This rule associates an event handler to a view if we define the name of the event handler as the view code plus the suffix EventHandler.

i.e., for the view fooBar we'll define the event handler class as FooBarEventHandler. Note that the mapping between the view code and the class name is case insensitive.

Event handler file and location

The file app/config/includepath.xml contains the following mapping rule:

<?xml version = "1.0" standalone="yes"?>
<classes>
 
  ...
 
  <cluster name="Event Handlers" path="/libs/eventhandlers">
    <class name="*" file="*.class.php"/>
  </cluster>
 
  ...
  
</classes>

This mapping rule let Lion know that any file placed in libs/eventhandlers with the suffix '.class.php' corresponds to a class with the same name without the suffix.

So, by placing event handler files in that directory and following the naming convention, it's not needed to declare explicitly the location of your event handlers in the includepath.xml file.

Defining Event Hadlers

The way to define event handlers is by implementing the __IEventHandler class. However, Lion proposes a class that already implements this interface: The __EventHandler class.

By subclassing the __EventHandler class, we just need to define a method for each component event that we need to handle taking into account the following naming convention for the method name: 'componentName' + '_' + 'eventName' (i.e. myButton_click, myTextBox_blur, ...).

And again: this naming convention belong to the __EventHandler. If you implement the __IEventHandler then you should develop your own ways to handle events.

i.e.

<?php
 
class FooBarEventHandler extends __EventHandler {
 
    /**
     * Set the 'FoO BaR!' string to the myLabel text
     * property when click the myButton component
     *
     */
    public function myButton_click() {
        //retrieve the component myLabel
        $my_label = $this->getComponent('myLabel');
        //assign the 'FoO BaR!' to the text property
        $my_label->setText('FoO BaR!');
    }
 
    
}

In this example, we have define how to handle the click event for a button component.

As we can also see in this example, one of the most interesting things of __EventHandler class is that allows to retrieve whatever component within the same view by calling to the __EventHandler::getComponent() method.

Try The Hello World Deluxe. It contains a practical tutorial regarding components and event handlers.

To see information regarding events handled in lion, see the Lion Events section