Pular para o conteúdo principal
Base de Conhecimento da FocusVision

Question Attributes

1:  Question Attributes

All question elements have access to the following attributes:

Attribute Type Default Description
adim enum auto The primary report dimension (rows,cols,choices,auto)
aggregate string -- Base the question on data from other questions
alt string -- Alternative <title> text displayed in the report
altlabel string -- Alternative label to be used everywhere except from within the survey XML
averages set none What to show the average (mean) calculation for (none, rows, cols, choices, nosummary, summary)
below string -- The label of the question to place this question below
blankIfZero bool 0 Output blank data if value is 0
blankValue string 0 Sets the value for blank responses in the data file
choiceCond string -- Show each choice if this condition is true
choiceGroups set report,survey,restrict Where should the choice groups show up? (report, survey, restrict)
choiceShuffle string -- Allows you to specify the permutations of the <choice> shuffling (flip, rflip, rotate, reverse-rotate, rrotate)
colCond string -- Show each column if this condition is true
colGroups set report,survey,restrict Where should the col groups show up? (report, survey, restrict)
colLegend enum default Placement of the legend for columns (default, none, both, top, bottom, group, beforeGroup)
colLegendRows slist -- Additional rows to have column legend
colShuffle string -- Allows you to specify the permutations of the <col> shuffling (flip, rflip, rotate, reverse-rotate, rrotate)
cond string -- Display the question if this condition is true
comment string -- Additional information displayed in the respondent view beneath the title
dataSource string -- Label of the <datasource> element to get data from
dataRef string -- What <datasource> column to get data from
exec string -- Execute this Python code before displaying the question
grouping enum auto Grouping of the question's components (auto, rows, cols)
horizontalPercentages bool 0 Calculate percentages across?
keepWith string -- Display these other questions on error
label string -- Symbolic name for the question
noTranslate set title, comment Disables translations for the values specified
open enum default Placement of the open-ended input field (default, left, right)
optional bool 0 Should the user be allowed to skip this question?
pii integer 0 Specify an integer between 0 and 9999, inclusive, to set the personally identifiable information protection level.
ratingDirection enum -- Which end of the rating scale is the high end? (default, reverse)
rightOf string -- The label of the question to place this question to the right of
rowCond string -- Show each row if this condition is true
rowGroups set report,survey,restrict Where should the row groups show up? (report, survey, restrict)
rowLegend enum default Placement of the legend for rows (default, both, right, left)
rowShuffle enum default Allows you to specify the permutations of the <row> shuffling (flip, rflip, rotate, reverse-rotate, rrotate)
showSource bool 0 Display the source code of the question for logged-in users
shuffle set none Elements to shuffle (none, rows, cols, choices)
shuffleBy string -- The label of the question to shuffle the elements by
sort set none Sort the results in the report (none, rows, cols, choices, desc, asc, percentages)
sortChoices set none Sort choices alphabetically (none, asc, desc, survey, report)
sortCols set none Sort columns alphabetically (none, asc, desc, survey, report)
sortRows set none Sort rows alphabetically (none, asc, desc, survey, report)
style string -- Alternative search path for styles
title string -- The displayed title of the question (required)
type enum none The type of question (none, rating)
uses string -- The dynamic question (DQ) style to use
values string none Sets the values for the question (none, order)
virtual string -- Python code to compute the data values
where set survey,report Specify where the variable should be available (survey,report,summary,none,notdp)
tv enum auto Change trackVars settings at the question level for surveys with trackVars="checkbox" specified (auto, off, force)

adim

The adim attribute controls the primary dimension displayed in the report. Usually if a report is 2-dimensional, then one table is created for each item in the shortest dimension showing all items in the secondary dimension. The adim attribute enables you to override this primary dimension.

<radio label="Q1" adim="rows">

aggregate

The aggregate attribute is for virtual questions, allowing you to perform calculations on data derived from other questions.

<radio label="Q1_Q2_Q3_Aggregated">
    <row label="r1">I like it</row>
    <row label="r2">I'm neutral about it</row>
    <row label="r3">I hate it</row>
    <aggregate>
