From e43c719d154e4eb869dc1cf40c77a045758578af Mon Sep 17 00:00:00 2001 From: Alexander Mtembenuzeni Date: Thu, 14 Jul 2022 05:52:09 +0200 Subject: [PATCH] Add nice table xlsform formatting to articles --- source/acknowledge.md | 8 ++- source/add_logo.md | 29 ++++---- source/alternative_enketo.md | 5 +- source/audit_logging.md | 17 +++-- source/cascading_select.md | 24 +++---- source/collect_gps.md | 100 +++++++++++++++------------- source/collecting_signatures.md | 11 ++- source/external_file.md | 16 +++-- source/getting_started_xlsform.md | 33 ++++----- source/group_repeat.md | 78 +++++++++++++--------- source/hxl.md | 13 ++-- source/language_xls.md | 107 ++++++++++++++++-------------- source/library_locking.md | 86 ++++++++++++------------ source/matrix_response.md | 25 ++++--- source/number_text_responses.md | 28 ++++++-- source/p_codes.md | 11 +-- source/photo_download.md | 21 +++--- source/restrict_responses.md | 34 ++++++---- source/unique_serial_numbers.md | 3 +- 19 files changed, 354 insertions(+), 295 deletions(-) diff --git a/source/acknowledge.md b/source/acknowledge.md index e8f5a7a1..43a77b41 100644 --- a/source/acknowledge.md +++ b/source/acknowledge.md @@ -1,5 +1,8 @@ # Acknowledge question type -**Last updated:** 18 Apr 2022 + +**Last updated:** +18 +Apr 2022 The "Acknowledge" question type displays a single option, to select "OK" on the form. @@ -43,8 +46,6 @@ In the above example, the group "Survey" will only be displayed if the Below is the equivalent form logic in XLSForm syntax: -**survey** - | type | name | label | relevant | | :---------- | :------ | :------------------------------------------------- | :---------------- | | acknowledge | consent | If you agree to continue with the survey, click OK | | @@ -52,6 +53,7 @@ Below is the equivalent form logic in XLSForm syntax: | text | name | What is your name? | | | integer | age | How old are you? | | | end_group | | | | +| survey |

You can download the example XLSForm diff --git a/source/add_logo.md b/source/add_logo.md index 118c651d..f998ad0d 100644 --- a/source/add_logo.md +++ b/source/add_logo.md @@ -15,11 +15,10 @@ To begin: label blank, and add a column titled `media::image` with your logo file name in the cell. As shown below: -**survey** - -| type | name | label | media::image | -| :--- | :--- | :---- | :----------- | -| note | logo | | logo.jpg | +| type | name | label | media::image | +| :----- | :--- | :---- | :----------- | +| note | logo | | logo.jpg | +| survey | 3. When you're done editing the form, upload the XLSForm to either a new or existing project. @@ -32,11 +31,15 @@ To begin: ## Tips: -- Keep your image small. -- Your logo image will not appear in the form preview, only when the form is - opened. -- Skipping the final step will mean that your form will be displayed without - the media files. Make sure the media files are uploaded before downloading - the form to your devices when using the Android app. - -

If you open the formbuilder after deploying your XLSForm with the logo image file, it will automatically give the question a text label and you'll need to delete it for the automated text not to appear next to your logo in your form.

+- Keep your image small. +- Your logo image will not appear in the form preview, only when the form is + opened. +- Skipping the final step will mean that your form will be displayed without the + media files. Make sure the media files are uploaded before downloading the + form to your devices when using the Android app. + +

+ If you open the formbuilder after deploying your XLSForm with the logo image + file, it will automatically give the question a text label and you'll need to + delete it for the automated text not to appear next to your logo in your form. +

