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:

  • panel(default)

  • tab

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