Toggle menu

HTML Ajax Template

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: {"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.

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


LabelDescriptionType Name
SummaryA short description of what the field does, displayed in the forms designer to help identify itSUMMARY
TemplateThe Handlebars template. Handlebars templates look like regular HTML, with embedded handlebars expressions. There's more information in the Handlebars Editors articleTEMPLATE
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

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
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, params) {
    // Add a property called fullName to the request
    params.fullName = helper.getFieldValue("FIRSTNAME") + " " + helper.getFieldValue("LASTNAME");
    return params;

Request Function
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
Response FunctionA 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 handlersCALCFUNCTION
HandlersA 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 ModifierAn optional CSS modifier for the field. See Common Field Properties for an exampleADDITIONALSTYLINGMODIFIER
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 11 November 2022

Share this page

Facebook icon Twitter icon email icon


print icon