this.r1 = Q1.r1 + Q2.r1 + Q3.r1
this.r2 = Q1.r2 + Q2.r2 + Q3.r2
this.r3 = Q1.r3 + Q2.r3 + Q3.r3
this.shown = Q1.shown + Q2.shown + Q3.shown
this.answered = Q1.answered + Q2.answered + Q3.answered
    </aggregate>
</radio>

Learn more: Data Aggregation

alt

The alt attribute allows you to specify an alternative short text for the element. If the element contains a title attribute, the alt attribute will override this text in the report and data downloads.

altlabel

The altlabel attribute is an alternative label that will be displayed in all other areas except from within the survey. This can be used for recoding or relabeling data.

averages

The averages attribute controls which averages are calculated for the question. The acceptable value is a comma-separated set containing rows, cols, choices or nosummary. By default, summary tables are automatically generated for 2-dimensional questions. Set averages="nosummary" to show a summary table.

<radio label="Q1" averages="rows,nosummary">

below

The below attribute allows you to group questions together vertically. The number of columns must be the same to use the below attribute.

<text label="Q1" title="Please specify a few of your favorite car brands.">
    <row label="r1">Car brands</row>
    <col label="c1">Brand #1</col>
    <col label="c2">Brand #2</col>
    <col label="c3">Brand #3</col>
</text>

<checkbox label="Q1_Ownership" title="Favorite car brand ownership" below="Q1" optional="1">
    <row label="r1">Do you own a car of this make?</row>
    <col label="c1"></col>
    <col label="c2"></col>
    <col label="c3"></col>
</checkbox>

blankIfZero

The blankIfZero attribute is only applicable to <checkbox> elements and will change 0 data to blanks.

<checkbox label="Q1" atleast="1" blankIfZero="1">

blankValue

The blankValue attribute allows you to set the value for blank data. If blankValue="No Data" is set, then the data will show the string "No Data" for blank values. This can be applied globally from within the <survey> element, or for each question type.

<checkbox label="Q1" atleast="1" blankValue="No Data">

choiceCond

The choiceCond attribute allows you to specify condition logic that will show or hide each <choice> element.

<select label="Q2" title="Which pizza is your favorite?" choiceCond="Q1.rows[choice.index]">
    <choice label="ch1">Cheese</choice>
    <choice label="ch2">Pepperoni</choice>
    <choice label="ch3">Meat-Lovers</choice>
    <choice label="ch4">Combination</choice>
    <choice label="ch5">Sausage</choice>
</select>

choiceGroups

The choiceGroups attribute allows you to specify where the <group> element associated with each choice will appear. By default, the groups will appear in the survey and report. If choiceGroups="restrict" is set, then the groups will only appear when creating a custom report.

choiceShuffle

The choiceShuffle attribute allows you to specify the shuffle order of <choice> elements. For example, if there are 3 choices in total, specifying choiceShuffle="ch1,ch2,ch3;ch3,ch2,ch1" will show in ascending order for the first respondent and in descending order for the second.

The order used depends on the respondent's record number. The shuffle order will not be balanced for qualified completes.

In addition to specifying the order using the choice labels, you may also use the keywords flip, rflip, rotate and rrotate.

  • flip : This means that 50% of the respondents will see the choices in order and the other 50% will see the choices in reverse order.
  • rflip : Similar to "flip" except that the first respondent will see the choices in reverse order and the next will see the choices in order.
  • rotate : The shuffle order wraps around for each new respondent. For example, "ch1,ch2,ch3" for the first, "ch2, ch3, ch1" for the second, "ch3,ch1,ch2" for the third, and back to "ch1,ch2,ch3" for the fourth.
  • rrotate : The shuffle order wraps in the reverse direction. For example, "ch1,ch2,ch3" for the first, "ch3,ch1,ch2" for the second, "ch2,ch3,ch1" for the third, and back to "ch1,ch2,ch3" for the fourth.

