Survey123 Tricks of the Trade: Groups, Grids and Pages

12784
19
11-20-2019 01:17 PM
Esri Frequent Contributor
10 19 12.8K

In this blog post I will explore a handful of XLSForm techniques to help you better control the organization and layout of questions within a form. You will learn about groups, grids and pages, but also other tricks to refine the size, placement and look and feel of questions within your form.

--------------Groups--------------


Groups: XLSForm Basics


Groups organize questions into sections, helping users more easily navigate complex forms.Our Survey123 for ArcGIS: Using Groups to split your survey into sections - YouTube  video is about the quickest way there is to learn the basics of XLSForm groups. I strongly suggest you watch it, it's only 2 minutes long.

As described in the video, you can create sections in your form by enclosing a set of questions within a begin group/end group block. You need to specify a value in the name column of the begin group row, and this name must be unique. If it helps you navigate the spreadsheet, you can also add a name to the end group row, but it is not compulsory.

nametypelabel
texthh_idHousehold ID
begin grouphh_groupBasic Household Information
geopointhh_locationGPS Location
hiddenhh_location_acHorizontal Accuracy
texthh_addressAddress
end group

You can add as many groups as you like to a form, and you can nest them too: you can add groups within groups!

On occasion, you may want to display groups collapsed and let the end-user expand them if needed. This can be achieved by setting the appearance column to compact.

It is not possible to dynamically expand or collapse a group with an XLSForm expression.

Use the compact appearance to make your group appear collapsed by default.

Formatting Group Headers

Since groups are fundamentally used to help users navigate long surveys, it is important to take pride in the headers. The group headers, if formatted appropriately, can really make a big difference for people.


The font of group labels by default is a bit bigger and bolder than the labels of questions. This helps the group header stand out. Using HMTL formatting within the label column of the begin group row, you can bring your own style to the group header. For example, you can center the label in the screen, change its color, and size.

In the example to the right, the group headers have been given different background colors to help users navigate more quickly between them. Note that the first two groups, in red and blue, are collapsed but users can choose to expand them.

The Style your survey—Survey123 for ArcGIS | Documentation help topic shows the most common HTML tags that you can use to format your labels. When setting colors, you can use either their HTML code name or their hexadecimal representation. At W3Schools you can use the handy color picker for HTML colors. All the properties described in the documentation are supported in the Survey123 mobile and web apps except for the background color, which is only supported in the field app. 

The next XLSForm sample shows the syntax for defining the background color of the group header.

Body bgcolor is only supported in the field app. Webforms will ignore this property.

nametypelabel
texthh_idHousehold ID
begin grouphh_group<body bgcolor="#C00000"><font color="white">Household Information</font></body>
geopointhh_locGPS Location
hiddenhh_loc_acHorizontal Accuracy
texthh_addrAddress
end group

Dynamic Labels for your Groups

When working with labels for your groups (and questions, actually), remember that on top of the formatting syntax described above, you can also dynamically change the label content. For example, say you have a health household interview survey where we you need to capture all symptoms detected in each of the household members. You can present the symptoms group with a label that matches the name of the household member for which you are capturing the data. This could help eliminate confusion. Below is the actual example. Look how the group header in black changes depending on the household member name entered.

Check out https://community.esri.com/groups/survey123/blog/2018/11/01/understanding-dynamic-labels-in-survey12... to learn more about this technique.

Visibility of Groups


One final note on groups relates to their visibility within the survey, which is controlled through the relevant XLSForm column. If an expression written in the relevant columns evaluates to true, the group is shown, otherwise it is hidden to the user. 

A common bad practice with form design consists on repeating the same relevant statement to a large collection of consecutive questions. This slows down your survey, because the same expression needs to be evaluated again and again for each of the questions. If a sequential set of questions shares the same relevant statement, it is good practice to group them and apply the relevant expression to the begin group row only. If the group is relevant, all questions within the group will show. If the group is not relevant, all questions inside the group will be hidden. There is no need to duplicate the relevant expression again and again.

--------------Pages--------------

Introduction to Pages

Pages are particularly useful when working with large forms, helping you logically organize your questions and giving end users a sense of progress across the entire survey.


