Instructions

android

Introduction

Creating a project

Form Builder

Adding a Form
          Key Field
          Title

Text Fields
          Plain

          Numeric
          Date
          Time
          Drop-Down
          Radio 
            Check Boxes
          
Media Fields
           Location

           Photo
           Video
           Audio
           barcode

Validation
           Text
           RegEx   
           Double Entry

Form Logic
           Jumps


Linking Forms
           Hierarchy

           Branching

android


Installing EpiCollect+
Loading a Project


Collecting Data

Text Fields
          Plain

          Numeric
          Date
          Time
          Drop-Down
          Radio
             Check Boxes

Media Fields
           Location

           Photo
           Video
           Audio
           barcode

Saving Data

List/Sync data

Maps

Backing up data

Remote Data

Settings

android


Project Website

Map View

Multiple Forms

Downloading Data

android


Introduction

EpiCollect Markup

The Document
           <model>

The Form
           <form>


Text Fields
           <input>
          <select>
           <select1>
          <radio>
Setting defaults

Media Fields
           <location>
           <photo>
           <video>
           <audio>
           <barcode>

Defining keys

Form Logic
           Jumps


Linking Forms
           Hierarchy

           Branching
  
Validating



Text Fields

 

There are four types of text field you can specify within your form.

<input> - defines a simple text field where the user types the answer to a question.
<select> - defines a set of 'tickboxes' where a user may select one or more of the possible answers.
<select1> - defines a 'drop-down' list where the user can only select ONE answer.
<radio> - defines a set of 'radio buttons' where a user can select only one answer.

Each of these will now be detailed ,along with attributes you can use to define details about a given question. Throughout, images of what a user will see on the mobile device are also provided.

 

The ref="" attribute

Every input within your ecML document requires a ref="" (reference) attribute which uniquely describes the question. Within your database, the ref="" can be thought of as a column heading and the data entered by the user is stored as a row underneath this column. Within a single form every ref="" must be unique.

Firstly, we describe the simplest text field - the <input>

 

Simple text field - The <input> tag

 

<input ref="SchoolID"> 

    <label>School ID</label> 

</input>

The ref="" attribute defines the unique name for your text input and the data entered by a user are stored using this reference. The screenshot to the right indicates how this would be presented to a user. Whatever the user enters in the text field will be stored as the value forthe SchoolID (the ref="") variable.

 

Each <input> must have one <label> tag which allows you to specify the text question presented to a user.

1

 

Specifying a text input as required (i.e. a user must enter a value).

 

<input ref="SchoolID" required="true"> 

    <label>School ID</label> 

</input>

The addition of the required="true" attribute indicates that a user MUST enter data for this field before progressing to the next question.

The screenshot to the right shows the warning a user will receive if no data are entered.

required

 

Specifying a text input as integer (i.e. only a whole number can be entered).

 

<input ref="anInteger" integer="true"> 

    <label>Enter an integer</label> 

</input>

The addition of the integer="true" attribute specifies that a user can only enter a whole number as the answer to this question.

By default, the touch keyboard will open with a numerical view.

You can also add the required="true" attribute if neccessary.

 

integer

 

Specifying a text input as a decimal (allows whole numbers of decimal to be entered).

 

<input ref="aDecimal" decimal="true"> 

    <label>Enter an integer</label> 

</input>

The addition of the decimal="true" attribute specifies that a user is required to enter a decimal. By default, the touch keyboard will open with a numerical view.

You can also add the required="true" attribute if neccessary.

 

integer

 

Specifying a minimum or maximum integer value.

 

<input ref="minexample" min="10"> 

    <label>Enter a number 10 or above</label> 

</input>

If you wish to set a minimum integer value for a user to enter, then the min="" attribute can be used within an input tag.

By default, this specifies that the user must enter an integer so the integer="true" attribute is not required.

The user is again presented with the numeric keypad and warned if their input violates the minimum criteria as in the following screenshots.

Similarly, the max="" attribute allows you to specify a maximum value a user may input.

You can also add the required="true" attribute if neccessary.

 

min1

 

 

 

 

arrow

 

 

 

 

 

min2

 

Specifying a minimum AND maximum integer value

 

<input ref="minmaxexample" min="10" max="20"> 

    <label>Enter a number between 10 and 20</label> 

</input>

The min="" or max="" attributes can be used on their own, however you can easily specify a range within which a user must enter an appropriate integer using both min="" and max=""

By default, this specifies that the user must enter an integer so the integer="true" is again not required.

The user is again presented with the numeric keypad and warned if their input violates the minimum or maximum criteria as in the following screenshots.

