The PROJECT.xml file will define the structure of your project. XML stands for “eXtensible Markup Language” and it was created to store and share data in a way that is both human and machine readable. The basic building block of an XML document is an ‘element’, represented by a beginning and an ending ‘tag’:
|
1 |
<Element> </Element> |
And in shortform:
|
1 |
<Element /> |
XML supports nested elements, or elements within elements (usually refered to as parent elements and children elements). This ability allows for the support of hierarchical structures, such as decision trees. Element names (or tags) describe the content of the element while the structure describes the relationship between the elements. Note that only stand-alone (not nested) elements or the innermost element of a nested hierarchy can be written in short form.
|
1 2 3 4 5 6 |
<ParentElement> <ChildElement1> <ChildElement2 /> </ChildElement1> </ParentElement> |
Furthermore, an element can have ‘attributes’ in its beginning tag that describe the characteristics of the element:
|
1 |
<Element attributeName="attributeValue"/> |
For more info on XML, please check this tutorial.
Sapelli XML
To create an XML file, you will need a simple text editor (i.e. Notepad++ or Brackets). Open the text editor and save the document as ‘PROJECT.xml’. This file will become the essential part of your Sapelli project (see The structure of a Sapelli project) and it will eventually take on these essential components:
|
1 2 3 4 5 6 7 8 9 |
<?xml version="1.0" encoding="UTF-8"?> <SapelliCollectorProject id="1234" defaultLanguage="en-GB" name="Transport Demo" version="2.3"> <Form id="Survey"> </Form> </SapelliCollectorProject> |
Now, let’s examine the different parts of the project. The XML document will always begin with the ‘declaration’. This is simply for the computer to be aware that the file contains XML content:
|
1 |
<?xml version="1.0" encoding="UTF-8"?> |
In the next line of the document, you can officially begin the Sapelli XML by giving the Project a name, ID, default language and version of the app. The project ID has to be unique to your project. Note that you can have several projects with the same name but not the same ID. The version number is for controlling improvements, updates or variant versions of your projects. These numbers are generally assigned in ascending order:
|
1 |
<SapelliCollectorProject id="1234" defaultLanguage="en-GB" name="Transport Demo" version="2.3"> |
Close the Sapelli XML Project tag at the bottom of your document so that everything you now type will be between these two tags:
|
1 |
</SapelliCollectorProject> |
Nested inside the SapelliCollectorProject element is the Form element, which will open just after the Project tag and close towards the bottom of your document just before the </SapelliCollectorProject> tag:
|
1 2 3 |
<Form id="Survey"> </Form> |
A Form describes one survey. Most projects contain a single Form, but it is possible to create a project with several consecutive Forms. The Form has an attribute called id, which can be freely set by the user. Note that each top-level element in the PROJECT.xml file must have a unique id.
Now you are ready to build in the choices that create your decision tree. Sapelli uses a unique version of XML with its own tags and attributes to describe data. In order to create a Sapelli decision tree, a hierarchy of ‘Choice’ elements is created. Each choice will lead to a different set of choices, until the user reaches the end of the tree. The depth of the tree can vary depending on the route. More detail on how to create Sapelli decision trees can be found in the next section.
Apart from the decision tree, Sapelli provides the option to collect further data. For example, the project can provide options for the user to capture their GPS location, take pictures, audio or video recordings. Each of these functionalities can be enabled by simply adding one of the specific tags <Location>, <Photo>, <Audio> or <Video> to the PROJECT.xml. All available tags are documented here.