Callback

From Daxipedia

Jump to: navigation, search


Contents

[edit] Overview

Callbacks are a way for the backend to respond to a certain event that occurs in a field on the frontend. When an event is triggered, the frontend will post the event information and field value to the backend. Once the backend received the information, it will execute the method that is set to handle callback for the given event. The response will be the value that is returned by the executed method.

Currently 4D Ajax Framework supports 2 events from the frontend: On Load (eventid=1) and On Data Change (eventid=20). 

     1. On Load - The event happened when the field object is about to be drawn on to the Detail View.
     2. On Data Change - The event happened when the user tabbed out of the field. This means that the
        value of the tabbed out field must be sent to the backend.

Each callback is associated with a specific table, field, and event.

[edit] Configuring Callbacks

[edit] Programmatically

Callbacks are installed in the method DAX_DevHook_InstallCallBack. To install a callback you call the method DAX_Dev_SetCallBack and pass the event id, table name, field name, and the name of the callback method as input parameters.

Parameters 

       $1   -   Longint   -   Event ID
       $2   -   Text      -   Table Name
       $3   -   Text      -   Field Name
       $4   -   Text      -   Method Name
       $5   -   Boolean   -   (Optional) True if non-modifiable, otherwise False

For example: 

       ` *** Method: DAX_DevHook_InstallCallBack
       DAX_Dev_SetCallBack (On Load;Table name(7);Field name(7;1);"mAssignSequenceID")
       DAX_Dev_SetCallBack (On Data Change;Table name(7);Field name(7;2);"mConvertToUpperCase")

or 

       ` *** Method: DAX_InstallCallBack
       DAX_Dev_SetCallBack (On Load;Table name(->[Customers]);Field name(->[Customers]ID);"mAssignDefaultValue")
       DAX_Dev_SetCallBack (On Data Change;Table name(->[Customers]);Field name(->[Customers]Name);"mConvertToUpperCase")

The table and field names can also be from a DCS or custom view. In the case of a View (which is only created from the frontend) you will have to get the name of the View from the Admin area on the frontend.

[edit] HTTP Request

Setting a callback can also be done through HTTP request by calling the command AdminSetCallBack. Please refer to the Commands section of the Callback.

[edit] Method that determines execution status

A new method named DAX_Dev_SetCallBackExeStatus has been added to version 1.1. This method set a flag to to the http response, letting the frontend know whether the execution is successful. It must be executed for every callback execution. 

       $1 - LONGINT - (Input) 1 for successful and 0 for failed

[edit] Method to be executed on a Callback

The method that is executed on a callback is the method that the developer specified through the Web-Admin or in the DAX_Dev_SetCallBack method. From the example above, we have to 2 methods that are installed for the On Load and On Data Change event. These methods must be created by the developer and they must return a text parameter as shown below: 

      $0 - TEXT - (Output) Processed value to be sent back to the frontend

Within your callback method you can retrieve 8 attributes from 4D Ajax Framework for each execution: 

       1. Event ID - Longint - Event ID
       2. Table Name - Text - Table Name
       3. Table ID - Longint - Table ID
       4. Field Name - Text - Field Name
       5. Field ID - Longint - Field ID
       6. Record ID - Longint - Record ID (-3 for new record)
       7. Field Value - Text - The current value of the field (in text)
       8. Message - Text - Text message to you want to be returned to the frontend

To get the value of these attributes, you need to execute the command DAX_Dev_GetCallBackVar. The following are the parameters that you need to pass into DAX_Dev_GetCallBackVar: 

      $1 - TEXT    - (Input) Name of the attribute
                     (Event ID, Table Name, Table ID, Field Name, Field ID, Record ID, Value, Message)
      $2 - POINTER - (Output) Pointer to a variable to receive the attribute value

At the moment, you can set a value only to the attribute named "Message". To set the value to the Message attribute, you need to execute the command DAX_Dev_SetCallBackVar. The following are the parameters that you need to pass into DAX_Dev_SetCallBackVar: 

      $1 - TEXT    - (Input) Name of the attribute
                     (Message)
      $2 - POINTER - (Input) Pointer to a variable containing a value you want to set to the attribute

