1. JavaRosa Team Dimagi Avatar JavaRosa Team Dimagi
  2. javarosa
  3. javarosa

Wiki

Clone wiki

javarosa / externalinstances

View History

NOTE: This is a prospective API that should not be assumed to be functional unless you know otherwise

External Instance API

By default, XForms reference an entirely self-contained set of data contained in the instance of the model. In many uses, though, it is important for the forms to be able to reference data which is external to the form. To do so, JavaRosa relies upon the XForms instance api to reference structured XML models, either concrete or abstract.

Basic Structure

From the XForms perspective, defining and utilizing an external instance is fairly straightforward. The instances are defined as per the xforms 1.0 specification:

<instance id="arbitraryid" src="URI"/>

Where URI is a valid URI reference, which for JavaRosa applications generally will be of the form (jr:something). General reference uri's should be expected to work here (jr:file/path/to/file.xml) like they would for multimedia files.

Any instance defined in an XForm can be referenced in an xpath expression using the instance xpath function. For some examples, assume that we're using the structured towns.xml file here:

file: towns.xml 

<towndata>
   <data_set>us_east</data_set>
   <town id="1">
      <name>New York</name>
   </town>
   <town id="2">
      <name>New York</name>
   </town>
...
</towndata>

Referencing Basic Values

<instance id="towns" src="jr://file/towns.xml"/>

<bind nodeset="/data/data_set_used" calculate="instance('towns')/towndata/data_set"/>

The Instances

Instances used with an xform in this manner must be defined as traditional XML, meaning there can only be one top level element, and for the moment are considered to be read-only. An instance file shouldn't be assumed to always contain the same data, but should always be considered to contain the same structure. Since the files aren't available at parse-time, references to them won't be checked until the xform entry session begins, so care should be taken to ensure that the files are valid.

For example, the following two files could both be used with the same JR application, possibly with the correct file located for the user's geographic area:

file: towns.xml 

<towndata>
   <data_set>us_east</data_set>
   <town id="1">
      <name>New York</name>
   </town>
   <town id="2">
      <name>New York</name>
   </town>
...
</towndata>

file: towns.xml 

<towndata>
   <data_set>us_west</data_set>
   <town id="4">
      <name>Los Angeles</name>
   </town>
   <town id="5">
      <name>San Francisco</name>
   </town>
...
</towndata>

Artificial Instances as an Interface

In addition to loading concrete xml data into a form, JavaRosa supports using the instance interface to load data into a form from the application layer. This data must be served up as an abstract XML data structure which is handled and processed like a real XML document. This permits loading structured data from JavaRosa, local databases, or other required structures.

All artificial instances should be presumed to be read-only, and cannot accept bind data.

Referencing Artificial Instances

In order to load data from an artificial interface, a specific JavaRosa URI should be used with the prefix jr://instance/. The set of available instance interfaces will depend on the specific javarosa deployment, along with their structure.

The first token in the URI after the jr://instance/ is treated as the instance type, any additional tokens are passed along to that type and handled at-will by the defined instance. The URI can contain in those tokens information which will index into dynamic data, for instance:

jr://instance/dbconnector/table/patients

In this example, dbconnector is the instance type, and table and patients are dynamic selectors which are utilized to further define the data to be accessed (with table defining a filter to be used, and patients being the parameter to that filter).

Note: Instance URI's can access dynamic sets of data, but the URI itself cannot accept parameters from the form data.

Mandatory Artificial Instances

Although some artificial instances are application/deployment specific, some instances should always function on a JavaRosa application:

Updated