Ordering multiple collections (r9)

Collections are sets of lists, options, or spreadsheets. Setlists and question widgets build their options from these collections. Unless multiple list calls or headers are used, a question or list widget only has a single collection. An order tag applied to the widget will order the options within this single collection. However, when multiple collections are present, this behavior changes.

Syntax and creation

A closed-end question widget has a single collection of options by default. This default collection is created either via a single listcall or inline options attached the question. There are two different ways a widget can have multiple collections. 

'collection header' decorator

First, if multiple collection headers are used, each will generate its own collection. Collection headers are indicated by placing the collection header decorator (alias header) next to the list item. In the example below, MYLIST has two collections: the first is the set of options after header '100', and the second is the set of options after header '200'.

setlist: MYLIST
100. List Header 1 {collection header: y}
1. Option
2. Option
#. etc
200. List Header 2 {collection header: y}
3. Option
4. Option
#. etc

Listcall tags

Second, listcall tags (optsfrom, rowsfrom, etc.) also create collections. Following this logical construction, each additional *from would create a new collection. Here, MYLIST2 has the single option '20' in its default collection, and it also has the collection of elements from the optsfrom tag, ANOTHER_LIST.

setlist: ANOTHER_LIST
10. New option 1
11. New option 2
12. New option 3

setlist: MYLIST2
20. An option added to those new options
optsfrom: ANOTHER_LIST

Order

Locally defined options, headers, and listcalls can all be combined to create different collections within a single widget. Options will be displayed in the order they are programmed unless the order tag is used to explicitly modify the placement, or additional collection decorators are added to specify the placement. 

Natural order

Consider the following example. Notice the placement of each option and collection. The list FOODANDDRINK displays options 13, 14, and 15 within the 'Condiments' collection because it is called in with optsfrom: FOOD. Then, option 20 will appear as the first option in the question's list because it is programmed inline and placed before the optsfrom listcall.

See demo See code Restart demo

Tags to modify order

The fundamentals of randomizing and controlling option order should be fully understood before attempting to apply those rules and tags to the complexity of multiple collection headers. To review the basics of anchors, randomization, alphabetical order, reverse order, and order positioning, see Randomizing and controlling option order.

An order tag applied to a widget with a single collection will define the order for all the options within this single collection, regardless of whether the tag is placed on a setlist or the question widget itself. However, when multiple collections are present, this behavior changes depending on the placement of the tag. In the context of multiple collections, order can be defined on the question widget, on the setlist, or as a decorator on the collection header.

To summarize, multiple headers and *from tags create multiple collections. This allows for syntax which lets the Survey Programmer (SP) control both the overall collection ordering, as well as the sub-ordering of options within a collection. It is therefore possible to define the order on the widget (which extends to all options across all collections), and then override that order by placing a different tag on a collection's header. 

Decorators to modify order

Specific decorators can also be used to label and place a list item in a different collection from that of where it is programmed. If a decorator is added, the item will be placed in the collection that is named after the colon. The item will be displayed on screen in the order it is found in the SPL (survey programming language). The decorators below are synonyms and can be used interchangeably. 

set list: THINGS
100. reddish {collection header: y}
1. red
200. blueish {collection header: y}
3. blue
300. other   {collection header: y}
2. orange    {collection: 100 }
4. green     {parent: 200}
7. salmon    {category: 100}
9. other

Examples

On a setlist

Consider a common client request. The client wants to randomize the order the groups are shown and the order of items within each group, but keep "Other" last. The randomize: y tag placed at the top of the list (before the first header) will handle the randomization of both the groups and the individual items. Then, the inline {anchor: y} decorator on each Other option keeps the "Other orange" and "Other apple" anchored last within their respective collection. Please scroll vertically to see the full demo.

See demo See code Restart demo

On a collection header as a decorator

Let's say the client wants the order of the groups randomized, but the items within each group to not be randomized. In the below example, the overall list utilizes randomize: y to randomize the collections. The tag would also randomize the options within the collections by default, so we need to include the decorator {order: (*)} on each header to indicate non-randomization. 

The decorators define the order of the options associated with each heading. Therefore, whether options from HEADING A, HEADING B, or HEADING C come first, second, or third will vary, but the option order within each heading group will always be the same.

See demo See code Restart demo

Anchoring the final collection last

In this example, the list's order tag order: [*],$ includes the dollar sign, which indicates the final item should be anchored last. Note that this anchors the final collection last, and not the final option in that collection. The '[*]' portion of the syntax still randomizes both the collections and the items within the collections.

See demo See code Restart demo

Alphabetical

Collection headers support the use of alphabetize: y, as well as order: AtoZ(*) and order: ZtoA(*). Just like the order tag, the alphabetize tag can define the relationship of all collections if placed on the question widget itself, or define the placement of options within a single collection by being placed directly on the collection header.

When the tag is placed directly on the question widget, both the collection headers and their individual elements are alphabetized. In Q11, the headers 'Large Dogs', 'Medium Dogs', and 'Small Dogs' are alphabetized, and all options in each group are alphabetized within their group. Please scroll vertically to see the full demo.

See demo See code Restart demo

When the tag is used as a decorator and placed directly on the collection header, only the elements in the group are alphabetized. In Q10, the elements in groups 'Small Dogs', 'Medium Dogs', and 'Large Dogs' will be alphabetized within their respective groupings, but the collection headers will remain in the order they are currently defined. Please scroll vertically to see the full demo.

See demo See code Restart demo

Notice that we have used a few different spellings of the collection header decorator here as well.

Explicit ordering

Ordering positions of option elements and collections

For questions with single collections, "explicit ordering" refers to the position of the elements themselves, not their IDs. However, in multiple collections, explicit ordering refers to the position of the collections when used on the question widget, a setlist, or when combining multiple collections. 

In the example below, all collections are in a single setlist. The Dogs and Cats collections each have explicit ordering with the order decorator on their collection headers. Meanwhile, the order tag on the setlist is describing the relationship of the three collections. The first two are randomized, and the last, 'Other', is always last. 

setlist: ANIMALS
order: ([1,2],3)
100. Dogs {order: (3,1,2)}{collection header: y}
1. Pug
2. Dalmatian
3. Boxer
200. Cats {order: (2,1,3)}{collection header: y}
4. Bengal
5. Serval
6. Siamese
300. Other
7. Guinea Pig

Order modifiers with curly and square brackets

Ordering from collections defined with listcalls utilize square brackets versus the curly braces in the above example for collections defined with headers. A list with multiple collections created with a mixture of headers and listcalls (including when referencing a spreadsheet) would therefore contain order modifiers with both types of brackets. Notice in the example below, optsfrom: OTHER_ANIMALS uses square brackets around the order decorator. 

setlist: OTHER_ANIMALS
7. Orangutan
8. Lemur

setlist: ANIMALS
order: ([1,2],3)
100 Dogs {order: (3,2,1)}{collection header: y}
1. Pug
2. Dalmatian
3. Boxer
200. Cats {order: (2,1,3)}{collection header: y}
4. Bengal
5. Serval
6. Siamese
optsfrom: OTHER_ANIMALS [order: 2,1]

Using a variable-based order string

If you need to customize an order string, you could leverage the power of programming a custom variable that creates a text string, which could then be referenced in the order decorator. In the example below we have four options in each collection. We want to randomize the positions for the four options (e.g., 1,3,4,2 or 3,4,1,2, etc.). We establish this randomized order at 'QORDER1TO4' and then call this text string in to replace '$QORDER1TO4' with the new value. We can imagine the decorator becoming '{order: 1,3,4,2}' and organizing the items within each collection in this explicit order.

See demo See code Restart demo