diff --git a/source/alternative_enketo.md b/source/alternative_enketo.md index 24d9ce4d..b888f593 100644 --- a/source/alternative_enketo.md +++ b/source/alternative_enketo.md @@ -13,7 +13,7 @@ of questions set to display on the same screen. This is the same way [KoboCollect works](group_repeat.md). **Grid Theme** is an alternative display of questions meant to be more compact -and more like paper forms where space is often a major concern. theme-grid +and more like paper forms where space is often a major concern. `theme-grid` allows displaying multiple questions per row and flexibly adapts in case of skip logic making a new question appear or disappear. To display multiple questions in a row they need to be part of a group, which by default shows up to four @@ -30,11 +30,10 @@ You can set these styles through the KoboToolbox formbuilder user interface: If you are building your survey project through XLSForm, you could do the same by defining the theme under the `style` column in the `settings` sheet: -**settings** - | form_title | style | | :---------- | :---- | | Themed form | pages | +| settings | ## Available styles in XLSForm: diff --git a/source/audit_logging.md b/source/audit_logging.md index de7e1fd0..2a3f9150 100644 --- a/source/audit_logging.md +++ b/source/audit_logging.md @@ -21,14 +21,13 @@ please follow the steps below: meta questions. Then upload the form file to your project and deploy the form. -**survey** - -| type | name | label | -| :---- | :---- | :--------------------- | -| start | start | | -| end | end | | -| audit | audit | | -| text | Q1 | Q1. What is your name? | +| type | name | label | +| :----- | :---- | :--------------------- | +| start | start | | +| end | end | | +| audit | audit | | +| text | Q1 | Q1. What is your name? | +| survey | 2. Collect data using the [Collect Andoid app](kobocollect-android.md) and send the finalized forms back to the server. Collect saves the audit logs for each @@ -42,7 +41,7 @@ please follow the steps below: ![image](/images/audit_logging/zip_export.png) -4. Once the ZIP file has been extracted and opened, click on the file labeled +4. Once the ZIP file has been extracted and opened, click on the file labelled 'audit.csv' to view the audit logs. It's important to note that the CSV uses [Unix Epoch](https://www.unixtimestamp.com/index.php) time so the logs are recorded in milliseconds. diff --git a/source/cascading_select.md b/source/cascading_select.md index 2cc58cee..3aa956f5 100644 --- a/source/cascading_select.md +++ b/source/cascading_select.md @@ -9,7 +9,11 @@ response to a previous question. For example, your form may first ask the region where a respondent is from, and then in the next question list only the towns and villages of that region. -

Adding sets of cascading select questions to your form can be done by importing them to a draft form in the formbuilder or adding them manually to an XLS Form and then uploading that file.

+

+ Adding sets of cascading select questions to your form can be done by + importing them to a draft form in the formbuilder or adding them manually to + an XLSForm and then uploading that file. +

