XLSForm

https://xlsform.org/en/
Admin
XLSForm is a standard for authoring complex data collection forms in Excel, which are then converted...
Tokens:11,494
Snippets:79
Trust Score:8.6
Update:1 year ago
Show doc for...
Tokens:
Raw
### XML external data setup for complex queries

Source: https://xlsform.org/en/index

This XLSForm configuration defines an XML file as external data using `xml-external`. It allows for complex queries using the `instance` function, referencing the XML file by its name. The example shows counting houses with a specific number of rooms.

```XLSForm
type | name | label | calculation
xml-external | houses |   | 
integer | rooms | How many rooms? | 
calculate | count |   | count(instance('houses')/house[rooms = current()/../rooms ])
```

--------------------------------

### Implement Select Multiple Question in XLSForm

Source: https://xlsform.org/en/index

Demonstrates how to create a multiple-choice question (`select_multiple`) in XLSForm. It includes examples for the survey and choices worksheets, highlighting the importance of choice names without spaces for `select_multiple`.

```XLSForm
type | name | label
---|---|---
select_multiple pizza_toppings | favorite_toppings | What are your favorite pizza toppings?

list name | name | label
---|---|---
pizza_toppings | cheese | Cheese
pizza_toppings | pepperoni | Pepperoni
pizza_toppings | sausage | Sausage
```

--------------------------------

### Add Guidance Hints to XLSForm Questions

Source: https://xlsform.org/en/index

This example demonstrates how to implement guidance hints in XLSForm using the 'guidance_hint' column. These hints are typically not shown during data entry but are visible in special views like print-outs or training materials.

```XLSForm
type	name	label	guidance_hint	relevant
integer	age	Age?		
text	name	Name?	This will only be shown for age > 18.	${age} > 18
```

--------------------------------

### Instance function examples for different data sources

Source: https://xlsform.org/en/index

Illustrates how to use the `instance` function with different types of data sources, including choice lists, CSV files, and GeoJSON files. The list name is derived from the choice list name or the filename without its extension.

```XLSForm
instance('fruits')
```

```XLSForm
instance('participants')
```

```XLSForm
instance('places')
```

--------------------------------

### Capture GPS Location with XLSForm

Source: https://xlsform.org/en/index

Demonstrates how to capture GPS coordinates using the `geopoint` question type in XLSForm. It also shows examples for capturing lines (`geotrace`) and shapes (`geoshape`).

```XLSForm
type | name | label
---|---|---
text | store_name | What is the name of this store?
geopoint | store_gps | Collect the GPS coordinates of this store.

type | name | label | hint
---|---|---|---
geotrace | pipe | Pipeline | Please walk along the pipeline and record the coordinates of each corner point
geoshape | border | Border | Please walk along the border and record the coordinates of each corner point
```

--------------------------------

### Instance function to retrieve a specific property after filtering

Source: https://xlsform.org/en/index

Provides examples of how to retrieve a specific property (e.g., 'age' or 'fname') from an item that matches the filter criteria, using the `instance` function.

```XLSForm
instance('participants')/root/item[name=${barcode_id}]/age
```

```XLSForm
instance('participants')/root/item[name=${participant}]/fname
```

--------------------------------

### CSV external data setup for lookup

Source: https://xlsform.org/en/index

This XLSForm snippet shows how to declare a CSV file as external data using `csv-external`. It includes columns for the type, name, label, and a calculation that uses the `instance` function to look up data.

```XLSForm
type | name | label | calculation
csv-external | participants |   | 
barcode | id | Scan id | 
calculate | first_name |   | instance('participants')/root/item[participant_id=${id}]/fname
```

--------------------------------

### XLSForm: Constraint with Message for Age

Source: https://xlsform.org/en/index

This example shows how to add a custom message when a constraint is violated. The 'constraint_message' column provides user feedback explaining why an answer is not accepted.

```XLSForm
type | name | label | constraint | constraint_message
---|---|---|---|---
integer | respondent_age | Respondent's age | . >=18 | Respondent must be 18 or older to complete the survey.
```

--------------------------------

### Perform Date Calculation (XLSForm)

Source: https://xlsform.org/en/index

This example demonstrates calculating a date using the 'today()' function in XLSForm. The 'date' type question 'day' will automatically be populated with the current date when the form is filled out. This is useful for tracking when a survey was completed.

```XLSForm
type | name | label | hint | calculation
---|---|---|---|---
date | day |   |   | today()
```

--------------------------------

### Adding Custom Attributes with 'instance::' Prefix in XLSForm

