Added Form Design documentation #217
Conversation
|
@adammichaelwood This content is ready for review sir. |
form-design.rst
Outdated
|
|
||
| These are explained in the following HTML example one by one. | ||
|
|
||
| .. code-block:: html |
There was a problem hiding this comment.
looks like XML to me...
form-design.rst
Outdated
| - The **bindings** -- for each instance variable, you can include information about those data like the type (string, integer, etc.), the constraints on those data (i.e. less than 3), whether they're required or not, etc. | ||
| - The **body** -- how prompts are displayed to the user. | ||
|
|
||
| These are explained in the following HTML example one by one. |
form-design.rst
Outdated
|
|
||
| Here we have a single instance called "data". This instance is identified via the 'id' attribute as the 'myform' form. This id attribute, and an optional version attribute, provide the internal unique name of this form to the software. The software only allows one form definition for each (id, version) pair. | ||
|
|
||
| The form itself has two variables; the first, called "instanceID" is nested within a "meta" block. The second variable is called "mystring." Nesting within blocks can help organize your data; we could have nested "mystring" within one or more blocks. The "meta" block and "instanceID" variable are defined as part of a form design standard, and must appear as shown by OpenRosa 1.0 Metadata Schema. |
There was a problem hiding this comment.
these are attributes of the element, not variables of the form
also, I think it is more clear to talk about "elements" than "blocks"
form-design.rst
Outdated
| </data> | ||
| </instance> | ||
|
|
||
| Here we have a single instance called "data". This instance is identified via the 'id' attribute as the 'myform' form. This id attribute, and an optional version attribute, provide the internal unique name of this form to the software. The software only allows one form definition for each (id, version) pair. |
There was a problem hiding this comment.
we have a single instance called "data"
I know this just came from the original documentation, but I don't know that this is sensible way to talk about this.
I'm opening a discussion issue because I think this language (Which is all over the old docs) is confusing. It is also not exactly consistent with what is going on in the ODK XLSForm output.
form-design.rst
Outdated
|
|
||
| We are going to compute and store a unique identifier for each filled-in form in the ``<instanceID/>`` variable. This will enable ODK Aggregate (or any back-end process) to de-duplicate submissions if, for example, the same filled-in form were somehow submitted twice. | ||
|
|
||
| The other variable, ``<mystring/>``, is where we're going to store the answer to our prompt, but it's only a placeholder. We **DO NOT** specify a data type here. |
There was a problem hiding this comment.
XML doesn't have variables.
There was a problem hiding this comment.
See my comments at #229 -- I think that this is fine to integrate with the changes @adammichaelwood and I have suggested but it will need some further revision to match usage today!
form-design.rst
Outdated
|
|
||
| Use an automated tool compatible with JavaRosa to build the basic XForm. These tools understand the text internationalization features of JavaRosa XForms and can restructure your input so that the question text is grouped into an ``<itext/>`` translation block for internationalization. | ||
|
|
||
| We have a `form design guide <https://opendatakit.org/help/form-design/guidelines/>`_, and the JavaRosa community has a `description of the specification <https://bitbucket.org/javarosa/javarosa/wiki/xform>`_ we support and a `good tutorial <https://bitbucket.org/javarosa/javarosa/wiki/buildxforms>`_. We also have `examples of forms available <https://github.com/opendatakit/sample-forms>`_ and a simple graphical form designer `ODK Build <https://opendatakit.org/use/build/>`_. Another form builder `XLSForm <https://opendatakit.org/use/xlsform/>`_ uses an Excel spreadsheet of questions to generate the XForm file; it is more suitable when working with larger forms. `PurcForms designer <https://code.google.com/archive/p/purcforms/>`_ is another tool. |
There was a problem hiding this comment.
https://bitbucket.org/javarosa/javarosa/wiki/xform -> https://opendatakit.github.io/xforms-spec/
PurcForms isn't really a thing anymore. I believe it is an ancestor of CommCare. Should be removed.
XLSForm is the tool most people use now.
form-design.rst
Outdated
|
|
||
| We have a `form design guide <https://opendatakit.org/help/form-design/guidelines/>`_, and the JavaRosa community has a `description of the specification <https://bitbucket.org/javarosa/javarosa/wiki/xform>`_ we support and a `good tutorial <https://bitbucket.org/javarosa/javarosa/wiki/buildxforms>`_. We also have `examples of forms available <https://github.com/opendatakit/sample-forms>`_ and a simple graphical form designer `ODK Build <https://opendatakit.org/use/build/>`_. Another form builder `XLSForm <https://opendatakit.org/use/xlsform/>`_ uses an Excel spreadsheet of questions to generate the XForm file; it is more suitable when working with larger forms. `PurcForms designer <https://code.google.com/archive/p/purcforms/>`_ is another tool. | ||
|
|
||
| Our experience is that these form design tools can provide a good starting point, but, to enable advanced features, you will inevitably need to edit the resulting form. After hand-editing, you should verify the syntax of the form using ODK Validate. |
There was a problem hiding this comment.
This should be walked back a lot. You could say that advanced forms OCCASIONALLY require manual editing of XML. But in reality XLSForm now supports most desired features.
form-design.rst
Outdated
| @@ -0,0 +1,420 @@ | |||
| **************** | |||
| Form Design | |||
There was a problem hiding this comment.
XForm, not just Form
Is this about designing forms? Is it about coding forms?
There was a problem hiding this comment.
This is exactly the anatomy of XForm, I have changed the name to that now. Is it okay?
|
@adammichaelwood I have changed the name to "XForm Anatomy" from Form Design because the latter doesn't really clear up what's mentioned in the doc. This doc is basically breakdown of the xform design. |
There was a problem hiding this comment.
I made some specific edits that will clear up a few things.
But...
moreover, I feel like this document is needlessly complex and somewhat redundant to the the XForm spec:
https://opendatakit.github.io/xforms-spec/
I think there's some value in having a simpler, more user-friendly explanation of the structure. But this document needs some more rewriting.
Fix the issues I mentioned, and see if you can clean up the piece as a whole to make it more straightforward. We can merge it in and iterate on it, as long as we realize there's more work to do on it.
xform-anatomy.rst
Outdated
| XForm Anatomy | ||
| **************** | ||
|
|
||
| The purpose of this document is to provide a detailed breakdown of XForms, specifically the subset of XForms implemented by JavaRosa, so that anyone can make their own forms. There are several tools to help create your own XForms that work on JavaRosa platforms. They all allow you to create XForms, and the easier they are to use the less advanced functionality they provide. |
There was a problem hiding this comment.
I think it would be a good idea to link to the ODK XForm specification here.
The purpose of this guide is not really a detailed breakdown (as that is the specification), but rather an introduction.
xform-anatomy.rst
Outdated
|
|
||
| Use an automated tool compatible with JavaRosa to build the basic XForm. These tools understand the text internationalization features of JavaRosa XForms and can restructure your input so that the question text is grouped into an ``<itext/>`` translation block for internationalization. | ||
|
|
||
| We have a `form design guide <https://opendatakit.org/help/form-design/guidelines/>`_, and the JavaRosa community has a `description of the specification <https://bitbucket.org/javarosa/javarosa/wiki/xform>`_ we support and a `good tutorial <https://bitbucket.org/javarosa/javarosa/wiki/buildxforms>`_. We also have `examples of forms available <https://github.com/opendatakit/sample-forms>`_ and a simple graphical form designer `ODK Build <https://opendatakit.org/use/build/>`_. Another form builder `XLSForm <https://opendatakit.org/use/xlsform/>`_ uses an Excel spreadsheet of questions to generate the XForm file; it is more suitable when working with larger forms. |
There was a problem hiding this comment.
XLSForm should be promoted as the primary way of building XForms.
- Link to xlsform.org
- Link to the online xlsform converter
- Link to the local Java tool
- Link to pyxform
You can mention Build as a simple online tool
The ODK XForm spec is now at:
https://opendatakit.github.io/xforms-spec/
xform-anatomy.rst
Outdated
|
|
||
| We have a `form design guide <https://opendatakit.org/help/form-design/guidelines/>`_, and the JavaRosa community has a `description of the specification <https://bitbucket.org/javarosa/javarosa/wiki/xform>`_ we support and a `good tutorial <https://bitbucket.org/javarosa/javarosa/wiki/buildxforms>`_. We also have `examples of forms available <https://github.com/opendatakit/sample-forms>`_ and a simple graphical form designer `ODK Build <https://opendatakit.org/use/build/>`_. Another form builder `XLSForm <https://opendatakit.org/use/xlsform/>`_ uses an Excel spreadsheet of questions to generate the XForm file; it is more suitable when working with larger forms. | ||
|
|
||
| XLSForms now support most of the desired features. To work on advanced forms, there might be some need of manually editing XML. |
There was a problem hiding this comment.
I would say:
XLSForms supports most features of the XForm specification. It is rare for ODK implementers to edit XForms manually, and doing so is highly error prone.
xform-anatomy.rst
Outdated
| - The **bindings** -- for each instance variable, you can include information about those data like the type (string, integer, etc.), the constraints on those data (i.e. less than 3), whether they're required or not, etc. | ||
| - The **body** -- how prompts are displayed to the user. | ||
|
|
||
| These are explained in the following HTML example one by one. |
xform-anatomy.rst
Outdated
| </data> | ||
| </instance> | ||
|
|
||
| Here we have a single instance called "data". This instance is identified via the 'id' attribute as the 'myform' form. This id attribute, and an optional version attribute, provide the internal unique name of this form to the software. The software only allows one form definition for each (id, version) pair. |
There was a problem hiding this comment.
Verbatim strings from the XML (like data or id) should be monospaced (inline literal) with double-backticks:
Here we have a single instance called ``data``. This instance is identified via the ``id`` attribute.
xform-anatomy.rst
Outdated
|
|
||
| The body represents what should be shown to the user. In this example, we have two variables, but the ``<instanceID>`` variable is merely for bookkeeping. Thus, we will only have one prompt displayed to the user for the ``<mystring>`` variable. This is placed in the body element: | ||
|
|
||
| .. code-block:: html |
xform-anatomy.rst
Outdated
| </input> | ||
| </h:body> | ||
|
|
||
| The type of widget/prompt to show the user is specified by the <input> tag. Where to put the data is specified by the ``ref=""`` attribute. The <label> is what will be shown to the user as the prompt header, and the ``<hint>`` is an optional piece of text to display. |
There was a problem hiding this comment.
- The type of form widget is specified by the tag name of the element.
- The ref attribute specifies which node the response will be stored in
xform-anatomy.rst
Outdated
|
|
||
| The type of widget/prompt to show the user is specified by the <input> tag. Where to put the data is specified by the ``ref=""`` attribute. The <label> is what will be shown to the user as the prompt header, and the ``<hint>`` is an optional piece of text to display. | ||
|
|
||
| For a full list of body element types see `form body <https://opendatakit.org/help/form-design/body/>`_ or look through the `widget examples <https://opendatakit.org/help/form-design/examples/>`_. |
There was a problem hiding this comment.
link to form-widgets page instead, not the old odk website
| Adding another prompt | ||
| ---------------------- | ||
|
|
||
| To finish our example, we'll add another prompt to our form. We'll need to add a new element to the instance, a new binding, and a new element to the body. This time, however, we'll make the prompt required for the user to answer. Changed lines are in red. We update our form ID to reflect that this is a different form than the original one. |
There was a problem hiding this comment.
Changed lines are in red.
They are?
xform-anatomy.rst
Outdated
|
|
||
| So our new form now looks like this: | ||
|
|
||
| .. code-block:: html |
xform-anatomy.rst
Outdated
|
|
||
| We are going to compute and store a unique identifier for each filled-in form in the ``<instanceID/>`` element. This will enable ODK Aggregate (or any back-end process) to de-duplicate submissions if, for example, the same filled-in form were somehow submitted twice. | ||
|
|
||
| The other variable, ``<mystring/>``, is where we're going to store the answer to our prompt, but it's only a placeholder. We **DO NOT** specify a data type here. |
There was a problem hiding this comment.
@adammichaelwood What is prompt here?
|
@adammichaelwood I am not sure what to call this page. XForm intro? or coding? |
|
Intro to XForm might be a good title. |
|
Heads up @mish24, we just merged some commits that conflict with the changes your made in this pull request! You can review this repository's recent commits to see where the conflicts occur. Please rebase your feature branch against the |
closes #20
important for #18
What is included in this PR?
This PR has the contents written in Official Form Design docs
What is left to be done in the addressed issue?
Some minor line edits for making the content more readable, clearer examples.