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:
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
You can also invoke the field's custom function "makerequest.
Properties
| Label | Description | Type Name |
|---|---|---|
| Summary | A short description of what the field does, displayed in the forms designer to help identify it | SUMMARY |
| Request Details | Details 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 Function | This 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) { | REQUESTFUNCTION |
| Make Request on Change | The 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 Update | Whether 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 |
| Handlers | A 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) { | HANDLERS |
| Documentation | Add 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 example | DOCUMENTATION |
Share this page
