Ajax Callback

Description

Define a user-defined ajax callback. The callback can be handled by an Xbasic function that is defined in the component, by a separate .a5w page, or by another page (.e.g., .php, .asp, etc.)

Used with the Grid and UX components

 Ajax Callback Properties

Submit data
Specify if data from the grid should be submitted to the server when the callback is made. IMPORTANT: Data from the current row are only submitted for fields that are editable. Primary key values, however, are submitted regardless of whether the current row is editable or not.
Submit part
Specify the part from which data should be submitted. Choices include.
Row number
Specify which row in the grid to submit data from. The {Grid.Rownumber} placeholder is used to indicate the 'current row' in the Grid. To submit data from ALL of the rows in the grid, set Row Number to: All. To specify a new record row, use a negative number. e.g. -1 for the first new record row, -2 for the second new record row, etc.
Callback type
Specify the callback type. The callback can be handled by a Xbasic function, or by a page referenced by a URL. The function can be defined in the Grid (see 'Xbasic function declarations' section of the Grid), or in an .AEX file. Choices include.
Function name
Specify the Xbasic function name (do NOT include '()' in the name. e.g. specify name as 'myFunction', not 'myFunction()' ). The Xbasic function prototype must be: function functionName as c (e as p). The function must return Javascript code that you want to execute on the client. The 'e' parameter that is passed into the function contains all of the data submitted to the server on the callback. TIP: Use the Firebug addin for Firefox to see what data is submitted on the callback. TIP: Click 'Create function prototype' for an example of the required syntax for the function.
URL
Specify the URL of the page that will handle the callback.
Action name
A variable called '_action' is passed to the URL. The value of _action is set to Action Name.

 Advanced Properties

Additional data to submit
Specify any additional data that you want to submit to the server. This data must be in the form of a URL parameters string (i.e. name/value pairs) and it must be enclosed in single quotes. For example '_var1=alpha&_var2=beta' TIP: The 'Additional data' can be computed by a Javascript function call. For example, you might have defined a Javascript function called 'gatherInfo'. If you specify 'gatherInfo()' here (without single quotes), the value returned by this function will be included in the data sent back to the server as part of the Ajax callback.
Compute current row data
If the current row is not editable, and the 'Submit Data' property is checked, field values from the current row are not submitted. Only the primary key values for the current row are submitted. However, if you check this box, then the server will query the database to retrieve the field values for the current row and make these values available to your callback handler.(IMPORTANT: To use this option in a read-only Grid based on SQL tables, you must ensure that you have defined the Primary Key for each table.)
After callback complete Javascript
Specify any Javascript you want to execute when the callback is complete and all of the Javascript returned by the callback (if any) has executed.
The 'After callback complete Javascript' property.

 A Note on the 'After callback complete Javascript' Property

To specify the after callback complete Javascript in the UX or Grid's .ajaxCallback() method, you set the onComplete property in the optional optionsObject passed in. For example:

{dialog.object}.ajaxCallback('','','myXbasicFunction','','',{onComplete: function() { 
        alert('callback is complete')
    }
})

 Location Data Properties

Submit location information
Specify if location information (longitude/latitude) should be submitted. The location information is obtained from the browser. The user will be prompted for permission to read location information. Not all browsers support retrieving location information. The 'e' object passed to the Xbasic function will contain these properties: __locationFound - true/false, __locationLatitude - the latitude value, __locationLongitude - the longitude value
High accuracy
If true, the device will use its most accurate method to get location information. If false, the device will use its fastest or lower power consumption method depending on the device.
Timeout
The amount of time in milliseconds to wait on the device to acquire location information excluding the amount of time it takes the user to grant the web page access to geolocation data.
Max age
The amount of time in milliseconds to accept a previously acquired location. 0 means that a new location must be acquired from the device.

 Ajax Failed/Offline Javascript Properties

Timeout setting
(Optional) Specify the time to wait (in milliseconds) for a response from the callback. If a response is not received within the specified time, the callback is considered to have failed and the 'onAjaxCallbackFailed' client-side event will be fired, and any Javascript defined in the optional 'Ajax failed Javascript' property will be executed. If you specify '<Default>' the global default value (defined in the {dialog.object}.ajaxCallbackTimeout property) will be used.
Ajax failed Javascript
(Optional) Specify the Javascript to execute if the Ajax callback fails (i.e. if the server does not send a response).
Offline Javascript
(Optional) Specify the Javascript to execute if the device is offline. Since the device is offline, the Ajax callback is not made. Therefore the code in the 'Ajax failed Javascript' property will not get executed.

 Using Action Javascript to Write an Ajax Callback Function

The Ajax Callback Action Javascript can be used to generate the Xbasic callback function that is called. The Xbasic callback function can be saved in the component in the Xbasic Functions section of the component builder. The action can be accessed anywhere the Action Javascript editor is available, including Javascript events for controls and Javascript Actions.

  1. In the event editor with Action Javascript mode selected, click the Add button to add a new action.

  2. Select the Ajax Callback action and click OK.

  3. Define the name for the callback function that will be called. In the image below, a new function will be created that performs the callback called MyCallback

  4. Define any additional (optional) data to submit to the callback function. Parameters sent to the callback function can be accessed through the e object in the Xbasic function.

  5. Click the Create function prototype link to generate the function prototype for the Ajax callback.

  6. Click the Copy to clipboard button to copy the function signature to the clipboard. When the code has been copied to the clipboard, click the Close button to close the dialog.

  7. Click the Open Xbasic Function Declarations link to open the Xbasic Function Declarations dialog. This is a shortcut to the Xbasic Functions section.

  8. Paste the code from the clipboard into the window and click OK.

  9. Click OK to save the Ajax Callback action.

  10. Optionally, add a comment that describes the action when prompted. Then, click the OK button.

  11. Click the Save button to save the changes made to the event or Javascript Action.

  12. Navigate back to the component builder. Expand the Code section in the far left column and click on Xbasic functions. This is where you can make changes to the Xbasic callback function you created using the Ajax Callback Action Javascript builder.

 Making Callbacks from Javascript

It's best to use Action Javascript if it's available to add functionality to an application. If you would rather make a callback using Javascript, however, the .ajaxCallback() method for the Grid or UX Component is available. To learn more, visit the Grid Component or UX Component Client API documentation for the .ajaxCallback() method.

See Also