Here are some of the examples: 

       ` *** Method: mAssignDefaultValue
       ` *** Assign a default value if the field is empty of the record is a new record
       C_TEXT($0)
       C_TEXT($Value_t;$Message_t)
       C_LONGINT($RecordID_l;$TableID_l;$FieldID_l)
       DAX_Dev_GetCallBackVar("Table ID";->$TableID_l)
       DAX_Dev_GetCallBackVar("Field ID";->$FieldID_l)
       DAX_Dev_GetCallBackVar("Record ID";->$RecordID_l)
       DAX_Dev_GetCallBackVar("Field Value";->$Value_t)
       If($RecordID_l=New record) | ($Value_t="")
          If(Type(Field($TableID_l;$FieldID_l)->)=Is Text ) | (Type(Field($TableID_l;$FieldID_l)->)=Is Alpha Field ) | (Type(Field($TableID_l;$FieldID_l)->)=Is String Var )
             $Message_t:="A default value has been assigned to the field."
             DAX_Dev_SetCallBackVar("Message";->$Message_t)
             $0:="My Default Value"
          End if
       Else
          $0:=$Value_t
       End if
       DAX_Dev_SetCallBackExeStatus(1)

       ` *** Method: mConvertToUpperCase
       C_TEXT($0)
       C_TEXT($Message_t;$Value_t)
       $Message_t:="The text value has been converted to uppercase."
       DAX_Dev_SetCallBackVar("Message";->$Message_t)
       DAX_Dev_GetCallBackVar("Field Value";->$Value_t)
       DAX_Dev_SetCallBackExeStatus(1)
       $0:=Uppercase($Value_t)

[edit] Commands

[edit] AdminSetCallBack

/DAX/AdminSetCallBack

This command allows a callback to be set from the Web-frontend. This call can be used to create a new callback or modify an existing callback. However, if the callback event is set programmatically through the method DAX_Dev_SetCallBack (with non-modifiable set), it cannot be modified by AdminSetCallBack command.

Parameters

Name Type Example Value
sessionId TEXT S9112006173404CCWB
eventid NUMERIC 0 or 20
tableid NUMERIC 1, 2, 3,..., N
fieldid NUMERIC or [NUMERIC][NUMERIC] 1, 2, 3,..., N or [PhysicalTableID][PhysicalFieldID]
methodname TEXT mAssignDefaultValue


For example:

1. Setting a callback for a field that is belongs to a physical table 

   eventid     =   1  (On Load)
   tableid     =   7  (Physical Table ID)
   fieldid     =   1  (Physical Field ID)
   method name =   mAssignDefaultValue

http://localhost:8000/DAX/AdminSetCallBack?sessionId=S9222006150444CCWB&eventid=1&tableid=7&fieldid=1&methodname=mAssignDefaultValue

OR 

   eventid     =   1  (On Load)
   tableid     =   7  (Physical Table ID)
   fieldid     =   [7][1]  (Physical Table and Field ID)
   method name =   mAssignDefaultValue

http://localhost:8000/DAX/AdminSetCallBack?sessionId=S9222006150444CCWB&eventid=1&tableid=7&fieldid=[7][1]&methodname=mAssignDefaultValue

2. Setting a callback for a field that is belongs to a view (or virtual table) 

   eventid     =   1  (On Load)
   tableid     =   -3  (View's Table ID)
   fieldid     =   [5][2]  (Physical Table and Field ID)
   method name =   mAssignDefaultValue

http://localhost:8000/DAX/AdminSetCallBack?sessionId=S9222006150444CCWB&eventid=1&tableid=-3&fieldid=[5][2]&methodname=mAssignDefaultValue

2. Setting a callback for a field that is belongs to a DCS view 

   eventid     =   1  (On Load)
   tableid     =   32001  (DCS's Table ID)
   fieldid     =   [32001][2]  (DCS's Table ID and Array Position in the DCS)
   method name =   mAssignDefaultValue

http://localhost:8000/DAX/AdminSetCallBack?sessionId=S9222006150444CCWB&eventid=1&tableid=32001&fieldid=[32001][2]&methodname=mAssignDefaultValue

Reply 

<AdminSetCallBack>
   <Status Success="True"/>
</AdminSetCallBack>

[edit] GetCallBack

/DAX/GetCallBack

This command allows the Web-frontend to get Callback information for the one or all fields from a table. If the field id is specified, the backend will find on the callback for the given field. If at least one callback event is found, the return XML will look like the example reply (shown below). If the field id is 0, all fields in the table (with at least one callback event) are returned in the XML response.

Parameters

Name Type Example Value
sessionId TEXT S9112006173404CCWB
tableid NUMERIC 1, 2, 3,..., N
fieldid [NUMERIC][NUMERIC] 1, 2, 3,..., N (0 for all fields) 
   tableid     =   7  (Physical, View or DCS Table ID)
   fieldid     =   [7][1]  (Physical Table and Field ID)

http://localhost:8000/DAX/GetCallBack?sessionId=S9222006150444CCWB&tableid=7&fieldid=[7][1]

Reply 

<GetCallBack>
   <CallBack eventid="1" fieldid="1" method="mConvertCase" tableid="7" notmodifiable="False"/>
   <CallBack eventid="20" fieldid="1" method="mAssignDefaultValue" tableid="7" notmodifiable="True"/>
</GetCallBack>

Please note that the "notmodifiable" attribute is set to True only if the Developer installed the callback programmatically inside the method DAX_DevHook_InstallCallback.

[edit] ExecuteCallBack

/DAX/ExecuteCallBack

This command executes the method that is installed for a specific event.

Parameters

Name Type Example Value
sessionId TEXT S9112006173404CCWB
eventid NUMERIC 1, 2, 3,..., N
tableid NUMERIC 1, 2, 3,..., N (Physical, View or DCS Table ID)
fieldid [NUMERIC][NUMERIC][NUMERIC] [T][F][R] ([T][F][-3] for new record)
value TEXT MyValue


For example:

1. Get a default value 


   eventid = 1 (On Load)
   tableid = 7 (Physical Table ID)
   fieldid = [7][1][-3] (Physical Table , Field and New Record ID)

http://localhost:8000/DAX/ExecuteCallBack?sessionId=S9212006224024CCWB&eventid=1&tableid=7&fieldid=[7][1][-3]

Reply

<Callback eventid="1">
   <Result fieldid="[7][1][-3]" value="Default Value" message="A default value has been assigned to the field." />
</Callback>


2. Convert text to uppercase 


   eventid = 20 (On Data Change)
   tableid = 7 (Physical Table ID)
   fieldid = [7][1][2] (Physical Table , Field and Record ID)

http://localhost:8000/DAX/ExecuteCallBack?sessionId=S9212006224024CCWB&eventid=20&tableid=7&fieldid=[7][1][2]&value=usa

Reply

<Callback eventid="20">
   <Result fieldid="[7][1][2]" value="USA" message="The text value has been converted to uppercase." />
</Callback>
Retrieved from "http://daxipedia.4d.com/index.php/Callback"
Personal tools