Component Events Implementation

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

Server-side Event Implementation

To implement a server-side event on your component:

1. Define the event. Server-side events are defined like common properties — null by default — but they must be named with a specific syntax.
2. Trigger the event. To trigger a server-side event from somewhere in your code, call the callEvent() method, and it will run the custom event handler, if any. callEvent() must get two parameters:
   • The name of the PHP property behind the event, without its _ prefix. For example, if your event is named OnEvent, the PHP property behind it should be named $_onevent, and you must set this parameter to "onevent".

     Note: The _ prefix is an RPCL naming convention for class properties.

   • The second argument is an array of additional parameters. You should use this array to provide your users additional information they can use on their event handler. If you are not passing anything, use an empty array instead: array().

For example, the following code defines a component that runs the event handler for an event during the rendering of the component:

class DummyComponent extends Component {

  // Definition of the OnRender server-side event.
  protected $_onrender = null;
  function getOnRender() { return $this->_onrender; }
  function setOnRender($value) { $this->_onrender=$value; }
  function defaultOnRender() { return null; }

  // Call to the OnRender server-side event during the rendering of the component.
  function dumpContents() {
    $this->callEvent("onrender", array());
  }
}

Server-side Event Naming

When naming a server-side event, you must always prefix it with On. Examples of valid PHP event names are OnStart or OnAfterRender. Following this naming convention lets HTML5 Builder tell apart your server-side events from common properties and client-side events.

Client-side Event Implementation

To implement a client-side event on your component:

1. Define the event. Client-side events are defined like common properties, null by default, but they must be named with a specific syntax.
2. Trigger the event. To trigger a client-side event from somewhere in your code, call the dumpJSEvent() method with the custom event handler name as parameter, and it will run the event handler if defined.

Note: Trigger client-side events only in parts of the resulting HTML document where JavaScript code is allowed.

For example, the following code defines a component that runs the event handler for a client-side event during the rendering of the JavaScript code of the component:

class DummyComponent extends Component {

  // Definition of the OnRender client-side event.
  protected $_jsonrender = null;
  function getjsOnRender() { return $this->_jsonrender; }
  function setjsOnRender($value) { $this->_jsonrender=$value; }
  function defaultjsOnRender() { return null; }

  // Call to the OnRender client-side event during the rendering of the JavaScript code of the component.
  function dumpJavaScript() {
    $this->dumpJSEvent($this->_jsonrender);
  }
}

Client-side Event Naming

When naming a client-side event, you must always prefix it with jsOn. Examples of valid client-side event names are jsOnLoad or jsOnClick. Following this naming convention lets HTML5 Builder tell apart your client-side events from common properties and server-side events.