colCond

The colCond attribute allows you to specify condition logic that will show or hide each <col> element.

<radio label="Q2" title="Which pizza is your favorite?" colCond="Q1[col]">
    <col label="c1">Cheese</col>
    <col label="c2">Pepperoni</col>
    <col label="c3">Meat-Lovers</col>
    <col label="c4">Combination</col>
    <col label="c5">Sausage</col>
</radio>

colGroups

The colGroups attribute allows you to specify where the <group> element associated with each col will appear. By default, the groups will appear in the survey and report. If colGroups="restrict" is set, then the groups will only appear when creating a custom report.

colLegend

The colLegend attribute allows you to specify the placement of the column legend. If colLegend="bottom" is specified, the legend will appear on the bottom. The possible values are none, both, top, bottom, group and beforeGroup.

colLegendRows

The colLegendRows attribute allows you to specify additional locations of the column legend. The value accepted is a comma-separated list specifying the row indices where the legend should appear before. For example, colLegendRows="4,7,9" will display the legend between rows 3 and 4, 6 and 7, and 8 and 9.

colShuffle

The colShuffle attribute allows you to specify the shuffle order of <col> elements. For example, if there are 3 cols in total, specifying colShuffle="c1,c2,c3;c3,c2,c1" will show in ascending order for the first respondent and in descending order for the second.

The order used depends on the respondent's record number. The shuffle order will not be balanced for qualified completes.

In addition to specifying the order using the col labels, you may also use the keywords flip, rflip, rotate and rrotate.

  • flip : This means that 50% of the respondents will see the cols in order and the other 50% will see the cols in reverse order.
  • rflip : Similar to "flip" except that the first respondent will see the cols in reverse order and the next will see the cols in order.
  • rotate : The shuffle order wraps around for each new respondent. For example, "c1,c2,c3" for the first, "c2, c3, c1" for the second, "c3,c1,c2" for the third, and back to "c1,c2,c3" for the fourth.
  • rrotate : The shuffle order wraps in the reverse direction. For example, "c1,c2,c3" for the first, "c3,c1,c2" for the second, "c2,c3,c1" for the third, and back to "c1,c2,c3" for the fourth.

cond

The cond attribute allows you to specify a Python expression that must evaluate to True in order for the question to be displayed.

<radio label="Q1" cond="list == '1'">

comment

The comment attribute allows you to specify additional text to display beneath the question's title attribute. This is often used to help respondents answer the question.

<comment>Please select one.</comment>

dataSource

The dataSource attribute allows you to specify which <datasource> element is to be used to read data into the question.

Learn more: Datasource Element

dataRef

The dataRef attribute, in associate with the dataSource attribute, specifies the column in the data source to read data from. This attribute is only applicable if the question contains one data point. For example, a <text> or <radio> element, or an individual row within a <checkbox> element.

Learn more: Datasource Element

exec

The exec attribute enables you to execute Python code before displaying the question. This attribute is commonly used and often times to manually set the question's shuffle order, disable question elements, and update question elements on-the-fly.

grouping

The grouping attribute controls how the question's <row> and <column> elements are grouped. For example, when grouped by rows, then answers are selected on a per row basis. On the other hand, when grouped by columns, selections are made on a per column basis.

horizontalPercentages

The horizontalPercentages attribute allows you to toggle the direction in which the question's base is calculated from. When horizontalPercentages="1" is specified, the base is calculated horizontally for each cell instead of vertically.

keepWith

The attribute keepWith allows you to display questions on the same page together even after an error has occurred. In the example below, Q1 will be shown on the same page as Q2 if an error is presented at Q2. The keepWith attribute is not transitive, meaning Q2 will not be shown with Q1 if only an error is present at Q1.

<checkbox label="Q1" atleast="1" title="Do you?">
    <row label="r1">Yes</row>
    <row label="r2">No</row>
</checkbox>

<checkbox label="Q2" atleast="1" title="Do you, really?" keepWith="Q1">
    <row label="r1">Yes</row>
    <row label="r2">No</row>