Source: https://xlsform.org/en/index

This example demonstrates how to add custom attributes to the XForm output's primary instance node using the 'instance::' column prefix in the survey sheet.

```XLSForm
type | name | label | instance::hxl
---|---|---|---
integer | population | How many people are present? | #population
```

--------------------------------

### Choices Worksheet: Dynamic Select Configuration

Source: https://xlsform.org/en/index

Example of a choices worksheet row for a dynamic select. It maps the choice list name, specifies the CSV column for the selected value (name), and the CSV column for the displayed label.

```XLSForm
list name | name | label
---|---|---
fruits | name_key | name
```

--------------------------------

### Configure Audit Metaquestion for Location Tracking in XLSForm

Source: https://xlsform.org/en/index

This example shows how to configure the 'audit' metaquestion in XLSForm to enable location tracking during data entry. It requires adding a 'parameters' column with specific values for location priority, minimum interval, and maximum age.

```XLSForm
type	name	label	parameters
audit	audit		location-priority=high-accuracy location-min-interval=180 location-max-age=300
```

--------------------------------

### XLSForm: Relevance for Select Multiple Question

Source: https://xlsform.org/en/index

This example demonstrates using the 'selected()' function in the 'relevant' column to check if a specific choice was selected in a 'select_multiple' question. This allows for more granular control over conditional questions.

```XLSForm
type | name | label | relevant
---|---|---|---
select_one yes_no | likes_pizza | Do you like pizza? |
select_multiple pizza_toppings or_other | favorite_topping | Favorite toppings | ${likes_pizza} = 'yes'
text | favorite_cheese | What is your favorite type of cheese? | selected(${favorite_topping}, 'cheese')
```

--------------------------------

### Survey Worksheet: Dynamic Select

Source: https://xlsform.org/en/index

Example of a survey worksheet row configuring a dynamic select_one question. It specifies the question type, name, label, and uses a search expression in the appearance column to pull choices from a CSV file.

```XLSForm
type | name | label | appearance
---|---|---|---
select_one fruits | fruits | Select a fruit | search('fruits')
```

--------------------------------

### Search Expression: Starts With Text

Source: https://xlsform.org/en/index

Illustrates the `search()` expression with a 'startswith' operator, allowing users to filter CSV rows where a specified column begins with a given text string. This is effective for prefix-based searches.

```XLSForm
search('csvName', 'startswith', 'columnsToSearch', ${textprefix})
```

--------------------------------

### XLSForm External Select Setup

Source: https://xlsform.org/en/index

To use external choices for select_one prompts in XLSForms, change the prompt type to 'select_one_external' and define choices in the 'external_choices' sheet instead of the 'choices' sheet. This is recommended for over 50k rows.

```XLSForm
select_one_external
```

--------------------------------

### Range Widget for Numerical Input

Source: https://xlsform.org/en/index

The range question restricts integer or decimal inputs to a specified range. It accepts optional 'start', 'end', and 'step' parameters. The 'rating' appearance can be used to display it as a star rating.

```XLSForm
type | name | label | parameters
range | amount | What is the age of the child? | start=0 end=17 step=1

type | name | label | appearance | parameters
range | rated | What rating do you give? | rating | start=1 end=5 step=1
```

--------------------------------

### Using Namespaced Attributes with 'bind::' Prefix in XLSForm

Source: https://xlsform.org/en/index

Illustrates using custom namespaces with the 'bind::' column prefix to add namespaced attributes to the XForm output, as shown in the example with 'esri:fieldLength' and 'enk:for'.

```XLSForm
type | name | label | bind::esri:fieldLength | bind::enk:for
---|---|---|---|---
text | desc | Describe | 50 |
text | desc_comment | Comments |   | ${a}
```

--------------------------------

### Calculate Timestamp on Value Change (XLSForm)

Source: https://xlsform.org/en/index

This example shows how to use a 'trigger' to recalculate a value when another question's value changes. Here, a 'dateTime' question ('temp_ts') is updated with the current time ('now()') whenever the 'integer' question ('temp') is modified. The 'trigger' column specifies the question that initiates the recalculation.

```XLSForm
type | name | label | calculation | trigger
---|---|---|---|---
integer | temp | Enter the current temperature |   |
dateTime | temp_ts |   | now() | ${temp}
```

--------------------------------

### Clear Value Using Trigger (XLSForm)

Source: https://xlsform.org/en/index

This example shows how a trigger can be used to clear a value. When the 'name' field is updated, the 'age' field (an integer type) is cleared because its calculation is triggered by '${name}'. This is useful for resetting dependent fields when a primary input changes.

