This page is primarily useful for programs using older versions of CommCare. A page directed at the newer user interface is under development.
This page provides an overview of how to navigate using CommCare Android, describes different types of settings you can consider, and presents question types that are only available on CommCare (not in J2ME).
This guide assumes that you have already installed CommCare or are going to be building an application for CommCare. The screenshots on this page are from CommCare 2.8.1. You may be interested in the below information about CommCare (for Android) as well:
One major decision in how to configure CommCare is Sense Mode. Sense Mode, when turned on, disables advanced features that may be confusing to new users, especially form management. Below, those features which are disabled in Sense Mode are indicated. More detail can be found on the page about CommCare for low-literate users.
There are some tricks to effectively navigating in CommCare, and some features that are not easy to find. Below are some of the key features you may find useful.
There may be a number of buttons on your Android device, but as pictured below there are three buttons that are important for using CommCare.
You can log into CommCare for Android as a Mobile User or as a Demo User.
After clicking on the CommCare icon, you will reach the log-in screen. Here you will need to enter a username and password (see left image). Note that unlike J2ME CommCare, there is no "admin" login.
You can get information on how to create and manager users here. Please note the following:
There is a demo mode- to enter demo mode you only need to push the phone's menu button while at the log-in screen. As shown in the left image, there is a small button at the bottom of the screen to log in as a demo user. After selecting it you will see a warning message.
The main screen (“home screen”) of CommCare has several important features clearly visible (note the above shows CommCare with form management active on the left, and with Sense Mode on the right):
Get Started: This is where your users will go in order to access the forms and submit data.
Form Records (Note: In CommCareHQ both “incomplete” and “saved” forms are disabled, as in the image on the right, above.):
Sync with Server: forces to phone to synchronize with data on the server. The text below the button will tell you if there are pending forms. If there are a lot of pending forms the text will turn red to alert the user. If you have forms you want to force the phone to submit, you can press “sync with server.” However, you will have to press it again after the forms have been submitted in order to actually sync and for the “last synced” time and date to update.
Log Out of CommCare: Logs the user out so that the data on the phone is secure.
You can translate many parts of the home screen into most languages. See our page on user-interface translations to learn more.
LEFT: If you click on the menu button on your phone (often looks like a box with lines, or three dots) you will access the home page settings menu:
Within the "saved" forms button you can find a list of all forms that were submitted since the last time the application data was cleared. You can further filter this list by submitted forms, unsent forms, or incomplete forms. After you "save a form as complete" it is tagged as "unsent" until CommCare confirms that the form has reached the CommCareHQ server, at which time the tag is removed. In the right image you can see a number next to "Incomplete" which indicates the number of incomplete forms.
When you open a form you will get the landing screen (left) that shows users how to navigate within a form by swiping the page. When you try to skip a required question, or enter a value that is outside of the permitted range, a message will alert you that you must correct your answer. If you press the options button/soft key, you will see four advanced options displayed at the bottom of the screen:
Settings includes the following options:
By default, starting in CommCare 2.14, there is a blue progress bar across the screen that indicates the portion of the form that is complete. It dynamically updates based upon changes in display logic.
Starting with CommCare 2.15 you can disable the progress bar. You may want to disable the bar in forms that are very large or complex as it can cause performance issues.
To disable the progress bar open the desired form and open the Form Settings from the menu. Uncheck the box (see images above). You only need to make this change one time per form and then the progress bar setting will be the same next time you open the form.
This section goes through some common question types to show how they will appear on the phone.
Labels are used to display messages. In CommCare for Android there is an option to also have a standard message and checkbox displayed on the screen. By default, the message reads "OK. Please continue." If you set the label to "required" then the user will have to check the box next to the message before continuing to the next screen. The message can be changed or translated through the User Interface Translations.
Text questions will appear with an alphabetic keyboard by default, while all numeric questions will display a number pad.
Single select questions are fairly easy- you simply select the desired option and the circle will show as filled. If you hold you finger continuously on an option you will get a pop-up screen that says "Edit Prompt: Remove Response." If, for example, you accidentally answered a question that you wanted to leave blank, you can remove your choice through the "remove response" tool. It is also common for users to "accidentally" get the remove response message by holding their finger too long when selecting an option.
In Multiple Choice questions you can select more than one option, which is usually indicated by square boxes. You can create useful constraint messages as well.
You can ask for a date, time, or a combination of date and time. You can use the up/down arrows to adjust the values. Time values are always shown in a 24 hour clock.
CommCare for Android can be used to take capture or upload images, audio, or video to a form.
CommCare cannot accept large image files. Anything greater than 1MB could cause issues including slow syncing and failure to upload the picture to CCHQ. The best rule of thumb is to use a small (< 1MB) file size when taking pictures within CC. VGA files seem to work particularly well. You may have to manually adjust this in your camera app if you prefer to take larger size pictures outside of CommCare. If you are looking at a report in CCHQ and you either can't find an image you know you captured, or you see an image file name but it is not linked to anything, make sure that you did not take a very large image that could not be submitted over the network.
When you get to a screen with a media capture question you will have the option of either capturing the data in real time (i.e. opening a camera app to take a picture) or choosing a file from you phone (i.e. navigating to a folder on your device to find a specific file).
The Signature Catpure question type can be used to capture a client's signature and send it to the CommCareHQ server. It can then be accessed as an image file in the form submission report from the attachments tab. Clicking on Gather Signature will open a screen where you can write a signature with your finger or a stylus. Then choose Save and Close to capture the signature. You can replace it by clicking on Gather Signature again.
When you reach a GPS question, the user will be presented with a "Record Location" button. Upon selecting the button, a loading screen will indicate the accuracy of the GPS coordinates. A spinning circle icon will be displayed while the devices searches for the location, and is replaced by a green check mark when the location is locked in. When accuracy gets to 5 m the coordinates will automatically be captured and displayed on the screen. If you do not need such high accuracy, you can record the location earlier. Once the location is displayed in your form, you simply swipe to go on to the next screen. Selecting "Record Location" again will re-initiate the GPS capture process and can overwrite the first set of coordinates.
The first time you try to do a GPS capture in a new location it can take a long time to find the location, sometimes as much as 10 minutes. Subsequent captures will likely be much faster.
The barcode question will call out to a barcode scanner application to capture data stored in an external barcode.
In CommCare you can call out to a different Android application to get an input. Instructions are at Integrating Android applications with CommCare.
In CommCare case list view it is important not to put too much text or data in the case list as this will make it very difficult to navigate through the case list. Below you can see examples of a case list (left) and case details (right). Click here for more information on case lists.
This section describes formatting and question types that are specific to CommCare for Android
For instructions on how to use and install multimedia in CommCare click here. When you add an audio or video file you can play it by selecting the button in the upper right-hand corner. Clicking on the button will start playing the file, and you can press it again to pause the playback.
In the place of an image, a question can be configured to display a QR code which contains text that is dynamically set in the form.
To configure a question to display a QR code in the Form Builder, find Add Other under the question's Content header, and click "custom". When prompted for a content type, enter qrcode, then enter the text you want to be encoded in the QR code into the new label.
If you want the code to contain data from the form (like a case ID or a computed value), you can use advanced <output> features as outlined in the Hidden Value Calculations Tutorial. You can test the content by displaying it first in a question's normal label if needed.
This feature is only available in CommCare 2.8 or higher.
In CommCare you can use "hint text" which will appear in a smaller font underneath your display text. To add hint text in the app builder, open the "Advanced Properties" tab and put your text in the "hint" field.
You can group questions on one screen by putting all of the relevant questions in a "Question List" group. This group type is available in the Form Builder under the Group set of question types. Note that you cannot run a calculation within a screen (i.e. you cannot have the outcome of a question at the top of a screen affect the display condition of one on the bottom of the same screen).
Q: Can you group questions horizontally to improve display on a tablet?
A: No, this is not possible at present
Q: How do you change the font in CommCare for Android?
A: You can adjust the font by pushing the settings button while inside any form. Once you change the font size one time from within any form, CommCare will remember the new font size and display it in all other forms. You can make the menu text larger by changing your phone's font settings (Settings -> Display -> Font Size)
Q: Can I have more than one CommCare app on my phone at the same time?
A: No, you cannot have more than one app on Android devices. This is on the CommCare development plan but there is no time estimate at present.
Q: When using the signature question type I notice that a copy of the signature is saved to the phone's gallery. Is there any way to prevent this or to encrypt the image?
A: Unfortunately neither of these is possible within CommCare at the moment. You can tell Android that you don't want media in a certain folder being indexed by adding a file called .nomedia to that folder (read more here). However, you'd have to do this yourself - enter CommCare's domained folder on the SD card and add this file either via USB or an Android text editor app. Its also worth noting that this is basically a voluntary opt out that "well behaved" applications will respect, but are not forced to.