Chapters organize a survey into sections, much like a table of contents. Reports reflect this organization in the exports, like Excel, and in the reporting field tree by grouping questions and variables by chapter.
Surveys can contain user-defined chapters in addition to default system chapters. User-defined chapters are created in two ways — globally, using define chapters
, and locally, with the chapter
tag attached directly to a widget.
Questions are then grouped by chapter. If no chapters are defined, questions are put in the next open place in the Survey fields chapter.
Global vs. local chapter creation
What's the difference between the two approaches?
In global chapter creation, the define chapters
widget must be used at the top of the survey source, and the chapters and sub-chapters are explicitly written. The define chapters
widget works in conjunction with the chapter
tag, which is placed on widgets to reference the previously created chapters. This method is ideal for surveys with more complex organizational needs.
In local chapter creation, the chapter
tags are placed directly on the widgets, and nothing else needs to be created or defined. This method works well for most surveys with a simple organizational structure.
If global chapter creation is mixed with the local creation method, all globally defined chapters will be listed first in the reporting field tree and data exports.
Tip! If you program in IntelliBuilder (IB) mode, use local chapter creation. Place the chapter
tag directly on any widget to organize the survey data as needed. Currently, the chapter
tag can only be applied via the SPL editor. Partner with a Survey Programmer for assistance.
If you program with templates, local chapter creation is also the preferred method.
'define chapters' - global chapter creation
Syntax
The define chapters
method works in conjunction with the chapters
tag. First, add the define chapters
widget at the top of the survey source, and define the parent (main) chapters. Parent chapters are encouraged to use alpha characters, e.g., 'A'. Next, create sub-chapters as needed. Sub-chapters can be created within the original define chapters
widget, or separately in a follow up widget with the parent
tag. Sub-chapters are encouraged to use the parent's alpha character followed by a numeral (e.g., 'A1').
Single 'define chapter' widget with parent chapters
define chapters
A. Chapter Name
B. Another Chapter Name
Single 'define chapter' widget with parent chapters and sub-chapters
define chapters
A. Chapter Name
A1. Sub chapter of Chapter A
A2. Another sub-chapter of Chapter A
B. Chapter Name
Multiple 'define chapters' widgets with 'parent' tag
define chapters A. Chapter Name B. Another Chapter Name define chapters parent: A A1. Sub-chapter of Chapter A A2. Another Sub-chapter of Chapter A
After the define chapters
widget is programmed at the top of the survey source, the chapter
tag is then placed on widgets, such as questions and/or groups, to reference the previously defined chapters.
Naming and organizational rules
The order in which the parent chapters and sub-chapters are defined is the order in which the data will be organized, regardless of the widget's location in the survey.
There are a few important points to consider when naming chapters and sub-chapters:
- At a minimum, a chapter must be defined with an alpha character. This is the chapter ID (name). A description must also be attached after the period, e.g.,
A. Section A
. - Chapter names cannot begin with a number.
- Alphanumerical combinations are allowed, e.g,
A1. Section A
. - An alpha character followed by an underscore and a numeral or text is allowed, e.g.,
A_1. Section A
orA_SECTION. Section A
. - Chapter names are case sensitive; e.g, a chapter named "appendix" should not be written as "Appendix." If the case does not match, a new chapter will be created.
Caution: Avoid using Roman numerals for chapter labels with define chapters
. They are interpreted as sub-chapters; for example, 'III' would be a sub-chapter of 'II', etc.
Adding widgets to chapters
To assign a widget to a specific chapter or sub-chapter, include the chapter
tag anywhere on the widget.
chapter: Chapter ID here
For the examples below, assume chapter 'S' has already been defined at the top of the survey source with define chapters
.
Locally on a 'start group' widget
startgroup: MY_GROUP chapter: S All content here belongs in chapter S endgroup: MY_GROUP
Locally on a question or variable
VAR. I am a variable in Chapter S.type: coded single select
optsfrom: LISTNAME
chapter: S
Inheritance with 'define chapters'
When a widget is not defined with a chapter
tag, it will inherit the chapter
tag defined for its group. If there is no chapter
tag on its group, or no group exists, the question is placed after all globally organized chapters, in the next available position in the Survey fields chapter.
In the example below, NESTED_GROUP is within OUTER_GROUP. Each widget within these groups will inherit the chapter assignment of the group it resides in unless otherwise specified with the chapter
tag. NESTED_GROUP's content is assigned to chapter B. Then, Q3 will inherit OUTER_GROUP's assigned chapter A just like Q1. On the other hand, Q4 includes 'chapter: B1' in its definition, and therefore, will be assigned to the sub-chapter B1. Next, Q5 is not defined with a chapter
tag and has no group chapter to inherit; therefore, it will move to the next available place in the survey data map, which is after all the organized chapter data. Notice, Q6, which has a chapter created with define chapters
, is before Q5 in the reporting field tree.
Code example | Reporting field tree |
---|---|
define chapters |
|
'chapter' tag - local chapter creation
Syntax
You can also include the chapter
tag on a widget to create custom chapters. This local method is the preferred method for programming in templates and in IntelliBuilder since it can be added in the front-end editor and removes the need to add anything directly to the survey code.
Reminder, when chapter
tags are used with this approach, it is not necessary to include define chapters
at the top of the source.
chapter: Chapter ID here
Tip! Sub-chapters can also be created locally. However, the nested sub-chapter should be inside the parent chapter with the start group
widget; otherwise use the define chapters
method for more flexibility.
Naming and organizational rules
Given there is no define chapters
at the top of the survey source to visually display how chapter names will be given or derived, it is worth understanding a few points for creating chapters and sub-chapters when the chapter
tag is used alone.
-
- At a minimum,
chapter
tags should have at least an alpha character as the input, e.g.,chapter: A
. This is the chapter ID (name). - Chapter names cannot begin with a number.
- Alphanumerical combinations are allowed, e.g,
chapter: A1
. - An alpha character followed by an underscore and a numeral or text is allowed, e.g.,
chapter: A_1
orchapter: A_cats
. - You can attach a reporting description to a chapter name. For example,
chapter: T. Text here
produces the chapter name 'T', and 'Text here' provides the description. It's shown in the reporting field tree as 'Text here'. -
chapter: T
produces the chapter name 'T', and since there is no description attached, it's shown in the reports as 'T'. - Roman numerals are allowed. Unlike the global chapter creation method, Roman numerals do not trigger sub-chapters. Roman numerals are organized in unique parent chapters in the order they appear.
- Sub-chapters can only be created if a new, unique chapter label is defined and nested within a
start group
widget. - Chapter names are case sensitive; e.g., a chapter named "appendix" should not be written as "Appendix." If the case does not match, a new chapter will be created.
- At a minimum,
Adding chapters to widgets
To assign a widget (e.g., a question, group, etc.) to a specific chapter or sub-chapter, include the chapter
tag anywhere on the widget.
Locally on a 'start group' widget
startgroup: MY_GROUP chapter: S All content here belongs in chapter S endgroup: MY_GROUP
Locally on a question or variable
VAR. I am a variable in Chapter S.type: coded single select
optsfrom: LISTNAME
chapter: S
Inheritance with the 'chapter' tag
Similar to global chapter creation, when a widget does not have a chapter
tag, it will inherit the chapter
tag defined for its group. If there is no chapter
tag on a question, and there is no group chapter to inherit, the question will fall naturally as the next question in the Survey fields chapter. Since chapters are created "in the moment," any question falling within the Survey fields chapter could potentially be placed as a stand-alone question, between chapters, as opposed to chapters organized globally with define chapters
, where all organized chapters are first in the data map, and all "loose" questions appear after the last chapter.
It's also important to highlight that unlike chapters organized globally with define chapters
, in local chapter creation, a sub-chapter must be within the parent group or the nested group.
Consider the following example:
Code example | Reporting field tree |
---|---|
1. I am question 1 in a chapter S. chapter: S type: radio 1. See section A 2. See section B start group: section_A condition: anyChecked($Q1,1) chapter: A. Section A - Important Alpha Questions 2. I am question 2 in parent chapter A. type: text 3. I am question 3 in sub-chapter A1. type: text chapter: A1. Follow up questions end group: section_A start group: section_B condition: anyChecked($Q1,2) chapter: B 4. I am question 4. In Chapter B. type: text end group: section_B |
In the example above, Q1 is the first question in the survey. It also has the first defined chapter, therefore, it has the first position in the reporting field tree. The group 'section_A' is created, so Q2 is found here. However, Q3 is found within the same group, but the chapter label is different than that of the parent chapter. Therefore, a sub-chapter is created under chapter A called 'A1. Follow up questions'.
Next, chapter B is created, and Q4 is organized here. Notice, Q5 is next in the survey source, but it does not have any chapter label or chapter group label to inherit. It will fall in the data map immediately after chapter B. Lastly, Q6 uses chapter name B1. Although B1 looks like a sub-chapter name, it will be a new parent chapter because it is found outside chapter B's group.
Comments
0 comments
Please sign in to leave a comment.