Component Events

From HTML5 Builder
Jump to: navigation, search

Component events are one of the keys of component-based applications. They are triggered under certain circumstances, and you can define functions — event handlers — that get called for those events, so you can control what happens under those specific circumstances: change property values, call other functions, and much more.

For example, a component to render a button could have an OnClick event, which you could use to define what will happen when the button is cliecked. Also, during the rendering of a component, there could be events defined to let you run code or print content at certain steps of the rendering — such as before and after the component itself is rendered.

Event Types

Events can be separated in two main types: server-side events and client-side events.

Server-side Events

Server-side events (also known as PHP events) are events that you can handle — react to — from the server, using PHP code.

There are two possible causes for a server-side event to be triggered:

  • It might be triggered from inside the component, as part of its logic. For example, all controls provide OnBeforeShow and OnAfterShow server-side events, which are triggered by the control during its rendering logic, both at the beginning and at the end.
  • It might be triggered from the user agent after an action from the user. This is the case of Button’s OnClick server-side event. These events reload the page as a side effect, since they need to submit to the server the current content of the page, perform the event, and return the page with whatever modifications were performed during the event. In server mobile pages, you can avoid the page reload using AJAX.

Client-side Events

Client-side events (also known as JavaScript events) are events that you can handle — react to — from the user agent, using JavaScript code.

These events are always triggered from the user agent after an action from the user. This is the case of Button’s OnClick client-side event.

In server pages, you can use AJAX to call a server-side event handler from any client-side event, so you can run server-side code — and change the page accordingly — without getting the page reloaded.

Usage

To handle an event, you need to write an event handler and link the event to that handler.

Server-side Event Handling

Server-side event handlers look like this:

function eventHandlerName($sender, $params)
{
    // Your PHP code.
}

Server-side Handler Parameters

Server-side event handlers always get two parameters:

$sender
The component originating the event.
$params
An array that might include further information about the circumstances surrounding the event.

Client-side Event Handling

Server-side event handlers look like this in server pages:

function eventHandlerName($sender, $params)
{
    echo "<JavaScript code>";
}

This provides a lot of flexibility, since — if you want to — you can use server-side code to generate the client-side code for the event handler.

You can also use PHP tags (<?php and ?>) to make the JavaScript code cleaner, and allow HTML5 Builder to provide you with JavaScript syntax highlighting:

function Button1JSClick($sender, $params)
{
    ?>
    //begin js
    // Your JavaScript code.
    //end
    <?php
}

However, in client pages, they will look like this instead:

function eventHandlerName(event)
{
    // Your JavaScript code.
}

Client-side Handler Parameter

Unlike server-side handlers, client-side event handlers only get one parameter: event.

This is true for both client and server pages. In server pages, $sender and $params are useless, but the JavaScript code you print in the handler can expect to have an event variable available.

For example, the following handler opens a dialog window with the coordinates of the point where the user clicked:

function Button1JSClick($sender, $params)
{
    ?>
    alert("(" + event.clientX + ", " + event.clientY + ")");
    <?php
}

For information on the content of the event parameter, you must check the DOM documentation for the specific event you are handling.

Linking Events to Handlers

Component events are managed as any other property. To associate an event to an event handler, you only need to change the value of that event (as a property) to the name of the function that will handle it.

Normally, you will use the Object Inspector to do that. In fact, if you double-click an event on the Object Inspector, you will get an event handler for it on your code, already linked to the event.

But you can also link them from PHP in server pages:

// ComponentName’s OnEventName server-side event will be handled by $this->eventNameHandler().
$this->ComponentName->OnEventName = "eventNameHandler";

// ComponentName’s OnEventName client-side event will be handled by $this->eventNameJSHandler().
$this->ComponentName->jsOnEventName = "eventNameJSHandler";

Implementation

When creating a custom component, providing events will extend the flexibility of your component.