</checkbox>

label

The label attribute is the symbolic name for the element. The system uses the label as the target when performing various Python-related functions. A label must be a valid Python identifier.

noTranslate

The noTranslate attribute allows you to disable translations for specific values. This can be helpful when you only need to translate certain parts of a virtual or hidden question (e.g., when piping only row content to the survey from a virtual question).

open

The open attribute allows you to control the placement of the open-ended input field for rows that have open="1" specified. The default placement of the input field is just after the row legend. If open="right" is specified and the row legend appears on the left, the input field will appear on the right without any legend text.

optional

The optional attribute allows you to specify whether or not a respondent must provide a value to the question. If optional="1" is specified, the respondent can skip the question.

pii

The pii attribute allows you to set the personally identifiable information (PII) protection level (0-9999, inclusive) to restrict data access. This protection level applies only to textual data.  For example, a PII level cannot be set on a radio or a checkbox question. Afterwards, in order for the question data to be visible to a user, the user's PII level must meet or exceed that specified for the question. Click here, for the details for setting PII access restrictions.

ratingDirection

The ratingDirection attribute allows you to specify the direction of the scale for any type="rating" question. If ratingDirection="reverse" is specified, the report will reverse the "Top 2" and "Bottom 2" accumulations.

<radio label="Q1" type="rating" values="order" ratingDirection="reverse">
   <title>Please rate this question.</title>
   <row label="r5">5</row>
   <row label="r2">4</row>
   <row label="r3">3</row>
   <row label="r2">2</row>
   <row label="r1">1</row>
</radio>

rightOf

The attribute rightOf allows you to group questions together horizontally. The number of rows must be the same to use the rightOf attribute.

<text label="Q1" title="Please specify a few of your favorite car brands.">
    <row label="r1">Car brands</row>
    <col label="c1">Brand #1</col>
    <col label="c2">Brand #2</col>
    <col label="c3">Brand #3</col>
</text>

<checkbox label="Q1_Ownership" title="Car brand ownership" rightOf="Q1" optional="1">
    <row label="r1">Do you own any of these types of cars?</row>
</checkbox>

rowCond

The rowCond attribute allows you to specify condition logic that will show or hide each <row> element.

<radio label="Q2" title="Which pizza is your favorite?" rowCond="Q1[row]">
    <row label="r1">Cheese</row>
    <row label="r2">Pepperoni</row>
    <row label="r3">Meat-Lovers</row>
    <row label="r4">Combination</row>
    <row label="r5">Sausage</row>
</radio>

rowGroups

The rowGroups attribute allows you to specify where the <group> element associated with each row will appear. By default, the groups will appear in the survey and report. If rowGroups="restrict" is set, then the groups will only appear when creating a custom report.

rowLegend

The rowLegend attribute allows you to specify how the row legends are displayed. By default, row legends are displayed on the left. If rowLegend="both" is specified, then the row text will appear on both sides. Illustrated in the example below, you may use the rightLegend attribute on a per row basis to specify alternative text for the right row legend.

<radio label="Q1" rowLegend="both">
  <title>
    Test
  </title>
  <comment>Please select one</comment>
  <row label="r1" rightLegend="4">1</row>
  <row label="r2" rightLegend="5">2</row>
  <row label="r3" rightLegend="6">3</row>
</radio>

rowShuffle

The rowShuffle attribute allows you to specify the shuffle order of <row> elements. For example, if there are 3 rows in total, specifying rowShuffle="r1,r2,r3;r3,r2,r1" will show in ascending order for the first respondent and in descending order for the second.

The order used depends on the respondent's record number. The shuffle order will not be balanced for qualified completes.