You can also add the required="true" attribute if neccessary.

 

minmax1

 

 

 

 

arrow

 

 

 

 

 

 

Specifying a text input as a date (user must enter a date in the format you specify).

 

<input ref="aDate" date="dd/MM/yyyy"> 

    <label>Enter the date(dd/MM/yyyy)</label> 

</input>

The addition of the date="dd/MM/yyyy" attribute specifies that a user must enter a date in the format specified. You can specify the format in any combination of day, month and year. MM/dd/yyyy or MM/yyyy for example would also work and if a user does not adhere to the format required they will receive a warning.

By default, the touch keyboard will open with a numerical view.

You can also add the required="true" attribute if neccessary.

date1

 

Specifying a text input as setDate (by default this records the current date but provides a control for changing).

 

<input ref="setaDate" setDate="dd/MM/yyyy"> 

    <label>Set the date(dd/MM/yyyy)</label> 

</input>

The addition of the setDate="dd/MM/yyyy" attribute specifies that a user must enter a date in the format specified. You can specify the format in any combination of day, month and year. MM/dd/yyyy or MM/yyyy for example would also work.

Please note: As Android is JAVA-like, within dates, the format for month must be in capital letters (ie MM). This differentiates from the JAVA representation of minutes (mm).

By default, the current date is automatically entered into the text input. However, by tapping the 'Set Date' button, the calendar control is presented to the user allowing them to change as required (see screenshots below).

Using this control provides a more rigorous method for setting dates than the date="" attribute.

You can also add the required="true" attribute if neccessary.

 

setdate1

 

 

 

 

arrow

 

 

 

 

 

setdate2

 

 

 

 

arrow

 

 

Specifying a text input as setTIme (by default records current time).

 

<input ref="currentTime" setTime="HH:mm:ss"> 

    <label>Set a time(HH:mm:ss)</label> 

</input>

The addition of the setTime="HH:mm:ss" attribute allows a user to record the current time. You can specify the format in any combination of hour, minutes and seconds. HH:mm:ss or HH:mm for example would also work.

By default, the current time is automatically entered into the text input in the format specified. However, by tapping the 'Set Time' button, the current time is updated.

You can also add the required="true" attribute if neccessary.

 

settime

 

 

 

 

arrow

 

 

 

 

 

settime2

 

Using verify="true" to check user data (user must answer the question twice)

 

<input ref="emailcontact" verify="true"> 

    <label>Contact email(enter twice)</label> 

</input>

There may be cases where you are collecting unknown data and you wish to try to be sure the user has not made a simple mistake. One way to aid this is to ask the user to answer the question twice, and for the two answers to be compared. You can specify this using the verify="true" attribute for any text input.

This is essentially the same as the method used commonly within web forms to check or confirm that a user has entered their email address or password correctly. When both text inputs are filled in by a user, the values are checked and if they are not identical, the user is warned and must correct accordingly.

Note: of course, if the user enters incorrect data twice, this method will not help, however, this does provide a method for minimising user-entered data errors.

 

SCREENSHOTS REQUIRES

 

settime

 

 

 

 

arrow

 

 

 

 

 

settime2

 

Using a regular expression (regex) to pattern match a users input.

 

<input ref="currentTime" regex="^(S|c)[a-zA-Z]\w\d\d\d\d$"> 

    <label>Enter a school ID (Sx00000)</label> 

</input>

The addition of the regex="" attribute allows you to specify a pattern matching regular expression which is used to check that the users input adheres to the pattern you define.

The example regex in the above xml (regex="^(S|c)[a-zA-Z]\w\d\d\d\d$") specifies that a user must enter a string which starts with 's' (either lower or upper case) followed by any letter, followed by five integers.

At first, regular expressions may seem complex but they provide a very powerful way of pattern matching and can be used for many kinds of validation (email, phone numbers, post / ZIP codes / numerical ranges etc.)

For a comprehensive introduction to the syntax, and further examples, we recommend visiting the website:-

Regular-Expressions.info

For a very good reference text we recommend

O'Reilly - Regular Expressions Cookbook

 

regex1

 

 

 

 

arrow

 

 

 

 

 

regex2

 

Setting a default value for a text input

 

<input ref="defaultTest" default="my default value"> 

    <label>Enter a school name</label> 

</input>

You can specify a default value for any text input by using the default="" attribute.

This can be useful if you wish some value to be entered into the database by default, for example, if a user chooses not to fill in a particular input.

The example above would, if a user does nt enter anything into the text box, record the value 'my default value'

SCREENSHOTS REQUIRED

regex1

 

 

 

 

arrow

 

 

 

 

 

regex2

 

Next | <select>