Wiki
Clone wikijavarosa / JavaRosa-XForm-Validator
''UPDATE 20-March''
''New version and new documentation. Old updates have been removed'' Find images here (http://code.javarosa.org/wiki/JavaRosa-XForm-Validator)
What is the JavaRosa-XForm-Validator?
The JavaRosa XForm Validator is a standalone java application that uses the same parser as JavaRosa to simulate loading an XForm. This is useful for XForm authors to validate their XForms before trying to using the form with a device. It supports two main actions: (1) Validation, where the form is checked for errors from the JavaRosa parser and (2) Form testing, where the form is launched with the sun WTK emulator so the author can test logic and see how the form would look on the phone.
What are the limitations?
To avoid making changes to the JavaRosa parser, the XForm Validator only outputs one error at a time. This means if your form has 10 errors, it will output only the first error. You will then need to fix it and re-run the XForm Validator to see the next error. Once you receive no more errors, you're finished and ready to try the form with JavaRosa.
What are the requirements?
Operating system
The XForm Validator has been successfully used with Windows XP, Windows Vista and even Windows 7. Since the application is written Java so should work anywhere Java does, and the validation portion has been shown to work on OS X 10.5. The validator requires a JRE (1.4+), but does NOT require a JDK. If you're unsure what the previous sentence means, just make sure that you have the latest version of [http://java.sun.com Java]] installed.
Form testing
Form testing requires the Sun WTK to be installed. This portion has only been confirmed to work with Windows, though in theory if you can install the sun WTK, you should be able to use it. See the [buildxforms] page for details on installing the WTK.
Other software
Also helpful is a good XML-editor. In XForm training sessions, we have recommended Notepad++ for Windows. We recommend TextMate for OS X, or the free TextWrangler. Again, the [wiki:buildxforms] page has details.
How do I use the XForm validator GUI?
1. Download the GUI version of the validator from the bottom of this page. Also download the JavaRosaFormTest.jar. This second file is required for doing form testing. '''NOTE:''' dimagi is working to automate the build of these two jars. In the meantime, if you need an updated version, mail the implementers mailing list and someone can update the build.
1. Put both files in the same directory. For this example, we are using the directory `C:\JavaRosa-XForm-Validator`, but any should work.
1. Double click the javarosa-xform-validator-gui.jar file to open it. '''NOTE:''' if you have PC Suite (either Sony Ericsson or Nokia) installed, it will associate JAR files with the Application Installer. In this case, please right-click on the validator and choose "Open With -> Java(TM) Platform SE Binary" as shown in the picture below.
){kind=link}
1. The first time the validator runs (or if it has changed directories), it will create a file called `settings.properties` in the same directory. When the validator opens, you'll see the screen below:
){kind=link}
1. We need to make sure some things are setup before using the validator and form tester. You'll notice that in the screenshot it is complaining that the XForm doesn't exist. Before we fix that, click on the `Settings` button on the top. That opens the following settings screen:
){kind=link}
1. The first option is to setup the directory where you installed the wireless toolkit. This defaults to `C:\WTK2.5.2\`, which should be fine for most installs.
1. The next setting is to choose the location of the `JavaRosaFormTest.jar` file. The application will by default look for the `JavaRosaFormTest.jar` file in the same directory. This should also be fine for most users.
1. The third and fourth options ask the user if a viewer should be opened after testing the form. If you select yes, the executable mentioned (Internet Explorer by default, though any web browser or text editor will work) will open up the resulting XML that would be sent from a server. It is personal preference whether this feature is enabled or not. The application does not check the existence of the executable and will likely fail silently if it cannot launch the viewer.
1. When you have finished, return to the main screen by clicking the `Main Screen` button. '''NOTE:''' You cannot actually save the settings now, because it will not save if there are errors. We must return to the main screen to set a form. (Maybe should change this? Email if this is a problem)
1. Once back at the main screen, click the `Choose form...` button and select the XForm you would like to test. The label above the text box for the `Form to test` should change to reflect the new XForm that has been selected.
1. Click on the `Validate` button to test! '''NOTE:''' Settings are saved automatically when the validator runs successfully.
1. If your output looks like the following, then your XForm passed validation! If there were any warnings or errors, they will be displayed. We've made every effort to provide useful error messages from the parser, but check the FAQ below to get more information on debugging your XForm.
){kind=link}
1. Once your form passes validation, it's time to test it in the emulator. Assuming everything was setup correctly on the settings screen and it passes validation, click the `Test Form` button. The validator will be run to ensure that the form is ok, then the application will unpack and repack the test JAR. This may run slowly if you have antivirus installed and monitoring your filesystem. The emulator should launch automatically and you should see:
){kind=link}
1. Press the right soft key below `Launch` to start the application. It will automatically start the form using the chatterbox interface. Make sure to test your form a lot, especially if you are using `relevant` to control logic. '''NOTE:''' to help with debugging the output from the emulator is displayed in the text box of the validator application. Be on the lookout for any null pointer exceptions or other Java errors!
TODO
There are a few features we would like to add when there is time. Feel free to add feature requests here, or :
- Cancel button so that if you start the emulator, but realize a mistake you don't have to wait for it to start to end it.
FAQ
In this section, I'll describe some common errors (with XForm syntax) that might show up along with possible solutions.
org.xmlpull.v1.XmlPullParserException
This generally means that there is a simple syntax error and the XML is not well formed. For example you might see:
C:\JavaRosa-XForm-Validator>java -jar javarosa-xform-validator.jar bad_form.xml
XForm validation on file: 'bad_form.xml'...
XML Syntax Error!
org.xmlpull.v1.XmlPullParserException: expected: /my_field read: my_form (position:END_TAG </my_form>@47:21 in java.io.InputStreamReader@6ca1c)
at org.kxml2.io.KXmlParser.exception(Unknown Source)
at org.kxml2.io.KXmlParser.error(Unknown Source)
This means that on line 47 at column 21 it found an end tag for my_form, but still has an open tag for "my_field". Looking at the form we see:
<my_form>
<field1 />
<field2 />
<field3 />
...
<my_field>
...
</my_form>
org.javarosa.xform.parse.XFormParseException
There are several different XFormParseExceptions, so we'll discuss each below:
<bind>s with duplicate ID
This error means your model has a <bind> statement and reuses an ID (very easy mistake to make when cutting and pasting). The name of the bind ID that is used more than once is given for your convenience.
invalid binding ID
This error means that in the body you are referencing a bind ID that was not defined in the model. Either change to ref (and give full path) or define a <bind> statement with the ID in question. Again, the offending bind ID will be given to make debugging easier.
<label>
If using the JavaRosa itext framework, you will generate an exception if there is no translation provided for the default language. The particular item in question will be given. Make sure to go back and add a <text> block in the default translation for that ID.
*WARNING: Missing translation
If there using the itext framework, the system will notify you of missing translations. If there is no exception thrown, this means there is a translation in the default locale, but not in one of the other supported locales. If you choose to ignore this warning, JavaRosa will use the translation in the default locale no matter what language is selected.
Downloads
Click 'login as guest' if prompted for a login.
Updated