Even for smaller surveys, pages can be useful. In the example below we have a Special-Use application permit form.  I added a welcome image and text on the first page to create a cover for the form. Note that the first page does not expect any input from the user. It is just a welcome page, or cover page to the survey. Next, I organized the actual questions within my form into pages, giving each page a descriptive title at the top. As users move from page to page, a progress bar at the bottom shows how close they are to the end of the survey.

In the Survey123 field app, users can easily move through pages in the form one by one. Alternatively, a page menu lets users jump to any of the pages in the form with a simple selection. In the example shown below, the page menu helps the user jump from page 3 to 32 with just a couple of taps.

Pages: XLSForm basics

If you want to add pages into your form, firstly you need to set the style of your XLSForm to pages. This is done through the settings XLSForm worksheet as shown below.

form_titleform_idinstance_namesubmission_urlstyle
Zika Household Surveypages

Once the style is set, add one group for every page you want and set the appearance of the group to field-list. For example

nametypelabelappearance
texthh_idHousehold ID
begin grouphh_groupHousehold Informationfield-list
geopointhh_locGPS Location
hiddenhh_loc_acHorizontal Accuracy
texthh_addrAddress
end group

When working with the pages style, it is good practice to have all questions within a page. That is: make sure all your questions in the form are within an existing group with an appearance set to field-list. If you leave questions outside of a page, you will get erratic behavior across the web and field apps where a single question may appear on every page.

You can combine groups and pages. That is, you can include groups within a page. Groups do not become pages unless you set their appearance to field-list.

All the header HTML formatting tricks described for groups above, also apply to pages. The same goes for the behavior with the relevant expressions. You can hide pages by using relevant statements, however keep in mind that the behavior across the web and field app is different. In the web app, non-relevant pages will be truly hidden, you will not even see them in the page navigator controls. This will cause the total count of pages in the page navigation control to vary as pages become visible or hidden. In the case of the field app, as of version 3.7, the pages will still show in the page navigation control, but will be shown blank. This is a known issue (BUG) in the field app.

Hidden (non-relevant) pages in the field app will be shown blank. This is a known issue as of version 3.7.

--------------Grids--------------

Grids: Introduction


Typically, questions within a form are arranged to take the full width of the screen. It is possible however to arrange multiple questions side by side using custom grids (theme-grid in XLSForm jargon). This is particularly useful when you are designing a form for use on a tablet.

With this type of grid layout, you can maximize the number of questions shown within the width of screen, reducing the need for users to scroll up and down. Grids can also help you mimic more closely the look and feel of legacy paper forms. Copying the layout of paper forms is not necessarily a good idea, but in some cases achieving some level of resemblance can make nostalgic users happier.

In the example shown to the right, you can see how questions can be arranged side by side. Crafting such a survey, defining exactly the placement of questions takes some thought and trial and error, but the experience it provides to the end user is significantly better than with a regular layout. This type of design is generally put together with a specific form factor in mind. That is, you design your survey for a particular minimum screen size. If a grid design like the one shown is loaded in a smart phone, the form is not going to look right. I have seen some people creating two flavors of the same survey: one for tablets and one for smart phones.  It clearly adds an overhead during design, but if your survey questions are not going to change much it is a good thing to consider.

The theme-grid style is not supported in the web form. It is only supported in Survey123 Connect and field app.

Grids: XLSForm Basics

To arrange questions in a grid layout, you first need to set the style of your survey to theme-grid. This is done in the settings sheet of your XLSForm.

form_titleform_idinstance_namesubmission_urlstyle
My Surveytheme-grid

Once the theme-grid is set, all groups within your survey will contain questions using a four-column grid layout. You can change the number of columns in a grid by simply adding the w (as in width) property to the appearance column of your group. For example, w2 means two columns, w8 means eight columns.

nametypelabelappearance
texthh_idHousehold ID
begin grouphh_groupHousehold Informationw2
geopointhh_locGPS Location
hiddenhh_addrAddress
texthh_cityCity
texthh_zipZIP Code
end group

Unless specified otherwise, questions within a group will always take one column of the grid. In the example above, the GPS Location and Address will be placed side by side in one row, and the City and ZIP Code will complete a second row.

Using the w property for the individual questions within the group, you can choose how many columns you want each question to take. In the example below, I gave two columns (one full row, since the grid has two columns) to the GPS Location question, and another full row (two columns) to the address. I then arranged the City and ZIP Code questions side by side giving them a w1 appearance.

