This field type lets you write an HTML template using Handlebars notation that can display values returned by an AJAX request to the API Server. Requests are made when the field is first rendered and, optionally, when the values of other fields change.
The Handlebars Examples article has worked examples of form fields using Handlebars, and different ways that responses from the API Server can be manipulated.
Use this field with caution. It operates in the browser and information about the requests being made will be visible in the page source and browser developer tools. Do not use this field to call any services that require an API key or username/password.
Request Parameters
Request parameters are supplied to the API Server as a JSON object. Requests can include the values of fields on the form by adding the name of a field between # characters. For example:
You can also define a request function. This will be passed the JSONRPC params object prior to making the request. At this point it can add or change parameters as required. This means it's possible to use the field name based parameters to trigger the request and then build the actual request parameters in this function.
Custom Functions
Custom functions can be called from the handlers of other fields using .invokeCustomFieldFn.
makeDataRequest - This will trigger the field's AJAX request
Properties
| Label | Description | Type Name |
|---|---|---|
| Summary | A short description of what the field does, displayed in the forms designer to help identify it | SUMMARY |
| Template | The Handlebars template. Handlebars templates look like regular HTML, with embedded handlebars expressions. There's more information in the Handlebars Editors article | TEMPLATE |
| 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 to set 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. If the request requires a username and password, these can be entered on the "Advanced" tab | DATAPARAMS |
| 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, params) { | 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 |
| Response Function | A data manipulation function that can be implemented to manipulate the AJAX response before processing the template. This function is executed browser-side after the AJAX request is performed but before generating any HTML. It is supplied with two parameters, a reference to the helper library and the data returned by the AJAX request as a JSON object. The second parameter is always supplied as a JavaScript JSON object. It will never be null or undefined. Note that it is not called if the AJAX call returns a JSONRPC error. This allows the returned data to be modified and additional data needed by the Handlebars template to be added. This modified data is also supplied to any event handlers | CALCFUNCTION |
| Handlers | A JavaScript function that is executed browser-side whenever the page loads or the field value changes. See Common Field Properties for an example | |
| Additional Styling Modifier | An optional CSS modifier for the field. See Common Field Properties for an example | ADDITIONALSTYLINGMODIFIER |
| 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
