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. When multiple collections are present, this behavior changes.
For a review on how the order
tags work, see Randomizing and controlling option order.
Syntax and creation
A closed-end question widget has a single collection of options by default. This default collection is either created via a single listcall or inline options attached the question.
There are two different ways a widget can have multiple collections. First, if multiple collection headers are used in a widget, each will generate its own collection. Collection headers are indicated by using an underscore with an alpha-numeric ID, e.g., ' _A'. For example:
setlist: MYLIST _A. This is collection A 1. An option 2. Another option _B. This is collection B 3. Different option 4. Yet another option
MYLIST has two collections: the first is the options after header A, and the second is the options after header B.
The optsfrom
/rowsfrom
/colsfrom
listcall tags also create collections. Following this logical construction, each additional optsfrom
/rowsfrom
/colsfrom
would create a new collection.
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
MYLIST2 has a single option in its default collection, and it also has the collection of elements from the optsfrom
tag.
Note: When combining locally defined options, headers, and/or listcalls, ensure all option IDs are unique. See Creating standalone lists to review the essentials.
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.
Consider the following example. Notice the placement of each option and collection. The list FOODANDDRINK displays options 1, 2, and 3 within collection '_C' and the "Last minute option added" will appear as the first option in the list.
Multiple collections with headers can also be (carefully) combined. Q1 combines the collection of options from MYLIST along with the collection of options from MYLIST2. Considering that MYLIST already has collection headers, MYLIST2 now needs a header as well in order to separate its options from those in MYLIST. Without the new header, all options from MYLIST2 would be placed within the last collection displayed on screen, in this case, collection '_B'.
Tip! Combining multiple collections can be complex. The system will do its best to render collections appropriately and understand the order desired. For best results, test multiple times to view the various order strings rendered on screen. In the event the result is not correct, it be necessary to create a new (full) list with all options and use explicit ordering.
Order and randomization
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.
Note: For simplicity's sake, the order
tag is used in the the table below, but the behavior is the same for all tags where order can be defined, as well as their shorthand aliases (e.g., randomize
, order: reverse(*)
, order: AtoZ
, order: ZtoA
, and alphabetize
, etc.).
Tag Placement (multiple collections) | Behavior |
---|---|
On a question widget | An order tag on a widget comprised of collections describes the ordering of the collections with respect to one another, and also extends to the options within the collections. For example, if adding randomize: y on the question widget, the order of the collections will be randomized, and the options within each collection will be randomized in respect to one another, but the options will not randomize/mix across collections. |
On a setlist | An order tag on a setlist comprised of collections will behave the same as above. |
On a collection header as a decorator |
An |
To summarize what is described above in the Syntax and creation section, multiple headers and optsfrom/rowsfrom/colsfrom
tags cause a list to be broken into multiple collections. This also 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. For example, the randomize
tag could describe randomization for all collections, and then at a particular header, the SP could use alphabetize: y
to alphabetize only the options in that collection. Tags such as anchor
and exclusive
can also be placed on individual options within a collection and function normally.
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 them anchored list within their respective collection.
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 order: [*]
to randomize the collections. Because the tag would also randomize within the collections, 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.
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.
Alphabetical
Starting in r8.2, 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.
Tip! Note that order: AtoZ(*)
is the functional equivalent of alphabetize: y
. Click on alphabetizing to learn the basics.
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.
Explicit ordering
Ordering positions of option elements and collections
For widgets with single collections, "explicit ordering" refers to the position of the elements themselves, not the element IDs. In multiple collections, explicit ordering can refer to the position of the elements when used on a setlist with a single collection, but explicit ordering can also refer to the position of the collections when used on the question widget, or on a setlist, when combining multiple collections. Consider the following:
# Example 1 setlist: DOGS order: (3,1,2) 1. Pug 2. Dalmatian 3. Boxer setlist: CATS order: (2,1,3) 4. Bengal 5. Serval 6. Siamese setlist: ANIMALS order: ([1,2],3) optsfrom: DOGS optsfrom: CATS 7. Guinea Pig
The list ANIMALS is composed of three collections: the list DOGS, the list CATS, and the final default collection which is the option Guinea Pig. The order
tags from the original lists DOGS and CATS describe each of those collections' ordering. The order: (3,1,2)
tag on DOGS indicates those will be listed in order as Boxer, Pug, Dalmatian; and the order: (2,1,3)
tag on CATS indicates those will be listed in order as Serval, Bengal, Siamese. The
order
tag on the ANIMALS list only describes how the three collections are ordered with respect to one another – '[1,2]' indicates to show either collection 1 (DOGS) or collection 2 (CATS) first, with those individual options in the orders mentioned previously, and the third and final collection (Guinea Pig) will always be shown last.
In Example 2, the ANIMALS list is re-formulated. All collections are expressed with multiple headers in a single setlist, instead of combining various listcalls like in Example 1. The Dogs and Cats collections each have explicit ordering with the order
decorator on their collection headers. Although this is programmed differently, the example below will render the same result as Example 1. Here the order
tag is describing the relationship of the three collections. Again, the first two are randomized, and the last, 'Other', is always last.
# Example 2 setlist: ANIMALS order: ([1,2],3) _A. Dogs {order: (3,1,2)} 1. Pug 2. Dalmatian 3. Boxer _B. Cats {order: (2,1,3)} 4. Bengal 5. Serval 6. Siamese _X. Other 7. Guinea Pig
In the following Example 3, the ANIMALS list is re-formulated yet again. In this case, the individual options within each collection are not defined, and so they will be displayed in the order they are programmed.
# Example 3 setlist: ANIMALS order: ([1,2],3) _A. Dogs 1. Pug 2. Dalmatian 3. Boxer _B. Cats 4. Bengal 5. Serval 6. Siamese _X. 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 list/spreadsheet calls would therefore contain order modifiers with both types of brackets.
setlist: OTHER_ANIMALS 7. Orangutan 8. Lemur setlist: ANIMALS order: ([1,2],3) _A. Dogs {order: (3,2,1)} 1. Pug 2. Dalmatian 3. Boxer _B. Cats {order: (2,1,3)} 4. Bengal 5. Serval 6. Siamese optsfrom: OTHER_ANIMALS [order: 2,1]
Comments
0 comments
Please sign in to leave a comment.