Instructions

Introduction

Creating a Project

Designing a Form
Form Elements
  Text Field
  Long Text
  Select One
  Select Multiple

Form Builder
  Text Field
  Long Text
  Select One
  Select Multiple

Loading a Project

Adding a New Entry
  Using GPS
  Adding a Photo
  Entering Form data

Listing Entries

Synchronising Entries

View Entries on Map
  Local Entries
  Remote Entries

Filtering Entries

Loading a Project

Adding a New Entry

Listing Entries

Synchronising Entries

View Entries on Map

Settings

Project Website

Viewing Data

Mapping Interface
  Data Points
  Chart View

Filtering Data

TIme Slider

Chat Panel

Google Earth

Customising

Developers

EpiCollect is an open project and the mobile app code is available to view at Google code. Click here.

We also provide a slightly simpler way for you to send data to servers other than Google's AppEngine (which we use for hosting projects created at EpiCollect.net). This can be achieved by hosting form definitions on your own servers and loading them as 'projects' in the EpiCollect app.

When a form is created using the online Form Builder, the definition of that form is stored as XML (we use a variation of the XForms vocabulary). You can define your own forms using this vocabulary and we have implemented a number of extra TAGS which allow you to specify where the data and photos are sent to and also to specify the location of a script which will retrieve data from the server for inclusion in the 'Remote Entry' sections within the EpiCollect App.

The XML used to define the forms is simple and the following describes the form definition generated and used within the 'demoproject' described in the Instructions. (For a general tutorial on XML see here).

The following code shows the required sections of the form definition:

<xform>

  <model>
<submission id="demoproject" projectName="demoproject" 
allowDownloadEdits="false" versionNumber="1.0" />
  </model>
</xform>

Firstly, the <xform> tag surrounds the form definition.

Secondly, every form must include <model> tags

The <model> contains the <submission> tag, consisting of 4 entities:

These sections are required and parsed when loaded into the EpiCollect app. We also use these within EpiCollect.net when defining project instances within AppEngine.

The definition of fields used within the form follow directly after the closing </model> tag and before the closing </xform> tag.

The types of form elements and associated TAGS / entities are listed as follows:

Text Input

<input ref="name" required="true" title="true" numeric="true" chart="pie">

  <label>What is your name?</label>

</input>

The <label> tag contains the text that will be displayed above the text input when the form is generated within the EpiCollect app.

Select One

<select1 ref="searchengine" required="true" chart="bar">
  <label>Which Search engine do you most often use?</label>
    <item>
      <label>Google</label>
      <value>Google</value>
    </item>
    <item>
      <label>Yahoo</label>
      <value>Yahoo</value>
    </item>
</select1>

The choices specified for the Select One element are defined within the <item> tags. The <label> is the text that will appear to the user and the <value> is the text which will be stored for that choice if chosen.

Select Multiple

<select ref="socialnetwork" chart="bar">
  <label>Which Social networking sited do you use?</label>
    <item>
      <label>MySpace</label>
      <value>MySpace</value>
    </item>
    <item>
      <label>Facebook</label>
      <value>Facebook</value>
    </item>
</select>

The choices specified for the Select One element are defined within the <item> tags. The <label> is the text that will appear to the user and the <value> is the text which will be stored for that choice if chosen.

Long Text

<textarea ref="myLongTextField">
  <label>Enter your description here</label>
</textarea>

Putting it all together

<xform>

  <model>
     <submission id="demoproject" projectName="demoproject"
 allowDownloadEdits="false" versionNumber="1.0" />
  </model>

<input ref="name" required="true" title="true" numeric="true" chart="pie">
   <label>What is your name?</label>
</input>

<select1 ref="searchengine" required="true" chart="bar">
  <label>Which Search engine do you most often use?</label>
    <item>
      <label>Google</label>
      <value>Google</value>
    </item>
    <item>
      <label>Yahoo</label>
      <value>Yahoo</value>
    </item>
</select1>

<select ref="socialnetwork" chart="bar">
  <label>Which Social networking sited do you use?</label>
    <item>
      <label>MySpace</label>
      <value>MySpace</value>
    </item>
    <item>
      <label>Facebook</label>
      <value>Facebook</value>
    </item>
</select>

<textarea ref="myLongTextField">
  <label>Enter your description here</label>
</textarea>
</xform>

This shows a trimmed version of the 'demoproject' XML but the actual form definition can be seen here.

Hosting form definitions on your own servers.

When loading a Project into the EpiCollect mobile app, the current method involves entering just the project name (eg demoproject). By default, data is submitted to AppEngine for viewing at the project homepage. However, to make the system flexible it is easy for you to host the XML at your own servers and for data to be directed to scripts on your own server for handling.

To do this you should create an XML form definition (as above) and host this on your server with a defined URL

eg http://www.myserver.com/myproject.xml

Within the XML you should also specify THREE additional TAGS to those detailed above. These TAGS should be placed just below the closing </model> tag within your XML and are as follows:

<uploadToServer>http://www.yourserver.com/uploadDataScript</uploadToServer>
<downloadFromServer>http://www.yourserver.com/downloadDataScript</downloadFromServer>
<uploadImageToServer>http://www.yourserver.com/imageHandlingScript</uploadImageToServer>

<uploadToServer> defines the name of a script where your entries should be submitted to. We use a simple POST method to send entry text data and your script should request the same variables as defined in the XML. Upon successful submission your script should return '1' to denote that synchronisation has been successful.

<downloadFromServer> defines the script which the EpiCollect app requests data from when loading remote entries. The data should be returned in XML in the same format as the form definition

<uploadImageToServer> to handle photos you should enable a script to upload binary files to your server and define the location of this script here.

Loading a Project XML definition, which is hosted on your server, into the EpiCollect App.

Simply enter the full URL to your XML file into the 'Load Project' text box (see here) .

So, enter http://www.myserver.com/myproject.xml rather than 'myproject'. The EpiCollect app will retrieve your XML, and providing the three TAGS above are included and correct will send and retrieve data from your server.

For any further help, please feel free to contact us.