In addition to specifying the order using the row labels, you may also use the keywords flip, rflip, rotate and rrotate.

  • flip : This means that 50% of the respondents will see the choices in order and the other 50% will see the choices in reverse order.
  • rflip : Similar to "flip" except that the first respondent will see the choices in reverse order and the next will see the choices in order.
  • rotate : The shuffle order wraps around for each new respondent. For example, "r1,r2,r3" for the first, "r2, r3, r1" for the second, "r3,r1,r2" for the third, and back to "r1,r2,r3" for the fourth.
  • rrotate : The shuffle order wraps in the reverse direction. For example, "r1,r2,r3" for the first, "r3,r1,r2" for the second, "r2,r3,r1" for the third, and back to "r1,r2,r3" for the fourth.

showSource

The showSource attribute allows you to view the source code of the question. If showSource="1" is set, users that are logged in with QA codes enabled will see the question's underlying source code.

shuffle

The shuffle attribute allows you to specify which of the question's elements to shuffle. If shuffle="rows,cols,choices" is specified, then the question will shuffle each of the <row>, <col> and <choice> elements.

shuffleBy

The shuffleBy attribute allows you to specify another question's label to shuffle the current question's elements by. The shuffleBy attribute uses the element's index value to match the shuffle order, so the number and meaning of the elements should be the same.

<radio label="Q1" shuffle="rows" title="First question.">
    <row label="r1">Item 1</row>
    <row label="r2">Item 2</row>
    <row label="r3">Item 3</row>
</radio>
<radio label="Q2" shuffle="rows" shuffleBy="Q1" title="Second question.">
    <row label="r1">Similar Item 1</row>
    <row label="r2">Similar Item 2</row>
    <row label="r3">Similar Item 3</row>
</radio>

sort

The sort attribute allows you to specify the sort order of the results in the report. If sort="rows,percentages,desc" is specified, the order of the results will be sorted based on the row's percentage values instead of the count values and in descending order. If sort="choices,asc" is specified, the question's choices will be sorted based on the count values in ascending order.

sortChoices

The sortChoices attribute allows you to specify the order in which to display the <choice> elements. If sortChoices="asc,report,survey" is specified, the choices will appear sorted alphabetically in ascending order for both the report and survey view of the question. In the example below, the choice elements will be sorted alphabetically in descending order in the survey view and remain in the order shown in the report view.

<select label="Q1" sortChoices="desc,survey">
    <choice label="ch1">c</choice>
    <choice label="ch2">b</choice>
    <choice label="ch3">a</choice>
    <choice label="ch4">d</choice>
</select>

sortCols

The sortCols attribute allows you to specify the order in which to display the <col> elements. If sortCols="desc,report,survey" is specified, the columns will appear sorted alphabetically in descending order for both the report and survey view of the question. In the example below, the col elements will be sorted alphabetically in ascending order in the report view and remain in the order shown in the survey view.

<checkbox label="Q1" sortCols="asc,report">
    <col label="c1">c</col>
    <col label="c2">b</col>
    <col label="c3">a</col>
    <col label="c4">d</col>
</checkbox>

sortRows

The sortRows attribute allows you to specify the order in which to display the <row> elements. If sortRows="asc,survey" is specified, the rows will appear sorted alphabetically in ascending order in the survey view of the question. In the example below, the row elements will be sorted alphabetically in ascending order in the survey view and remain in the order shown in the report view.

<radio label="Q1" sortRows="asc,survey">
    <row label="r1">c</row>
    <row label="r2">b</row>
    <row label="r3">a</row>
    <row label="r4">d</row>
</radio>

style

The style attribute allows you to specify a style prefix that can be used to add and/or modify additional components of the question. This attribute corresponds to the project's styles/nstyles files.

This attribute is deprecated and the new XML style system should be used instead. Click here for more details.

title

The title attribute is required for all question elements and can be seen in both the report and survey view. The title attribute is also subject to variable replacement, meaning that variables from other survey components can be piped into the question's title text.

<radio label="Q1" title="Please choose your favorite color:">
    <row label="r1">Red</row>
    <row label="r2">Green</row>
    <row label="r3">Blue</row>
    <row label="r4" open="1">Other:</row>
</radio>
<suspend/>

<text label="Q2">
    <title>Why is [pipe: Q1] your favorite color?</title>
