A Form element consists of one or more Fields and allows for the collection of data. A Project can have more than one Form that can be used to separate groups of Fields and collect data on different topics. For instance, a Project could have a Form for collecting data about schools and a Form for collecting data about the students within that school:

The above code gives two Forms:

  1. A Form with an ID of “SchoolsForm” and using British English as its language.
  2. A Form with an ID of “StudentsForm”, using British English as its language and with vibration disabled when the user’s data record is saved.

 

Therefore, a Sapelli Form element embodies the traditional concept of a paper form or survey by grouping related Fields together for the user to complete. The table below displays the XML documentation for all the attributes that can be included within the Form tag.

Attribute Required Values Default Value Explanation
id Yes Any unique text n/a ID used to recognise and refer to this Form.
storeEndTime No true, false false Whether or not to store the time at which the user saved and exited this form.
startField No Any text (id of an existing Field) (first field) Which of the form’s fields should be presented to the user first. If no field is specified then the first defined field in the form will be shown to the user.
clickAnimation
(formerly animation)
No true, false true Whether or not to animate the widget that the user has clicked for providing visual feedback.
screenTransition No none, vertical, horizontal none Whether the next screen in this form should transition onto the display vertically or horizontally, or if no transition should be shown at all. See this for an example.
obfuscateMediaFiles No true, false false Whether or not the names of media files captured by the user (e.g. photo, video, audio recordings) should be obfuscated to impede their detection. NOTE: This is not a form of safe encryption and the obfuscation can still be reverted to retrieve the media files.
next
(formerly end)
No loopform,
loopproj,
exitapp,
prevform,
nextform
loopform What to do once the user completes this form: start this form again (“loopform”), start this project again (“loopproj”), exit the application (“exitapp”), return to the previous form (“prevform”) or go to the next form (“nextform”).
saveSound
(formerly endSound)
No Relative path to sound file null A relative path to the sound file that should be played when the user saves their input for this form.
saveVibrate
(formerly endVibrate)
No true, false true Whether or not to make the device vibrate when the user saves their input for this form.
controlBackgroundColor
(aka: buttonBackgroundColor)
No Hex colour code (e.g. #000000) #BABABA (light grey) The colour of the background for the control buttons (back, forward, cancel) as a hexadecimal #RRGGBB code
shortcutImage No Relative Path to Shortcut Button Image null A relative path to the image file that should be used as a project shortcut for Android’s Home Launcher or for Sapelli Launcher. Only the image of the first form in a project file will be used as a shortcut.
singlePage No true, false false Whether or not all of the fields included in this form should be displayed on a single page. The default behaviour is to use a different page for every defined field, for instance a Choice field will occupy a full page and so will a Text field.
defaultLanguage No Text representing a language according to the BCP-47 syntax (e.g. “fr-CA” for Canadian French) en (English) The language to use when displaying this particular form to the user (e.g. for text-to-speech synthesis).
showImgSizes No true, false false When set to true Sapelli will display the exact sizes (measured in pixels) of each <Choice> image occurring anywhere in the Form.

 

The example below shows all the possible attributes that can be used in a Form to fine tune the behaviour of the Sapelli Collector app: