Custom Forms
A Form Definition should serve as a set of input-output rules between a user client and a GIS Cloud data container such as a layer. The definition must contain information on individual data items as well as their hierarchy. Item information has to describe the type of the data contained in the field as well as its input/output methods and optional bindings to the data source.
The definition can contain rules for multi language support as well as data validation rules.
Definition is written using JSON and has to adhere to standard JSON specification.
Data types
Number
An integer or floating point number, this should follow Javascript number notation rules.
String
A set of characters enclosed in double quotes. Follow Javascript string notation rules.
MultiLanguageString
A multi language string can appear as a normal string type but can also appear as a JSON object with keys corresponding to language abbreviations and values containing localized text.
Timestamp
With the lack of standard datetime data type support in JSON specifications, a UNIX timestamp should be used to express datetime values.
Object
An object is a collection of key/value pairs. Keys are strings and values can be any other data type, including objects.
Array
An array is an ordered collection of same type values. The JSON spec allows members of an array collection to be of varying types, but for the sake of simplicity, this is discouraged when describing GIS Cloud forms.
AutocompleteDef
This is an object which describes autocomplete rules for a text field. In it simplest form it only has a data parameter which is an array of strings which are possible autocomplete values:
{ "data": ["value 1", "second value", "another", ...] }
It can also describe a datasource from which to get possible values:
{ "layer": layerId || "auto", "url": "http://...", "rest": "datasources/2/data", "dataNode": "data", "queryExpression": "name = ${term} AND status <> 0", "valueExpression": "${ID}", "labelExpression": "${nameField} ${address}", "minTermLength": 3 }
If you set the layer id parameter to “auto” an ID of the layer the form is applied to will be used. Also, some template forms are defined:
-
${term} represents the current autocomplete term entered into the text box
-
${some_name} will reference a data field in the rest response
-
${ID} will reference the feature id
AutoitemsDef
This is an object which describes rules for getting items of a select element.
{ "sourceType": "layer", "sourceId": layerId | "auto", "queryExpression": "name = ${term} AND status <> 0", "valueExpression": "${ID}", "labelExpression": "${nameField} ${address}" }
Similar rules apply as for in AutocompleteDef.
Structure
The definition follows a hierarchical structure native to JSON. Each hierarchy item is a JSON object containing key/value pairs which describe the item.
If the item has descendants, those should be put in an array value with the key items. An exception to this rule is the SelectItem which can have its descendant data items in a property called options.
Form Definition Items
Root item
The Form Definition root item is an object with properties describing the form itself. None of the properties are mandatory and a simple empty object is in itself a valid form definition.
{ }
Property |
Type |
Description |
name |
String |
Name of the form. |
title |
MultiLanguageString |
Localizable form title. |
items |
Array |
An array of form items. |
Group item
A number of form items can be logically grouped together as items of group item. Normally, organizing items in groups has nothing to do with their data, but rather with form presentation. For example, one could use a group item to organize their form into tabs. This would require the group item mode to be set to tab.
{ "type": "group", "mode": "tab", "items": [...] }
Property |
Type |
Description |
name |
String |
Group name. |
title |
MultiLanguageString |
Localizable group title. |
mode |
String |
One of these values:
|
items |
Array |
An array of form items. |
Text item
The text data item holds one string value.
{ "type": "text", "title": "textItem", "name": "itemKey", "value": "some text value", "multiline": true, }
Property |
Type |
Description |
name |
String |
Item name. |
title |
MultiLanguageString |
Localizable item title. |
value |
String |
Initial value. Default is null. |
autocomplete |
AutocompleteDef |
Optional autocomplete data. Default is null. |
multiline |
Boolean |
Multiline text element or not. Default is false. |
Numeric item
The numeric data item holds one number value.
{ "type2": "numeric", "title": "numericItem", "name": "itemKey", "value": 0 }
Property |
Type |
Description |
name |
String |
Item name. |
title |
MultiLanguageString |
Localizable item title. |
value |
Number |
Initial value. Default is null. |
max |
Number |
Maximum value. |
min |
Number |
Minimum value |
step |
Number |
Difference between two adjacent values. |
Recording item
The text data item holds one audio recording. Internally, this is a text field holding the path to the audio file.
{ "type": "recording", "title": "recordingItem", "name": "itemKey" }
Property |
Type |
Description |
name |
String |
Item name. |
title |
MultiLanguageString |
Localizable item title. |
Photos item
The photos data item holds one or more photos. This is actually a text field containing a comma separated list of file paths.
{ "type": "photos", "title": "photosItem", "name": "itemKey" }
Property |
Type |
Description |
name |
String |
Item name. |
title |
MultiLanguageString |
Localizable item title. |
Radio item
This item represents a choice between multiple options shown as a group of radio buttons.
{ "type": "radio", "title": "radioItem", "name": "itemKey", "options": [ { "title": "value 1", "value": "one" }, { "title": "value 2", "value": "two" } ] }
Property |
Type |
Description |
name |
String |
Item name. |
title |
MultiLanguageString |
Localizable item title. |
options |
Array |
An array of Options items. |
value |
String or number |
Initial value. Default is null. |
Select item
This item represents a choice between multiple options shown as list.
{ "type": "select", "title": "selectItem", "name": "itemKey", "options": [ { "title": "value 1", "value": "one" }, { "title": "value 2", "value": "two" } ] }
Property |
Type |
Description |
name |
String |
Item name. |
title |
MultiLanguageString |
Localizable item title. |
options |
Array |
An array of Options items. |
autoitems |
AutoitemsDef |
Autopopulate definition. |
value |
String or number |
Initial value. Default is null. |
Options item
This is an item which represent one of the possible choices of the radio or the select item.
{ "title": "optionName", "value": "some value" }
Property |
Type |
Description |
title |
MultiLanguageString |
Localizable item title. |
value |
String |
Item value |
Sample form definition
{ "name": "forms_demo", "title": "MDC Demo", "items": [ { "name": "text", "title": "Text field", "type": "text" }, { "name": "number", "title": "Nuber field", "type": "numeric" }, { "name": "radio", "title": "Radio buttons", "type": "radio", "options": [ { "title": "Choice A", "value": "a" }, { "title": "Choice B", "value": "b" }, { "title": "Choice C", "value": "c" } ] }, { "name": "select", "title": "Selection", "type": "select", "options": [ { "title": "Option 1", "value": "1" }, { "title": "Option 2", "value": "2" }, { "title": "Option 3", "value": "3" }, { "title": "Option 4", "value": "4" }, { "title": "Option 5", "value": "5" } ] }, { "name": "photos", "title": "Photos", "type": "photos" }, { "name": "audio", "title": "Audio recording", "type": "recording" } ] }