Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Cherrypicked improvements and corrections from https://dimagi.github.io/xform-spec/ #53

Merged
merged 11 commits into from
Dec 23, 2016
Merged

Cherrypicked improvements and corrections from https://dimagi.github.io/xform-spec/ #53

Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
9aa9b1a
cc -> introduction
MartijnR Dec 9, 2016
3f531e9
cc -> structure, #22
MartijnR Dec 9, 2016
dde05f9
cc -> templates, style
MartijnR Dec 9, 2016
e3c8cc8
cc -> instance
MartijnR Dec 9, 2016
ccb6acb
cc -> bindings #43 (partial), closes #30, closes #29, closes #28, clo…
MartijnR Dec 9, 2016
f25b07d
cc -> body
MartijnR Dec 9, 2016
ac36632
cc -> repeats
MartijnR Dec 12, 2016
c0fcec7
cc -> languages
MartijnR Dec 12, 2016
1581250
cc -> media
MartijnR Dec 12, 2016
378fc15
cc -> uri + removed sections, closes #33
MartijnR Dec 12, 2016
e6c0d67
cc -> final edits
MartijnR Dec 22, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 0 additions & 6 deletions _includes/footer.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,3 @@
</div>

</footer>
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<script>
$(document).ready(function(){
$(".post-content > ul:first-child").appendTo(".sidenav");
});
</script>
2 changes: 1 addition & 1 deletion _sections/00-Introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,6 @@ title: Introduction

