ClientAction - cWebObject

Calls a function of the client JavaScript object

Parameters

Parameter	Type	Description
sName	String	Name of the method to call on client
aOptParams	String[]	(optional) Array of parameters to pass to the client method
vActionData	Variant	(optional) Optional set of structured data associated with the client action. This data is formatted as a value tree which can be used to represent data with an arbitrary structure. The aOptData parameter is typically used to populate large sets of data, for example a treeview, combo list or grid.

Syntax

Procedure ClientAction String sName String[] aOptParams Variant vActionData

Call Example

Send ClientAction sName aOptParams vActionData

Description

Send ClientAction to call a function that belongs to the JavaScript object on the client that represents the DataFlex object. Any JavaScript function available on a web object can be called. The ShowInfoBox method is an example of a client action that shows an info box.

Normally you do not need to send ClientAction, as the Web Framework classes wrap these calls into their interface. If you are designing your own JavaScript Web Framework classes, you would use ClientAction to call the interface methods of your JavaScript object and to pass complex data to it.

Note that ClientAction merely queues calls to the JavaScript objects and these requests are only processed when the current server action (e.g. OnClick event) has completed. The action data is passed back to the client in the set of response data that is returned after each successful server action.

Multiple ClientAction calls may be queued during execution of each server action.

ClientActionEx adds a client action to the response that will be executed on the client

ClientActions are executed in order. Only web property changes do not and get processed before client actions. When Web Setting the same property twice during the same call, only the last value is sent to the client and the set_ JavaScript function only gets executed once.

The sName parameter may include an object specification. Use this to call a function on the client-side object that belongs to this web object and use window to call a global JavaScript function. If no object specification is included, the framework applies its automatic resolution rules to determine whether the function should be treated as a local or global function. Use an explicit prefix when you want to make the target clear.

See Building Custom Controls, Communication for an example of how to utilise the ptActionData property.

Samples

The samples below show common ways to use ClientAction.

Calling a global function with window.

String[] aParams

Move "John" to aParams[0]
Send ClientAction "window.showNotification" aParams

window.showNotification = function(sName){
    window.alert("Hello " + sName);
};

Prefixing the name with window. makes it explicit that the function is defined globally.

Calling a function on the local client object with this.

String[] aParams

Move "Processing complete" to aParams[0]
Send ClientAction "this.showStatus" aParams

showStatus(sMessage){
    this.displayMessage(sMessage);
}

Use this. when the function belongs to the JavaScript object that represents the current web object.

Relying on automatic local or global detection

Send ClientAction "showStatus" aParams

When you omit this. or window., the framework decides how to resolve the name. This is convenient for short calls, but using an explicit prefix makes the intended target easier to understand.
### Passing structured action data

Struct tClientRow
    String sId
    String sDescription
End_Struct

Struct tClientRows
    tClientRow[] aRows
End_Struct

String[] aParams
tClientRows tData

Move "100" to tData.aRows[0].sId
Move "Bicycle" to tData.aRows[0].sDescription

Send ClientAction "this.loadRows" aParams tData


loadRows(){
    const tData = this._tActionData;

    if(tData && tData.aRows && tData.aRows.length){
        this.renderRows(tData.aRows);
    }
}

Structured action data is made available on the local client object through this._tActionData, so this pattern is typically used with this.-prefixed client actions.