The various Field types collect different types of data. Attributes can be included within the Field tags to fine tune the functionality of each Field. All the Field types share a set of common attributes but they can also have their own specific attributes. Click on the relevant field to see the attributes that you can include within the Field tag:

  • Page field:  allows multiple fields to be displayed together on a page
  • Choice field: allows the collection of a user’s “choice” from a set of options
  • Location field: captures the device’s location
  • Orientation field: captures the device’s orientation
  • Media fields: abstract notion of a field which can collect one or more media attachments
  • Button field: represents a button the user can press
  • Label field: represents a non-interactive text label
  • Text field: allows a string of text to be captured
  • Check field: represents a ‘true’/’false’ check box the user can check
  • List field: represents a flat list of items
  • MultiList field: represents a hierarchical list of items
  • Item: represents the options within a List or MultiList
  • HTML field: acts as a web browser and can display either locally stored or online web pages
  • Trigger field: acts as a jump from a particular Field within a Form
  • LinksTo field: acts as a navigational jump from one Form to another (without any relationship between the two Forms)
  • BelongsTo field: used to declare a one-to-many relationship between an instance of the current Form and an instance of an “owning” Form
  • Constraint: used to impose constraints on the set of Form instances (not a field, only can be used as a child element)
  • Logging field: used to store log files (analytics of where users click within a project)

Page

   Parent elements: Form
   Child elements: any Field, except for another Page

   The Page field has none of its own specific attributes.

Common field attributes

Attribute Required Values Default value Explanation
id Yes if the field is a root Any text n/a A unique identifier for a particular field
caption (aka: label) No Any text n/a A written description of what this field represents (to display alongside the field where necessary).
optional No true, false false Whether or not the user can skip this field without entering information.
jump No Any text (id of an existing field) n/a The ID of the field to jump to once the user has finished with this field, or one of the special jumps documented here.
skipOnBack No true, false false Whether or not this field should be skipped when the user goes backwards through fields they have already encountered. This behaviour could be useful in fields such as Location or Orientation.
showOnCreate No true, false true Whether or not to show this field when the user is in ‘create’ mode (they are creating a new record, rather than editing an existing one).
showOnEdit No true, false true Whether or not to show this field when the user is in ‘edit’ mode (they are editing an existing record).
editable No true, false true Whether or not the value originally set for this field can later be changed when the user is in ‘edit’ mode.
showBackOnCreate No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘create’ mode.
showBackOnEdit No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘edit’ mode.
showCancelOnCreate No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘create’ mode.
showCancelOnEdit No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘edit’ mode.
showForwardOnCreate No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘create’ mode.
showForwardOnEdit No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘edit’ mode.
showBack No true, false true Whether or not to present the ‘back’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showCancel No true, false true Whether or not to present the ‘cancel’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showForward No true, false true Whether or not to present the ‘forward’ button to the user on this field. NOTE: Overrides mode-specific settings above.

Choice

   Parent elements: Form, Page, Choice
   Child elements: Choice

Choice attributes