## Importing cascading question sets in the formbuilder @@ -17,14 +21,14 @@ and villages of that region. [follow this template as an example](https://docs.google.com/spreadsheets/d/1C_uDOkjjbv5Kx3lyOY7ORwM-muW6BKVzdaPMB1X8-2A/edit#gid=0) to create your template of questions and responses to be added. - ![image](/images/cascading_select/template.png) + ![image](/images/cascading_select/template.png) 2. Select and copy the whole cascading table template, then paste it into the Import Cascade, then click Done to import it. (If there were any mistakes in the formatting you will not be able to import the set - correct any formatting mistakes and make sure you followed the template instructions.) - ![image](/images/cascading_select/import.gif) + ![image](/images/cascading_select/import.gif) 3. You can move the imported questions anywhere in your form and change the labels of both the question and responses and delete responses. @@ -34,7 +38,7 @@ and villages of that region. 5. You can preview the form to test the cascading questions. - ![image](/images/cascading_select/form_preview.gif) + ![image](/images/cascading_select/form_preview.gif) ## Adding cascading question sets in XLSForm (Option 1) @@ -45,13 +49,12 @@ in Excel or another spreadsheet program). following [this template](https://docs.google.com/spreadsheets/d/10gpBV6YaYGx1i367hyW-w1Ms9tkUQnCx0V8YsdwYxmk/edit#gid=0). -**survey** - | type | name | label | choice_filter | | :------------------ | :--- | :------------ | :--------------------------- | | select_one states | Q1 | Which state? | | | select_one counties | Q2 | Which county? | state=${Q1} | | select_one cities | Q3 | Which city? | state=${Q1} and county=${Q2} | +| survey | 2. In the same survey sheet, add a column called `choice_filter` and add the XLSForm reference to each of the parent items. @@ -60,8 +63,6 @@ in Excel or another spreadsheet program). appear in the different questions, e.g. the lists of states, counties, and cities (follow the above template). -**choices** - | list_name | name | label | state | county | | :-------- | :---------- | :---------- | :--------- | :------ | | states | texas | Texas | | | @@ -78,6 +79,7 @@ in Excel or another spreadsheet program). | cities | redmond | Redmond | washington | king | | cities | tacoma | Tacoma | washington | pierce | | cities | puyallup | Puyallup | washington | pierce | +| choices | 4. Note that for each of the child elements you need to add a column to specify its parent. For example, King and Pierce counties are in Washington state, so @@ -93,14 +95,11 @@ in Excel or another spreadsheet program). Sometimes a researcher wishes to limit the choices of one question based on the responses from a previous question. For this one could do the following: -**survey** - | type | name | label | choice_filter | | :-------------------- | :--- | :------------------------------------------------------------------------------- | :-------------------- | | select_multiple brand | Q1 | Q1. Which brand comes to mind comes to mind when you think about life insurance? | | | select_multiple brand | Q2 | Q2. Which branch would you choose for your future life insurance purchase? | selected(${Q1}, name) | - -**choices** +| survey | | list_name | name | label | | :-------- | :--- | :----------------- | @@ -114,6 +113,7 @@ responses from a previous question. For this one could do the following: | brand | 8 | Tata AIA Life | | brand | 9 | ICICI Prudential | | brand | 10 | PNB Met Life | +| choices | Preview the data collecting form in Enketo: diff --git a/source/collect_gps.md b/source/collect_gps.md index 42471b05..a725f826 100644 --- a/source/collect_gps.md +++ b/source/collect_gps.md @@ -13,21 +13,20 @@ To collect GPS coordinates during the data collection process simply add a GPS question to your form. There are three types of GPS questions: **Point**, **Line** and **Area** -- When using the **formbuilder** these question types can be found when one - clicks the add question button as illustrated below. +- When using the **formbuilder** these question types can be found when one + clicks the add question button as illustrated below. ![image](/images/collect_gps/formbuilder.jpg) -- When using **XLSForm** design, you have to define the question types as - below to get the question you desire. - -**survey** +- When using **XLSForm** design, you have to define the question types as below + to get the question you desire. | type | name | label | hint | | :------- | :---- | :--------------------------- | :----------------------------------------------------------------------------------- | | geopoint | point | Record your current location | This question collects a single GPS coordinate that denotes a single point | | geotrace | line | Record a line | This question collects two coordinates to form a line | | geoshape | area | Record an area | This question collects GPS coordinates that mark out a closed loop/area in any shape | +| survey | ## Collecting Data Using the GPS Questions @@ -61,37 +60,35 @@ The interviewer will see various options depending on the GPS question type **1. Single GPS point coordinate** -- The enumerator will see this screen which they can tap on the Start - GeoPoint. +- The enumerator will see this screen which they can tap on the Start GeoPoint. ![image](/images/collect_gps/geopoint.jpg) -- If enumerators taps the Start Geopoint they will see the location loading - and the accuracy achieved. If the question had not been set to pick a - specific accuracy level, it will wait for the enumerator to save the - GeoPoint as illustrated below. +- If enumerators tap the Start Geopoint they will see the location loading and + the accuracy achieved. If the question had not been set to pick a specific + accuracy level, it will wait for the enumerator to save the GeoPoint as + illustrated below. ![image](/images/collect_gps/autopoint.jpg) **2. GPS Line** -- The enumerators will see the following option for the line question. +- The enumerators will see the following option for the line question. ![image](/images/collect_gps/line.jpg) -- If they tap the Start GeoTrace button they will see an option to either - collect the trace manually or automatically as shown below. +- If they tap the Start GeoTrace button they will see an option to either + collect the trace manually or automatically as shown below. ![image](/images/collect_gps/trace_mode.jpg) -- If the enumerators select manual mode for collecting data then they will be - able to select the points manually by pressing the points on the map. The - enumerator will have to select at least two coordinates to make a line - trace. +- If the enumerators select manual mode for collecting data then they will be + able to select the points manually by pressing the points on the map. The + enumerator will have to select at least two coordinates to make a line trace. -- If the enumerators select the automatic mode, then they will see an option - for how long the system should take before collecting different points as - shown in the figure below. +- If the enumerators select the automatic mode, then they will see an option for + how long the system should take before collecting different points as shown in + the figure below. ![image](/images/collect_gps/automodes.jpg) @@ -117,38 +114,47 @@ rather than using satellite navigation systems. **The time it takes for a device to determine its GPS coordinates varies strongly and may depend on:** -- The quality of the GPS sensor -- The last time since the device had last determined its GPS location -- Cloud cover -- Buildings or other structures obstructing view of the sky +- The quality of the GPS sensor +- The last time since the device had last determined its GPS location +- Cloud cover +- Buildings or other structures obstructing view of the sky **To obtain a GPS signal you should be outdoors with good visibility of the sky. To get a strong GPS signal:** -- Stand as far from buildings, trees, or other structures as possible -- Make sure your body isn't obstructing view of the sky -- Get an initial GPS location at the beginning of the day before starting to - collect points in the field -- Enable A-GPS (data-network assisted) on your device - -

GPS in this context does not exclusively refer to the Global Positioning System but also to other satellite navigation systems used by mobile devices, such as GLONASS.

+- Stand as far from buildings, trees, or other structures as possible +- Make sure your body isn't obstructing view of the sky +- Get an initial GPS location at the beginning of the day before starting to + collect points in the field +- Enable A-GPS (data-network assisted) on your device + +

