-
Notifications
You must be signed in to change notification settings - Fork 158
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* added form update guide * added image * added xlsx and xml forms * added form-update to Form Building toc * added images for form in collect * added form update info in collect and extra changes for existing form * updated example form * minor fix in table * update on using external select * clarified media update
- Loading branch information
1 parent
26d206a
commit 7548582
Showing
9 changed files
with
341 additions
and
0 deletions.
There are no files selected for viewing
Git LFS file not shown
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,66 @@ | ||
| <?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" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> | ||
| <h:head> | ||
| <h:title>Example_form</h:title> | ||
| <model> | ||
| <instance> | ||
| <example_form id="example_id" version="2017120700"> | ||
| <name/> | ||
| <sid/> | ||
| <age/> | ||
| <course/> | ||
| <course_cnt/> | ||
| <marks/> | ||
| <total/> | ||
| <meta> | ||
| <instanceID/> | ||
| </meta> | ||
| </example_form> | ||
| </instance> | ||
| <bind nodeset="/example_form/name" required="true()" type="string"/> | ||
| <bind nodeset="/example_form/sid" required="true()" type="int"/> | ||
| <bind constraint=".<=18" jr:constraintMsg="You should be below 18 years to be eligible for the survey." nodeset="/example_form/age" required="true()" type="int"/> | ||
| <bind nodeset="/example_form/course" required="true()" type="select1"/> | ||
| <bind constraint=".>=1 and .<=6" jr:constraintMsg="You should choose atleast 1 course and atmost 6 courses." nodeset="/example_form/course_cnt" relevant=" /example_form/course !='none'" required="true()" type="int"/> | ||
| <bind constraint=" /example_form/marks <= /example_form/total " jr:constraintMsg="You cannot obtain more than maximum marks." nodeset="/example_form/marks" relevant=" /example_form/course !='none'" required="true()" type="int"/> | ||
| <bind calculate=" /example_form/course_cnt *100" nodeset="/example_form/total" relevant=" /example_form/course_cnt !=''" type="string"/> | ||
| <bind calculate="concat('uuid:', uuid())" nodeset="/example_form/meta/instanceID" readonly="true()" type="string"/> | ||
| </model> | ||
| </h:head> | ||
| <h:body> | ||
| <input ref="/example_form/name"> | ||
| <label>Enter your name</label> | ||
| </input> | ||
| <input ref="/example_form/sid"> | ||
| <label>Enter your student id</label> | ||
| </input> | ||
| <input ref="/example_form/age"> | ||
| <label>Enter your age</label> | ||
| </input> | ||
| <select1 ref="/example_form/course"> | ||
| <label>In which department have you chosen courses?</label> | ||
| <item> | ||
| <label>PHY</label> | ||
| <value>Physics</value> | ||
| </item> | ||
| <item> | ||
| <label>MAT</label> | ||
| <value>Maths</value> | ||
| </item> | ||
| <item> | ||
| <label>CHEM</label> | ||
| <value>Chemistry</value> | ||
| </item> | ||
| <item> | ||
| <label>none</label> | ||
| <value>none</value> | ||
| </item> | ||
| </select1> | ||
| <input ref="/example_form/course_cnt"> | ||
| <label>Enter number of courses you have chosen</label> | ||
| </input> | ||
| <input ref="/example_form/marks"> | ||
| <label>Enter total marks obtained in all courses</label> | ||
| </input> | ||
| </h:body> | ||
| </h:html> |
Git LFS file not shown
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,112 @@ | ||
| <?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" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> | ||
| <h:head> | ||
| <h:title>Example_form</h:title> | ||
| <model> | ||
| <itext> | ||
| <translation lang="Español (es)"> | ||
| <text id="/example_form/sid:label"> | ||
| <value>Ingrese su identificación de estudiante</value> | ||
| </text> | ||
| <text id="/example_form/course:label"> | ||
| <value>Nombre del departamento</value> | ||
| </text> | ||
| <text id="/example_form/name:label"> | ||
| <value>Introduzca su nombre</value> | ||
| </text> | ||
| <text id="/example_form/marks:label"> | ||
| <value>Ingrese las calificaciones totales obtenidas en todos los cursos</value> | ||
| </text> | ||
| <text id="/example_form/course_cnt:label"> | ||
| <value>Ingresa el número de cursos que has elegido</value> | ||
| </text> | ||
| <text id="/example_form/age:label"> | ||
| <value>Introduzca su edad</value> | ||
| </text> | ||
| </translation> | ||
| <translation lang="English (en)"> | ||
| <text id="/example_form/sid:label"> | ||
| <value>Enter your student id</value> | ||
| </text> | ||
| <text id="/example_form/course:label"> | ||
| <value>Name of Department</value> | ||
| </text> | ||
| <text id="/example_form/name:label"> | ||
| <value>Enter your name</value> | ||
| </text> | ||
| <text id="/example_form/marks:label"> | ||
| <value>Enter total marks obtained in all courses</value> | ||
| </text> | ||
| <text id="/example_form/course_cnt:label"> | ||
| <value>Enter number of courses you have chosen</value> | ||
| </text> | ||
| <text id="/example_form/age:label"> | ||
| <value>Enter your age</value> | ||
| </text> | ||
| </translation> | ||
| </itext> | ||
| <instance> | ||
| <example_form id="example_id" version="2017120701"> | ||
| <sid/> | ||
| <name/> | ||
| <age/> | ||
| <course/> | ||
| <course_cnt/> | ||
| <marks/> | ||
| <total/> | ||
| <meta> | ||
| <instanceID/> | ||
| </meta> | ||
| </example_form> | ||
| </instance> | ||
| <bind nodeset="/example_form/sid" required="false()" type="int"/> | ||
| <bind nodeset="/example_form/name" required="true()" type="string"/> | ||
| <bind constraint=".<=20" jr:constraintMsg="You should be below 20 years to be eligible for the survey." nodeset="/example_form/age" required="true()" type="int"/> | ||
| <bind nodeset="/example_form/course" required="true()" type="select1"/> | ||
| <bind constraint=".>=1 and .<=6" jr:constraintMsg="You should choose atleast 1 course and atmost 6 courses." nodeset="/example_form/course_cnt" relevant=" /example_form/course !='none'" required="true()" type="int"/> | ||
| <bind constraint=" /example_form/marks <= /example_form/total " jr:constraintMsg="You cannot obtain more than maximum marks." nodeset="/example_form/marks" relevant=" /example_form/course !='none'" required="true()" type="int"/> | ||
| <bind calculate=" /example_form/course_cnt *50" nodeset="/example_form/total" relevant=" /example_form/course !='none' and /example_form/course_cnt !=''" type="string"/> | ||
| <bind calculate="concat('uuid:', uuid())" nodeset="/example_form/meta/instanceID" readonly="true()" type="string"/> | ||
| </model> | ||
| </h:head> | ||
| <h:body> | ||
| <input ref="/example_form/sid"> | ||
| <label ref="jr:itext('/example_form/sid:label')"/> | ||
| </input> | ||
| <input ref="/example_form/name"> | ||
| <label ref="jr:itext('/example_form/name:label')"/> | ||
| </input> | ||
| <input ref="/example_form/age"> | ||
| <label ref="jr:itext('/example_form/age:label')"/> | ||
| </input> | ||
| <select1 ref="/example_form/course"> | ||
| <label ref="jr:itext('/example_form/course:label')"/> | ||
| <item> | ||
| <label>PHY</label> | ||
| <value>Physics</value> | ||
| </item> | ||
| <item> | ||
| <label>MATHS</label> | ||
| <value>Mathematics</value> | ||
| </item> | ||
| <item> | ||
| <label>CHEM</label> | ||
| <value>Chemistry</value> | ||
| </item> | ||
| <item> | ||
| <label>COMP</label> | ||
| <value>Computer</value> | ||
| </item> | ||
| <item> | ||
| <label>none</label> | ||
| <value>none</value> | ||
| </item> | ||
| </select1> | ||
| <input ref="/example_form/course_cnt"> | ||
| <label ref="jr:itext('/example_form/course_cnt:label')"/> | ||
| </input> | ||
| <input ref="/example_form/marks"> | ||
| <label ref="jr:itext('/example_form/marks:label')"/> | ||
| </input> | ||
| </h:body> | ||
| </h:html> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,147 @@ | ||
| Updating forms | ||
| ================= | ||
|
|
||
| .. _change-existing: | ||
|
|
||
| Making changes to existing form | ||
| --------------------------------- | ||
|
|
||
| Certain changes which don't involve adding or removing a question can be made without needing to replace the existing forms. The kind of changes are: | ||
|
|
||
| - Changing the text or translation of a label | ||
| - Changing validations, calculations, relevants | ||
| - Changing options for a select_one or select_multiple | ||
| - Changing the order of questions | ||
| - Adding translations | ||
| - Updating media including CSVs for your form | ||
|
|
||
| For such changes you can update the version and re-upload the form. | ||
|
|
||
| .. note:: | ||
|
|
||
| - If you add new media files or update existing media files for your form without any change in the form definition file or :file:`.xml` file, you don't need to change the version. | ||
| - If you have used external select and add, update or delete the choices in external :file:`.csv` file without any change in the form definition file or :file:`.xml` file, you don't need to change the version. For more details on using external choices in your form, see `this <http://xlsform.org/#external>`_ | ||
|
|
||
| .. tip:: | ||
|
|
||
| Form version in XLSForm is a string of up to 10 numbers that describes this revision. Revised form definitions must have alphabetically greater versions than previous ones. A common convention is to use strings of the form **yyyymmddrr**. For example, 2017120701 is the 1st revision from Dec 7th, 2017. | ||
|
|
||
| For example: | ||
|
|
||
| .. csv-table:: **Survey** | ||
| :header: "type", "name", "label", "constraint", "constraint_message", "relevant", "read_only", "default", "required", "calculation" | ||
| :widths: auto | ||
|
|
||
| "text", "name", "Enter your name", "", "", "", "", "", "yes", "" | ||
| "integer", "sid", "Enter your student id", "", "", "", "", "", "yes", "" | ||
| "integer", "age", "Enter your age", ".<=18", "You should be below 18 years to be eligible for the survey.", "", "", "", "yes", "" | ||
| "select_one dept", "course", "In which department have you chosen courses?", "", "", "", "", "", "yes", "" | ||
| "integer", "course_cnt", "Enter number of courses you have chosen", "1<=.<=6", "You should choose atleast 1 course and atmost 6 courses.", "${course}!='none'", "", "", "yes", "" | ||
| "integer", "marks", "Enter total marks obtained in all courses", "", "", "${course}!='none'", "", "", "yes", "" | ||
| "calculate", "total", "", "", "", "${course_cnt}!=''", "", "", "", "${course_cnt}*100" | ||
|
|
||
| .. csv-table:: **Choices** | ||
| :header: "list name", "name", "label" | ||
| :widths: auto | ||
|
|
||
| "dept", "Physics", "PHY" | ||
| "dept", "Maths", "MAT" | ||
| "dept", "Chemsitry", "CHEM" | ||
| "dept", "none", "none" | ||
|
|
||
| .. csv-table:: **Settings** | ||
| :header: "form_title", "form_id", "default_language", "version" | ||
| :widths: auto | ||
|
|
||
| "Example_form", "example_id", "English", "2017120700" | ||
|
|
||
| If you want to make the following changes to the above form: | ||
|
|
||
| - Add a Spanish translation | ||
| - Change the relative order of first and second question | ||
| - Change age constraint from **18** to **20** | ||
| - Change the sid field to not required | ||
| - Change label for third question from **In which department have you chosen courses?** to **Name of Department**. | ||
| - Change the calculation from **${course_cnt}*100** to **${course_cnt}*50** | ||
| - Change the relevant for calculate to **${course}!='none' and ${course_cnt}!=''** | ||
| - Change the list name in choices from **dept** to **dept_name** | ||
| - Add a new choice in deptartment list as **Computer** | ||
| - Change **Maths** to **Mathematics** and **MAT** to **MATHS** in choices | ||
|
|
||
| These changes can be made as: | ||
|
|
||
| .. csv-table:: **Survey** | ||
| :header: "type", "name", "label::English (en)", "label::Español (es)", "constraint", "constraint_message", "relevant", "read_only", "default", "required", "calculation" | ||
| :widths: auto | ||
|
|
||
| "integer", "sid", "Enter your student id", "Ingrese su identificación de estudiante", "", "", "", "", "", "no", "" | ||
| "text", "name", "Enter your name", "Introduzca su nombre", "", "", "", "", "", "yes", "" | ||
| "integer", "age", "Enter your age", "Introduzca su edad", ".<=20", "You should be below 20 years to be eligible for the survey.", "", "", "", "yes", "" | ||
| "select_one dept_name", "course", "Name of Department", "Nombre del departamento", "", "", "", "", "", "yes", "" | ||
| "integer", "course_cnt", "Enter number of courses you have chosen", "Ingresa el número de cursos que has elegido", "1<=.<=6", "You should choose atleast 1 course and atmost 6 courses.", "${course}!='none'", "", "", "yes", "" | ||
| "integer", "marks", "Enter total marks obtained in all courses", "Ingrese las calificaciones totales obtenidas en todos los cursos", "", "", "${course}!='none'", "", "", "yes", "" | ||
| "calculate", "total", "", "", "", "", "${course}!='none' and ${course_cnt}!=''", "", "", "", "${course_cnt}*50" | ||
|
|
||
| .. csv-table:: **Choices** | ||
| :header: "list name", "name", "label" | ||
| :widths: auto | ||
|
|
||
| "dept_name", "Physics", "PHY" | ||
| "dept_name", "Mathematics", "MATHS" | ||
| "dept_name", "Chemsitry", "CHEM" | ||
| "dept_name", "Computer", "COMP" | ||
| "dept_name", "none", "none" | ||
|
|
||
| .. csv-table:: **Settings** | ||
| :header: "form_title", "form_id", "default_language", "version" | ||
| :widths: auto | ||
|
|
||
| "Example_form", "example_id", "English", "2017120701" | ||
|
|
||
| These are the :file:`.xml` files for the above forms: | ||
|
|
||
| 1. :download:`example_form_v1.0 </downloads/form-update/example_form_v1.0.xml>` | ||
| 2. :download:`example_form_v1.1 </downloads/form-update/example_form_v1.1.xml>` | ||
|
|
||
| These are the :file:`.xlsx` files for the above forms: | ||
|
|
||
| 1. :download:`example_form_v1.0 </downloads/form-update/example_form_v1.0.xlsx>` | ||
| 2. :download:`example_form_v1.1 </downloads/form-update/example_form_v1.1.xlsx>` | ||
|
|
||
| .. note:: | ||
|
|
||
| You cannot change the question type or name, form id and title. | ||
| Example: In above form you cannot change the type from **select_one** to **select_multiple** or change name from **dept** to **department**. | ||
|
|
||
| .. note:: | ||
|
|
||
| ODK Collect treats different versions of the same form completely independently. It won't explicitly notify the users of the existence of new versions. When a user tries to get new blank forms, a form with updated version will be selected by default in the list but there will be no explicit notification unless a user tries to get new blank forms. | ||
|
|
||
| .. image:: /img/form-update/get-new-version.png | ||
| :alt: Image showing new version 2017120708 selected in the list of forms to be downloaded. | ||
| :class: device-screen-vertical | ||
|
|
||
| | | ||
| Both versions of the form exist in the device of the user and the user will be allowed to fill an older version and submit the form to the Aggregate server. You will need to manually delete an older version from your device. | ||
|
|
||
| .. image:: /img/form-update/two-version-form.png | ||
| :alt: Image showing two versions 2017120700 and 2017120701 in the form list. | ||
| :class: device-screen-vertical | ||
|
|
||
| .. _replace-form: | ||
|
|
||
| Replacing existing form | ||
| --------------------------- | ||
|
|
||
| If you need to make deeper changes like changing question type, name, form id, form title etc then you will need to create a new form with the required changes. | ||
|
|
||
| Once you will modify your form, the data you will collect will be stored under that new form. However, you do not need to delete the previous form, instead, you may change the name of the new form. For example, if you had form name as **Example_form**, the revised form can be named as **Example_form_1.1**. Additionally, on your Aggregate restrict the previous form by unchecking :guilabel:`Downloadable` and :guilabel:`Accept Submissions` options. | ||
|
|
||
| .. warning:: | ||
|
|
||
| If you make changes like changing a question type or name with the same form id and title and update the version, you won't be able to re-upload the form. Aggregate will reject the form upload with an error message. | ||
|
|
||
| .. image:: /img/form-update/update-error.png | ||
| :alt: Image showing error message when trying to re-upload a form with changed question type or name. | ||
|
|
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters