The listeners are definitions that can be included in the form XML specification to define event handlers for the form fields and buttons. An event defined in the XML file is always related with JavaScript code. PHP2Go doesn't have (at least no yet) a tool to link two different requests using events. So, the listener entity in the forms DTD is scrictly related to a shortcut to easily bind javascript functions with fields and buttons.

A listener have an attribute called type. The attribute type can have two different values: JS and JSRS. JS means that the listener is bound with a simple javascript event and an action (a function or static method call). JSRS is an acronym for JavaScript Remote Scripting. JSRS is a tool created to allow JavaScript to perform requests to a PHP script using hidden layers. PHP2Go uses this functionality in the field/button listeners.

In the forms DTD specification, the LISTENER entity has attributes that can be used in the JS listeners and in the JSRS listeners.

When using a simple JS listener, you must provide an event and an action (a function or method name, including the necessary parameters).

When using a JSRS listener, bound with a PHP script, you must provide the event name (attribute EVENT), the PHP script name (attribute FILE, expects the path to the PHP script), the remote function name (REMOTE), the JavaScript callback function that will handle the return of the function (attribute CALLBACK, the function must be built by the developer) and the parameters of the PHP function (accepts a single parameter, an array or a function call that returns the parameter(s)).

Here's an example of the two types of listeners:

JS

<listener type="JS" event="onClick" action="location.href='another_page.php'"/>
<listener type="JS" event="onChange" action="loadValues( )"/>
    
JSRS

<listener type="JSRS" event="onClick" file="remote.php" remote="myFunc"
    callback="handleReturn" params="document.myform.myfield.value"/>
    
Important notes about JSRS:

1) JSRS listeners have also the DEBUG attribute, that accepts the values T or F. If the value is T, every JSRS request to the PHP script will turn the "hidden" layer visible, so that the developer can see the return of the PHP function. Besides, using the DEBUG attribute, anything that is sent to the standard output in the PHP script (using print or echo) will also appear in the layer. The position of the layer depends on the browser. IE shows it in the top of the page. Mozilla shows it in the bottom.

2) In the PHP script, besides of defining the function that is called from the javascript source, you must call a function of the JSRS library that register your function, so that it can be called from outside. Browse the "jsrs" folder in the PHP2Go distribution and you will find a file called csvdbpersist.php. There you can find an example of a function that is called from the javascript code.

3) The fields can have more than one listener, even using the same event and even with different types. PHP2Go will put them together, and the first defined action will execute first.

4) The REMOTE and CALLBACK attributes expect only the function name, without parameters nor parenthesis.

5) If the parameter list for a JSRS call is too big, consider the possibility of using a user function to build the array of parameters and return it.

6) In the JSRS library (Jsrs.lib.php), included in the PHP2Go documentation, there are some utility functions to build return values. The most "classic" example is send a search query to the database and return the values that will be used to populate a "SELECT" element in the form. Considering that you must return the "VALUE" and the "TEXT" attributes for every option of the SELECT, your return value will be something like this:

1~John|2~Mary|3~Paul|4~Anna|5~Jerry|6~Mark|7~Sandra

In order to process a string in the above format, PHP2Go has a javascript function called createOptionsFromString. This function receives the two delimiters (in this case ~ and | ) as parameter and inserts in the provided SELECT element the returned options.

I hope this explanation can help you to use listeners in you forms. I believe that, using this, your productivity will increase a lot.