XML provides an inherently simple way of describing data, and can be produced using any standard text editor. XML does not really do much of anything itself. Rather, it allows software developers to create vocabularies that allow for the description of specific types of data. Data described can be used within software applications (that understand the vocabulary) to do any number of things. (For a further introduction to XML we recommend the W3C Schools pages - Click here )
For EpiCollect+, we have defined a vocabulary which we call Epicollect Markup Language (ECML) which allows you to describe all aspects of a data gathering project - location of central server, forms, text and media fields within forms, form logic, validation and the ability to link multiple forms together in a hierarchy and by specifying branch forms. These will all be explained within the following documentation.
Introduction to ecML
A concise listing of the ecML specification can be downloaded here.
The following pages document in detail all of the elements available for you to define your project.
Your ecML document needs to reside on a webserver (where you have your database) and is used in a number of ways as in the following figure:
The ecML file is located on a web server and when loaded into the EpiCollect+ mobile app defines the interface on the phone presented to a user (A); On the server, the XML file is used to define the database structure for storage of data (B); The XML file also defines the form structure available for data entry and download directly via the web (C) and also defines the interface for viewing data gathered in tabular format and where applicable, using Google Maps and Google Earth.
In ecML, data is ‘marked up’ with ‘tags’ in plain text. For example, the following is a simplified view of the tags used to describe a single text field within EpiCollect.
Note: Throughout the documentation, whenever we demonstrate ECML, the plain text will be formatted as in the following box:
ECML tags must be ‘opened’ (eg <input> - line 1 above) and ‘closed’ using a forward slash (eg </input> - Line 3 above). Data are contained within the opening and closing tags and this can include nesting other tags, providing a tree-like structure for describing data.
The example above includes a <label> tag nested within the <input> tag. The label tag contains the text presented to the user as a prompt for answering a particular question (‘What is your name?’) and this is nested within the opening and closing <input> tags, indicating that the question type is a simple text input..
Differentiating tags using ‘attributes’
In a particular form we may have 10 simple text questions and we need to differentiate between them. To do this, we use what are known as XML ‘attributes’.
Atributes define specific properties about a particular instance of a tag. In the following example, we now have two questions:
<input ref = “Question1”>
Both input tags are opened and closed and contain a label, however, the opening tags of each input now contain an attribute (ref="") which differentiates between the two questions and allows us, when storing data, to record the answer to ‘Question1’ as whatever the user enters.
Attributes within ECML can be used to describe a number of extra features specific to a particular question. For example:
<input ref = “Question2” required=”true” numeric=”true”>
These attributes should be relatively self explanatory and when loaded into EpiCollect+, a user is presented with a text field with the label (What is your age?) which they must answer (specified by the attribute required="true”) otherwise they receive a warning, and for which they will only be allowed to enter a numeric value (numeric="true").
By adhering to the vocabulary of tags/attributes and rules we have defined, all of the complexities of a particular project can be described in this fashion (multiple forms / linking of forms / branch forms / text and media fields / jumps and validation etc.)
In the next section we describe the overall structure of an ecML document.