nametypelabelappearance
texthh_idHousehold ID
begin grouphh_groupHousehold Informationfield-list w2
geopointhh_locGPS Locationw2
hiddenhh_addrAddressw2
texthh_cityCityw1
texthh_zipZIP Codew1
end group

You will also note in the screenshot above that the Household ID question is taking the full width of the screen. That is expected. When using the theme-grid, questions outside of a group always get rendered as usual, taking the full width of the screen.

Grids: A few extra tips and things you should know

  • Survey123 Connect includes a handy XLSForm sample called Grid Style Groups. It shows some advanced techniques, including arranging repeats and geopoint questions side by side, combining pages with grids, etc.

  • Working with grid layouts gives you a lot of flexibility, but mastering it takes time and trial and error. Always test your designs on a mobile device that you are targeting to make sure things look as you expect.
  • Do not expect the grid layout, or questions within a grid, to automatically adjust to the size of the screen. If you do not give enough space to your questions, they will look ugly. For example, in practice, you can't work with more than 2 columns on a smartphone. Even when working with 2 columns you need to be careful when working on small screens: you need to keep the labels of questions and choices short and avoid question types like geopoint or dateTime which tend to take more space. Do not take this the wrong way, you can use 2 columns in a smart phone, but with caution.
  • I know I said this before, but I will say it again: the theme-grid is not supported in the webform. It is only supported in the Survey123 field app.
  • You can combine pages and grids. Simply set the style of your form as follows:

form_titleform_idinstance_namesubmission_urlstyle
My Surveytheme-grid pages

  • When using theme-grid, questions outside of a group (grid) will always take the full width of the screen.
  • If you do not define a width (w parameter) for a group, the number of columns in the grid will be four (as in w4)
  • If you do not define a width (w parameter) for a question within a group, it will default to w1.
  • Non-relevant questions will still take space in your layout. If a question is non-relevant, you will see an empty space in your grid.
  • Be careful with or_other. If you use a select question with the or_other option, your question will always take one extra cell (column). This is in anticipation that the end-user selects the 'other' choice. In that case, a new free text question appears, taking the extra space.
  • You cannot apply a width parameter to a repeat, but you can apply it to a group within a repeat.  If you want to learn how to arrange repeats side by side, have a look at the Grid Style Groups XLSForm sample in Survey123 Connect.
  • The table-list appearance does not work in combination with theme-grid or pages.
  • The body::esri:style XLSForm column can help you refine the height of questions. This can be useful, particularly when working with the theme-grid. For example, if you put a text and a geopoint question side by side, the layout will show unbalanced, because the text question by default is not as tall as a geopoint question. You can change the height of geopoint, geotrace, geoshape signature and multiline text questions. Learn more at Esri custom columns—Survey123 for ArcGIS | Documentation 

When using the body:esri:style column, keep in mind that some properties are not compatible with theme-grid. For example, borderColor is not supported (do you need border colors? If so Vote for this GeoNet idea), and repeats inside of grid style groups do not support backgroundColor either.

19 Comments
Occasional Contributor III

What is the difference between table-list and field-list for Pages? I can get field-list to work in Connect but having issue with table-list.

Esri Frequent Contributor

Hi. Both table-list and field-list are appearance values that can be applied to a group:

  • table-list is designed specifically to arrange a set of select_one questions sharing the same choice list as a grid.
  • field-list converts your group into a page, if the style setting of your XLSForm is set to pages.

The following animation shows the effect of applying table-list to a group. In this case, the group has 5 select_one questions sharing the same choice list (Minor/None, Moderate, Severe).

I can see how you got confused on this one because as of version 3.6, if you apply the table-list appearance to a group on a survey set for pages, it will be rendered as a page. This is a software defect. In other words: the table-list appearance does not work when working with pages.  This issue is logged as

ENH-000126229 Table-list appearance not working when style is set to pages and using field-list

this is tentatively scheduled for the 3.8 release, but if you really want to add a select_one grid to a survey with pages, I strongly recommend you raise the importance of this ENH via Esri Tech Support. You can open a case and tell Esri Tech Support to have your Esri Customer number attached to that ENH.

Occasional Contributor III

