gICAPI.onData()

The gICAPI.onData() function is executed when field data is sent by the program.

Purpose of gICAPI.onData()

The gICAPI.onData() function is called each time the WEBCOMPONENT field content modification comes from the program. This occurs for example when the current dialog sets the field value, or when a DISPLAY value TO wc_field instruction is performed.

The gICAPI.onData() function is also used to check that the runtime system has accepted the web component value change, after a call to the gICAPI.SetData() function, when the value needs to be transmitted from the WEBCOMPONENT field to the program.

Handling gICAPI.onData() values

When the gICAPI.onData() function is fired, assign the data value to the web component, or check that the runtime system has validated the value provided with gICAPI.SetData().

The data parameter is a string that contains the field value as provided by the program. It is up to your JavaScript code to interpret the program value to be rendered on the HTML page. For example, the value may just be GPS coordinates, that will be used to display a location on a map. The data is typically serialized as a JSON string.

Note: Use util.JSON classes to serialize / de-serialize structured data (RECORDs or ARRAYs)

If the WEBCOMPONENT field value can be NULL, the onData() function must check for null values as follows:

gICAPI.onData = function(value) {
    if (value == null || value.length == 0) {
        // Process null case.
        ...
    }
    ...

Example

The following code example defines the onData() function to set the content on a textarea element:

var onICHostReady = function(version) {

    ...

    gICAPI.onData = function(content) {
        $('textarea#value').val(content);
    }

    ...

};