XLSForm tutorial: Your first form

ODK forms are created using spreadsheets by following the rules of a standard called XLSForm.

Using spreadsheet software to design forms is helpful because you can see a lot of information about your form on one screen, you can share your form definition with anyone, and you can use powerful spreadsheet features (formulas, drag to fill, copy and paste, automatic highlighting, and more).

Anyone who can use spreadsheet software can create a form! In less than 20 minutes, you'll build a school census survey.

If you'd like a sneak peek at what the survey looks like for data collectors, try this web preview.

See also

• 🇫🇷 French translation

Goals

In this tutorial, you'll:

• Design a short form using a variety of question types

• Use the major XLSForm logic building blocks

• Learn next steps to grow your skills

Ready to begin your XLSForm journey? Let's go!

Open the XLSForm template

You can use any spreadsheet software to create and update an XLSForm: Excel, Google Sheets, OpenOffice Calc, and more. Pick your favorite and open the XLSForm template:

• Google Sheet (use File > Make a copy)

• Microsoft Excel (XLSX) file

Add a required text question

1. In the survey sheet, use the dropdown in the type column to select text. This will create a text question that the user can answer.

2. In the name column, put the name of the field that will be used in analysis. Let's use school_name

3. In the label column, put the label that you want the data collector to see: What is the school's name?

4. In the required column, put yes to indicate that the question must be answered.

Add a required image question

In the row below the school name question, let's add a required question to capture a picture of the school.

1. In the type column, put image

2. In the name column, put school_front_picture

3. In the label column, put Take a picture of ${school_name}

4. Let's also add a hint to give data collectors more information about what we want to capture. In the hint column, put Include the front door

5. In the required column, put yes

6. In the parameters column, put max-pixels=1024 to limit the length of captured image to 1024 pixels.

Add an optional location question

1. In the type column, put geopoint

2. In the name column, put school_location

3. In the label column, put What is ${school_name}'s location?

Add an integer question that only allows positive values

1. In the type column, put integer

2. In the name column, put student_count

3. In the label column, put How many students are enrolled?

4. In the required column, put yes

5. Let's make sure that only positive student counts are allowed. In the constraint column, put . > 0 to say that the entered value (.) must be greater than 0.

6. Let's give the data collector feedback if they enter a value that's not allowed. In the constraint_message column, put Must be a positive number

Add a question for selecting multiple options

Let's add a question that asks the data collector what grades are taught at the school. We'll show three grade choices (primary, middle, high), and let the data collector select one or more.

1. Go to the choices sheet. This sheet is used to specify lists of choices that will be used in select questions.

2. Add a choice for primary grades:

   1. In the list_name column, put the name of the list that all of our choices will belong to: grades

   2. In the name column, put the value that will be stored in the data that we will analyze: primary

   3. In the label column, put the text that data collectors will see for the choice: Primary (1-5)

3. Add a choice for middle grades:

   1. In the list_name column, put grades to put this choice in the same list as above.

   2. In the name column, put middle

   3. In the label column, put Middle (6-8)

4. Add a choice for high grades:

   1. In the list_name column, put grades to put this choice in the same list as above.

   2. In the name column, put high

   3. In the label column, put High (9-12)

5. Go back to the survey sheet.

6. In the row after the student_count question, put select_multiple grades in the type column.

   Note

   Your spreadsheet software will show a validation warning because it doesn't know about your list name (grades). That's expected for select questions and can be safely ignored.

7. In the name column, put grades_taught

8. In the label column, put What grades are taught?

9. In the required column, put yes

10. Let's make the choices appear horizontally next to each other. In the appearance column, put columns

Add a question that is shown depending on a previous answer

1. In the type column, put text

2. In the name column, put advanced_math

3. In the label column, put What is the most advanced math class available?

4. In the required column, put yes

5. Let's make this question appear only if the school teaches high school grades. In the relevant column, put selected(${grades_taught}, 'high')

Specify the form's title and ID

1. Go to the settings sheet.

2. In the form_title column, put a title that people who interact with this form should see: Verdant school district census 2023

3. In the form_id column, put an ID that uniquely identifies this form: school_census_23

4. In the instance_name column, put a name that identifies each submission of this form: ${school_name}

Try your form in Central

Note

Don't yet have an ODK Central server? 1. Get a Central server or use XLSForm Online to try your form in a web browser.

1. Save or download your form as an XLSX file.

2. Log into your Central server.

3. If you don't already have a Project, create one and give it a name.

4. Click on the New button next to Forms.

5. Drag and drop your XLSX file onto the file uploader.

   

6. Click the Preview button to see your form in your web browser 🎉

   

7. To see the form in the ODK Collect mobile app, click on the Testing tab and scan the QR code with Collect.

Your turn

1. Can you make the location question required?

2. Can you make the grade level question show only if more than 100 students are enrolled?

3. Can you show the grade level options vertically rather than horizontally? (Hint: The vertical layout is the default appearance for selects)

Next steps

Congratulations! You've now designed a form that uses most of the XLSForm building blocks. Below are more resources to grow your skills.

• Deepen your understanding

  • XLSForm introduction

  • Question types

  • Required questions

  • Constraints on user input

  • Selects

  • Relevance

• Broaden your knowledge

  • Groups of questions

  • Form Styling

  • Form language

  • Form Operators and Functions

• ODK Collect introduction

Did this page help you?

Selecting an option will open a 1-question survey

👍 Yes 👎 No