Clone wiki

javarosa / UsingJavaRosa

Using JavaRosa

This page describes the general process which can be followed in order to develop an xform, obtain and install a JavaRosa platform onto a phone, download the xform onto that phone, and fill out and return the data. It largely serves as an introduction to how the JavaRosa tools are structured from an end-to-end perspective more than a guide on how to use the tools in depth.

This guide may not be perfectly up to date at all times, and if any issues are encountered please contact the skype chat, or the Developer or Implemented mailing lists linked on the main page.

Developing XForms

JavaRosa (and other OpenRosa apps) use a subset of a file format called XForms to describe a form. Full documentation is available on this wiki regarding the subset of XForms which JavaRosa supports and how, including examples.

You can either develop your forms by writing the raw XML, which is fairly challenging, editing an existing form, or using a form designer.

There are a few form designers created by the community to create JavaRosa XForms.

Testing XForms

After using one of the methods to create an XForm, you will have a your form in a file, and you will probably want to test it and make sure it'll work like you expect.

The JavaRosa XForms Validator (available here) can be used both to validate your xforms for correctness and (If you have the WTK 2.5.2 installed) test your forms on a phone emulator.

If only testing is desired, your form can be played with Dimagi's XForms Player to make sure everything works as expected.

Configuring a Server

Once your form is ready to go, you'll need to find a server to host your forms and receive data. There are a couple to choose from. This lists the most straightforward options for servers you won't have to host yourself.

  • ODK Aggregate - Is a cloud hosted service which will live in a Google App Engine.
  • DataHQ - Is a cloud service hosted by Dimagi.

Create an account (or domain) on the server of your choice and upload your XForm to it.

Installing the Client

Now it's time to install the JavaRosa client, install it on a phone, and download and fill out your form.

Instructions on downloading and installing the client are available here. You should follow them to get JavaRosa running on the phone.

Once you have done so, start up the application, and choose "Options -> Settings". Navigate to the Form Download URL and enter the URL of the server you have configured. Press "done", and from the home screen select the option to download forms. The application will list the form that you uploaded to the server. Once you click on it, it will be downloaded to your phone and ready to fill out.

Select the form from the main menu and fill it out. Upon completion, it should be submitted to your server, where you can view the data.