```XLSForm
type | name | label | calculation | trigger
---|---|---|---|---
text | name | What is the name of the oldest person here? |   |
integer | age | How old is this person? |   | ${name}
```

--------------------------------

### Instance function general structure

Source: https://xlsform.org/en/index

This demonstrates the basic syntax for using the `instance` function to look up values. It specifies the list name, a filter expression to select an item, and the property to retrieve from that item.

```XLSForm
instance('list_name')/root/item[filter expression]/desired_property
```

--------------------------------

### Create Grid Theme XLSForm

Source: https://xlsform.org/en/index

Applies a 'theme-grid' style to compact multiple questions into a single row, mimicking paper surveys. Best for larger screens. Set the 'style' column in settings to 'theme-grid' and specify column widths (e.g., w3, w1, w4) in the survey tab's appearance column.

```XLSForm Settings
form_title | form_id | style
---|---|---
example title | example_id | theme-grid
```

```XLSForm Survey
type | name | label | appearance
---|---|---|---
begin group | group1 |
text | name | Respondent's name | w3
integer | age | Respondent's age | w1
text | address | Respondent's address | w4
end group |   |
```

--------------------------------

### Instance function with filter expression for select lookup

Source: https://xlsform.org/en/index

Demonstrates using a filter expression with the `instance` function to retrieve data based on a value selected from a previous question. The `${participant}` placeholder refers to the selected value.

```XLSForm
instance('participants')/root/item[name=${participant}]
```

--------------------------------

### Styling Prompts with Markdown in XLSForm

Source: https://xlsform.org/en/index

Learn how to use Markdown syntax within XLSForm to style text prompts for emphasis, links, headers, and special characters. This styling is supported in ODK Collect and Enketo.

```XLSForm Markdown
Markdown support in XLSForm allows for increased emphasis through bold and italics, different-sized headers, various fonts and colors, and clickable web links in ODK Collect 1.4.9 and Enketo.
  * _emphasize_ words by wrapping them inside `_` or `*`
  * **strongly emphasize** words by wrapping them inside `__` or `**`
  * add a link by using `[name of link](url)`
  * add various sized headers by prepending # (biggest) to ###### (smallest) to header text
  * style text for color or font with span tags (e.g., `<span style="color:#f58a1f">`orange`</span>`, `<span style="color:red; font-family:cursive">`red and cursive`</span>`)
  * add a line break where you want it with Ctrl-Enter or Ctrl-Alt-Enter (may be a different key combination for some spreadsheet software)
  * add your favorite emojis 😍📋😍!
  * use superscript with the `<sup>` tag (e.g. `100 m<sup>2</sup>` turns into 100 m2)
  * use subscript with the `<sub>` tag (e.g. `H<sub>2</sub>O` turns into H2O)
  * use the `` character before `#`, `*`, `_`, and `` to prevent special styling effects from being triggered by these characters
```

--------------------------------

### Implement Select One Question in XLSForm

Source: https://xlsform.org/en/index

Shows how to create a single-choice question (`select_one`) in XLSForm. It details the structure for both the survey worksheet and the choices worksheet, ensuring the `list name` matches.

```XLSForm
type | name | label
---|---|---
select_one yes_no | likes_pizza | Do you like pizza?

