Multi-page tables - page_every & page_by_group

Occasionally, surveys call for tables with a large number of rows, making them unwieldy or difficult to view on a single page. The page_every and page_by_group tags alleviate this by automatically splitting the table rows across multiple survey pages.

Use page_every to display a set number of rows on each page. This tag accepts a number representing the max number of rows to show per page. 

Use the page_by_group tag for finer control over exactly which rows should be shown on which page. Add an option data decorator to each item in the row list that contains a word, number, or letter to group the rows together.

Syntax

In most scenarios, Survey Programmers (SPs) should be able to use "simple tables" (e.g., type: radio table) with page_every and page_by_group. For more complicated tables (e.g., multi-column tables with varying question types, tables with validation or dynamic value tags, vscales), SPs should use the start table widget.

# Table using page_every tag
TableID. Question Text
instructions: Any additional instructions needed (optional).
type: radiotable, checkboxtable, etc.
optsfrom: OPTSLIST
rowsfrom: ROWSLIST
page every: N   # Where N is an integer equaling the MAX number of rows to show per page

# Table using page_by_group tag
set list: ROW_LIST
1. A    {{ GROUP_TITLE: 1 }}
2. B    {{ GROUP_TITLE: 1 }}
3. C    {{ GROUP_TITLE: 2 }}
4. D    {{ GROUP_TITLE: 2 }}
5. E    {{ GROUP_TITLE: N }}

TableID. Question Text
instructions: Any additional instructions needed (optional).
type: radio table, checkbox table, etc.
optsfrom: OPTSLIST
rowsfrom: ROW_LIST
page by group: [GROUP_TITLE]

Examples

page_every

Even distribution

The page_every tag is designed to allow the survey creator to specify a max number of rows displayed per page of the table. With page_every: N, the system determines how many rows qualify to be shown and then makes a determination for how many rows to show on each page. This number will be less than or equal to the number specified at the tag.

All formatting rules applied to the table widget such as intro, instructions, headings, etc. will be applied to the tables rendered on each page.

See demo See code Restart demo

Notice that page_every permits the order or flatorder tags to be applied to lists used within the table.

Uneven distribution part 1

The page_every tag accepts a number that does not divide evenly into the total number of rows. In this case, the system will attempt to make the number of rows per page as even as possible, rather than leave a smaller remainder for the final page.

In the following example, we utilize a list of the United States as our rows. The sheet system.states is 51 items long (option 51 is Washington D.C.; option 52 is Other and has been excluded). With a page_every input of 20, the system opts for 17 rows per page, rather than 20 on the first two pages and 11 on the third page.

See demo See code Restart demo

17 rows per page is still a large table to navigate. Let's try fewer rows per page, resulting in more pages.

Uneven distribution part 2

In this example, we're using the same 51-item list as before, but with page_every: 10 instead of 20. Rather than five pages of 10 rows and just one row on the last page, the number of rows in each page is: 9, 9, 9, 8, 8, 8.

See demo See code Restart demo

page_by_group

When the rows to show on each page are known ahead of time, the page_by_group tag can be used to manually assign each row to the page it should appear on. The page_by_group tag allows us to assign group IDs within option data decorators at the list level. When the option data decorator's label is used as the value for page_by_group, the system uses this value to group each row into the pages to show. In other words, there will be a new page for each unique value found within the option data decorators.

Again, all formatting rules applied to the table widget such as intro, instructions, headings, etc. will be applied to the tables rendered on each page.

See demo See code Restart demo

Collection headers and page_every

When the table rows list has collection headers, page_every will treat the collection headers the same as regular row items when it calculates how many items to display per page. For example, given the following list: 

setlist: MYLIST
_A. Group A
1. Row A1
2. Row A2
3. Row A3
_B. Group B
4. Row B4
5. Row B5
6. Row B6
_C. Group C
7. Row C7
8. Row C8
9. Row C9

There are technically twelve items in the list in total. So, if you use page_every: 4, it will split the table into three pages: you will see Group A and its three items on the first page, then Group B, then Group C on the third page. If you use page_every: 6, the first page will show Group A through Row B4, including the Group B header. Then, the second page will have Row B5  through Row C9. As shown in examples above, the exact number of rows displayed per page can vary if the page_every value doesn't divide evenly into the number of rows, so use caution and test thoroughly.

In general, it is recommended to avoid using collection headers with page_every. There are a couple of alternate solutions:

1. Make a new list with all header rows removed from the list. Also, list out all options locally at the new list, instead of using references to other lists as in optsfrom: ANOTHER_LIST.
2. Use the [header: n] decorator at the rowsfrom tag to remove headers at the table. Also, if the list is randomized, you may use the [flatorder: [*]] or [flatorder: (*)] decorators to flatten the options (re-randomized or left as originally randomized) down to the same hierarchical level.

In the example below, we do the second, short-hand approach:

See demo See code Restart demo