The ODK XForm specification is a subset of the far larger [XForm 1.0 specification](http://www.w3.org/TR/xforms/). It contains a few additional features not found in the XForm specification.

The ODK XForm Specification continues to evolve. On the web you will often see references to _JavaRosa_ and _OpenRosa_ when the spec is discussed. OpenRosa was the name of the [initial specification](https://bitbucket.org/javarosa/javarosa/wiki/xform) that formed the basis of the ODK specification. JavaRosa is the name of a Java library that implements the OpenRosa specification. ODK, JavaRosa, OpenRosa are still often used to refer to the same, but we recommend using this document to build tools that are compliant with the ODK Ecosystem.
This specification continues to evolve. On the web you will often see references to _JavaRosa_ and _OpenRosa_ when the spec is discussed. OpenRosa was the name of the initial specification that formed the basis of this document. JavaRosa is a library that implements the XForm part of the OpenRosa specification.

The document assumes at least a fair understanding of XML and XPath. It is also useful to refer to [XForms 1.0](http://www.w3.org/TR/2003/REC-xforms-20031014/) for details about shared features.
27 changes: 17 additions & 10 deletions _sections/10-structure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,16 +9,15 @@ The high-level form definition is structured as follows:
* bindings
* body

The model contains the **[instance](#instance)**(s) and the **[bindings](#bindings)**. The first instance is the XML data structure of the _record_ that is captured with the form. A binding describes an individual instance node and includes information such as _datatype, skip logic, calculations, and more_.
The model contains the **[instance](#instance)**(s) and the **[bindings](#bindings)**. The first instance is the XML data structure of the _record_ that is captured with the form. A binding describes an individual instance node and includes information such as _datatype, skip logic, calculations,_ and more.

The **[body](#body)** contains the information required to _display_ a form.

Below is an example of a complete and valid ODK XForm:
Below is an example of a complete and valid XForm:

{% highlight xml %}
<?xml version="1.0"?>
<h:html xmlns="http://www.w3.org/2002/xforms"
xmlns:ev="http://www.w3.org/2001/xml-events"
xmlns:h="http://www.w3.org/1999/xhtml"
xmlns:jr="http://openrosa.org/javarosa"
xmlns:orx="http://openrosa.org/xforms"
Expand All @@ -27,18 +26,19 @@ Below is an example of a complete and valid ODK XForm:
<h:title>My Survey</h:title>
<model>
<instance>
<data id="mysurvey" version="2014083101">
<data id="mysurvey" orx:version="2014083101">
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I know the document pre-supposes a good working understanding of XML but I'm wondering whether it might be worth linking to a quick resource about namespaces along with introducing this (good) change? It might also be good to explain things like the value of having separate OpenRosa XForms and OpenRosa javarosa namespaces as defined in this example.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, that's excellent. I've added a separate issue for this, so this PR stays focused on #33.

<firstname></firstname>
<lastname></lastname>
<age></age>
<meta>
<instanceID/>
</meta>
<orx:meta>
<orx:instanceID/>
</orx:meta>
</data>
</instance>
<bind nodeset="/data/firstname" type="string" required="true()" />
<bind nodeset="/data/lastname" type="string" />
<bind nodeset="/data/age" type="integer" />
<bind nodeset="/data/firstname" type="xsd:string" required="true()" />
<bind nodeset="/data/lastname" type="xsd:string" />
<bind nodeset="/data/age" type="xsd:int" />
<bind nodeset="/data/orx:meta/orx:instanceID" preload="uid" type="xsd:string"/>
</model>
</h:head>
<h:body>
Expand All @@ -54,3 +54,10 @@ Below is an example of a complete and valid ODK XForm:
</h:body>
</h:html>
{% endhighlight %}

Outside of this simplified structure there are ways to define:

* form title as the `<title>` element, a child of the `<head>` element,
* [linkages with external (mobile) applications](#external-applications),
* [language dictionaries](#languages).

18 changes: 10 additions & 8 deletions _sections/20-instance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ The primary instance should contain a single childnode. In the example below `<h

{% highlight xml %}
<instance>
<household id="mysurvey" version="2014083101">
<household id="mysurvey" orx:version="2014083101">
<person>
<firstname/>
<lastname/>
Expand All @@ -23,22 +23,24 @@ The primary instance should contain a single childnode. In the example below `<h
</instance>
{% endhighlight %}

Any value inside a primary instance is considered a default value for that question. If that node has a corresponding input element that value will be displayed to the user when the question is parsed.
Any value inside a primary instance is considered a default value for that question. If that node has a corresponding input element that value will be displayed to the user when the question is rendered.

Nodes inside a primary instance can contain attributes. The client application normally retains the attribute when a record is submitted. There are 3 pre-defined instance attributes:

| attribute | description
|---------------|------------
| `id` | on the childnode of the primary instance: This is the unique ID at which the form is identified the server that publishes the Form and receives data submissions. For more information see [this Form List Specification](https://bitbucket.org/javarosa/javarosa/wiki/FormListAPI).
| `version` | on the childnode of the primary instance can contain any string value.
| `jr:template` | on any repeat group node: This serves to define a default template for repeats and is useful if any of the leaf nodes inside a repeat contains a default value. It is not transmitted in the record. For more details, see the [repeats](#repeats) section.
| `id` | on the childnode of the primary instance: This is the unique ID at which the form is identified the server that publishes the Form and receives data submissions. For more information see [this Form List Specification](https://bitbucket.org/javarosa/javarosa/wiki/FormListAPI). \[required\]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence doesn't parse. Maybe "on the server that publishes..."

| `orx:version` | on the childnode of the primary instance in the _http://openrosa.org/xforms/_ namespace: Form version which can contain any string value. Like [meta nodes](#metadata) this information is used as a _processing cue_ for the server receiving the submission.
| `jr:template` | on any repeat group node in the _http://openrosa.org/javarosa namespace_: This serves to define a default template for repeats and is useful if any of the leaf nodes inside a repeat contains a default value. It is not transmitted in the record and only affects the behavior of the form engine. For more details, see the [repeats](#repeats) section.

The primary instance also includes a special type of nodes for metadata inside the `<meta>` block. See the [Metadata](#metadata) section


The primary instance also includes a special type of nodes for metadata inside the `<meta>` block. [pending]() - See the [Metadata](#preloaders---metadata) section


### Secondary Instances
### Secondary Instances - Internal
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would suggest holding off on adding "Internal" until there's a corresponding "External" (#50). Or maybe acknowledging that there's a proposal in place and linking to it could be interesting.


Secondary instances are used to pre-load data inside a form. This data is searchable in XPath. At the moment the only use case is so-called _cascading selections_ where the available options of a multiple-choice question can be filtered based on an earlier answer.
Secondary instances are used to pre-load read-only data inside a form. This data is searchable in XPath. At the moment the key use case is in designing so-called _cascading selections_ where the available options of a multiple-choice question can be filtered based on an earlier answer.

A secondary instance should get a unique `id` attribute on the `<instance>` node. This allows apps to query the data (which is outside the root, ie. the primary instance, and would normally not be reachable). It uses the the `instance('cities')/root/item[country='nl']` syntax to do this.

Expand Down
Loading