list name | name | label
---|---|---
yes_no | yes | Yes
yes_no | no | No
```

--------------------------------

### XLSForm: Select from Map Appearance

Source: https://xlsform.org/en/index

Allows select choices to be displayed on a map by adding the 'map' or 'quick map' appearance attribute. Requires a 'geometry' column in the choices sheet for the specified list name.

```XLSForm
list name | name | label | geometry
---|---|---|---
site | shofco | Shofco | 36.7965483 -1.3182517 0 0
site | gemkam | Gemkam Medical Clinic | 36.7967088 -1.3170903 0 0
```

```XLSForm
type | name | label | appearance
---|---|---|---
select_one_from_file health_facility.geojson | site | Select the health facility visited | map
```

--------------------------------

### Perform Basic Calculation (XLSForm)

Source: https://xlsform.org/en/index

This snippet demonstrates how to use the 'calculate' question type in XLSForm to perform a simple multiplication. The result is displayed to the user in a 'note' type question. The calculation is defined in the 'calculation' column.

```XLSForm
type | name | label | calculation
---|---|---|---
decimal | amount | What was the price of the meal? |
calculate | tip |   | ${amount} * 0.18
note | display | 18% tip for your meal is: ${tip} |
```

--------------------------------

### Group Questions in XLSForm

Source: https://xlsform.org/en/index

Organize related questions in an XLSForm using the 'begin_group' and 'end_group' syntax. This improves form structure for data export and analysis.

```XLSForm
type | name | label
---|---|---
begin group | respondent | Respondent
text | name | Enter the respondent’s name
text | position | Enter the respondent’s position within the school.
end group |   |    
surveychoicessettings
```

--------------------------------

### XLSForm Question Types

Source: https://xlsform.org/en/index

Lists and describes various question types supported by XLSForm. This includes data input types like integer, decimal, text, and specialized types for media, location, and calculations.

```XLSForm
Question type | Answer input
---|---
integer | Integer (i.e., whole number) input.
decimal | Decimal input.
range | Range input (including rating)
text | Free text response.
select_one [options] | Multiple choice question; only one answer can be selected.
select_multiple [options] | Multiple choice question; multiple answers can be selected.
select_one_from_file [file] | Multiple choice from file; only one answer can be selected.
select_multiple_from_file [file] | Multiple choice from file; multiple answers can be selected.
rank [options] | Rank question; order a list.
note | Display a note on the screen, takes no input. Shorthand for type=text with readonly=true.
geopoint | Collect a single GPS coordinate.
geotrace | Record a line of two or more GPS coordinates.
geoshape | Record a polygon of multiple GPS coordinates; the last point is the same as the first point.
date | Date input.
time | Time input.
dateTime | Accepts a date and a time input.
image | Take a picture or upload an image file.
audio | Take an audio recording or upload an audio file.
background-audio | Audio is recorded in the background while filling the form.
video | Take a video recording or upload a video file.
file | Generic file input (txt, pdf, xls, xlsx, doc, docx, rtf, zip)
barcode | Scan a barcode, requires the barcode scanner app to be installed.
calculate | Perform a calculation; see the Calculation section below.
acknowledge | Acknowledge prompt that sets value to "OK" if selected.
hidden | A field with no associated UI element which can be used to store a constant
xml-external | Adds a reference to an external XML data file
```

--------------------------------

### Add Regular Hints to XLSForm Questions

Source: https://xlsform.org/en/index

This snippet illustrates how to add regular hints to questions in an XLSForm. A 'hint' column is used to provide instructional text to the user, which appears alongside the question.

```XLSForm
type	name	label	hint
text	name	What is the name of this store?	Look on the signboard if the store has a signboard.
geopoint	geopoint	Collect the GPS coordinates of this store.	
```

--------------------------------

### Create Multi-Page XLSForm

Source: https://xlsform.org/en/index

Splits web forms into multiple pages using the 'pages' style. In the settings tab, set the 'style' column to 'pages'. Group questions in the survey tab and set their appearance to 'field-list'.

```XLSForm Settings
form_title | form_id | style
---|---|---
example title | example_id | pages
```

```XLSForm Survey
type | name | label | appearance
---|---|---|---
begin group | group1 |   | field-list
text | name | Respondent's name |
integer | age | Respondent's age |
text | address | Respondent's address |
end group |   |
```

--------------------------------

### XLSForm Default Values

Source: https://xlsform.org/en/index

This snippet illustrates how to set default values for questions in an XLSForm. This pre-populates answers, saving user time or indicating expected input. Defaults can be static values or dynamic calculations.

```XLSForm
type | name | label | default
---|---|---|---
date | survey_date | Survey date? | 2010-06-15
decimal | weight | Respondent's weight? (in kgs) | 51.3

type | name | label | default
---|---|---|---
date | d | Enter the date the event occurred? | today()
```

--------------------------------

### Rank Widget for Ordered Lists

Source: https://xlsform.org/en/index

The rank widget enables respondents to order a list of options. The answer is stored as a space-separated ordered list of option values. This functionality is configured similarly to multiple-choice questions.

```XLSForm
type | name | label
rank pizza_toppings | toppings | Order pizza toppings with your favorite on top

