Toggle menu

API Server AJAX

This field makes an AJAX request to an API Server, storing the response as its value.

There's an example of it calling an End Point in the Using the Ajax Field article.

Request Parameters

Request parameters are supplied to the API Server as a JSON object. Requests can include the values of fields on your form by including the name of a field wrapped in # characters. For example: '{"postcode":"#POSTCODEFIELD#"}' would send the value of the POSTCODEFIELD in the request. This must be the complete field name when an external type definition is used.

It is possible to build up the parameters one item at a time using the property editor in the field type. Each line represents one top level parameter within the object.

You can also define a request function. This will be passed the JSONRPC parameter object prior to making the request. At this point it can add or change parameters as required. It is possible to use the field name based parameters as a means of triggering the request and then build the actual request parameters in this function.

Making a Request

A request will be automatically made whenever a field referenced in the service parameters is changed.

There are two methods of manually triggering the sending of a request to the service.

Updating the field's value using helper.setFieldValue("FIELDNAME", "") will make a request using the current parameters. A new set of parameters can be supplied as the value. This must be a valid JSON object represented as a string.

You can also invoke the field's custom function "makerequest. helper.invokeCustomFieldFn( "FIELDNAME", "makeRequest") which will make a request using the current parameters. Additional parameters can be supplied to the custom function that contain the parameters to send. This can be a JSON object or a string representing a JSON object.

Properties

LabelDescriptionType Name
SummaryA short description of what the field does, displayed in the forms designer to help identify itSUMMARY
Request DetailsDetails of the API Server AJAX request that will be performed to retrieve data for the template. The 'Worker URL' should take the form /apiserver/worker-name, where /apiserver is the API Server proxy URL setup for the site, and worker-name is the worker to be called. It is possible to add the full URL, for example http://myapiserver.company.co.uk:5706.

The 'Method Name' is the name of the method that should be called on the worker. Use the 'Worker parameters' grid and the buttons it provides to specify the parameters that should be supplied to this worker method.

Each parameter is added as a name/value pair. A parameter value can contain any JavaScript literal: 'string', 123, true, { object }, [ array ]. In addition, a value may contain #FIELDNAME# placeholders which will be replaced with the referenced field value prior to performing the request.

If the request requires a username and password, these can be entered on the "Advanced" tab
REQUESTPARAMS
Request FunctionThis function is executed browser-side before making the AJAX request. It is supplied with two parameters, a reference to the helper library and the current value of the JSONRPC request 'params' object. The second parameter is always supplied as a JavaScript JSON object. It will never be null or undefined.

For example:

function (helper, value) {
    // Add a field called fullName to the object
    value.fullName = helper.getFieldValue("FIRSTNAME") + " " + helper.getyFieldValue("LASTNAME"); 
    return value;
}
REQUESTFUNCTION
Make Request on ChangeThe AJAX call will be performed when any field referenced in the requested parameters, using the #FIELD# syntax, is changed.

The request will only be performed if the field is changed to a valid value
REQUESTONCHANGE
Make Request on UpdateWhether to perform the AJAX request when the field value is updated.

If the new value of the field is an empty string, the current request parameters will be sent (after replacing any #FIELD# strings).

If the new value is a non-empty string, it is assumed to contain the new parameters as a valid JSON object represented as a string
REQUESTONUPDATE
HandlersA JavaScript function that is called following a request to the service.

The 'valid' parameter will indicate if the request completed without error.
The 'value' parameter will contain the returned data. In most cases this will be a JavaScript object or array rather than a simple string.

For example:

function (helper, fieldName, value, valid, eventName) {
    if ( valid ) {
        helper.setFieldValue( "RESULTS", "apiServercall OK: " + JSON.stringify(value) );
    } else {
        helper.setFieldValue( "RESULTS", "apiServercall ERROR: " + JSON.stringify(value) );
    }
}
HANDLERS
DocumentationAdd documentation to your field to help explain any complex functionality to future users. You might include information on what the field does and how it relates to other fields on the form. Notes added here are only ever visible in the Forms Designer, they can be searched for, viewed and downloaded from the action panel. See Common Field Properties for an exampleDOCUMENTATION
Last modified on November 11, 2022

Share this page

Facebook icon Twitter icon email icon

Print

print icon