gICAPI.SetData()

The gICAPI.SetData() function registers WEBCOMPONENT field data to be sent to the program.

Purpose of gICAPI.SetData()

If the content of the WEBCOMPONENT field needs to be transmitted to the program, use the gICAPI.SetData() function to register the data to be sent to the runtime system.

Important: The WEBCOMPONENT field must be the current field (therefore the field must have the focus), otherwise gICAPI.SetData() will be ignored. Use the gICAPI.onFocus() callback function to detect if the WEBCOMPONENT field has the focus.

The data must be a string. It is typically serialized as a JSON string.

Note: Data is transmitted as plain text. Sending a large amount of data is not recommended.

When to use gICAPI.SetData()?

If the gICAPI.onFlushData() callback function is used, use the gICAPI.SetData() function in this callback function, to provide the WEBCOMPONENT field value. When the WEBCOMPONENT field loses the focus, or when the gICAPI.Action() function is called, the gICAPI framework will call the gICAPI.onFlushData() function implicitly.

The gICAPI.SetData() can also be called outside the context of gICAPI.onFlushData(), or when this callback is not implemented, typically before calling gICAPI.Action(). If no gICAPI.onFlushData() is implemented, the value provided by the last gICAPI.SetData() call will be used.

Handling NULL values

In order to send a NULL value, call the gICAPI.SetData() function with JavaScript null as parameter:

if (value.length==0) {
   gICAPI.SetData(null);
} else {
   gICAPI.SetData(value);
}

Example

The following code example registers data to be sent to the runtime system when the gICAPI.onFlushData() callback function is invoked:

var onICHostReady = function(version) {

    ...

    gICAPI.onFlushData = function() {
        var field1 = document.getElementById("field1");
        gICAPI.SetData( field1.value );
    };

    ...

};