Attribute Required Values Default Value Explanation
caption (aka: label, alt) No Any text n/a If a caption is present for a non-root Choice field, it will be displayed beneath the choice’s image whenever the choice is to be presented as an answer. For root choices, the caption will only ever be displayed above the choice field if it is on a page. To control how the caption is displayed on non-root items see the captionHeight attribute.
value No Any text n/a The value that this choice represents when the user selects it as an answer (i.e. the data to record for this field, if this choice was a leaf of the choice tree).
img No Relative Path to Image File n/a The image to display for this choice when it is presented to the user as one possible answer to a question.
captionHeight No Any decimal between 0 and 1 (inclusive) 0.25; or 0 when caption is given using the alt alias; or inherited from parent choice Determines what proportion of the UI element that represents the choice as an answer should be taken up by the caption text, as opposed to the corresponding image. For example, setting captionHeight to 0.4 would give 60% of the choice’s height to its image and the remaining 40% to the textual caption.
matchTextSize No true, false true; or inherited from parent choice Whether or not the font size of text displayed on choices (as captions or instead of an image) should be coordinated across choice siblings (i.e. per “screen”).
backgroundColor No Hex colour code (e.g. #000000) #FFFFFF (white) Background colour for the UI element that represents this choice when presented as an answer, expressed as a hexadecimal #RRGGBB code.
crossed No true, false false Whether or not a cross should be positioned on top of the UI element for this choice when it is presented as an answer.
crossColor No Hex colour code (e.g. #000000) #A5FF0000 (Red with 65% alpha) The colour of the cross that could be positioned on top of the choice, expressed as a hexadecimal #AARRGGBB code (supports an opacity value).
noColumn No true, false false Setting this attribute to true on the root of a choice tree (it is ignored on children) specifies that the choice tree will not produce any data (i.e. the field will not be backed by a database column). Such choice trees without a column are useful as a means to direct control flow in a form or project.
cols No Any positive whole number 1 The number of columns with which to display children (answers) of this choice when it is presented as a question.
rows No Any positive whole number 2 The number of rows with which to display children (answers) of this choice when it is presented as a question.


Common field attributes

Attribute Required Values Default value Explanation
id Yes if the field is a root Any text n/a A unique identifier for a particular field
caption (aka: label) No Any text n/a A written description of what this field represents (to display alongside the field where necessary).
optional No true, false false Whether or not the user can skip this field without entering information.
jump No Any text (id of an existing field) n/a The ID of the field to jump to once the user has finished with this field, or one of the special jumps documented here.
skipOnBack No true, false false Whether or not this field should be skipped when the user goes backwards through fields they have already encountered. This behaviour could be useful in fields such as Location or Orientation.
showOnCreate No true, false true Whether or not to show this field when the user is in ‘create’ mode (they are creating a new record, rather than editing an existing one).
showOnEdit No true, false true Whether or not to show this field when the user is in ‘edit’ mode (they are editing an existing record).
editable No true, false true Whether or not the value originally set for this field can later be changed when the user is in ‘edit’ mode.
showBackOnCreate No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘create’ mode.
showBackOnEdit No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘edit’ mode.
showCancelOnCreate No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘create’ mode.
showCancelOnEdit No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘edit’ mode.
showForwardOnCreate No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘create’ mode.
showForwardOnEdit No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘edit’ mode.
showBack No true, false true Whether or not to present the ‘back’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showCancel No true, false true Whether or not to present the ‘cancel’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showForward No true, false true Whether or not to present the ‘forward’ button to the user on this field. NOTE: Overrides mode-specific settings above.

Location

   Parent elements: Form, Page
   Child elements: none

Location attributes

Attribute Required Values Default Value Explanation
type No any, GPS, network GPS Specifies which source of location data should be recorded at this field.
startWith No form, page, field form When to start ‘listening’ for location data — as soon as the user enters the form (‘form’), as soon as the user enters the page containing this field (‘page’ — only valid if the location field is actually on a page), or not until the user reaches this particular field (‘field’).
waitAtField No true, false false If true, the application will force the user to wait until a sufficiently accurate and recent (as specified by the maxAccuracyRadius and maxAge attributes respectively) location is received using the provider specified in the type attribute. The user must wait at this field until an acceptable location is found in the time since they entered this field, regardless of the setting on the startWith attribute. Once such a location is received the user can proceed to the next field. If false, the current best known location will be used if it is sufficiently recent and accurate and is from the specified provider, even if it was recorded before the user entered this location field.
useBestKnownLocationOnTimeout No true, false true Whether or not to accept a sub-optimal location (in terms of accuracy, recency and provider) if no satisfactory location is detected after listening for timeout seconds.
timeout No Any positive whole number (seconds) 300s (5min) Amount of time to wait before using the best known location regardless of whether or not it is sufficient in terms of accuracy, recency and provider.
maxAge No Any positive whole number (seconds) 600s (10min) The maximum age that location data can be before it is deemed too old to record.
maxAccuracyRadius No Any positive float (meters) 75.0m The maximum accuracy that location data can be before it is deemed too inaccurate to record, expressed as a float that represents the maximum accuracy radius in metres.
doublePrecision No true, false false Whether to use double precision (64 bits) or single precision (32 bits) when storing latitude, longitude and altitude values
storeAltitude No true, false true Whether or not the user’s altitude should be stored for this field (if the survey device supports it).
storeBearing No true, false false Whether or not the user’s bearing should be stored for this field (if the survey device supports it).
storeSpeed No true, false false Whether or not the user’s speed should be stored for this field (if the survey device supports it).
storeAccuracy No true, false true Whether or not the accuracy of the final location data that is stored with this field should also be stored.
storeProvider No true, false false Whether or not the location provider used to obtain the final location data should also be stored.

 

Common field attributes

Attribute Required Values Default value Explanation
id Yes if the field is a root Any text n/a A unique identifier for a particular field
caption (aka: label) No Any text n/a A written description of what this field represents (to display alongside the field where necessary).
optional No true, false false Whether or not the user can skip this field without entering information.
jump No Any text (id of an existing field) n/a The ID of the field to jump to once the user has finished with this field, or one of the special jumps documented here.
skipOnBack No true, false false Whether or not this field should be skipped when the user goes backwards through fields they have already encountered. This behaviour could be useful in fields such as Location or Orientation.
showOnCreate No true, false true Whether or not to show this field when the user is in ‘create’ mode (they are creating a new record, rather than editing an existing one).
showOnEdit No true, false true Whether or not to show this field when the user is in ‘edit’ mode (they are editing an existing record).
editable No true, false true Whether or not the value originally set for this field can later be changed when the user is in ‘edit’ mode.
showBackOnCreate No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘create’ mode.
showBackOnEdit No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘edit’ mode.
showCancelOnCreate No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘create’ mode.
showCancelOnEdit No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘edit’ mode.
showForwardOnCreate No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘create’ mode.
showForwardOnEdit No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘edit’ mode.
showBack No true, false true Whether or not to present the ‘back’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showCancel No true, false true Whether or not to present the ‘cancel’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showForward No true, false true Whether or not to present the ‘forward’ button to the user on this field. NOTE: Overrides mode-specific settings above.

Orientation

   Parent elements: Form, Page
   Child elements: none

Orientation attributes

Attribute Required Values Default Value Explanation
storeAzimuth No true, false true Whether or not to store azimuth.
storePitch No true, false true Whether or not to store pitch.
storeRoll No true, false true Whether or not to store roll.

Common field attributes

Attribute Required Values Default value Explanation
id Yes if the field is a root Any text n/a A unique identifier for a particular field
caption (aka: label) No Any text n/a A written description of what this field represents (to display alongside the field where necessary).
optional No true, false false Whether or not the user can skip this field without entering information.
jump No Any text (id of an existing field) n/a The ID of the field to jump to once the user has finished with this field, or one of the special jumps documented here.
skipOnBack No true, false false Whether or not this field should be skipped when the user goes backwards through fields they have already encountered. This behaviour could be useful in fields such as Location or Orientation.
showOnCreate No true, false true Whether or not to show this field when the user is in ‘create’ mode (they are creating a new record, rather than editing an existing one).
showOnEdit No true, false true Whether or not to show this field when the user is in ‘edit’ mode (they are editing an existing record).
editable No true, false true Whether or not the value originally set for this field can later be changed when the user is in ‘edit’ mode.
showBackOnCreate No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘create’ mode.
showBackOnEdit No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘edit’ mode.
showCancelOnCreate No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘create’ mode.
showCancelOnEdit No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘edit’ mode.
showForwardOnCreate No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘create’ mode.
showForwardOnEdit No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘edit’ mode.
showBack No true, false true Whether or not to present the ‘back’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showCancel No true, false true Whether or not to present the ‘cancel’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showForward No true, false true Whether or not to present the ‘forward’ button to the user on this field. NOTE: Overrides mode-specific settings above.

Photo

   Parent elements: Form, Page
   Child elements: none

Photo attributes

Attribute Required Values Default Value Explanation
max No Any integer (whole number) 255 The maximum number of photos that can be attached to this field. If max is set to 1, then the multi-item review interface is disabled and the user can only ever visit the single-item review interface to review their capture.
review No true, false true Whether or not to allow the user to review the photo they have just made. If set to false, the user will be taken straight to the next field when they make a capture.
discardImg No A relative path to an image file n/a Path to a custom image to use on the “discard media” button (default is a trash can icon).
approveImg No A relative path to an image file n/a Path to a custom image to use on the “approve media” button (default is a tick icon).
useFrontCamera No true, false false Whether or not to use the device’s front-facing camera (if it exists).
captureImg No A relative path to an image file n/a Path to a file containing the custom image to be used for the “take photo” button (default is a camera icon).
flash No on, always, true, auto, off, never, false auto Which setting to use for the camera’s flash (if it exists — note that most phones do not have flashes on their front-facing cameras).

 

Common field attributes

Attribute Required Values Default value Explanation
id Yes if the field is a root Any text n/a A unique identifier for a particular field
caption (aka: label) No Any text n/a A written description of what this field represents (to display alongside the field where necessary).
optional No true, false false Whether or not the user can skip this field without entering information.
jump No Any text (id of an existing field) n/a The ID of the field to jump to once the user has finished with this field, or one of the special jumps documented here.
skipOnBack No true, false false Whether or not this field should be skipped when the user goes backwards through fields they have already encountered. This behaviour could be useful in fields such as Location or Orientation.
showOnCreate No true, false true Whether or not to show this field when the user is in ‘create’ mode (they are creating a new record, rather than editing an existing one).
showOnEdit No true, false true Whether or not to show this field when the user is in ‘edit’ mode (they are editing an existing record).
editable No true, false true Whether or not the value originally set for this field can later be changed when the user is in ‘edit’ mode.
showBackOnCreate No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘create’ mode.
showBackOnEdit No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘edit’ mode.
showCancelOnCreate No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘create’ mode.
showCancelOnEdit No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘edit’ mode.
showForwardOnCreate No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘create’ mode.
showForwardOnEdit No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘edit’ mode.
showBack No true, false true Whether or not to present the ‘back’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showCancel No true, false true Whether or not to present the ‘cancel’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showForward No true, false true Whether or not to present the ‘forward’ button to the user on this field. NOTE: Overrides mode-specific settings above.

Audio

   Parent elements: Form, Page
   Child elements: none

Audio attributes

Attribute Required Values Default Value Explanation
max No Any integer (whole number) 255 The maximum number of audio recordings that can be attached to this field. If max is set to 1, then the multi-item review interface is disabled and the user can only ever visit the single-item review interface to review their audio.
review No true, false true Whether or not to allow the user to review the audio they have just made. If set to false, the user will be taken straight to the next field when they make a recording.
approveImg No A relative path to an image file n/a Path to a custom image to use on the “approve media” button (default is a tick icon).
discardImg No A relative path to an image file n/a Path to a custom image to use on the “discard media” button (default is a trash can icon).
startRecImg No A relative path to an image file n/a Path to a file containing the custom image to be used for the “start recording” button.
stopRecImg No A relative path to an image file n/a Path to a file containing the custom image to be used for the “stop recording” button.
recordingImg No A relative path to an image file n/a Path to a file containing the custom image to be used to represent the audio at the review stage (default is a cassette icon).
startPlaybackImg No A relative path to an image file n/a Path to a file containing the custom image to be used for the “start audio playback” button (default is a play icon).
stopPlaybackImg No A relative path to an image file n/a Path to a file containing the custom image to be used for the “stop audio playback” button (default is a stop icon).

 

Common field attributes

Attribute Required Values Default value Explanation
id Yes if the field is a root Any text n/a A unique identifier for a particular field
caption (aka: label) No Any text n/a A written description of what this field represents (to display alongside the field where necessary).
optional No true, false false Whether or not the user can skip this field without entering information.
jump No Any text (id of an existing field) n/a The ID of the field to jump to once the user has finished with this field, or one of the special jumps documented here.
skipOnBack No true, false false Whether or not this field should be skipped when the user goes backwards through fields they have already encountered. This behaviour could be useful in fields such as Location or Orientation.
showOnCreate No true, false true Whether or not to show this field when the user is in ‘create’ mode (they are creating a new record, rather than editing an existing one).
showOnEdit No true, false true Whether or not to show this field when the user is in ‘edit’ mode (they are editing an existing record).
editable No true, false true Whether or not the value originally set for this field can later be changed when the user is in ‘edit’ mode.
showBackOnCreate No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘create’ mode.
showBackOnEdit No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘edit’ mode.
showCancelOnCreate No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘create’ mode.
showCancelOnEdit No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘edit’ mode.
showForwardOnCreate No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘create’ mode.
showForwardOnEdit No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘edit’ mode.
showBack No true, false true Whether or not to present the ‘back’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showCancel No true, false true Whether or not to present the ‘cancel’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showForward No true, false true Whether or not to present the ‘forward’ button to the user on this field. NOTE: Overrides mode-specific settings above.

Video

   Parent elements: Form, Page
   Child elements: none

Video attributes

Attribute Required Values Default Value Explanation
max No Any integer (whole number) 255 The maximum number of photos that can be attached to this field. If max is set to 1, then the multi-item review interface is disabled and the user can only ever visit the single-item review interface to review their capture.
review No true, false true Whether or not to allow the user to review the photo they have just made. If set to false, the user will be taken straight to the next field when they make a capture.
approveImg No A relative path to an image file n/a Path to a custom image to use on the “approve media” button (default is a tick icon).
discardImg No A relative path to an image file n/a Path to a custom image to use on the “discard media” button (default is a trash can icon).
useFrontCamera No true, false false Whether or not to use the device’s front-facing camera (if it exists).
startRecImg No A relative path to an image file n/a Path to a file containing the custom image to be used for the “start recording” button.
stopRecImg No A relative path to an image file n/a Path to a file containing the custom image to be used for the “stop recording” button.
startPlaybackImg No A relative path to an image file n/a Path to a file containing the custom image to be used for the “start video playback” button (default is a play icon).
stopPlaybackImg No A relative path to an image file n/a Path to a file containing the custom image to be used for the “stop video playback” button (default is a stop icon).

 

Common field attributes

Attribute Required Values Default value Explanation
id Yes if the field is a root Any text n/a A unique identifier for a particular field
caption (aka: label) No Any text n/a A written description of what this field represents (to display alongside the field where necessary).
optional No true, false false Whether or not the user can skip this field without entering information.
jump No Any text (id of an existing field) n/a The ID of the field to jump to once the user has finished with this field, or one of the special jumps documented here.
skipOnBack No true, false false Whether or not this field should be skipped when the user goes backwards through fields they have already encountered. This behaviour could be useful in fields such as Location or Orientation.
showOnCreate No true, false true Whether or not to show this field when the user is in ‘create’ mode (they are creating a new record, rather than editing an existing one).
showOnEdit No true, false true Whether or not to show this field when the user is in ‘edit’ mode (they are editing an existing record).
editable No true, false true Whether or not the value originally set for this field can later be changed when the user is in ‘edit’ mode.
showBackOnCreate No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘create’ mode.
showBackOnEdit No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘edit’ mode.
showCancelOnCreate No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘create’ mode.
showCancelOnEdit No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘edit’ mode.
showForwardOnCreate No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘create’ mode.
showForwardOnEdit No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘edit’ mode.
showBack No true, false true Whether or not to present the ‘back’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showCancel No true, false true Whether or not to present the ‘cancel’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showForward No true, false true Whether or not to present the ‘forward’ button to the user on this field. NOTE: Overrides mode-specific settings above.

Button

   Parent elements: Form, Page
   Child elements: none

Button attribute

Attribute Required Values Default Value Explanation
column No none, boolean, datetime none The type of data to store, associated with this button. If “none”, no data is stored regardless of user interaction. If “boolean”, then “true” will be stored if the button was pressed and “false” will be stored if the button was displayed to the user but they chose not to press it. If “datetime”, then pressing the button will store the timestamp for the point in time when the button was pressed. Note that if the column type is set to “datetime” and the field is not marked as optional then the user will not be able to complete the form until they press the button.

Common field attributes

Attribute Required Values Default value Explanation
id Yes if the field is a root Any text n/a A unique identifier for a particular field
caption (aka: label) No Any text n/a A written description of what this field represents (to display alongside the field where necessary).
optional No true, false false Whether or not the user can skip this field without entering information.
jump No Any text (id of an existing field) n/a The ID of the field to jump to once the user has finished with this field, or one of the special jumps documented here.
skipOnBack No true, false false Whether or not this field should be skipped when the user goes backwards through fields they have already encountered. This behaviour could be useful in fields such as Location or Orientation.
showOnCreate No true, false true Whether or not to show this field when the user is in ‘create’ mode (they are creating a new record, rather than editing an existing one).
showOnEdit No true, false true Whether or not to show this field when the user is in ‘edit’ mode (they are editing an existing record).
editable No true, false true Whether or not the value originally set for this field can later be changed when the user is in ‘edit’ mode.
showBackOnCreate No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘create’ mode.
showBackOnEdit No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘edit’ mode.
showCancelOnCreate No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘create’ mode.
showCancelOnEdit No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘edit’ mode.
showForwardOnCreate No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘create’ mode.
showForwardOnEdit No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘edit’ mode.
showBack No true, false true Whether or not to present the ‘back’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showCancel No true, false true Whether or not to present the ‘cancel’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showForward No true, false true Whether or not to present the ‘forward’ button to the user on this field. NOTE: Overrides mode-specific settings above.

Label

   Parent elements: Form, Page
   Child elements: none

Label attributes

Attribute Required Values Default Value Explanation
caption (aka: label) No Any text n/a The caption attribute is used to specify the text content of the label.
scale No Any positive number 1.0 Factor by which to scale the text in the label from the default size specified by Android.
centered No true, false false Whether or not the text should be centred within the label.

 

Common field attributes

Attribute Required Values Default value Explanation
id Yes if the field is a root Any text n/a A unique identifier for a particular field
caption (aka: label) No Any text n/a A written description of what this field represents (to display alongside the field where necessary).
optional No true, false false Whether or not the user can skip this field without entering information.
jump No Any text (id of an existing field) n/a The ID of the field to jump to once the user has finished with this field, or one of the special jumps documented here.
skipOnBack No true, false false Whether or not this field should be skipped when the user goes backwards through fields they have already encountered. This behaviour could be useful in fields such as Location or Orientation.
showOnCreate No true, false true Whether or not to show this field when the user is in ‘create’ mode (they are creating a new record, rather than editing an existing one).
showOnEdit No true, false true Whether or not to show this field when the user is in ‘edit’ mode (they are editing an existing record).
editable No true, false true Whether or not the value originally set for this field can later be changed when the user is in ‘edit’ mode.
showBackOnCreate No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘create’ mode.
showBackOnEdit No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘edit’ mode.
showCancelOnCreate No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘create’ mode.
showCancelOnEdit No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘edit’ mode.
showForwardOnCreate No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘create’ mode.
showForwardOnEdit No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘edit’ mode.
showBack No true, false true Whether or not to present the ‘back’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showCancel No true, false true Whether or not to present the ‘cancel’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showForward No true, false true Whether or not to present the ‘forward’ button to the user on this field. NOTE: Overrides mode-specific settings above.

Text

   Parent elements: Form, Page
   Child elements: none

Text attributes

Attribute Required Values Default Value Explanation
caption (aka: label) No Any text n/a The field caption is used as a label for the text box.
minLength No Any unsigned whole number greater than or equal to 0 0 (if this field is optional), 1 (if this field is not optional) The minimum number of characters that should be deemed an acceptable submission for this field.
maxLength No Any unsigned positive whole number 128 The maximum number of characters that should be deemed an acceptable submission for this field.
multiLine No true, false false Whether or not the user’s submission for this field may span multiple lines.
defaultValue (aka: initialValue) No Any text Null if field is optional, empty text otherwise The default value to submit for this field if the user does not provide a response.
content No text, password, email, phonenumber, unsignedint, signedint, unsignedlong, signedlong, unsignedfloat, signedfloat, unsigneddouble, signeddouble text The content type that this field expects (this may alter how the user interacts with the field – for example, selecting a numerical content type may present a numerical keyboard rather than the usual alphanumeric).
regex No A Java-syntax regular expression as a string n/a A regular expression against which to match the user’s submission. If this attribute is provided, only submissions which match the regular expression will be accepted.
autoCaps No none, all, words, sentences none The mode for auto-capitalising user submissions for this field: none (no auto-capitalisation), all (capitalise all characters), words (only capitalise letters at the start of words), sentences (only capitalise letters at the start of sentences) Note these are only applied if content = “text”.

 

Common field attributes

Attribute Required Values Default value Explanation
id Yes if the field is a root Any text n/a A unique identifier for a particular field
caption (aka: label) No Any text n/a A written description of what this field represents (to display alongside the field where necessary).
optional No true, false false Whether or not the user can skip this field without entering information.
jump No Any text (id of an existing field) n/a The ID of the field to jump to once the user has finished with this field, or one of the special jumps documented here.
skipOnBack No true, false false Whether or not this field should be skipped when the user goes backwards through fields they have already encountered. This behaviour could be useful in fields such as Location or Orientation.
showOnCreate No true, false true Whether or not to show this field when the user is in ‘create’ mode (they are creating a new record, rather than editing an existing one).
showOnEdit No true, false true Whether or not to show this field when the user is in ‘edit’ mode (they are editing an existing record).
editable No true, false true Whether or not the value originally set for this field can later be changed when the user is in ‘edit’ mode.
showBackOnCreate No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘create’ mode.
showBackOnEdit No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘edit’ mode.
showCancelOnCreate No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘create’ mode.
showCancelOnEdit No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘edit’ mode.
showForwardOnCreate No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘create’ mode.
showForwardOnEdit No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘edit’ mode.
showBack No true, false true Whether or not to present the ‘back’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showCancel No true, false true Whether or not to present the ‘cancel’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showForward No true, false true Whether or not to present the ‘forward’ button to the user on this field. NOTE: Overrides mode-specific settings above.

Check

   Parent elements: Form, Page
   Child elements: none

Check attributes

Attribute Required Values Default Value Explanation
caption (aka: label) No Any text n/a The field caption is used as a label for the check box.
defaultValue No true, false false Whether or not to check this check box before the user has interacted with it.

 

Common field attributes

Attribute Required Values Default value Explanation
id Yes if the field is a root Any text n/a A unique identifier for a particular field
caption (aka: label) No Any text n/a A written description of what this field represents (to display alongside the field where necessary).
optional No true, false false Whether or not the user can skip this field without entering information.
jump No Any text (id of an existing field) n/a The ID of the field to jump to once the user has finished with this field, or one of the special jumps documented here.
skipOnBack No true, false false Whether or not this field should be skipped when the user goes backwards through fields they have already encountered. This behaviour could be useful in fields such as Location or Orientation.
showOnCreate No true, false true Whether or not to show this field when the user is in ‘create’ mode (they are creating a new record, rather than editing an existing one).
showOnEdit No true, false true Whether or not to show this field when the user is in ‘edit’ mode (they are editing an existing record).
editable No true, false true Whether or not the value originally set for this field can later be changed when the user is in ‘edit’ mode.
showBackOnCreate No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘create’ mode.
showBackOnEdit No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘edit’ mode.
showCancelOnCreate No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘create’ mode.
showCancelOnEdit No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘edit’ mode.
showForwardOnCreate No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘create’ mode.
showForwardOnEdit No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘edit’ mode.
showBack No true, false true Whether or not to present the ‘back’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showCancel No true, false true Whether or not to present the ‘cancel’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showForward No true, false true Whether or not to present the ‘forward’ button to the user on this field. NOTE: Overrides mode-specific settings above.

List

   Parent elements: Form, Page
   Child elements: Item

List attributes

Attribute Required Values Default Value Explanation
caption (aka: label) No Any text n/a The title of the list.
preSelectDefault No true, false true Whether or not to automatically select the default item before the user has interacted with the list.

 

Common field attributes

Attribute Required Values Default value Explanation
id Yes if the field is a root Any text n/a A unique identifier for a particular field
caption (aka: label) No Any text n/a A written description of what this field represents (to display alongside the field where necessary).
optional No true, false false Whether or not the user can skip this field without entering information.
jump No Any text (id of an existing field) n/a The ID of the field to jump to once the user has finished with this field, or one of the special jumps documented here.
skipOnBack No true, false false Whether or not this field should be skipped when the user goes backwards through fields they have already encountered. This behaviour could be useful in fields such as Location or Orientation.
showOnCreate No true, false true Whether or not to show this field when the user is in ‘create’ mode (they are creating a new record, rather than editing an existing one).
showOnEdit No true, false true Whether or not to show this field when the user is in ‘edit’ mode (they are editing an existing record).
editable No true, false true Whether or not the value originally set for this field can later be changed when the user is in ‘edit’ mode.
showBackOnCreate No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘create’ mode.
showBackOnEdit No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘edit’ mode.
showCancelOnCreate No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘create’ mode.
showCancelOnEdit No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘edit’ mode.
showForwardOnCreate No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘create’ mode.
showForwardOnEdit No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘edit’ mode.
showBack No true, false true Whether or not to present the ‘back’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showCancel No true, false true Whether or not to present the ‘cancel’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showForward No true, false true Whether or not to present the ‘forward’ button to the user on this field. NOTE: Overrides mode-specific settings above.

MultiList

   Parent elements: Form, Page
   Child elements: Item

MultiList attributes

Attribute Required Values Default Value Explanation
caption (aka: labels, captions, label) Yes A list of caption texts, one for each level of the list hierarchy, separated by a semi-colon (;) n/a The titles for each sub-list, increasing in specificity from left to right.
preSelectDefault No true, false true Whether or not to automatically select the default item before the user has interacted with the list.

 

Common field attributes

Attribute Required Values Default value Explanation
id Yes if the field is a root Any text n/a A unique identifier for a particular field
caption (aka: label) No Any text n/a A written description of what this field represents (to display alongside the field where necessary).
optional No true, false false Whether or not the user can skip this field without entering information.
jump No Any text (id of an existing field) n/a The ID of the field to jump to once the user has finished with this field, or one of the special jumps documented here.
skipOnBack No true, false false Whether or not this field should be skipped when the user goes backwards through fields they have already encountered. This behaviour could be useful in fields such as Location or Orientation.
showOnCreate No true, false true Whether or not to show this field when the user is in ‘create’ mode (they are creating a new record, rather than editing an existing one).
showOnEdit No true, false true Whether or not to show this field when the user is in ‘edit’ mode (they are editing an existing record).
editable No true, false true Whether or not the value originally set for this field can later be changed when the user is in ‘edit’ mode.
showBackOnCreate No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘create’ mode.
showBackOnEdit No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘edit’ mode.
showCancelOnCreate No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘create’ mode.
showCancelOnEdit No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘edit’ mode.
showForwardOnCreate No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘create’ mode.
showForwardOnEdit No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘edit’ mode.
showBack No true, false true Whether or not to present the ‘back’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showCancel No true, false true Whether or not to present the ‘cancel’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showForward No true, false true Whether or not to present the ‘forward’ button to the user on this field. NOTE: Overrides mode-specific settings above.

Item

   Parent elements: List, MultiList, Item (when used within a Multilist)
   Child elements: Item (when used within a Multilist)

Item attributes

Attribute Required Values Default Value Explanation
value Yes Any text n/a The value to be displayed on this list item.
default No true, false false Whether or not this item is the default item in its containing list. If multiple items are marked as the default then the first such item will be used as the default.

Common field attributes

Attribute Required Values Default value Explanation
id Yes if the field is a root Any text n/a A unique identifier for a particular field
caption (aka: label) No Any text n/a A written description of what this field represents (to display alongside the field where necessary).
optional No true, false false Whether or not the user can skip this field without entering information.
jump No Any text (id of an existing field) n/a The ID of the field to jump to once the user has finished with this field, or one of the special jumps documented here.
skipOnBack No true, false false Whether or not this field should be skipped when the user goes backwards through fields they have already encountered. This behaviour could be useful in fields such as Location or Orientation.
showOnCreate No true, false true Whether or not to show this field when the user is in ‘create’ mode (they are creating a new record, rather than editing an existing one).
showOnEdit No true, false true Whether or not to show this field when the user is in ‘edit’ mode (they are editing an existing record).
editable No true, false true Whether or not the value originally set for this field can later be changed when the user is in ‘edit’ mode.
showBackOnCreate No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘create’ mode.
showBackOnEdit No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘edit’ mode.
showCancelOnCreate No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘create’ mode.
showCancelOnEdit No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘edit’ mode.
showForwardOnCreate No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘create’ mode.
showForwardOnEdit No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘edit’ mode.
showBack No true, false true Whether or not to present the ‘back’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showCancel No true, false true Whether or not to present the ‘cancel’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showForward No true, false true Whether or not to present the ‘forward’ button to the user on this field. NOTE: Overrides mode-specific settings above.

HTML

   Parent elements: Form, Page
   Child elements: none

HTML attributes

Attribute Required Values Default Value Explanation
caption (aka: label) No Any text n/a The caption attribute is used to specify the text content of the label.
url Yes The URL of any website n/a The URL of any website that will be loaded inside the webview
externalLinks No true, false false Whether or not the the links of this webpage will load open externally on the device’s default brwoser.

 

Common field attributes

Attribute Required Values Default value Explanation
id Yes if the field is a root Any text n/a A unique identifier for a particular field
caption (aka: label) No Any text n/a A written description of what this field represents (to display alongside the field where necessary).
optional No true, false false Whether or not the user can skip this field without entering information.
jump No Any text (id of an existing field) n/a The ID of the field to jump to once the user has finished with this field, or one of the special jumps documented here.
skipOnBack No true, false false Whether or not this field should be skipped when the user goes backwards through fields they have already encountered. This behaviour could be useful in fields such as Location or Orientation.
showOnCreate No true, false true Whether or not to show this field when the user is in ‘create’ mode (they are creating a new record, rather than editing an existing one).
showOnEdit No true, false true Whether or not to show this field when the user is in ‘edit’ mode (they are editing an existing record).
editable No true, false true Whether or not the value originally set for this field can later be changed when the user is in ‘edit’ mode.
showBackOnCreate No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘create’ mode.
showBackOnEdit No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘edit’ mode.
showCancelOnCreate No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘create’ mode.
showCancelOnEdit No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘edit’ mode.
showForwardOnCreate No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘create’ mode.
showForwardOnEdit No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘edit’ mode.
showBack No true, false true Whether or not to present the ‘back’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showCancel No true, false true Whether or not to present the ‘cancel’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showForward No true, false true Whether or not to present the ‘forward’ button to the user on this field. NOTE: Overrides mode-specific settings above.

Trigger

  Parent elements: Form, Page
  Child elements: none

Trigger attributes

Attribute Required Values Default Value Explanation
jump No Any text (id of an existing Field) n/a The ID of the field to jump to when this trigger is activated.
key (aka: keys) No A list of key codes separated by |; or simply ANY to respond to any key input n/a The key(s) that will activate this trigger when pressed.
fixedTimer No No timeout n/a The duration (in seconds) to wait before enacting the specified jump.

  Parent elements: Form
  Child elements: none

LinksTo attribute

Attribute Required Values Default Value Explanation
form Yes The ID of a different form n/a The ID of the form to link to.

Common field attributes

Attribute Required Values Default value Explanation
id Yes if the field is a root Any text n/a A unique identifier for a particular field
caption (aka: label) No Any text n/a A written description of what this field represents (to display alongside the field where necessary).
optional No true, false false Whether or not the user can skip this field without entering information.
jump No Any text (id of an existing field) n/a The ID of the field to jump to once the user has finished with this field, or one of the special jumps documented here.
skipOnBack No true, false false Whether or not this field should be skipped when the user goes backwards through fields they have already encountered. This behaviour could be useful in fields such as Location or Orientation.
showOnCreate No true, false true Whether or not to show this field when the user is in ‘create’ mode (they are creating a new record, rather than editing an existing one).
showOnEdit No true, false true Whether or not to show this field when the user is in ‘edit’ mode (they are editing an existing record).
editable No true, false true Whether or not the value originally set for this field can later be changed when the user is in ‘edit’ mode.
showBackOnCreate No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘create’ mode.
showBackOnEdit No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘edit’ mode.
showCancelOnCreate No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘create’ mode.
showCancelOnEdit No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘edit’ mode.
showForwardOnCreate No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘create’ mode.
showForwardOnEdit No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘edit’ mode.
showBack No true, false true Whether or not to present the ‘back’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showCancel No true, false true Whether or not to present the ‘cancel’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showForward No true, false true Whether or not to present the ‘forward’ button to the user on this field. NOTE: Overrides mode-specific settings above.

BelongsTo

  Parent elements: Form
  Child elements: Constraint

BelongsTo attributes

Attribute Required Values Default Value Explanation
form Yes The ID of a different form n/a The ID of the form to which this one “belongs” (e.g. the “pet” form belongs to the “pupil” form).
remember (aka: hold) No true, false false Whether or not an instance of the “owning” form (e.g. “pupil”) should be remembered. If “true”, any submissions of the “owned” form (e.g. “pet”) will be associated with the same instance of the owning form until the user explicitly requests that a new instance of the owning form be created (a one-to-many relationship). If “false” the user will be prompted to create a new instance of the “owning” form each time they start a new instance of the “owned” form (a one-to-one relationship).

Common field attributes

Attribute Required Values Default value Explanation
id Yes if the field is a root Any text n/a A unique identifier for a particular field
caption (aka: label) No Any text n/a A written description of what this field represents (to display alongside the field where necessary).
optional No true, false false Whether or not the user can skip this field without entering information.
jump No Any text (id of an existing field) n/a The ID of the field to jump to once the user has finished with this field, or one of the special jumps documented here.
skipOnBack No true, false false Whether or not this field should be skipped when the user goes backwards through fields they have already encountered. This behaviour could be useful in fields such as Location or Orientation.
showOnCreate No true, false true Whether or not to show this field when the user is in ‘create’ mode (they are creating a new record, rather than editing an existing one).
showOnEdit No true, false true Whether or not to show this field when the user is in ‘edit’ mode (they are editing an existing record).
editable No true, false true Whether or not the value originally set for this field can later be changed when the user is in ‘edit’ mode.
showBackOnCreate No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘create’ mode.
showBackOnEdit No true, false true Whether or not to show the ‘back’ button when the user is on this field and in ‘edit’ mode.
showCancelOnCreate No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘create’ mode.
showCancelOnEdit No true, false true Whether or not to show the ‘cancel’ button when the user is on this field and in ‘edit’ mode.
showForwardOnCreate No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘create’ mode.
showForwardOnEdit No true, false true Whether or not to show the ‘forward’ button when the user is on this field and in ‘edit’ mode.
showBack No true, false true Whether or not to present the ‘back’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showCancel No true, false true Whether or not to present the ‘cancel’ button to the user on this field. NOTE: Overrides mode-specific settings above.
showForward No true, false true Whether or not to present the ‘forward’ button to the user on this field. NOTE: Overrides mode-specific settings above.

Constraint

  Parent elements: Relationships such as (BelongsTo)
  Child elements: none

Constraint attributes

Attribute Required Values Default Value Explanation
column Yes The ID of a field in the “foreign” form n/a The ID of the field whose value we will use to constrain the set of instances of the “foreign” form in the relationship.
One of {smaller, smallerEqual, equal, notEqual, greaterEqual, greater} Yes The value to use in this condition false The value against which every value in the specified column should be compared, using the specified comparision operator.

Logging

  Parent elements: Configuration
  Child elements: none

Logging attribute

Attribute Required Values Default Value Explanation
enabled No true, false true Whether or not to enable logging for this project.