Saving forms (including partially completed forms)

Saving Data

media_1351373482345.jpg

Once you have entered all the data into your phone click Save

media_1351374050301.jpg

New list of data is started

media_1351374526323.jpg

A list of data saved for that form will now be started. If you press Back from this screen, you will taken back to the list of forms.

Saved data indicator

media_1351374721793.jpg

You will be returned to your list of forms but there will now be a small grey dot indicating that data is saved for that form.

media_1351374772285.jpg

This indicator is also present on the list of studies

Saving partially completed forms

media_1351375671872.jpg

If a form has required data that has not yet been entered, you will be able to save the form, but you will not be able to upload it.

media_1351375699476.jpg

Partially completed forms are then marked with a * to indicate that required data is still left to be completed.

View your saved data

To edit your data or complete your form, simply select the row you wish to edit and you will be returned to the form.

Multimedia questions (Audio, Video, Image)

Audio, Video and Image questions are available if the phone supports them.

User permission

media_1351381340640.jpg

When you enter a multimedia question the user will typically be asked for permission to access this feature of the phone.

Problems saving large videos

There is a known bug (https://trac.openxdata.org/ticket/842) when you try to save video larger than your phone can handle which may well cause mforms to crash.

Repeat questions

Using the Example Form, in the Example Study we look at how to use repeat questions on the mForms client.

Open the repeat question “Details of Children”

media_1333309500300.jpg

You are presented with a blank screen

media_1333309570268.jpg

This blank screen will contain a list of all of the groups of questions you have added, as you add them. For now, it is empty.

  1. Click New

You now have the questions that are in the repeating group

media_1333309654544.jpg

Note that as no information is added only “Cancel” is available as an option

Add information to each question

media_1333309683257.jpg

The list of questions now has OK option

media_1333309829711.jpg

After entering data for some or all of the questions, the OK option has appeared on the Right Option

Click OK

Now add more repeat question data (or return back to main form)

media_1333309919953.jpg

You now have a list of the data you entered. From here you can use the “Menu” button to add new data, delete a data set you’ve added or return to the main form.

Added some more data rows

media_1333310228253.jpg

In the above shot I have entered three seperate groups of answers to the repeat question.

Group 1
Name: NameOne
Age:
Sex:

Group 2
Name: NameTwo
Age: 23
Sex: Female

Group 3
Name: NameThree
Age:
Sex: Male

You can also go up and down this list and select a row, to return and edit it.

To return to the main form

media_1333310254075.jpg
  1. Click Menu
  2. Click OK

Repeat data is now displayed in main form

media_1333310326482.jpg

The different rows are seperated by |

Note there is currently a ticket, to change the display on the main form from this to simply a count of the number of groups of repeat data entered.

Entering Data

Entering data on the phone is very self explanatory. The best way to learn is to try entering data a few times on the sample form that comes with a default openXdata implementation.

Text question

media_1351288008140.jpg

Text questions will take all values using your phone’s standard input – whatever language your phone’s writing settings are set to is what will appear here.

Number

media_1351288136864.jpg

Number questions only accept integers, like 65, not decimals like 65.3. Your phone will be forced to enter numbers on number fields. Negative numbers are accepted

Decimal

media_1351288193013.jpg

Deciml accepts both integers and decimals. Your phone will be forced to enter numbers. Negative numbers are accepted.

Date

media_1351288390359.jpg

Date questions will allow you to enter a date manually. But there will also usually be a Select Day option presented in the bottom menu which will bring up a calendar as shown above.

Time

media_1351288512254.jpg

A time question will force the user to enter numerical values for hour and minute

Boolean / Single Select

media_1351288633141.jpg

On a single select, the default selection will be No Selection (unless you’ve specified a default in your form definition). Scroll up and down to select the value you want.

Multi Select

media_1351288700022.jpg

On a multi-select, use the middle key on your phone to select all the values that apply. In this screenshot, you can also see the help text that can be set in the form designer scrollign along the top of the mobile screen.

Repeat Question & Multimedia

Repeat and Multimedia questions are covered in seperate sections: Repeat questions

GPS

media_1351289459321.jpg

If your phone has GPS, and mForms can detect it, when you click the GPS question, you will be asked for permission to use the GPS. There is no way to circumvent this, the user must agree to use the GPS. Once GPS co-ordinates have been determined, they will be shown in the question.

If your phone does not have GPS, you will be given a screen to enter co-ordinates manually

Single Select Dynamic

Single select dnyamic questions look just like single select questions except that no options will be presented to the user until the preceding questions are entered. E.g. if you have a single select dynamic question Country, that presents a list of countries based on the Continent previously selected, until Continent is selected, no Countries will display in the question.

Required

media_1351372849362.jpg

Required questions are marked with a * (red asterisk)

Disabled

media_1351372933202.jpg

Disabled questions are marked with a grey stop sign.

Locked

If a locked question is enabled, you will be able to enter the question, but not enter data. Depending on the phone, the phone may show a lock symbol when you attempt to enter data.

Downloading studies and forms

List of Studies

media_1351223661553.jpg

After logging in, the first screen is always the List of Studies.

Download studies

media_1351223749844.jpg

To download studies to your phone click Menu and Download Studies. You will need mobile signal and a data connection to download studies.

You may wish to download studies to:

  • update your list after new studies were added
  • update your list ater permissions were updated
  • update your list if sharing a phone with someone

You will not be able to download studies if there is data on the phone waiting to be uploaded.

Download forms in a study

media_1351223918839.jpg

From your list of studies, scroll up and down and select the one you want, then press the middle button on your phone to select that study (or choose Menu -> Select).

If you have already downloaded the forms for that study, this will take you to the list of forms. If you have not yet downloaded the forms for that study, then you will need mobile signal and a data connection to download the studies.

Updating forms

media_1351287445277.jpg

If you are in your list of forms and you wish to update the list of forms. You can download the forms again for that study by using Menu -> Download Forms

Permissions

Remember you will only be able to see the studies and forms that your user has been granted access to. See server documentation for instructions on assigning studies and forms to users.

Running the first time

The first time mForms runs on a phone, the user will see some additional screens by default,

First time login

wpid1618-media_1333318061240.jpg

The application is designed to be used offline, so user names and passwords are stored in the phone so that a user can login even when she doesn’t have a cell phone signal.

However, the first time you login, the phone has no knowledge of the users on the server. So the first time you login, only the first time, the login screen will accept any username and password – these are later checked once you have confirmed the server details on the next screen.

Confirm connection settings

wpid1615-media_1333318113090.jpg

This is only presented to the user on the first login, afterwards the Connection Settings are available through the Settings menu.

You can confirm or edit the server settings.

For more information, see the Settings section.

Project administrators may also want to change this default URL before loading the mobile client onto the phone – for more information see Configuring the server URL

Application confirms user password and downloads list of studies assigned to user

wpid1617-media_1333322548521.jpg

Every time the application needs to access the internet, the user will be asked to confirm whether to allow the connection. This is something the phone does, not the application and we cannot change. Experience may vary from phone to phone.

  1. You must click yes to continue

User is presented with the list of Studies

wpid1616-media_1333323044147.jpg

This is the screen that the user will now see each time they log in

What if I enter the wrong username / password?

wpid1614-media_1333323250209.jpg

If you enter the wrong username or password, you will see an Access denied message. Pressing ok will return you to the login page you will then have the opportunity to enter a correct username and password.

What if I enter the wrong server address?

wpid1619-media_1333323833640.jpg

If you enter the wrong server address, you will see an error message. You will then be returned to the login screen, and then once again to the connection settings screen.

Note: In the unlikely even that you enter a valid openXdata server address, but not the correct openXdata server address then the application will think that you have an incorrect username and password and you will be taken back to the username and password screen but will not be shown the Connection Settings screen again and you will not be able to login. In this case you will need to delete the app from your phone and reinstall.

Configuring the server URL

When you go live with a project, you may not want to manually edit the server URL on every phone. You can edit the .jar (the mobile client) file before putting it on the phone so that your server URL is the default URL in the mobile application.

To do this you will need java installed on your desktop machine where you are editing the .jar

Open a terminal / command prompt:

  • Windows: from the start menu, go to run a program and type cmd
  • Mac: Terminal is in the utilities
  • Linux: gnome-terminal / xterm / terminator etc.

From the command prompt type:
$ java -version
If you see something like
java version "1.6.0_32"
Java(TM) SE Runtime Environment (build 1.6.0_32-b05)
Java HotSpot(TM) 64-Bit Server VM (build 20.7-b02, mixed mode)
you should be able to update your jar.

Extract the default.properties file from the jar

At the command prompt, navigate to the location of your mobile client – e.g. mforms-midlet-2.4.8-me.jar

$ jar -xf mforms-midlet-2.4.8-me.jar defaults.properties

(Don’t forget to use your midlet name)

This extracts the defaults.properties file from your jar and you should now see it in the folder you are in with your mforms-midlet-2.4.8-me.jar. If you omit defaults.properties from the end of the command it will extract the entire contents of the jar which is a lot of files but is fine and you can continue with the following instructions

Edit the default.properties file

Open default.properties in your favorite text editor (not Word) e.g. notepad, gedit

It should contain one line:
httpUrl=http://localhost:8080/openxdata/mpsubmit

Edit this to be your server – do not forget the /mpsubmit at the end of the URL for example:
httpUrl=http://www.myopenxdataserver.net:8080/webapp-1.16.7/mpsubmit

When you are finished, save this file back to where you opened it

Update your jar with your new defaults.properties

At the command prompt, navigate to the location of your mobile client again

$ jar -uf mforms-midlet-2.4.8-me.jar defaults.properties

This is the same as before but with -uf instead of -xf

(Don’t forget to use your midlet name)

Done!

Copy your jar onto your phone and you should now have a new default URL.

Start, End time and today’s date

Using ‘now()’ for start time and today’s date

media_1344532069638.jpg

If we use the special syntax ‘now()’ in the default value we can get a date and timestamp of the date and time “now”

Note the single quotes around ‘now()’, these are necessary.

‘now()’ is used in two common ways:

  1. Start time – sometimes we want to capture the time that a user started to enter data into a form. This can be hidden from the user by making the question Enabled but not visible. Used with endtime this can be very helpful for monitoring field workers. To just capture the time, set the question type to time. Note that this is better than submission time, because it is perfectly legitimate for a user to only upload all their forms at once in the evening – perhaps because they are now back in cell phone range. It is less likely, for example, that it is appropriate for them to be collecting all their data in quick succession in the evening.
  2. Default date – to reduce errors and reduce data entry time, we may want fill in today’s date for a user. ‘now()’ can also be used for this. If you only want the date, set the question type to Date

Endtime

media_1344532371353.jpg

Endtime is used to capture when a form is saved.

To capture endtime, you must specify the question binding as endtime – no quotes

Skip Logic, Validation and Calculation

Visible, Enabled, Locked

wpid1515-media_1344533153244.jpg

The Visible and Enabled settings that you check when you design a form are the initial defaults when a form is opened. They can then be modified through skip logic.

Disabled is the opposite of Enabled, if you un-check the Enabled box, we will refer to that as Disabled.

Disabled and Locked are similar but distinct properties:

  • Locked means that the user can not edit the value, but any default or calculated values will be shown (if the question is visible) stored on save.
  • Disabled, means that no data for that question will be stored, it is regarded as skipped. A disabled question also can’t be edited.

Say the following:
Question1 Locked with default ‘now()’ would store the value generated
Question2 Disabled with default ‘now()’ would not store the value generated.

To the data capture user, the effect would be similar: They can’t edit the question. But the data that is uploaded is different.

Note the implementation of Locked is not always perfect – check you forms to see they perform as you expect.

Skip Logic – new thinking

wpid1520-IMG_0138.jpg

When you look at a paper form, it will usually say things like "If you answered No to Question 4, skip to Question 8. If you answered Yes, continue at Question 5" e.g.

  • Smoker? – Yes / No (if No, skip to Question "History of Cancer?")
  • How many? – Conditional on "Smoker?"
  • How often? – Conditional on "Smoker?"
  • Want to quit? – Conditional on "Smoker?"
  • History of Cancer?- Always required

One way we could do this in openXdata is the following:

  • For questions 5, 6 and 7 hide/disable them if the answer to question 4 is No – this may feel natural if translating from a paper form

However, it is often cleaner to do the reverse, which is not really possible with paper.

  • Start out with questions 5,6 and 7 hidden so your form looks like this
  • - Smoker?
  • - History of Cancer?
  • Then add logic so that if the answer to "Smoker?" is Yes the relevant questions appear
  • - How many?
  • - How often?
  • - Want to quit?
  • - History of Cancer?

Obviously, how you structure your form depends on your data, your users, and feedback from form testing

Adding Skip Logic

wpid1522-media_1344534847657.jpg

Once you have worked out how you want your form to look at the start and after the skip logic, adding the skip logic will be relatively simple.

Before you start adding skip logic:

  1. Add all your questions,
  2. Save your form and
  3. Refresh the page

This ensures that all possible values are available to the logic builder

Select how conditions will apply

wpid1518-media_1344534959307.jpg

Click on the all to edit

Conditions can apply

  • all – all the conditions must be met for the skip logic to occur
  • any – if any one of the following conditions occurs, the skip logic will happen
  • none – if none of the following conditions are true then the skip logic will happen
  • not all – if any of the following conditions does not occur, the skip logic will happen

 

Add conditions

wpid1514-media_1344535475731.jpg

Once you click < Click here to add new condition > a question will be automatically filled in for you, in the above diagram it was Options, my first question.

When you click Options (or whatever your question Text is) it will open up a box where you can get the question you’re looking for. To find the question you want, delete the text that’s in the box and type the first few letters of the question you’re looking for – a drop down will appear with the possible questions in.

When you click is equal to you will get a dropdown that will give you different options depending on the question type. For a list:

  • is equal to
  • is not equal to
  • is in list
  • is not in list
  • is null
  • is not null

For a number or date value

  • is equal to
  • is not equal to
  • is greater than
  • is greater than or equal to
  • is less than
  • is less than or equal to
  • is null
  • is not null

For a text value

  • is equal to
  • is not equal to
  • is null
  • is not null
  • starts with
  • does not start with
  • contains
  • does not contain

Skip logic can’t evaluate certain question types like Picture, Audio, Video.

When you click ______ you will either be shown a list of options in the case of a Select box (as pictured above) or a blank box with a checkbox Question value, as shown below

wpid1516-media_1344536200795.jpg

From this point, you can enter a number which will be a constant in your form. Or you can compare one number to another number from another question. To do the latter, check Question value and then ciick in the box and start typing to enter the name of the question

wpid1513-media_1344536304028.jpg

Repeat this process until you have all your conditions. Then save your form.

It is a good idea to back-up frequently when adding skip logic to a form

Delete a condition

wpid1517-media_1344536702849.jpg

Click on <> to delete a condition

Adding skip logic to multiple questions at once

wpid1519-media_1344536589876.jpg

If, as in our earlier smoking example, you have a set of questions for which the same logic applies. Click on < Click here for other questions >
to get a dialog that allows you to select multiple questions to apply the skip logic too.

Validation logic

wpid1521-media_1344536862094.jpg

The interface for validation logic is similar to that for Skip Logic.

Validtaion compares this questions Value or Length with another value. e.g. maybe you don’t want a name longer than 10 characters – use a text question and validate with Length -> is than or equalt to -> 10

Note that the conditions that you enter are the conditions that describe a valid value, and the error message is the message that appears when a user has done something wrong and the conditions are not met.

Check out the sample form to see how to prevent a future date from being added.

Calculations

media_1344537273867.jpg

The calculat ions field allows you to enter calculations using the questions bindings as a substitiute for the value. Calculations only work on the mobile client at the moment. To run calculations on the web form use the Javascript tab.

To help with the question bindings. click on Add Field and find questions these will then be added to the calculation field for you. You do not need = at the beginning of the row, like you do in excel. You can use mathematical operators like + * – to manipulate your values.

Javascript in Web Forms

Javascript Tab

media_1344524499712.jpg

The Web Form does not, as of 1.16.3, automatically handle calculations or complex skip logic. However, it is possible to add this functionality by using the Javascript tab.

It is beyond the scope of this book to give a tutorial on Javascript or traversing a DOM, please see other internet references such as http://www.w3schools.com for this.

Add HTML Ids for your form elements

media_1344526505995.jpg

The javascript tab, relies on identifying the elements of your form by Id. However, if does not use the bindings to do this, instead these must be set manually in the Design Surface.

  1. Select the Design Surface
  2. Select the element you are interested in
  3. Scroll down to the bottom of the Widget Properties window to find the Field Id
media_1344526645858.jpg

Once all the necessary id’s have been set, save your form, edit and save your javascript.

Test in the Preview Tab

media_1344526848283.jpg
  1. Right click in the Preview tab and hit Refresh if necessary

You can then test your javascript including using standard browser debugging tools like Firebug and console.log() if necessary.