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.

{ }

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": [...]
}

Text item

The text data item holds one string value.

{
    "type": "text",
    "title": "textItem",
    "name": "itemKey",
    "value": "some text value",
    "multiline": true,
}

Numeric item

The numeric data item holds one number value.

{
    "type2": "numeric",
    "title": "numericItem",
    "name": "itemKey",
    "value": 0
}

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"
}

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"
}

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" }
     ]
}

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" }
    ]
}

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"
}

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"
       }
   ]
}