list name | name | label
pizza_toppings | cheese | Cheese
pizza_toppings | pepperoni | Pepperoni
pizza_toppings | sausage | Sausage
```

--------------------------------

### Defining Custom Namespaces in XLSForm Settings

Source: https://xlsform.org/en/index

Shows how to define multiple custom namespaces and their prefixes in the 'settings' sheet using the 'namespaces' column, enabling their use in the survey sheet for custom attributes.

```XLSForm
title | namespaces
---|---
My Form | esri="http://esri.com/xforms" enk="http://enketo.org/xforms
```

--------------------------------

### Basic Repeat Group in XLSForm

Source: https://xlsform.org/en/index

Demonstrates the fundamental structure of a repeat group in XLSForm, where a set of questions can be repeated multiple times. This includes 'begin repeat', data fields, and 'end repeat'.

```XLSForm
type | name | label
---|---|---
begin repeat | child_repeat |
text | name | Child's name
decimal | birthweight | Child's birthweight
select_one male_female | sex | Child's sex
end repeat |   |
```

--------------------------------

### Configure Audio Recording Quality

Source: https://xlsform.org/en/index

Users can configure audio recording quality for 'audio' and 'background-audio' question types using the 'quality' parameter. Accepted values include 'voice-only', 'low', and 'normal'. The 'audio' type also supports 'external' for using external recording applications.

```XLSForm
type | name | parameters
audio | animal_sound | quality=normal
```

--------------------------------

### Instance function with filter expression for barcode lookup

Source: https://xlsform.org/en/index

Shows how to use a filter expression within the `instance` function to find an item in a CSV file based on a scanned barcode value. The `${barcode_id}` placeholder represents the scanned value.

```XLSForm
instance('participants')/root/item[name=${barcode_id}]
```

--------------------------------

### XLSForm: Multiple Choice from File (CSV, XML, GeoJSON)

Source: https://xlsform.org/en/index

Enables using external files (CSV, XML, GeoJSON) for multiple-choice options, improving manageability and reusability. Supports specifying columns for CSV and requires specific structures for XML and GeoJSON.

```XLSForm
type | name | label | choice_filter
---|---|---|---
select_multiple_from_file country.csv | liv | In which countries did you live? |
select_one_from_file countries.xml | cou | In which country do you live now? |
select_one_from_file cities.xml | cit | What is the closest city? | country=${cou}
```

```CSV
name,label
value1,Label 1
value2,Label 2
```

```XML
<root>
  <item>
    <name>value1</name>
    <label>Label 1</label>
  </item>
  <item>
    <name>value2</name>
    <label>Label 2</label>
  </item>
