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

Add section on representing zero repeats and add subheadings to repeat section #179

Merged
merged 6 commits into from
Nov 5, 2019
Merged

Add section on representing zero repeats and add subheadings to repeat section #179

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
47c0d23
Pull repeats section up one level
lognaturel Oct 23, 2019
94776b9
Simplify 'repeat group' to 'repeat'
lognaturel Oct 23, 2019
7e23e7e
Add section on representing zero repeats
lognaturel Oct 23, 2019
edc79e9
Simplify sample form
lognaturel Oct 23, 2019
1c60e99
Document repeat summary label
lognaturel Oct 23, 2019
7ae0bfe
Remove 'some platforms' language
lognaturel Oct 24, 2019
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
75 changes: 51 additions & 24 deletions _sections/home-english.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -502,9 +502,9 @@ One neat feature of XLSForm is the ability to skip a group of questions by combi

In this example, the two child group questions (**muac** and **mrdt**) will only appear if the child's **age** from the first question is less than or equal to five.

### Repeats
## Repeats

A user can repeat a group of questions by using the **begin repeat** and **end repeat** construct:
A user can repeat questions by using the **begin repeat** and **end repeat** construct:

| type | name | label |
| ---------------------- | ------------ | ------------------- |
Expand All @@ -525,57 +525,84 @@ A user can repeat a group of questions by using the **begin repeat** and **end r
| =================== | =========== | =========== |
| choices | | |

In this example, the **name**, **birthweight**, and **sex** fields are grouped together in a repeat group, and the user can repeat this group as many times as required by selecting the option in the form to start another repeat.
In this example, the **name**, **birthweight**, and **sex** fields are grouped together in a repeat, and the user can collect the same information about multiple children by selecting the option in the form to add another repeat.

The **label** column is optional for **begin repeat**. Assigning a label to a repeat group will add the label as a title to the block of repeat questions in the form.
The **label** column is optional for **begin repeat**. Assigning a label to a repeat will add the label as a title to the block of repeat questions in the form.

The [Delivery Outcome](https://docs.google.com/spreadsheets/d/1_gCJml_FzJ4qiLU-yc67x1iu_GL-hfU3H8-HvINsIoE/edit?usp=sharing) XLSForm illustrates another repeat group example.
When a repeat is shown in a table of contents, the label used to represent each repeat is the label of the first group inside that repeat. In the example below, if a repeat is filled out with values `Preity` for `first_name`, `Zinta` for `last_name` and `71` for `age`, that repeat will be summarized as "Preity Zinta - 71":

Instead of allowing an infinite number of repeats, the user can specify an exact number of repeats by using the **repeat_count** column:
| type | name | label |
| ---------------------- | ------------ | ------------------------------------------------------- |
| begin repeat | person_repeat| |
| begin group | person | ${first_name} ${last_name} - ${age} |
| text | first_name | First name |
| text | last_name | Last name |
| integer | age | Age |
| end group | | |
| end repeat | | |
| ================= | ======== | ======================================================= |
| survey

The [Delivery Outcome](https://docs.google.com/spreadsheets/d/1_gCJml_FzJ4qiLU-yc67x1iu_GL-hfU3H8-HvINsIoE/edit?usp=sharing) XLSForm is another repeat example.

### Fixed repeat counts

Instead of allowing an infinite number of repeats, the form designer can specify an exact number of repeats by using the **repeat_count** column:

| type | name | label | repeat_count |
| ---------------------- | ------------ | -------------------- | ------------ |
| begin repeat | child_repeat | | 3 |
| text | name | Child's name | |
| decimal | birthweight | Child's birthweight | |
| select_one male_female | sex | Child's sex | |
| end repeat | | | |
| ================= | ======== | ==================== | ============ |
| survey | | | |

<p/>

| list name | name | label |
| ------------------- | ----------- | ----------- |
| male_female | male | Male |
| male_female | female | Female |
| =================== | =========== | =========== |
| choices | | |
In the above example, exactly **3** child repeats will be created.

In the above example, the repeat group is restricted to **3** repeats.
### Dynamic repeat counts

Some platforms also support dynamic repeat counts. In the example below, the number that the user inputs for the **num_hh_members** field dictates the number of times the **hh_member** group repeats:
The repeat count can be set to an expression that refers to other fields in the form. In the example below, the number that the user inputs for the **num_hh_members** field dictates the number of **hh_member** repeats added:

| type | name | label | repeat_count |
| ---------------------- | -------------- | ---------------------------- | ----------------- |
| integer | num_hh_members | Number of household members? | |
| begin repeat | hh_member | | ${num_hh_members} |
| text | name | Name | |
| integer | age | Age | |
| select_one male_female | gender | Gender | |
| end repeat | | | |
| ================= | ======== | ==================== | ============ |
| survey | | | |

### Only add repeats in certain conditions

Like [with groups](#skipping), all of the questions in a repeat can be skipped based on some condition. In the example below, the person filling out the form will only be given the opportunity to add children if they first indicate that there are children to add:

| type | name | label | relevant |
| ---------------------- | ------------ | ---------------------------|---------------------|
| select_one yes_no | has_child | Do any children live here? | |
| begin repeat | child_repeat | | ${has_child} = 'yes'|
| text | name | Child's name | |
| decimal | birthweight | Child's birthweight | |
| end repeat | | | |
| ================= | ======== | ========================== | =================== |
| survey | | | |

<p/>

| list name | name | label |
| ------------------- | ----------- | ----------- |
| male_female | male | Male |
| male_female | female | Female |
| =================== | =========== | =========== |
| choices | | |
| list_name | name | label |
| ------------ | ----------- | -------- |
| yes_no | yes | Yes |
| yes_no | no | No |
| ============ | =========== | ======== |
| choices | | |

### Representing zero repeats

By default, the person filling the form will see the questions corresponding to one repeat before getting the option to add more. To represent 0 repeats, there are three options:
- teach the people filling out the form to delete the first repeat added
- if the exact number of repeats is known ahead of time, [use a dynamic repeat count](#dynamic-repeat-counts)
- if the exact number of repeats is not known ahead of time, [use `relevant`](#only-add-repeats-in-certain-conditions) to only prompt the user for repeats if there are some to add

## Multiple language support

Expand Down