+ GPS in this context does not exclusively refer to the + Global Positioning System + but also to other satellite navigation systems used by mobile devices, such as + GLONASS. +

## Troubleshooting If you are unable to get a GPS location with the GPS response type, please check these options: -- Location settings on your device to ensure GPS is enabled -- Install a free app that uses GPS to see if you can get a GPS location that - way (e.g. - [GPS Status for Android](https://play.google.com/store/apps/details?id=com.eclipsim.gpsstatus2) - or - [GPS Status for iPhones](https://apps.apple.com/ca/app/gps-status/id378085995) -- Check your phone settings/manufacturer manual to see if the device has GPS - available -- If your collected GPS points are pointing to the wrong location, it's - possible your device is set to collecting its location from a network tower - that was bought second hand and has not properly been reset with the new - hard-coded location. You can avoid this issue by turning off network - location as an option within the Android system settings, forcing Collect to - wait for the actual GPS location. +- Location settings on your device to ensure GPS is enabled +- Install a free app that uses GPS to see if you can get a GPS location that way + (e.g. + [GPS Status for Android](https://play.google.com/store/apps/details?id=com.eclipsim.gpsstatus2) + or + [GPS Status for iPhones](https://apps.apple.com/ca/app/gps-status/id378085995) +- Check your phone settings/manufacturer manual to see if the device has GPS + available +- If your collected GPS points are pointing to the wrong location, it's possible + your device is set to collecting its location from a network tower that was + bought second hand and has not properly been reset with the new hard-coded + location. You can avoid this issue by turning off network location as an + option within the Android system settings, forcing Collect to wait for the + actual GPS location. diff --git a/source/collecting_signatures.md b/source/collecting_signatures.md index 3b4297cb..a429868d 100644 --- a/source/collecting_signatures.md +++ b/source/collecting_signatures.md @@ -26,12 +26,11 @@ option to use a draw widget to collect signatures. In your XLSForm just add `signature` or `draw` under the `appearance` column for an `image`-type question. -**survey** - -| type | name | label | appearance | hint | -| :---- | :--- | :--------------- | :--------- | :------------------------------- | -| image | draw | Draw widget | draw | Image type with draw appearance | -| image | sign | Signature widget | signature | Image type with signature widget | +| type | name | label | appearance | hint | +| :----- | :--- | :--------------- | :--------- | :------------------------------- | +| image | draw | Draw widget | draw | Image type with draw appearance | +| image | sign | Signature widget | signature | Image type with signature widget | +| survey | [Follow this link](https://enke.to/draw) to test the difference between the draw and signature widgets. diff --git a/source/external_file.md b/source/external_file.md index 71ae1d92..3a741d2c 100644 --- a/source/external_file.md +++ b/source/external_file.md @@ -19,24 +19,27 @@ more information. **1.** In the XLSForm, the type should be either `select_one_from_file [filename]` or `select_multiple_from_file [filename]`: -

The file-type can be either CSV or XML

- -**survey** +

+ The file-type can be either CSV or XML +

| type | name | label | | :------------------------------ | :----- | :---------------------------- | | text | name | What is your name? | | select_one sex | sex | What is your sex? | | select_one_from_file fruits.csv | fruits | What is your favourite fruit? | - -**choices** +| survey | | list_name | name | label | | :-------- | :--- | :----- | | sex | 1 | Male | | sex | 2 | Female | +| choices | -

The fruits.csv is the file name containing the choices for the question "What is your favorite fruit?".

+

+ The fruits.csv is the file name containing the choices for the + question "What is your favorite fruit?". +

**2.** Create a new `CSV` file and structure it the same as the `choices` sheet in the XLSForm: @@ -56,6 +59,7 @@ in the XLSForm: | fruits | 9 | Mango | | fruits | 10 | Blueberry | | fruits | 11 | Pomegranate | +| choices | **3.** Upload and deploy the XLSForm in KoboToolbox. diff --git a/source/getting_started_xlsform.md b/source/getting_started_xlsform.md index bf039127..ee51a7ef 100644 --- a/source/getting_started_xlsform.md +++ b/source/getting_started_xlsform.md @@ -6,10 +6,10 @@ Feb 2022 This article will show you how to: -- Set up an XLSForm using Microsoft Excel. -- Upload and preview the XLSForm in KoboToolbox. -- Download a form you have been creating using the KoboToolbox formbuilder as - an XLSForm. +- Set up an XLSForm using Microsoft Excel. +- Upload and preview the XLSForm in KoboToolbox. +- Download a form you have been creating using the KoboToolbox formbuilder as an + XLSForm.