</root>
```

```GeoJSON
{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "id": "value1",
      "properties": {
        "title": "Label 1"
      },
      "geometry": {
        "type": "Point",
        "coordinates": [0, 0]
      }
    }
  ]
}
```

--------------------------------

### Adding Attributes with 'attribute::' Prefix in XLSForm

Source: https://xlsform.org/en/index

Demonstrates adding attributes to the main instance element of the XForm output using the 'attribute::' column prefix in the settings sheet.

```XLSForm
title | attribute::xyz
---|---
My Form | 1234
```

--------------------------------

### XLSForm Settings Worksheet Configuration

Source: https://xlsform.org/en/index

This snippet illustrates the structure and key fields of the settings worksheet in XLSForm, which is crucial for defining form metadata like title, ID, version, and submission behavior. It also covers optional settings for localization and encryption.

```XLSForm
form_title | form_id | version | instance_name | default_language | public_key
---|---|---|---|---|---
Example | ex_id | 2017021501 | concat(${firstname}, ' ', ${lastname}) | English (en) | IIBIjANBg…
```

--------------------------------

### Search Expression: All Distinct Rows

Source: https://xlsform.org/en/index

Demonstrates the basic `search()` expression to include all distinct rows from a specified CSV file as choices for a select question.

```XLSForm
search('csvName')
```

--------------------------------

### XLSForm Media Inclusion

Source: https://xlsform.org/en/index

This snippet shows how to include media files such as images, videos, or audio in an XLSForm. Media files should be placed in a specific folder on the mobile device and referenced by their exact filename in the 'media' column.

```XLSForm
type | name | label | image | video
---|---|---|---|---
note | media_example | Media example | example.jpg | example.mp4
```

--------------------------------

### Repeat Group with Label and Summary in XLSForm

Source: https://xlsform.org/en/index

Shows how to define a label for a repeat group, which is used as a title for the block of questions. It also illustrates how the label of the first group within a repeat is used to summarize each instance of the repeat.

```XLSForm
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 |   |
```

--------------------------------

### XLSForm: Relevance for Select One Question

Source: https://xlsform.org/en/index

This snippet illustrates how to control the appearance of a question based on the answer to a previous 'select_one' question. The 'relevant' column uses the ${variable_name} syntax to reference previous answers.

```XLSForm
type | name | label | relevant
---|---|---|---
select_one yes_no | likes_pizza | Do you like pizza? |
select_multiple pizza_toppings or_other | favorite_topping | Favorite toppings | ${likes_pizza} = 'yes'
```

--------------------------------

### Adding Namespaced Attributes with 'attribute::' Prefix in XLSForm

Source: https://xlsform.org/en/index

Shows how to combine the 'attribute::' prefix with custom namespaces to add namespaced attributes to the XForm output's main instance element.

```XLSForm
title | attribute::abc:xyz
---|---
My Form | 1234
```

--------------------------------

### Set Instance Name in XLSForm

Source: https://xlsform.org/en/index

Defines a unique name for each form submission using user-entered data. Add an 'instance_name' column to the settings worksheet and provide an expression referencing survey fields.

```XLSForm Settings
instance_name
---
```

--------------------------------

### Reproducible Randomization with Seed in XLSForm

Source: https://xlsform.org/en/index

To ensure reproducible randomization of choices in XLSForm, provide an explicit 'seed' value in the 'parameters' column. This is often combined with a calculation to generate a unique seed.

```XLSForm
type | parameters | name | label | calculation
---|---|---|---|---
calculate |   | sd |   | once(decimal-date-time(now()))
select_one toppings | randomize=true, seed=${sd} | top | Favorite? |    
surveychoicessettings |   |    
```

--------------------------------

### Calculate and Display Fahrenheit and Kelvin (XLSForm)

Source: https://xlsform.org/en/index

This snippet illustrates using a single trigger ('${temp}') to update multiple calculations. One calculation ('temp_F') is displayed to the user in a 'readonly' text field, while another ('temp_K') is a hidden 'calculate' type. Both are dependent on the 'temp' integer input.

```XLSForm
type | name | label | calculation | trigger | readonly
---|---|---|---|---|---
integer | temp | Enter temperature in Celsius |   |   |
dateTime | temp_ts |   | now() | ${temp} |
text | temp_F | Temperature in Fahrenheit | 32 + 1.8 * ${temp} | ${temp} | true
calculate | temp_K |   | 273.15 + ${temp} | ${temp} |
```

--------------------------------

### Collect All Metadata Types in XLSForm

Source: https://xlsform.org/en/index

This snippet demonstrates how to include various metadata collection types in an XLSForm. These fields are automatically captured by the device and do not appear on the user interface but are visible in the submitted data.

```XLSForm
type	name	label	parameters
start	start		
end	end		
today	today		
deviceid	deviceid		
phonenumber	phonenumber		
username	username		
email	email		
audit	audit		[optional, see below]
```

--------------------------------

### Specify Alternative Submission URL in XLSForm

Source: https://xlsform.org/en/index

Allows specifying a custom server URL for form submissions. The 'submission_url' column in the settings worksheet must contain the full URL, including the path. If omitted, submissions go to the default provider's destination.

```XLSForm Settings
submission_url
---
```

--------------------------------

### XLSForm Choices Worksheet Columns

Source: https://xlsform.org/en/index

Details the mandatory columns for the 'choices' worksheet in XLSForm: 'list name', 'name', and 'label'. This section explains how these columns are used to define answer options for select questions.

```XLSForm
list_name | name | label
---|---|---
gender | transgender | Transgender
gender | female | Female
gender | male | Male
gender | other | Other
```

--------------------------------

### Image Upload with Max Pixels

Source: https://xlsform.org/en/index

The image question type allows users to upload image files. The 'max-pixels' parameter can be used to automatically resize uploaded images, ensuring they do not exceed a specified pixel dimension on the largest side.

```XLSForm
type | name | label | parameters
image | img | Upload an image | max-pixels=1000
```

--------------------------------

### Configure Encrypted XLSForm

Source: https://xlsform.org/en/index

Enables encryption for finalized records in XLSForms to ensure data privacy during storage and transport. Requires adding a 'public_key' column to the settings worksheet with a base64-encoded RSA public key.

```XLSForm Settings
form_id | public_key
---|---
mysurvey | IIBIjANBgklawWEserewrwesgdreewrwe32serfserfewrwerewtwer23sgfrqjwerk3423432…
```

--------------------------------

### XLSForm: Relevance for Select Multiple with 'Other'

Source: https://xlsform.org/en/index

This snippet shows how to display a free-text 'other' field when 'other' is selected in a 'select_multiple' question. It uses the 'selected()' function and requires 'other' to be defined as a choice.

```XLSForm
type | name | label | relevant
---|---|---|---
select_multiple pizza_toppings | favorite_toppings | What are your favorite pizza toppings? |
text | favorite_toppings_other | What other toppings do you like? | selected(${favorite_toppings}, 'other')
```

--------------------------------

### Randomize Choices in XLSForm

Source: https://xlsform.org/en/index

For questions with a list of choices, you can randomize the order displayed to users by adding 'randomize=true' to the 'parameters' column. This enhances survey engagement.

```XLSForm
type | parameters | name | label
---|---|---|---
select_one toppings | randomize=true | top | Favorite? 
surveychoicessettings |    
```

--------------------------------

### XLSForm Survey Worksheet Columns

Source: https://xlsform.org/en/index

Defines the mandatory columns for the 'survey' worksheet in XLSForm: 'type', 'name', and 'label'. It explains the purpose of each column in defining form questions and their properties.

```XLSForm
type | name | label
---|---|---
today | today |
select_one gender | gender | Respondent's gender?
integer | age | Respondent's age?
```

--------------------------------

### Allow Duplicate Choice Names in XLSForm

Source: https://xlsform.org/en/index

Explains how to handle duplicate choice names in XLSForm by using the `allow_choice_duplicates` setting. This is useful in scenarios like cascading selects where duplicate names might occur but are differentiated by context.

```XLSForm
allow_choice_duplicates
---
yes
```

--------------------------------

### Specify GPS Capture Accuracy in XLSForm

Source: https://xlsform.org/en/index

Explains how to set target accuracy for GPS capture using `capture-accuracy` and `warning-accuracy` parameters for `geopoint` questions in XLSForm. This allows control over when GPS data is recorded and when warnings are displayed.

```XLSForm
type | name | label | parameters
---|---|---|---
geopoint | store_gps | Collect the GPS coordinates of this store. | capture-accuracy=10 warning-accuracy=10
```

--------------------------------

### Conditional Repeats in XLSForm

Source: https://xlsform.org/en/index

Shows how to control the appearance of a repeat group based on a condition defined in the 'relevant' column. The repeat questions are only presented if the specified condition is met.

```XLSForm
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 |   |   |
```

--------------------------------

### Pull Data from CSV using pulldata()

Source: https://xlsform.org/en/index

This snippet demonstrates how to use the `pulldata()` function in an XLSForm to retrieve specific data from a CSV file. It requires a CSV file with a unique identifier column (ending in `_key`) and specifies the CSV file name, the column to retrieve, the key column name, and the key value to match.

```XLSForm
type | name | label | calculation
calculate | fruit |   | pulldata('fruits', 'name', 'name_key', 'mango')
note | note_fruit | The fruit ${fruit} pulled from csv. |    
```

--------------------------------

### XLSForm: Cascading Selects with choice_filter

Source: https://xlsform.org/en/index

Enables filtering options in subsequent select questions based on previous selections. Requires a 'choice_filter' column in the survey worksheet to define the filtering logic.

```XLSForm
type | name | label
---|---|---
select_one country | country | Country
select_one state | state | State
select_one city | city | City
```

```XLSForm
list name | name | label | country
---|---|---|---
states | state1 | State A | country1
states | state2 | State B | country1
states | state3 | State C | country2
```

```XLSForm
list name | name | label | state
---|---|---|---
cities | city1 | City X | state1
cities | city2 | City Y | state1
cities | city3 | City Z | state2
```

--------------------------------

### Mark Questions as Required in XLSForm

Source: https://xlsform.org/en/index

To make questions mandatory in an XLSForm, add a 'required' column to your survey worksheet and mark the relevant questions with 'yes'. Users cannot proceed or submit the form without answering these questions.

```XLSForm
type | name | label | constraint | required
---|---|---|---|---
integer | age | How old are you? | . <= 150 | yes
surveychoicessettings |   |    
```

--------------------------------

### Dynamic Repeat Count in XLSForm

Source: https://xlsform.org/en/index

Demonstrates how to set the repeat count dynamically based on user input from another field. The number of repeats generated is determined by the value entered in a specified field.

```XLSForm
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 |
end repeat |   |   |
```

--------------------------------

### XLSForm: 'Other' Choice Shortcut

Source: https://xlsform.org/en/index

Provides a shortcut for multiple-choice questions to include an 'other' option. Appending 'or_other' to the select list name in the survey sheet automatically adds this functionality.

```XLSForm
type | name | label
---|---|---
select_multiple pizza_toppings or_other | favorite_topping | What are your favorite pizza toppings?
```

```XLSForm
list name | name | label
---|---|---
pizza_toppings | cheese | Cheese
pizza_toppings | pepperoni | Pepperoni
pizza_toppings | sausage | Sausage
```

--------------------------------

### XLSForm: Integer Constraint for Age

Source: https://xlsform.org/en/index

This snippet demonstrates how to set a constraint for an integer field to ensure the entered value is within a valid range. The constraint '. <= 150' ensures the age is not greater than 150.

```XLSForm
type | name | label | constraint
---|---|---|---
integer | age | How old are you? | . <= 150
```

--------------------------------

### Specify Custom Labels/Values in Select Questions

Source: https://xlsform.org/en/index

Allows users to define custom column names for 'name' and 'label' in select questions when using external CSV, XML, or GeoJSON files. This is achieved by adding a 'parameters' column to the survey sheet with 'value=' and 'label=' arguments.

```XLSForm
type | name | label | parameters
select_multiple_from_file country.csv | liv | In which countries did you live? | value=ccode
select_one_from_file countries.xml | cou | In which country do you live now? | label=cname
select_one_from_file households.csv | hh | Select household number | value=housenum label=housename
```

--------------------------------

### XLSForm Multiple Language Support

Source: https://xlsform.org/en/index

This snippet demonstrates how to add multiple languages to an XLSForm. By appending '::language (code)' to column headers like 'label' or 'hint', forms can support different languages. A default language can also be specified in the settings sheet.

```XLSForm
type | name | label::English (en) | label::Español (es) | constraint
---|---|---|---|---
integer | age | How old are you? | ¿Cuántos años tienes? | . <= 150