</text>

type

The type attribute is used to affect the report output for rating questions. If type="rating" is specified, the question's table in the report will show a "Top 2" and "Bottom 2" net in addition to the average rating. The question must have the values attribute specified at the question level or on a per row basis.

uses

The uses attribute is used to modify the question's layout and presentation using our dynamic question styles. The shorthand notation for any of the dynamic questions available can be supplied and the question will transform into the DQ style specified.

<radio label="Q1" title="Please select a bucket for each item below." uses="cardsort.3">
    <row label="r1">Item 1</row>
    <row label="r2">Item 2</row>
    <row label="r3">Item 3</row>
    <col label="c1">Bucket 1</col>
    <col label="c2">Bucket 2</col>
    <col label="c3">Bucket 3</col>
</radio>

values

The values attribute allows you to override the default data values of the question's <row>, <col>, or <choice> elements. If values="order" is specified, the data values for each element will correspond to the order in which it sits. In the example below, the data value for "r3" will be 3 (corresponding to the position), the data value for "r5" will be 99 since a specific value was set, and the value for any non-checked item will be 0.

<checkbox label="Q1" title="Please select all that apply." values="order">
    <row label="r1">Item 1</row>
    <row label="r2">Item 2</row>
    <row label="r3">Item 3</row>
    <row label="r4">Item 4</row>
    <row label="r5" exclusive="1" value="99">None of the above</row>
</checkbox>

This attribute also accepts the reverse option, which excludes explicit value answers first. This means you can have an input like: 5 - 1, 9

virtual

The virtual attribute allows you to evaluate Python expressions each time the report is ran. Any question with a virtual attribute declared is a virtual question. A virtual question can compute its value based on other non-virtual questions.

Set newVirtual="1" inside the main <survey> tag to enable the same syntax for your virtual code that's available in the survey.

<text label="vQ1">
    <virtual>
this.r1.val = "$" + Q1.r1.val
this.r2.val = S5.r1.val + ", " + Q1.r2.val
    </virtual>
    <row label="r1">Income</row>
    <row label="r2">City, State</row>
</text>

where

The where attribute controls where a variable should be available. It can be set to any of the following:

  • survey: The element will be shown in the survey
  • execute: The element will be shown as a hidden question in the survey
  • report: The element will be shown in the report
  • summary: The element will appear in the report summary table
  • none: The element will not appear anywhere (neither survey nor report)
  • notdp: The element will appear in the survey and report, but not in the data downloads

 

By default, most elements are set to where="survey,report" and will appear in both the survey and report. If where="none" is specified, the element will not appear anywhere.

For example:

<text label="Q1" optional="0">
  <title>
    (Default) Shown in survey and report.
  </title>
</text>

<text label="Q2" optional="0" where="execute">
  <exec>
# do something here
  </exec>
  <title>
    Shown as hidden question in survey.
  </title>
</text>

<text label="Q3" optional="0" where="none">
  <title>
    Not shown at all.
  </title>
</text>

<text label="Q4" optional="0" where="report">
  <title>
    Only shown in report.
  </title>
</text>

<text label="Q5" optional="0" where="notdp">
  <title>
    Shown in survey and report, but not in data downloads.
  </title>
</text>

The code above produces the following result:

Learn more: Controlling Where an Element Appears & Hiding Questions with Where

tv

The tv attribute applies to surveys with trackVars="checkbox" specified and enables you to control how trackVars (TV) works at the question level.

By default, tv="auto" is specified and TV will behave as expected, showing the percentage calculation base based on individual checkboxes.

When tv="off" is specified, TV will be disabled for this question and normal checkbox calculations will be performed. (e.g. a data value of blank will only exist when the question wasn't seen altogether)

When tv="force" is specified, TV will assume that allow checkbox items were seen and none were hidden.

Learn more: Setting an Answer Option Base to Total Shown for Multi-Select Questions

2:  What's Next?

Check out the Overview of the Survey Tag and Quick Links

  • Este artigo foi útil?