OK, that explains it better. The table-list I was testing didn't have select_one type questions so I can understand the error now.

Are these settings documented somewhere in a styling reference?

New Contributor III

Great post! Thanks so much. I have one question. The article says that non-relevant questions will still take up a blank space in the grid, but mine are not. Is this a change that was made? Is there a setting you can enter to force them to take up a space? I have a 2 width grid with a list of select one questions where if they answer "Action Needed" I want them to explain it to the right of the question. However the relevant question space is not reserved and all the questions are side by side. So if they answer "Action Needed" in column 2 the details question gets sent over to column 1 on the next line.

Esri Contributor

Hi Luke, questions will always be placed into a single row if they fit. Once a row has been filled, the next question will be placed onto a new row. So if the question following your non-relevant question can fit onto the previous row, it will. It then get pushed onto the next row when that question is made relevant. In your example with 2 columns you won't see any blank space in the grid because all questions occupy 1 column so they can fit anywhere.

You could achieve the result you're after by having a 3 column grid ('w2' for the select_one questions, and 'w1' for the explanation which becomes relevant when 'Action needed' is selected). In this way, your next select_one question won't fit into the gap made by your non-relevant question so is always forced onto a new row.

Hope this helps,

Brett

New Contributor III

Thanks Brett. That's very helpful. I may actually use that workaround instead of removing the relevant condition on the details questions. I did create an esri idea just in case anyone else would like the same functionality added.

 

Frequent Contributor II

The trick I use is to have a dummy field with the opposite relevant.  That way something is always there.

But I agree changing it would be great.

New Contributor III

Great post. I love pages. I have created a 7 page survey with about 50 questions. I don't like how the "next page" and "submit survey" buttons are in the exact same location. When I quickly review the pages of the survey, I accidentally submit the survey. I don't think that this is a good design. I would prefer to see a "Submit" button labeled Submit.

On a different topic, I would also like some way to have the final page present a summary of all questions answered grouped by page. I think I might be able to do that with "note" type fields, maybe.

New Contributor

Any chance the grid style theme will be supported on the web form version of Survey123? 

Esri Esteemed Contributor
New Contributor

Thanks for this informative post! How can one create a page menu, so that users can toggle between different pages? This feature is described above but there's no instruction on how to create that. For context, I am creating my survey in Survey123 Connect (desktop) and want users to fill out the survey using the web link, not necessarily the Survey123 web app.

Esri Esteemed Contributor

Hi Sana,

The page menu is automatically generated from the labels of the pages when using the field app.  There is not equivalent functionality in the web app yet.

New Contributor

I see, thank you!

by
Occasional Contributor III

if you apply the table-list appearance to a group on a survey set for pages, it will be rendered as a page. This is a software defect. In other words: the table-list appearance does not work when working with pages.  This issue is logged as

ENH-000126229 Table-list appearance not working when style is set to pages and using field-list

this is tentatively scheduled for the 3.8 release

3.10 release is out, but issue is still with us.

Any update on this?

Cheers

Stefano

Esri Esteemed Contributor

Hi Stefano,

At this point, there isn't an update.  Part of the problem is that while field-list and table-list are seperate appearances in the XLSForm, they are turned into the same keyword ('field-list') when the XForm XML is generated; resolving that ambiguity will require some additional design work.

New Contributor II

Thanks for the detailed post Ismael, which almost a year on is still super helpful  

When using the grid theme on select_multiple question, they seem to default to horizontal appearance - this can cause problems with longer labels or choice lists.  Is there a way to set the appearance of a select multiple in a grid back to the normal 'vertical' appearance?  I tried to set a height or defaultHeight style but this had no effect. 

e.g. see precipitation from the grid example below where the words in the labels are split as the options are compressed into the row:

Frequent Contributor II

For me it worked to just leave the appearance blank.  Then it went vertical.

Occasional Contributor III

Hi@Ismael Chivite,

Are grid themes supported in web browsers yet? In particular, I was thinking of using grid theme in an embedded survey in dashboard.

Regards,

Craig

New Contributor II

@CraigPoynter  Grid is not supported in web browsers yet (I just tried it). I am also curious to know if this is being planned, as it would be extremely useful.

@JamesTedrick or @IsmaelChivite Do you know if support for the grid-theme in a web form is in the production plan?

Thanks!