type | name | hint::English (en) | hint::Dutch (nl) | image::English (en) | image::Dutch (nl)
---|---|---|---|---
surveychoicessettings |   |    

form_id | version | default_language
---|---|---
test_form | 101 | French (fr)
```

--------------------------------

### Skip Questions Using Relevant Attribute in XLSForm

Source: https://xlsform.org/en/index

Implement conditional logic in XLSForms to skip groups of questions based on previous answers. Use the 'relevant' attribute on a group to define the condition for its appearance.

```XLSForm
type | name | label | relevant
---|---|---|---
integer | age | How old are you? |
begin group | child | Child | ${age} <= 5
integer | muac | Record this child’s mid-upper arm circumference. |
select_one yes_no | mrdt | Is the child’s rapid diagnostic test positive? |
end group |   |   |    
surveychoicessettings |    
```

--------------------------------

### XLSForm Appearance Attributes

Source: https://xlsform.org/en/index

This snippet lists various appearance attributes that can be used in XLSForm to modify how questions are presented to users. These attributes affect text input, select choices, dates, and group displays, with some being client-specific (web or mobile).

```XLSForm
Appearance attribute | Question type | Description
---|---|---
multiline | text | Best if used with web clients, makes the text box multiple lines long.
minimal | select_one, select_multiple | Answer choices appear in a pull-down menu.
quick | select_one | Relevant for mobile clients only, this attribute auto-advances the form to the next question after an answer is selected.
no-calendar | date | For mobile devices only, used to suppress the calendar.
month-year | date | Select a month and year only for the date.
year | date | Select only a year for the date.
horizontal-compact | select_one, select_multiple | For web clients only, this displays the answer choices horizontally.
horizontal | select_one, select_multiple | For web clients only, this displays the answer choices horizontally, but in columns.
likert | select_one | Best if used with web clients, makes the answer choices appear as a Likert scale.
compact | select_one, select_multiple | Displays answer choices side by side with minimal padding and without radio buttons or checkboxes. Particularly useful with image choices.
quickcompact | select_one | Same as previous, but auto-advances to the next question (in mobile clients only).
field-list | groups | Entire group of questions appear on one screen (for mobile clients only).
label | select_one, select_multiple | Displays answer choice labels (and not inputs).
list-nolabel | select_one, select_multiple | Used in conjunction with the **label** attribute above, displays the answer inputs without the labels (make sure to put **label** and **list-nolabel** fields inside a group with **field-list** attribute if using mobile client).
table-list | groups | An easier way to achieve the same appearance as above, apply this attribute to the entire group of questions (might slow down the form a bit).
signature | image | Allows you to trace your signature into your form (mobile clients only).
draw | image | Allows you to sketch a drawing with your finger on the mobile device screen.
map, quick map | select_one, select_one_from_file | Allows a user to select a choice from many features on a map
```

--------------------------------

### XLSForm Read-Only Fields

Source: https://xlsform.org/en/index

This snippet demonstrates how to create read-only fields in an XLSForm. These fields cannot be edited by the user and can be combined with default values to display information.

```XLSForm
type | name | label | read_only | default
---|---|---|---|---
integer | num | Please patient is: | yes | 5
```
Tokens:
Raw