The Survey Designer enables you to create questions and Text/HTML objects, and to configure preferences for an entire survey. The pages in this section describe how to use each of the Survey Designer's features.
|
|||
The Survey Designer enables you to create questions and Text/HTML objects, and to configure preferences for an entire survey. The pages in this section describe how to use each of the Survey Designer's features.
This article outlines a specific set of practices to improve survey quality, describing the benefits of each practice and the consequences of neglecting each practice. These practices have the following goals:
Group logically-related questions into collections with logical names. For example, if your survey contains 20 questions about travel, put all of those questions into a collection called TRAVEL. See Creating a Collection for details. Why
Use poplists for select-one type questions that have many options (generally more than 10). Use radio buttons for select-one type questions that have few options (generally less than 10). Use likert scales for select-one type questions that use a continuum (a scale of values that ranges from one extreme, such as "very likely" to the opposite extreme, such as "very unlikely"). Use text questions for any type of short free-form answer (up to 255 characters). Use commentary questions for longer verbal responses (more than 255 characters). See Setting a Question's Display Properties for more information. Use question tables for numerous questions that share a common set of response options. For example, if your survey includes 20 select-one questions with the options "For," "Against," and "Undecided," creating a single question table takes much less time than creating 20 separate questions. The question table layout presents the questions simply and clearly, enabling participants to answer the questions more quickly and easily. See Creating a Question Table for more information about Question Tables.
If your question requires a numeric response, choose the most specific numeric data type that applies. This applies above all to Text questions. For example, a question that asks a participant's age should use the type "Whole Numbers >= 0" since age cannot be less than zero. When asking a participant's grade point average, choose the type "Decimal Numbers," since grade point average tend to include decimal components. See Setting a Question's Response Options for details. Why
Assigning specific response guides prevents bad data from getting into your survey results. For example, when asking for a participant's grade point average, assign lower and upper bounds that ensure a valid response. A reasonable lower bound would be 0; a reasonable upper bound may be 4 or 5, depending on the grading scale. See Setting a Question's Response Guides for details. Starting in version 2.2, Illume enables you to set dynamic bounds, which customize response guides for each participants. For example, one question called KIDS may ask, "How many children do you have?" A later question called KIDS_IN_SCHOOL may ask, "How many of your children are currently in school?" You can define upper bound (i.e. maximum allowable response value) for the second question as less than or equal to the answer to the first question. See Setting Dynamic Defaults and Bounds for specifics about dynamic bounds. Why
In order to determine the value of a calculated variable, each of the variables used in the calculation must have a value. For example, a variable calculated as {Value:HEIGHT} / {Value:WEIGHT} cannot be calculated unless the participant has answered both the HEIGHT and WEIGHT questions. To get meaningful data in a calculated variable, you must require that participants answer the questions on which the calculation is based. The answers to those questions, as noted above, must be of the correct data type! See Setting a Question's Response Options for details on how to select a question's data type. See Setting a Question's Response Guides for help in setting the response guides, and Using Calculated Variables for more information on creating calculated variables.
Each calculated variable in Illume includes a default value. Whenever Illume is unable to perform a calculation, it sets the value of the calculated variable to the default value. For example, if the variable DRINKS_PER_WEEK is calculated as {Value:DRINKS_PER_DAY} * 7, Illume will not be able to calculate a value until the participant has answered DRINKS_PER_DAY question. If DRINKS_PER_DAY does not require an answer, Illume may never be able to calculate a value for DRINKS_PER_WEEK. If you assign a default value of 0 to the DRINKS_PER_WEEK calculation, then all participants who answered 0 to DRINKS_PER_DAY, and all participants who did not answer DRINKS_PER_DAY, will have a value of 0 for DRINKS_PER_WEEK. This is incorrect, and will result in invalid aggregate data for the DRINKS_PER_WEEK variable. A more intelligent design would set the default value of DRINKS_PER_WEEK to -1 (or any other number less than zero). Setting the calculation's default value outside the range of legitimate values enables analysts to identify which data to ignore. In this example, the analyst knows that when DRINKS_PER_WEEK is 0, it can only be because the participant answered 0 to DRINKS_PER_DAY. When DRINKS_PER_WEEK is less than 0, it can only be because the participant did not answer DRINKS_PER_DAY. The analyst can then ignore all values less than 0 and focus only on the valid data. See Using Calculated Variables for more information.
Preloaded variables are variables loaded from the participant list into the survey, as described in Preloading Participant Data. When creating a preloaded variable, the data type must match the type of data being loaded from the participant list, and the data type should be as specific as possible. For example, when loading a participant's year of birth into a variable called BIRTHYEAR, the data type should be set to "Whole Numbers," because a year is whole number. When loading data from a field that may include non-numeric data, set the data type of the preload to "Text." Why
Except for the following cases, using show-if conditions is always preferable to using jumps:
The Date, Time, and Date/Time data types rely on values having specific formats. Values that may appear valid may not be accepted because of formatting requirements, and this may frustrate survey participants. For example, the date "Thu, 03 Jan 2002" is valid, but "Thurs, 03 Jan 2002" is not. "Thursday, January 03, 2002" is valid, but "Thu January 03, 2002" is not. Try writing an error message that will explain this to a participant. The Date, Time, and Date/Time data types will accept a standardized set of date and time formats, and may reject or incorrectly interpret dates and times in non-standard formats. Dates may also be misinterpreted in cases where the participant is in a different cultural locale than the Illume server. (E.g. Servers in the US are configured to interpret 06/12/2005 as June 12, 2005. A participant in the UK typing in that date would mean December 6, 2005, but the date will show up in the survey results as June 12!) When asking a participant to supply a date, the best solution may be to specify a format. For example, "Please enter your date of birth (mm/dd/yyyy)." Another solution is to create three questions: a poplist containing the 12 months, a poplist containing 31 days, and a poplist containing a valid range of years. See Date and Time Data for more information.
Because Illume uses Microsoft's .NET framework to interpret and store dates, Illume will correctly interpret and store dates that were produced by other Microsoft products running on computers whose locale is the same as the locale of the Illume server. Exporting data from Microsoft Excel, Access, or SQL Server into a participant list is generally safe. You can preload these dates (and times and datetimes) into a variable of type Date (or Time or Date/Time). Use the Date data type only for variables that must include a day, month, and year. If your variable requires only one of these values (day or month or year), choose the whole number or text data type. Choose Date/Time data type only for variables that require a day, month, and year value with an optional time value. See Date and Time Data for more information.
You may lose your connection to the Illume server after an extended period of inactivity, or if there is a problem with your network connection. To reconnect, simply choose the Reconnect option from the Survey Console's File menu. You will need to log in again.
If you have more than one Illume login and you want to switch to your other login while you are already connected, File > Reconnect will let you do that when it presents the login dialog.
The Survey Console lists surveys available for editing and review. The surveys that appear beneath the My Surveys tab are on your computer's hard drive and are available for editing. Surveys appearing in red type were checked out from the Illume server to which you are currently connected. Clicking on the Name column header sorts the surveys by name in ascending or descending alphabetical order.
The Survey Administration tab lists the surveys available on the Illume server, along with the status of each survey. From this list, you can preview surveys, check them out for editing, and (if you have sufficient privileges) publish or suspend surveys.
To create a new survey:
1. Choose New... from the Survey Manager's File menu, or right click in the My Surveys pane and select New... from the context menu.
2. Choose a template for your survey. The template determines how the survey will appear in a participant's web browser. If you are not sure which template to choose, choose the Default Template. You can change the template later if you want the survey to have a different look.
3. Type a name for your survey into the New Survey Name field. You must choose a name that is not already in use. (The survey manager lists the names of all of the available surveys.)
4. Click Create Survey.
To edit an existing survey, simply double-click on the survey name in the My Surveys tab of the Survey Console. If the survey does not appear under the My Surveys tab, you will have get a copy of it from the Illume server. See Checking Out a Survey for details.
If your survey includes more than one language, and you have translation tools enabled, you can view and edit the survey in any of its component languages. Simply choose Edit > Languages, and pick the language you want to work with.
The languages that appear in the list include all of the languages into which the survey has been translated. The language marked by an asterisk (*) is the survey default language.
To clone a survey, right click on the name of the survey in the Survey Manager and select the Clone... option from the context menu.
Type in a name for the new survey when prompted. Check the box next to "Do not include disabled items in clone" to omit survey items whose show-if condition is set to "Never shown (disabled)."
Click OK to create the clone.
To delete a survey, right click on the name of the survey in the Survey Manager and select the Delete option from the context menu. When deleting from the My Surveys tab, you can only delete a survey that has not yet been checked in. To permanently delete a survey from the Illume server, use the link below to Deleting a Survey in the Survey Administration section.
To rename a survey, right click on the name of the survey in the Survey Manager and select the Rename... option from the context menu. Type in a new name for the new survey when prompted, and click OK.
A survey's description appears in the Web Console, on the survey console page, just below the survey name.
To edit this description:
The End Page is the page participants see after they submit the survey. Illume enables you to define custom content for the end page. Each block of end page content can include show-if conditions so that it appears only to participants who meet specific criteria. For example, your survey may screen participants to see if they are eligible for a more detailed follow-up study. Those who qualify for the follow-up study will see on the end page an invitation to participate in the follow-up. Others will see only a message thanking them for their participation. You can determine which content a participant sees by attaching simple show-if logic to each end page content block. For example, the "invitation" may appear to all participants who answered yes to a certain question. Anyone who did not answer yes will see the thank you message.
To create a End Page content, follow these steps:
Yes. If a participant meets the show-if conditions for more than one block of end page content, the content from each end page will appear in the same order that the content appears in the End Page Content Editor. All of the content appears on a single HTML page. For example, assume your survey has one question that asks "Which end page would you like to see?" The options are "blue," "red," and "green." You survey has the following four end pages:
Survey redirects allow participants to be redirected to another web site or URL after they have submitted a survey. Survey redirects can also be used to chain one survey to another.
If you need the redirect to occur in the middle of a survey, a Jump object can added that specifies “Jump to the end and automatically submit” and the redirect will occur after the submit.
After a participant submits a survey each redirect is visited in top to bottom order in which they are specified in the Survey Designer. The participant is redirected to the first redirect that matches the criteria. Once a participant matches the criteria of one redirect, all redirect and end page processing stops. This means that if a redirect is being performed, no end page Text/HTML object content will be displayed. For SDK users this means that no runtime content objects in the end page will be processed.
It is important to note that order is very important when specifying redirects. To change the order of redirects, click on a redirect in the Survey Redirects dialog and drag it up or down.
The Survey Designer keeps track of up to 8 previous changes. You can undo any of these changes by choosing Edit > Undo from the Survey Designer menu, or by pressing Control-Z.
You can redo any action you have undone by choosing Edit > Redo from the Survey Designer menu, or by pressing Control-R.
Every Illume survey includes a collection called Root, which contains all of a survey's items.
Each of the collections immediately below the Root collection becomes a Section in the Data Dictionary. The section name is the same as the collection name.
By default, each section of the Data Dictionary contains the contents of the top-level collection and the contents of any other collections within that top-level collection.
That is, if your survey contains collections C1, and C2 under the Root collection, the Data Dictionary will display sections C1 and C2. If C1 contains another collection called C1_Subsection, that sub-collection will not appear in the Data Dictionary. All of the questions in C1_Subsection will be listed with the items in C1.
This may not always produce the best results. In some cases, a single section of the data dictionary may wind up with hundreds of questions, making it difficult for data analysts to find specific items. Customizing the sections of the Data Dictionary solves this problem.
You can make any collection in your survey appear as a section in the Data Dictionary, and you can customize the section's name.
To see how this appears in the Data Dictionary, choose Tools > Review Data Dictionary... from the Survey Designer menu.
To see your survey's Data Dictionary, choose Review Data Dictionary... from the Tools menu. This displays the same data dictionary that appears in the Web Console.
For more information, see the Related articles below.
Beginning in Illume 4.5, you can drag an entire survey out of the Survey Console and drop it into a folder or application. For example, you can drag a survey into Microsoft Outlook email message, and Outlook will attach the survey the email you are composing. The recipient of your email can then drag the attachment back into Illume for editing.
The survey that you drag into and out of Illume is an XML document. It's in a format that another Illume user can edit with the Illume Survey Designer. It's not in a format that a survey participant can fill out.
Because the survey is an XML file, the types of applications into which you can drag it include email clients (such as Microsoft Outlook), text editors (such as Notepad), and browsers (such as Internet Explorer and Mozilla Firefox).
Illume surveys include numerous customizable settings, such as page headers and footers, stylesheets, error messages, numbering styles, and more. To view and edit these preferences, choose Edit > Preferences... from the Survey Designer menu.
This brings up the Survey Preferences Editor, in which you can review and edit each of the preferences described below. Illume automatically saves your survey changes when you click OK in the Survey Preferences Editor.
To edit general survey preferences, choose Edit > Preferences... from the Survey Designer menu. The Survey Preferences Editor will appear with the General preferences tab showing.
A survey's general preferences include the following:
The title of the survey appears in the title bar at the very top of the participant's browser window, above the toolbar, and outside of the HTML page that contains the survey questions.
Illume provides options for manually or automatically numbering questions. While manual question numbering offers more control, keep in mind that if you move questions that are manually numbered, you may have to re-number many items in your survey.
If you choose to have Illume automatically number questions, you will never have to reassign question numbers when you add, move or delete questions from your survey.
Automatic numbering provides the following options:
Question numbering style determines how the numbers will appear. Sub-question numbering styles determines how sub-question numbers will appear. This applies to the numbering of individual items within Question Tables.
The sub-question numbering options have the following effects:
You can turn off numbering altogether by checking the "Don't number questions' option on the General tab of the Survey Preferences Editor.
In addition to sequencing, you can choose a numbering style for your survey. Styles include Arabic and Roman numerals followed by different types of punctuation.
Simply choose the style you prefer from the list of available styles. Question numbering styles apply to question numbers, while sub-question numbering styles apply to the individual prompts of question blocks.
If you choose not to number the questions in your survey, Illume will automatically add a small image to the left of each new question prompt. This serves as a visual marker to alert participants to the start of a new question. By default, the image is a small blue triangle. If you don't like the default, follow these steps to use your own image:
button to choose an image.
Illume includes an HTML editor that enables you to customize the page header, page footer, and resume page of each individual survey.
The page header appears at the top of every HTML page in your survey. To edit the page header:
The page footer appears at the bottom of every HTML page in your survey. To edit the page header:
Illume surveys include a resume/restore feature that allows participants to log back in to resume a partially completed survey. When a participant logs in and Illume finds a partially completed survey for that user, Illume presents a resume/restore page, which asks the user whether they would like to resume the existing survey where they left off, or start over with a new survey.
You can customize the message on the resume/restore page by following these steps:
A suspended survey is one that has been published, but is not currently available to participants. The "Survey Suspended" page text is what participants will see if they come to your survey when the survey is suspended.
To customize the message on this page:
The save page appears when a participant clicks the Save button. This saves the participant's responses so he/she can continue the survey later. See Setting up Save and Restore for details.
The Cascading Style Sheet(CSS)/JavaScript page is a place where custom CSS and/or JavaScript code can be set and included on every survey page. The content specified on this page is inserted between the tags on every page of the survey.
This page text can be edited by selecting the Edit > Preferences... menu option, clicking the Page Text tab, and then selecting the Cascading Style Sheet(CSS)/Javascript option in the Set text for: poplist.
Custom CSS styles must be defined between style tags. DatStat advises naming custom CSS styles with a custom prefix (e.g. “.__”) in order to avoid collision with the built-in DatStat survey styles.
Example of a custom CSS style:
This page can also be used to modify a built-in DatStat survey style. These styles are subject to change between versions of the product but such changes are not common. DatStat advises caution to customers changing the built-in styles and, if possible, recommends thorough testing of active surveys before upgrading to the next version. There are no guarantees that changing a built-in style will work on the next version of the product.
Custom JavaScript must be defined between script tags. This JavaScript code can either be inline or reference a resource. The JavaScript placed on this page cannot directly reference form elements because the content of this page is placed between the head HTML tags, however, form element objects can be passed as function arguments to JavaScript functions declared on this page.
Example of inline JavaScript:
Example of referencing JavaScript source from a resource:
Illume surveys include a standard set of buttons for common actions such as navigating forward or backward, submitting a survey, saving a survey, etc.
You can customize the text and positioning of these buttons, and configure them to use images instead of the standard browser buttons with text.
To customize survey buttons, follow these steps:
Illume surveys include the following buttons:
To set the text for any button, click on the name of the button in the Buttons list, then type the text in the Button Text field. Your changes will take effect when you click OK.
To replace a simple HTML button with an image:
This brings up the Button image editor.
When you set a button image, the text in the Button Text field becomes that alt text of the button. Alt text appears when the mouse hovers over the button and when the browser is unable to load or display the image.
Each button can appear in more than one place on your survey pages. To place a button, select the button from the Buttons list, then check one or more of the Placement options.
In some cases, you may have selected more than one button to appear in the same location on the page. For instance, you may choose to place the Previous, Save, and Next buttons in the bottom center of the page.
To set the order in which these buttons display,
Survey parameters are custom variables consisting of a name and a value. Generally, you use them to display data that may appear in several places throughout the survey and/or data that may have to change frequently.
For example, if you administer an employee satisfaction survey every quarter you may create a parameter called "quarter", and then change the value of this parameter from "Spring" to "Summer" to "Fall" to "Winter", as necessary.
In question prompts, text and HTML throughout your survey, place the marker {ParamValue:quarter} wherever you want the quarter to appear. Illume will automatically replace {ParamValue:quarter} with the value of the "quarter" parameter when it displays pages to survey participants.
Similarly, if your questions ask participants about a specific product, you may want to create a parameter for the product name. Then, if you want to ask the same questions about another product in the future, you can retrieve the questions from the repository, drop them into a new survey, and change the product name parameter in the survey to the name of the new product. Illume will then automatically insert the new product name into all the question prompts.
To set survey parameters, follow these steps:
To delete a parameter, click in the gray column to the left of the parameter name. This highlights the parameter name and value. Press the delete key on your keyboard.
To display a survey parameter in a question prompt or in the survey's HTML, simply type {ParamValue:NAME_OF_PARAMETER}, substituting the actual parameter name for NAME_OF_PARAMETER. Illume will display the proper parameter value when the survey appears in the previewer, or in a participant's browser. For more information about adding custom HTML to your survey, see "Using the HTML Editor."
All Illume surveys include a set of default error messages. These are messages that participants will see when they fail to provide a valid response to a survey question.
Note: You can also create a custom error message for any question in your survey. See Setting a Question's Response Guides. A default error message appears only for questions that does not have a custom error message.
To customize your survey's default error messages, follow these steps:
Illume surveys include the following default error message types:
Default error messages include special parameters to make them meaningful for participants. Each of these parameters is replaced by a relevant value while the survey is running.
For example, if you define this default error message:
The value, {Response}, specified in question #{QNum} is greater than the maximum allowed value of {MaxValue}.
When a participant provides an invalid response, Illume replaces these three parameters with 1) the participant's response, 2) the number of question to which the participant was responding, and 3) the maximum allowed value for the particular question.
As a result, the actual error message that a participant sees will look like this:
"The value, 150, specified in question #12 is greater than the maximum allowed value of 100."
Default error messages can use the following parameters:
Illume's Survey Styles Editor enables you to define styles that will be applied throughout your survey. Style can be set broadly, at they survey level, or more narrowly to items such as buttons or question prompts.
To define styles:
Illume uses Cascading Style Sheets (CSS) to define the fonts, colors, borders, and other stylistic elements of your survey. The styles you define will apply to the selected object and to all of the items contained within the selected object, except where you explicitly define those properties differently. To understand what this means, look at the left pane of the Survey Styles Editor. It shows a hierarchy of survey objects. At the top of the hierarchy is the object called Survey. If you choose the Survey object in the left pane and then define properties like font, color, etc., those properties will be applied to all objects within the survey, except where you explicitly define them differently. Similarly, if you define properties for Question, those properties will apply to Questions and to all of the sub-items below it in the hierarchy: Question Numbers, Question Prompts, Scale Labels and Values, Question Error Messages, etc. To override these settings in any of the Question sub-items, select the sub item and define the properties you want.
Example: You want your survey to use Verdana font throughout, and to display black text everywhere except in the question prompts. The question prompts should use bold blue text in the same Verdana font. To do this, you would follow these steps:
When you add a question prompt, a response option, or some custom HTML to your survey, Illume provides an HTML editor that enables you to format your text as you compose it. What happens if your Survey Style says the font color should be blue and you used the HTML editor to make some green text? The text will be green. Any formatting you apply in the HTML editor overrides the formatting from the Survey Styles Editor.
You can set styles for the following objects. Note that not all styles apply to all objects. For example, you cannot set border properties for Radio Buttons and Checkboxes because these items do not have borders.
| Object | Definition |
| Survey | Properties you apply to the Survey object will apply to all parts of your survey where those properties are not otherwise defined. |
| Header | The header appears at the top of each page of your survey. You define header content in the Page Text tab of the Survey Preferences Editor. |
| Progress Bar | The progress bar (if enabled) appears on all pages of the survey to indicate how far a participant has progressed. |
| Collection | Properties applied to a collection are applied to all elements within all collections. |
| Text/HTML | Properties applied to Text/HTML objects will affect all Text/HTML objects, but note that any formatting you apply within the HTML editor will override the style properties. |
| Collection Error Messages | These are error messages that are not associated with a particular question. Examples include messages for invalid logins and attempts to submit a survey more than once. |
| Question | Properties applied to questions will affect all parts of all questions (prompts, response options, question numbers, etc.) except where overridden. |
| Question Number | The Question Number appears to the left of each question prompt in the survey. (Question numbers will not appear of question numbering is disabled in the Survey Preferences.) |
| Question Prompt | The Question Prompt is the text to which participants respond. |
| Scale Labels and Values | Scale Labels are the response options from which a participant chooses when answering a question. Scale Values are the values associated with each label. Generally, only Labels are displayed to the participant. |
| Alternating Radio Scale Labels | This sets the background color of even numbered scale items in radio type questions. |
| Alternating Checkbox Scale Labels | This sets the background color of even numbered scale items in check all that apply questions. |
| Question Error Messages | Question Error Messages are the messages participants see when they have failed to supply a valid response to a question. Note that most error messages for most users will appear as JavaScript alerts (the little pop-up dialog with the OK button). You cannot set styles for JavaScript alerts. This is a limitation of browser technology, not a limitation of the Illume product. Any errors that are not caught by the JavaScript validation will be caught by the Illume server, and the server will display an error message in the current page of the survey. When you define styles for Question Error Messages, the styles are applied to these messages. |
| Input Controls | Input controls include items like text boxes and popup menus. Font properties apply to the text within the controls. |
| Radio/Checkbox Controls | The only property available for Radio and Checkbox controls is ControlSize. Set this to a numeric value to set the height and width of the controls. A value of "20" will set the height and width to 20 pixels. A value of "20pt" will set the height and width to 20 points. |
| Question Tables | Question Tables are groups of questions that share a common set of responses. The prompts for each question appear in the first column of the table, and the response options appear in the following columns. Any attributes you set for Question Tables will apply to Row Headings, Column Headings, Alternating Row and Alternating Column, unless you specifically override the settings in any of those objects. |
| Sub-Question Number | Properties you define here apply to the question number that precedes the prompt of each item in a Question Table. |
| Prompts | Properties you define here will apply to each individual prompt within a Question Table. |
| Column Headings | Column Headings in Question Tables appear at the top of each of the columns that contains a response option. The text of the response options is printed in the column headers. |
| Alternating Row | Alternating Row properties will be applied to the even numbered rows in a Question Table. |
| Alternating Column | Alternating Column properties will be applied to the even numbered columns in a Question Table. The properties will not apply to the question prompts. |
| Alternating Question | The background against which survey questions appear alternates by default between white and yellow. |
| Button Box | The Button Box is the area around the buttons at the top and/or bottom of the page. It extends almost to the full width of the page, and is normally not visible. You can make it visible by setting a background color and border. |
| Buttons | The properties you set here will apply to all of the buttons in your survey. |
| Footer | The footer appears at the bottom of each page of your survey. You define footer content in the Page Text tab of the Survey Preferences Editor. |
Most style properties present a list of valid values from which to choose. Those properties that do not display a list of valid values expect you to supply numeric values. Some properties, such as font size, allow you to ignore all of the items on the list and type in a number of your choosing. Numeric values use the following units:
| Unit | Abbreviation | Description |
| Pixels | px | One pixel represents 1/72 of an inch (1/29 cm.) on most computer monitors, though it may represent 1/90 of an inch (1/36 cm.) on some monitors. |
| Points | pt | One point represents 1/72 of an inch (1/29 cm.). |
| Picas | pc | One pica is 12 points (1/6 in. or about 2/5 cm.) |
| Inches | in | One inch is 72 points, or approximately 2.5 cm. |
| Centimeters | cm | One centimeter is approximately 29 points, or 0.4 inches. |
| Millimeters | mm | One millimeter is approximately 3 points or 0.04 inches. |
| Em | em | Em-units are calculated relative to each participant's system-wide default font-sizes. |
| Ex | ex | An ex unit is the height of the letter x calculated from the participant's system-wide default font size. This height will differ for each font. |
| Percent | % | Percent values represent widths relative to the nearest block-level container. E.g. If you set the width of a button to 50%, the button will be half as wide as the table cell that contains it. |
While you may set font sizes to a numeric value such as 12pt or 16px, Illume uses em values by default to comply with Section 508 of the US Rehabilitation Act. If your survey needs to comply with Section 508, you should use em values to define font sizes because em values set font sizes relative to each participant's system default font sizes. Participants who have difficulty reading text on a computer monitor will generally use a large font size as the default. Em values respect these settings. For example, and em value of 1.00 displays text at exactly the system default point size. An em value of 1.50 displays fonts at 1.5 times the system default font size.
Items which require participants to select a single answer, such as poplists and radio buttons, may include an "unanswered" option reminding participants to answer the question.
Generally, this is a simple message, like "Select One" or "Please Answer." It appears as the first option in a poplist. In a radio group, it appears as the first answer, and is displayed in red text.
To customize unanswered data labels, follow these steps:
If you do not want the "unanswered" option to appear, leave the unanswered data label fields blank.
Beginning in Illume 3.0, all surveys include a survey-wide default setting to indicate whether responses are required or optional. This default setting applies to each question in your survey*, unless you specify otherwise.
To set the survey-wide response requirement:
While this setting provides a default, individual questions can override the default. Follow the link to the article "Setting a Question's Response Guides" below for instructions on how to override this setting for an individual question or for a group of questions.
* Note: The survey-wide response requirement does not apply to attached text fields. These are always optional by default. You can make attached text fields required on a case-by-case basis. See "Setting a Question's Response Guides" below.
Beginning in Illume 3.0, all questions inherit a survey-wide "required" setting which describes whether questions are optional or required. Each individual question within a survey can override the survey-wide option. (See the links below for more information on survey-wide and question-specific settings.)
Illume also provides a convenient way to whole sets of questions as "required" or "optional."
When you check the Always use the following setting option, the setting continues to apply to your selected questions, no matter what you do to the survey-wide "required" setting. The only way to change the setting is to manually change the "required" setting for the specific question or group of questions.
Note: The setting you apply to the selected group does not apply to attached text fields. These are always optional by default.
To add a new collection to your survey:
in the toolbar or choose Survey > Add Collection... from the menu. 
If you define a default name prefix for a collection, then the variable names that Illume assigns to the questions in this collection will all begin with that prefix. This option can be useful when you are analyzing data, since it enables you to quickly identify related variables in your data set by their similar names.
For example, if you create a collection of questions about what type of car a person drives, you may choose to call the collection "Automobile", and set the default name prefix to "CAR."
If the collection has five questions, participant responses will appear in the data set under the variable names CAR1, CAR2, CAR3, CAR4, and CAR5.
Keep in mind that whether or not you set the default name prefix, you can always override Illume's automatic question naming with names of your choice. See Creating a Question for more information.
A randomized collection is one whose contents will be displayed in random order. When you randomize a collection, each participant will see the complete set of questions in a random order.
To randomize the items in a collection, check the box next to Randomize display of objects in this collection in the Collection Editor.
When you randomize the display of items in a collection, ALL of the items will be randomized, including Text/HTML items. If you want a Text/HTML item to display before a set of randomized questions, put the Text/HTML item outside the collection.
Randomized collections cannot contain conditionally displayed items (items that have show-if conditions). The items must be either always shown or never shown.
Randomized collections cannot contain Jumps, and cannot be the target of a Jump.
Randomized collections cannot contain page breaks.
You can also reach the Collection Editor using any of the methods listed below. In each case, be sure to first select the folder in which you want to add the collection by clicking on that folder in the left pane of the survey editor.
To edit a collection, double click on the collection in the right pane of the Survey Editor, or right click on the name of the collection in the left pane of the Survey Designer and choose Edit... from the context menu.
This presents the Collection Editor. See Creating a Collection for more information on how to use the Collection Editor.
The Login Collection is used to authenticate participants and includes some special rules. See Configuring the Login Collection for details.
There are 3 ways to delete a collection:
on the toolbar.
Immediately after deleting a collection, you can undo the deletion by choosing Edit > Undo Delete from the Survey Designer menu.
To move a collection into another collection, simply drag it from it's current location and drop it into the desired folder in the left pane of the survey editor. You can drag and drop a collection from the right pane into the left pane, or from the left pane into the left pane.
To change the order in which a collection is displayed:
To create a question...
in the toolbar.Note that you can move a question from one collection to another by dragging and dropping it.
Once you've selected the collection in which you would like to add a question, you can use any of the following methods to create a new question:
General options appear on the General tab of the Question Editor and include a question's display type and prompt. The prompt is the text to which you want the participant to respond: e.g., "What is your name?"
Your question's prompt will appear in a participant's browser exactly as you type it in the prompt field. Note, however, that HTML tags within a prompt will be ignored when the question is displayed.
Note that when you select a display type, an example of the display type appears in the yellow box to the right of the Display Type list. Display types include the following:
If you are editing a multilingual survey, and you have the translation tools enabled, you will see a list of languages at the bottom of the Question Editor. Choose the language you want to edit from the list, and the prompt for that language will appear, if the question has been translated. You may edit the prompt, and your edits will apply to that translation of the prompt only.
Response options appear on the Response Options tab of the Question Editor. This is where you define a question's list of available responses.
The options available on this tab vary, depending on the type of the question. For Text Field and Commentary questions, the only item on the response options tab will be the Data Type list.
This section focuses on configuring response options for "Select One" and "Check all that apply" type questions. For information about configuring response options to Yes/No questions, see "Configuring Yes/No Response Options" at the end of this section.
To set response options...
The type of data you choose here is the type of data you will end up with in your data set for this particular question.
Generally, you use whole numbers for Select One type questions. Note that for display types Check all that apply and Yes/No , the only available data type is Yes/No. For the Commentary display type, Text is the only available data type. Text questions have the largest range of data types, permitting participants to enter almost any kind of data. See the section on Date and Time Data below for details about the date, time and date/time data types.
Users are now able to create Group Headers in Select One and Check All that Apply type questions. Group Headers label subgroups of response options.
To add a header:
Participants will see something like this:
NOTE: Group headers are purposely ignored when the question type is likert scale OR semantic differential
Randomization may be implemented in questions utilizing Group Headers. Items will only be randomized per group. If a group is anchored then that group’s items will always be displayed in that position among the other groups.
You can set a default value for your question by typing the value into the Default field. Default values are optional. The value you enter in the default field will be pre-selected the first time the participant sees this question on the survey. The participant is free to change accept the default selection. Use one of the following two methods to set the default value:
Scale values are the options from which participants may choose when responding to your question. To add numeric scale values, follow these steps:
Note that for each response option, the value is what will be stored with your data set, while the display text is what participants will see when they are reading through the question's available answers.
If you don't want to type a value for each individual response option, and you know that the values will be in sequential order, check the box labeled "Generate values automatically", and indicate the number at which the values should begin. Then you can add response options simply by typing them into the display text field and pressing Enter.
Note: If you have translation tools enabled, and your survey includes multiple translations, you can set the scale values for each language individually. Simply choose the language you want to work with from the list at the bottom of the question editor, and then edit the scale values for that language.
For each checkbox in a "Check all that apply question," you must supply a name for the checkbox and the text that should appear next to the checkbox.
Choose a name for each checkbox that will be helpful during data analysis, so the data analyst can see instantly what the participant was saying yes to when they checked the box.
A Check All That Apply question can include one or more mutually exclusive check box responses. Mutually exclusive check boxes allow survey designers to specify “Does not apply” or “Refuse to answer” type responses in Check All That Apply questions. When one of these responses is checked no other responses can be checked.
To make a response option mutually exclusive, click the Response Options tab in the question editor and then click the checkbox in the Exclusive column for the desired response option.
When JavaScript is enabled, the client web browser prevents having a mutually exclusive check box being checked when other check boxes are checked. If JavaScript is not enabled both types of check boxes (exclusive and non-exclusive) are able to be checked at the same time and this condition will be caught on the server and an error message will be displayed. The error message can be edited by clicking Edit > Preferences… and the Error Messages tab. In the drop-down menu select the error for: A mutually exclusive check box is checked when other check boxes are checked.
When a mutually exclusive checkbox is selected, the response guide for minimum # of responses is ignored if set to a value greater than 1.
You may want to display response options only under certain conditions. To set show-if conditions on a response option:
In this image above, the circle to the left of the first option is yellow because this option includes a show-if condition.
Once you click the Show-if button, the process is the same as setting a show-if condition for a question, which is described in detail in Setting Show-if Conditions.
Once you set a show-if condition for a response option, the Survey Designer displays a yellow control-type image next to the question to indicate that some response options have display conditions attached. In the image below, the question FREQ includes response options that display conditionally. For the other questions, all response options always appear.
Note that in multilingual surveys, show-if conditions apply across all translations. If you edit the show-if conditions within a single translation, the edited conditions will apply to ALL translations!
Show if logic can be applied to a Group Header. If the Group Header has show-if logic, the Header and all of the prompts below that header will not be shown unless the logic criteria are met. If all of the prompts under a specific Header are not shown due to show-if logic then the Group Header will not be displayed. At least one prompt must be visible for the Header to display.
You may want to attach a text field to a scale value, so that participants can explain their responses. For example, if one of your response options is "Other (please specify)," you should give participants a place to specify what they mean by "other." If you have not yet added the response option to the list, create the option, as described above, then check the "Attach text field" box, and click the Add button to add the option to the list. In the list of response options, you'll notice that when an item has an attached text field, the Text Field box next that item is checked. If you want to add a text field to an item that is already in the list of response options, simply check the "Text Field" box next to the item in the list. You can delete the text field by unchecking the box.
After attaching a text field to a response option, you may want to set some properties for the text field. To do so, follow these steps:
The General Tab of the Scale Text Question Editor enables you to configure the following properties:
The Response Guides tab of the Scale Text Question Editor enables you to configure the following properties:
If your survey includes multiple translations, you will obviously separate translations for any labels and error messages belonging to attached text fields. Generally, you would do this by creating a Translation Package, but in some cases, you may need to edit these items individually.
To set the label, description, and error message for an attached text in a specific language:
The changes you make to attached text field properties affect only the language that was selected when you opened the Scale Text Question Editor.
By default, Illume presents response options to participants in the same order they appear in the Question Editor. If you check the Randomize Display Order box, Illume will present the options in random order. Even when response options are presented in random order, you may want to fix the location of certain options. For example, if your question includes an "Other" or "I choose not to answer" option, you may want this option to always appear last. You can ensure an option appears in a particular place within a randomized list by checking the option's Anchored box. In the screenshot above, the 4th option, "Other," is anchored as the last item on the list. While the other three options are shuffled around, "Other" will always appear as the last option. Checking the Anchored box caused the corresponding option to appear on the survey in the same position in which it appears in the Question Editor. Thus, clicking the Anchored box next to the second option in the list, "I work part time," would cause "I work part time" to always be displayed as the second option. Similarly, dragging "Other" to the top of the list of options, and leaving the Anchored box checked would cause "Other" to always be displayed as the first response option.
To edit an existing response option:
To delete a response option:
The only available data type for Yes/No questions is Yes/No. Unless you redefine these values, "No" answers are stored as zero (0) and "Yes" answers are stored as one (1) in the survey results.
You can change this if you want by assigning scale values as described below. In some cases, you may want the value 1 to represent No. For example, if you have a calculated variable that adds up all the No answers, you'll need to set No to 1, or the calculated variable will just keep adding up zeros... which doesn't do anyone any good.
The text you type next to the No option (i.e. next to the zero) will not be displayed in the survey . It will appear in the data dictionary to describe what it means when a participant did not check the checkbox for this question.
The text you type next to the Yes option (i.e. next to the one) will appear next to the checkbox in the participant's survey.
Setting the default state for a Yes/No item to "None" or to "0" leaves the checkbox unchecked by default. Setting the default to "1" leaves the box checked by default.
Text questions can be of virtually any data type, including Date, Time, and Date/Time. Illume use's Microsoft's .NET DateTime object to store dates and times. The .NET DateTime object can represent dates between 12:00 a.m. January 1, 0001 CE and 11:59:59 p.m. on December 31, 9999. Illume considers dates outside of this range to be invalid. You can narrow the range by setting minimum and/or maximum dates in your question's Response Guides. Non-existent dates are also invalid. For example, February 29, 2005 is invalid because 2005 is not a leap year. Participant must enter dates or times in a format that .NET recognizes. In general, for the United States locale, dates in the following formats are valid:
Illume and .NET use the locale settings of the Illume server to determine dates and times. This can cause some confusion if a survey is not designed correctly. For example, if you are administering a survey to participants in both the US and the UK, you should be aware that the two locales use different date formats. A US participant entering 06/12/2006 will mean June 12, 2006, while a British participant entering the same thing will mean December 12, 2006. If the survey is running on a server whose locale is set to EN-US (English, United States), the date will always be interpreted as June 12. If the server's locale is set to EN-GB (English, Great Britain), the date will always be interpreted as December 6. This will be a problem if your question includes a minimum and/or maximum date. The British user or the US user may not be able to get past the date question simply because the participant and the server do not agree on what the date means. One way to avoid date/time problems caused by local differences is to break dates and times into separate questions, each of which is of type whole number. For example, instead of asking for a participant's birth date, ask for his or her year of birth, then month of birth, then day of birth.
The Display Properties tab of the Question Editor enables you to control some aspects of your question's appearance. The available display options are described below.
Note: If you are editing a multilingual survey, and you have the translation tools enabled, you will see a list of languages at the bottom of the Question Editor. Choose the language you want to edit from the list, and the label for that language will appear, if the question has been translated. You may edit the label, and your edits will apply to that translation of the label only. Edits to other items on this tab, such as display width and height, will affect all translations.
This option applies to Text Fields only. If you type in a label here, the text of the label will be displayed to the left of the text box, unless you check "Display label after," in which case the label appears to the right of the text field.
Examples: A "$" label would precede a text box in which participants are expected to enter a dollar amount.
A "%" label would follow a text box in which participants are expected to enter a percentage amount.
This property applies to Text Fields and Commentaries. This is the width, measured in characters, of the Text Field or Commentary.
This property applies to Commentary questions only. This is the number of lines of text that can be displayed at one time in the commentary field. Note that if participants type in more text than the field can display, a scrollbar will appear.
This option applies to Text Fields only. If you check this, the text field will display only asterisks (*) as the participant types, just as a password field on an HTML form displays only asterisks when you type in your password.
This applies to Radio Groups and Checkboxes only. By default, Illume displays all of checkbox/radio options in a single column. You can override this by setting the number of columns here.
This applies to Question Tables.
You can set the column width for question tables by typing a value in the Column Width box. The width you set here applies to each of the columns in the question table to the right of the prompts. That is, each column that contains a checkbox, radio button, poplist or text box.
To set the width to an absolute value, type in a whole number or a whole number followed by the letters px. For example, a setting of either 100 or 100px sets the width of each column to 100 pixels.
To set the columns to a relative width, use percent values like 15%. This sets the width of each column containing a response option to 15% of the total width of the table. (Keep in mind that the prompt occupies one column of the table, and this is generally the widest column, since it contains text.)
Columns with fixed width values (e.g. 100 or 100px will keep a constant width even as participants re-size their browswer windows. Columns with percentage widths will expand and contract as the participant changes the width of the browser window.
Note that if your question table includes text inputs, all browsers will force columns to be wide enough to accomodate the text boxes, regardless of the column width you assign.
This option applies to Select One type questions only. Select One questions can be displayed in any of the following formats:
The Response Guides tab of the Question Editor enables you to define what constitutes a valid response for a given question. This tab includes the following properties:
Note: If you are editing a multilingual survey, and you have the translation tools enabled, you will see a list of languages at the bottom of the Question Editor. Choose the language you want to edit from the list, and the error message for that language will appear, if the question has been translated. You may edit the error message, and your edits will apply to that translation of the error message only. Edits to all other items on this tab, such as whether the question requires a response, will affect all translations.
This indicates whether the current question requires a response. By default, all questions inherit the survey-wide Required setting. In the example above, the survey-wide preference is set to Not Required. The question itself is set to Required.
The minimum number of characters required for a valid response to this item. This applies only to Text Field and Commentary items .
The maximum number of characters allowed for a valid response to this item. This applies only to Text Field and Commentary items .
The minimum number of items that must be checked in a group of checkboxes. For example, if you ask participants to select at least three items from the list of checkboxes, you would set Min # of Responses to 3. This applies only to questions of type "Check all that apply."
The maximum number of items that may be checked in a group of checkboxes. For example, if you ask participants to select no more than three items from the list of checkboxes, you would set Max # of Responses to 3. This applies only to questions of type "Check all that apply."
Check this option and select a meta-type from the accompanying list if you want your participants' responses to be of a particular type (such as email address, phone number, etc.)
If you want the participant's response to match a regular expression, enter the regular expression here. Writing regular expressions generally requires specialized knowledge. However, you can find regular expressions to validate US and international phone numbers, zip codes, and other types of meta-data by searching the Internet.
Illume uses Microsoft's .NET implementation of regular expressions, which is documented here: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/cpguide/html/cpconregularexpressionexamples.asp
The minimum allowable value for a numeric response. Note that you may specify whether responses may not be less than (<) or may not be less than or equal to (<=) the minimum value.
The maximum allowable value for a numeric response. Note that you may specify whether responses may not be greater than (>) or may not be greater than or equal to (>=) the maximum value.
You can set both the Upper and Lower bounds to compare against values that a participant has entered in response to prior questions. That is, you can say that the answer to the current question has to greater than (or less than) the answer to a previous question. See Setting Dynamic Defaults and Bounds for details. If you are setting bounds for a question that uses the Date, Time, or Date/Time data type, see Date and Time Data in Setting a Question's Response Options for some important considerations.
This is the message participants will see if 1) they fail to enter a response when the response is required, or 2) the response they enter does not meet the question's validation requirements.
If you leave this blank, Illume will use the appropriate system-wide default error message defined in the Survey Preferences. (See Customizing Survey Error Messages for more information about survey-wide error messages.)
Illume enables you to pipe relevant data from the current question directly into a custom error message. This makes the error messages more useful to participants, and relieves survey designers of the burden of having to update error messages when questions change.
See the section on Piping Data for a detailed description of how to pipe data into custom error messages.
Illume surveys enforce response guides both in the participant's browser and on the server. If the participant's browser does not support JavaScript, response guides will be enforced by the server. When an error occurs, participants will be presented with the page they just submitted, with error messages printed above the question.
Users who have JavaScript enabled (typically more than 95% of users) will see both a JavaScript alert and the red-text error message.
Illume surveys include a data dictionary, which is available when you query and review the data your survey has collected. The data dictionary lists all variable names, question prompts, and response options.
For example, if you have a question called WINE that asks what type of wine a participant prefers to drink, the data dictionary will include an entry like this:
WINE "What type of wine do you prefer?"
0 = I don't drink wine
1 = Red
2 = White
Note: If you are editing a multilingual survey, and you have the translation tools enabled, you will see a list of languages at the bottom of the Question Editor. Choose the language you want to edit from the list, and the variable description for that language will appear, if the question has been translated. You may edit the description, and your edits will apply to that translation of the description only. Edits to other items on this tab, such as the question's unique name and whether it is "runtime only", will affect all translations.
Illume generates the data dictionary automatically. However, you may want to exercise some additional control over what goes into the data dictionary. You can do this through the Data Dictionary tab of the Question Editor, which enables you to set the following attributes:
This is the name of the variable in which responses to the current question will be stored. For example, if you name this question "HOMEPHONE," then the data that participants give in response to this question will be stored in a database field called HOMEPHONE.
The name you supply here will also appear as the name of the current question in the Survey Designer.
A unique name must start with a letter, and can contain any combination of letters, numbers, underscores (_), or hyphens (-). Unique names must be 20 characters or less in length.
If you leave the description blank, Illume automatically uses the question prompt as the description in the data dictionary. At times, however, you may want to provide more information than the prompt can give.
If you type a description here, that description, rather than the question prompt, will appear in the data dictionary. This can help you quite a bit when you are analyzing your data and you're wondering how the variable AGE1 differs from AGE2.
Check this box if you do not want responses to the current question to be stored with the rest of the data you collect in your survey. Runtime only data are available to Illume when a participant is taking a survey and are discarded when the survey is submitted. This type of data is often used in calculated variables and show-if conditions.
You can set conditions on when page breaks, Text/HTML items, questions, and collections will appear. Each of the editors for these items includes a Show-if tab that enables you to define when the item should be displayed, and when it should be hidden.
Warning: If you are editing a multilingual survey, be aware that any changes to an item's show-if conditions affect ALL translations of the survey. Each item in an Illume survey has one set of show-if conditions, and that single set of conditions applies across all translations!
The Show-if tab includes the following options:
An item set to "Always shown" will be presented to all participants, and will appear in the Survey Editor with a green circle next to its name. By default, all questions, collections, Text/HTML items and page breaks are always shown.
An item set to "Never shown" will not be shown to any participants, and will appear in the Survey Editor with a red circle next to its name.
An item set to "Only show if..." will be displayed only if the conditions you define are met. Follow these steps to set show-if conditions:
To edit existing Show-if conditions:
To remove individual show-if conditions:
To quickly remove all of an item's Show-if conditions:
To set show-if conditions on the individual prompts within a question table, follow these steps:
Early versions of Illume required all show-if conditions to be grouped with AND or with OR. Illume versions 2.1.14 and higher support complex grouping of show-if conditions. Custom grouping enables you to mix AND and OR in your show-if conditions.
To use custom grouping,
When you define the conditions you want to test, you'll see that the Question Editor assigns a label to each condition. In the image below, the test "AGE > 18" is labeled as test A. The test "DRINK = [Yes]" is labeled as test B and the test "SMOKE = [Yes]" is labeled as test C.
If we want our question to appear to all participants over the age of 18 who drink or smoke, we would type the following under Custom group expression: A and (B or C) This means, display the question if condition A is true (participant is over 18) and if either B or C is true (participant drinks or smokes). Note that parentheses are important here. Any items in parentheses will be evaluated before items not in parentheses. In this example, Illume will first check to see if either conditions B or C is true. If either one is true, Illume will go on to see if condition A is also true. If either one of B or C is true, and A is also true, Illume will display the question. The following grouping would give a completely different result: (A and B) or C In this grouping, Illume will display the question if both A and B are true (participant is over 18 and drinks) OR if C is true (participant smokes).
If your expression uses nested parentheses, the more deeply nested parentheses are evaluated first. For example, in the following expression: A and (B or (C and D)) Illume first checks to see if conditions C and D are both true. Illume then checks to see if B is true (if necessary-- this expression requires only that one item inside the blue parentheses be true). Finally, Illume checks to see if A is true. Each parenthesized expression is always reduced to a single true or false value. In the following example, let's assume that underlined conditions are false and non-underlined conditions are true. (A and (B and (C or D or (E and F)))) Here is how Illume interprets the expression: Starting within the purple parentheses, Illume sees that condition F is false. Because E and F are not BOTH true, the entire expression within the purple parentheses is then false. So now we have this: (A and (B and (C or D or false))) Illume then looks at the items in the red group. Because these are grouped with OR, if any one of the conditions is true, the whole parenthesized expression is true. Illume sees that false is not true. It sees that condition D is not true. It sees that condition C is true. Now the entire group within the red parentheses is true. (A and (B and (true))) Illume then sees that both B and the condition that follows B are true, so the entire green expression becomes true. (A and (true)) Now Illume sees that both A and the condition that follows A are true, so the entire blue expression is true. (true) Illume has reached the outermost condition, and it is true, so Illume will display this item.
A question block is a group of questions that shares a common set of response options. Generally, a question block will have three components: instructions, prompts, and a set of response options.
Instructions tell the participant what type of response is expected. For example, "Please indicate the extent to which you agree or disagree with the following statements."
Prompts are the individual items to which participants respond. A question block that uses the instructions above may include prompts such as:
The final component in a question block is a set of response options shared by all of the prompts. In the example above, each of the prompts would include the following options:
Note: If you are editing a multilingual survey, and you have the translation tools enabled, you will see a list of languages at the bottom of the Question Table Editor. Choose the language you want to work with from the list. You may edit most text properties (prompts, scale values, error messages, etc.) in each language individually (though it's much easier to create a Translation Package and do all of the translation at once). Display and show-if properties apply across all translations.
The general tab of the Question Table Editor provides a list of display types. When you choose a type from the list, you'll notice that a sample appears to the right of the list showing what the selected display type looks like.
The Select One display type actually shows two samples: one with radio buttons and one with poplists. When you choose the Select One display type, you must use the "Select-one style" list in the Display Properties tab to indicate whether the collection should use radio buttons or poplists.
Type the instructions for your question block into the Instructions entry under the General tab. These instructions will appear above the collection's set of prompts.
To add prompts to the collection, click the Prompts tab. For each prompt you want to add, type the prompt into the Prompts box and press Enter (or click the Add button). You'll see that each new prompt appears in the list of prompts at the bottom of the Question Table Editor.
To edit an existing prompt, click on the prompt in the list, make your changes to the prompt's text in the Prompts box, and click Replace . (Note that if you press the Enter key instead of clicking Replace, you will create a new prompt.)
To delete a prompt, click on the prompt you want to delete (it should be highlighted against a blue background once you click on it) and then click the Remove button.
To set other properties of a question block, see the descriptions of how to set question properties: Setting a Question's Response Options, Setting a Question's Display Properties, Setting a Question's Response Guides, Setting Data Dictionary Options, and Setting Show-if Conditions. You can set show-if conditions on the individual prompts within a question table! Follow the link to Setting Show-if Conditions below.
Questions Tables may have both Response Headers as well as Prompt Headers. Response Headers are labels that apply to multiple column headers, e.g. "Gender" might be a response header for the column headers "Male" and "Female".
Adding Response Headers to a Question Table
Response Headers are added to Question Tables in the same way as standard response options. They are only available for Select One and Check All That Apply Display Types.
To add a response header:
Adding Prompt Headers to a Question Table
Prompt Headers can be used with all of the Display Types in a Question Table. Prompt Headers are created by selecting the Prompts tab in the Question Table Editor and checking the “Group header” box. Prompts can me moved up and down in the list by clicking and dragging.
Example Question Table with Response and Prompt Headers
Every item in an Illume survey must have a unique name. Items include questions, collections, Text/HTML objects, page breaks, and survey resources.
Illume automatically assigns a unique name to each object when it is created, but you may want to assign a more meaningful name.
A unique name must start with a letter, and can contain any combination of letters, numbers, underscores (_), or hyphens (-). Unique names must be 20 characters or less in length.
To edit an existing question:
This brings up the Question Editor. For information about setting specific attributes of the question, see Setting a Question's General Options, Setting a Question's Response Options, Setting a Question's Display Properties, Setting a Question's Response Guides, Setting Data Dictionary Options, and Setting Show-if Conditions.
You can add comments to any question, Text/HTML item, or page break in a survey. Comments are available only to those editing the survey; participants cannot see them.
Once you check your survey in to the repository, any comments you added in the most recent round of editing become read-only. Others may contribute additional comments, but neither you nor anyone else can alter the comments you checked in.
To add comments from within the Survey Designer:
in the toolbar. In the Previewer, you can add comments only to questions. To add comments from the Survey Previewer
next to the question prompt. You can review and edit comments to any question, Text/HTML item, or page break in a survey. Comments are available only to those editing the survey; participants cannot see them.
You may edit any comments that have not yet been checked in to the repository, but you cannot edit comments that have been checked in.
To review all survey comments at once, select View > Review All Comments... from the Survey Designer menu.
To edit or review comments from within the Survey Designer:
In the Previewer, you can add comments only to questions. To review or edit comments from the Survey Previewer, simply click the Comments icon next to the question prompt.
The spell checker checks spelling as you type in any of Illume's HTML editors, underlining misspelled words with a wavy red line. The spell checker checks spelling as you type in question prompts, response options, and Text/HTML items.
To correct the spelling of any misspelled word, right-click on the word, and choose one of the suggested spellings from the list.
If the correct spelling is not in the list, click within the HTML editor to make the context menu disappear, then manually correct the spelling.
If the spelling of the word is correct, but the spell checker identifies it as incorrect, the context menu provides two options:
When Include item descriptions is checked, Illume will find and replace text within the data dictionary descriptions of questions and question tables. This is the text that appears on the Description tab of the question editor and in the description field of each item in the data dictionary.
Illume can spell check an entire survey at once, including:
To spell check an entire survey at once click Tools > Spell Check... Illume will read through the survey, stopping at each potential misspelling. Illume loads the text containing the misspelling into the HTML editor, with the misspelled words underlined in red. Right-click on any misspelled word to view the list of suggested spellings.
The survey-wide spell checker includes a Revert to Saved button that will undo any changes made by the spell checker in the text currently displayed.
After correcting a word in the survey-wide spell checker, click Next Error to resume spell checking.
You can limit the spell check operation to a single item or to a group of items by selecting the item(s) in the survey designer before choosing Spell Check... from the Tools menu.
To choose a single item for spell checking, simply click on the name of the item in the Survey Designer. To choose multiple items, hold the Control key and click each item individually. Holding the Shift key while you click selects every item between the the item you are clicking on and the last selected item.
When working within a group of selected items, checking Include items within selected collections will extend the find and replace operation into each of the collections that you have selected.
Because Illume uses Microsoft Word's spell checker, you must have Microsoft Word 2000 or later installed in order to use spell check.
When the spell checker replaces an individually formatted word (for example, an italicized, bolded or underlined word), Illume may not preserve the formatting when it replaces the word.
The spell checker will work for each language in a multilingual survey, provided:
The Survey Designer's Find and Replace feature can find and replace text in any of the following items:
By default, Find and Replace operates on the entire survey. You can limit the find and replace operation to a single item or to a group of items by selecting the item(s) in the survey designer before choosing Find and Replace... from the Edit menu.
To choose a single item for find and replace, simply click on the name of the item in the Survey Designer. To choose multiple items, hold the Control key and click each item individually. Holding the Shift key while you click selects every item between the the item you are clicking on and the last selected item.
To find and/or replace all instances of word throughout your survey, follow these steps:
Find Next and Replace display the next result of the word search in the HTML editor, giving you a chance to review the text before you decide to make a replacement. If you do want to replace the highlighted word, click Replace again to make the replacement.
Clicking Replace All will replace all instances of a word within the survey without asking you to confirm. Illume simply reports the number of occurrences replaced when the operation is complete. You cannot undo the Replace All operation.
The Start Over begins a new search from the beginning of the survey document.
By default, find and replace operates on your entire survey. If you selected one or more survey items before starting Find and Replace, you can check the Selected items only option to limit the operation to the items you have selected.
When working within a group of selected items, checking Include items within selected collections will extend the find and replace operation into each of the collections that you have selected.
The Include variable references is useful in surveys that include near-identical collections of questions.
For example, your survey may ask the same 10 questions about a participant's mother and father. The easiest way to build this survey would be to create a collection of the 10 "mother" questions first, and then to copy that entire collection and name the copy "father."
When you copy the collection, Illume asks you to rename each of the questions. In this example, the question names may change from "AGE_MOTHER," "OCCUPATION_MOTHER," etc. to "AGE_FATHER," "OCCUPATION_FATHER," etc. There may be several places in the original collection that pipe data from reponses to previous questions. The piping might look like this:
How many years has you mother been working as a {OCCUPATION_MOTHER:Response}?
In the collection of questions about the father, you would obviously want the reference in the new collection to look like this:
How many years has you father been working as a {OCCUPATION_FATHER:Response}?
Running Find and Replace with the Include variable references option checked will make this replacement for you.
To undo a find and replace operation:
The Revert to Saved button at the bottom of the Find and Replace dialog undoes changes to the text currently being displayed in the HTML editor.
This article describes how to rename whole groups of questions, collections, and other survey items in a single operation.
Because the Rename feature includes so many options, the best way to understand how it works is to experiment. Follow steps 1 and 2 below, try various options, and click Generate Names. The Rename Summary display will show the new names produced by the various options you select. None of the new names will be applied until you click Rename, so you can experiment without affecting your survey.
To rename a several questions at once, follow these steps:
As noted above, Illume does not actually rename any items until you click the Rename button.
If you do rename items and then want to undo the changes, choose Edit > Undo Rename Items from the Survey Designer menu, or press Control-Z.
You may not undo the rename operation after performing another undoable action such as Spell Checking or Find and Replace.
Beginning in Illume 3.0, all questions inherit a survey-wide "required" setting which describes whether questions are optional or required. Each individual question within a survey can override the survey-wide option. (See the links below for more information on survey-wide and question-specific settings.)
Illume also provides a convenient way to set whole groups of questions as "required" or "optional."
If you selected a mix of questions and collections, and you want your setting to apply to all of the items within the collections you have selected, check the box labeled Include items in selected collections.
When you check the Always use the following setting option, the setting continues to apply to your selected questions, no matter what you do to the survey-wide "required" setting. The only way to change the setting is to manually change the "required" setting for the specific question or group of questions.
Note: The setting you apply to the selected group does not apply to attached text fields. These are always optional by default.
In a multilingual survey, response guides, such as whether or not a question is required, apply across all translations of the survey. You may set error messages individually for each translation, as described in Setting a Question's Response Guides.
To quickly find a survey item by name, use the Go to item list at the bottom of the survey designer. Start typing the name of the item you want to find, or simply click the arrow to browse the list. The survey designer will find and highlight the item selected in the list.
Quota management is an add-on module that provides survey designers with a mechanism to control the number of survey respondents, meeting a specified set of criteria, who are allowed to participate in a given survey. When purchased, this module can be enabled with a license modification from DatStat Customer Support.
A survey may have one or more quota group objects, each containing multiple quotas, which define the criteria limiting the number of respondents submitting data for that survey.
To add quotas the user must create at least one Quota Group Object. The Quota Group Object will set the criteria for the quotas it contains.
The position of the Quota Group Object in the survey should be carefully considered, as the Quota Group Object and the Quotas it contains will be evaluated wherever it is placed in the survey.
The first step in adding a quota is to create the Quota Group Object.
One or more quotas can be defined for a quota group object
NOTE: The ordering of quotas may be used to determine priority if a maximum number of quotas is specified (see below) and the quota selection rule is determined by the order in the list. The ordering of the quotas can be changed by simply selecting a quota and dragging it up or down in the list.
There are three conditions that can be set on a Quota:
There are a number of options that apply solely to an entire quota group. See the segments below for more information on these options.
The Auto-Suspend Options are used to suspend the survey when one or more of the quotas are filled. Users are limited to one option being selected per Quota Group Object.
The options are:
NOTE: Testing the Auto-Suspend Options is only possible in a published version of the survey.
The Quota Minimums ensure that participants meet a minimum set of the created quotas to either continue with the survey or for their data to be counted in any quota limits.
Checking the box under “Quota Minimums” will activate the Quota Minimums limit. Once checked, using the drop-down box users may select the minimum number of quotas to be met before the participant may continue.
Users may then select what should happen if the participant does not meet this minimum limit. The choices are:
The Quota Maximum puts a limit as to the number of quotas that a participant can be included. If this number is exceeded then only the maximum number of quotas specified will be selected using a quota selection rule.
Checking the box under “Quota Maximums” will activate the Quota Maximums limit. Once checked, using the drop-down the users may select from the Maximum number of quotas the participant may meet, based on the number created in the Quotas tab.
After evaluating the quota conditions, if a participant exceeds this maximum number of quotas, only the maximum number of quotas determined to have a higher priority will be selected. The following lists these rules and how the priority is determined:
If one of your survey items exists in the repository, you will not be able to edit certain properties of that item. Repository items are marked by one of the following icons:
Repository Question 
Repository Text/HTML Item 
Repository Collection 
Repository Collection (Open) If you must edit these properties, you can break the item's link to the repository. 
One of the benefits of repository items is that they are guaranteed to be the same in all of the surveys that use them. This makes them ideal for Cross Survey Views, which show responses to similar questions across multiple surveys.
One alternative to breaking the question's link to the repository is to update the question directly in the repository, and then to get the latest repository version. Updating the question in the repository will not affect any existing surveys that use the repository item. All future surveys, however, will use the newest version of the item. Note that updating repository items may require special privileges. For more information, see Editing Repository Items and Getting the Latest Repository Version.
If your survey includes an item from the repository, and the item has been updated in the repository after you added it to your survey, you will need to manually retrieve the updated version if you want to include it in your survey. Repository items are marked by one of the following icons:
Repository Question Repository Text/HTML Item Repository Collection Repository Collection (Open) This is by design. Illume will not automatically update repository items in your surveys, for reasons described in the Editing Repository Items. To get the latest repository version of an item, simply click on the item in the right pane of the Survey Designer and choose Get Latest Repository Version from the Repository menu. (This option is also available from the context menu.)
If there is a newer version to get, Illume will display a message confirming that it has retrieved the latest version. Otherwise, Illume will not present any message.
Piping usually refers to the practice of inserting the response from one question into the prompt of another question. For example, if a participant indicates in question #3 that he drives a Toyota, that information can be piped in to the prompt for question #10, which may ask "How satisfied are you with your Toyota?"
Illume expands on this idea, enabling you to pipe several types of data into a variety of locations.
You can pipe data by including a variable name enclosed in curly braces in the text where you want the data to appear. Illume will replace the variable with its value while the survey is running. See the specific descriptions and examples below for more information.
Illume can pipe data into question prompts, scale values, Text/HTML objects, error messages, question default values, and the upper and lower bounds of a question's response requirements.
Illume supports piping of:
To pipe a participant response into a question prompt, or into a Text/HTML object, use the tag {Response:QuestionId}, where QuestionId is the unique name of the question whose response you want to pipe in.
For example, you have a question with the unique name "AUTOMOBILE" that asks what type of car a participant drives. The list of responses includes Ford, Chevy, Toyota, etc.
You want to pipe this question's response into a later question that asks how satisfied a participant is with his or her automobile. You would write the prompt for the satisfaction question like this:
How satisfied are you with your {Response:AUTOMOBILE}?
Participants who indicated that they own a Ford will see "How satisfied are you with your Ford?" Those who said they own a Chevy will see "How satisfied are you with your Chevy?"
Piping tags are not case sensitive. That means {RESPONSE:QUESTIONID} and {response:questionid} will yield the same result.
If you need to pipe data from text fields attached to checkboxes or radio buttons, see Piping Data from Attached Text Fields below.
Because checkbox questions permit a participant to select multiple responses, the Response tag produces a comma-separated list of responses. For example, a checkbox question FOODS asks a participant to check each of the foods he or she has eaten in the past week. If the participant checks 10 items, then {Response:FOODS} will produce a comma-separated list of those 10 items. The list includes the labels that the participants saw, not the numeric codes that will be stored in the database. So you {Response:FOODS} would produce a piece of text like Peas, Carrots, Potatoes, Apples, Chocolate, etc.. The {Value} tag also behaves differently when applied to checkboxes, returning the number of items checked. Continuing the example above, the tag {Value:FOODS} would return the number 10 because the participant checked 10 items in the list.
Illume enables you to upload participant lists, which define the login names and/or passwords of participants who will be permitted to take your survey.
These participant lists may contain additional information about participants, such as first and last names, email addresses, or any other data you choose to include.
You may want to pipe this user data into your survey; for example, to welcome participants by name, or to display their email address as a pre-selected response option (so they don't have to type it in themselves).
Let's assume your participant list includes a piece of user data called FIRSTNAME that contains a participant's first name. To greet participants after they log in, you would include a Text/HTML object with the following text:
Greetings {UserData:FIRSTNAME}! Thank you for taking the time to visit our survey! Note that the following built-in variable exist for all participants on all Illume surveys, whether or not you have assigned them a value:
Preloaded and hidden data can have several purposes. For example:
The article on Hidden Variables and Preloaded Participant Data provides information on how to create these variables.
When you want the value of a hidden or preloaded variable to appear in a hidden input on a survey page, use the {Hidden} tag.
For example, adding the tag {Hidden:IQ} to a Text/HTML object causes Illume to output the following hidden HTML element on the survey page:
Q9$1" value="<current value>" />
Note that current_value will be the current value of the variable IQ. Q9$1 is the internal variable name. Generally, you cannot anticipate what this name will be.
Once the hidden variable is on your survey page, you can get the value of the hidden variable through JavaScript using the following:
var iq = document.DatStatForm.{FormElement:IQ}.value;
You can set the value like this:
document.DatStatForm.{FormElement:IQ}.value = 210;
When you set this value with JavaScript, Illume will save the value when the participant submits the current page (i.e. clicks next, previous, save or submit).
Parameter values are described in detail in the article Working with Survey Parameters. To pipe parameter values into your text, use the tag {ParamValue:PARAMNAME}, where PARAMNAME is the name of the parameter whose value you want to pipe in.
You can pipe the following information about a question into the question's custom error message:
For example, if your question requires a numeric answer between 1 and 100, you may write a custom error message like this:
The value "{Value}" that you entered for question #{QNum} is not valid. Please enter a value between {MinValue} and {MaxValue}.
Participants will see an error message like this:
The value "I don't know" that you entered for question #12 is not valid. Please enter a number between 1 and 100.
This type of custom error message is helpful to both participants and survey designers. The message is specific enough to inform the participant of exactly what is wrong, and where.
The use of parameters ensures that the designer will not have to rewrite the error message if the question's minimum and maximum values change, or if the question is assigned a new question number.
As noted under Participant Responses above, you can pipe the response from one question into the prompt for another question. You can pipe values into the default value of a question. For details, see Setting a Question's Response Options. In addition, you can pipe values into the upper and lower bound fields of a question's response requirements. This enables you to say that the answer to question C must be a value greater than the answer to question A and less than the answer to question B. For details, see Setting a Question's Response Guides.
Illume surveys include three built-in objects that can be piped in to question prompts, responses, error messages, and/or Text/HTML objects:
You can pipe data from a text box that is attached to a checkbox or radio button. For example, you have the following question whose name is ASSOCIATION:
You can pipe the text a participant entered into the text fields attached to each of the "Other" options by referring to one of the following variables: {Response:Association.Text} Retrieves the response from the text box next to Other Professional Association. {Response:Association.Text2} Retrieves the response from the text box next to Other Amateur Association.
{Response:Association.Text3} Retrieves the response from the text box next to Other Misc. Association. If your radio button or checkbox question has only one attached text field, the tag to retrieve the text from that field will always be {Response:QuestionID.Text}, where QuestionID is the unique name of your radio button or checkbox question. You can get the text from any subsequent attached text fields by using {Response:QuestionID.Text2}, {Response:QuestionID.Text3}, etc.
Note that the number of the text field (Text2, Text3, etc.) refers to the order in which the field was created, not the order in which the field appears. This allows you to reorder the responses to your checkbox/radio button question without having to modify any of the piping tags that exist elsewhere in your survey.
If you ever find yourself in a situation where you cannot figure out which attached text field is Text2, which is Text3, etc., do this: Open Microsoft WordPad. This is a free application that comes with Microsoft Windows. It's available from the Accessories section of the Windows Start menu. Drag the radio button/checkbox question out of the Survey Designer and drop it into WordPad. This will reveal the XML behind the question.
Each attached text field in the question includes a Description element and an attribute called textQuestionName. Look for the description that matches the textfield you're interested in, and get the field's name from textQuestionName (which usually appears on the line above the description).
All Illume surveys contain the following built-in variables. Note that variable names are not case sensitive.
User Data comes from participant lists uploaded through the Illume Web Console. These are data that you supply about your participants. Illume surveys always include the following variables for each participant on a participant list. Except for ID, if you do not define these variables, they will simply contain empty values.
Participant response data refers to data that an individual participant has submitted in response to a survey question. These data are not available until the survey is running. You can access any participant response using the variable {Response:QuestionName}, where QuestionName is the question's unique name. See Piping Data for practical information on how to pipe participant responses into custom text or into the prompt of a new question.
ProgressBar and PercentComplete appear in the header of the default survey template to remind participants of how far they have progressed through the survey.
See Composing an Email Message for details about the context in which these tags may appear.
See Setting up Save and Restore for information about the context in which these tags may appear.
Note: The Save Email that Illume sends to the participant is an HTML formatted email. Illume does not send a plain text version.
These are not really built-ins. Parameters are variables whose names and values you define for an individual survey. For example, if you want surveyadmin@yourcompany.com to be the email address to which participants write for help, you can define a parameter called "help" and set its value to surveyadmin@yourcompany.com. You can display the variable on any page of the survey, or in the header or footer, or in a question prompt or error message by using the placeholder {ParamValue:help}. Like built-ins, parameter names are not case sensitive, so {ParamValue:help} works the same as {PARAMVALUE:HELP}. If you ever need to change the help contact, simply change the value of help parameter, and Illume will update it everywhere it appears in your survey. See Working with Survey Parameters for details on how to define parameters. See Piping Data for information on how to display parameters in your survey.
In versions 2.2 and later, Illume supports dynamic question default and bounds. This means you can set a question's default response, upper bound, or lower bound to a value from one of the following sources:
Questions that use a numeric data type allow you to define the upper and lower bounds of a valid response. You set the bounds in the Response Guides tab of the Question Editor, or in the Response Guides tab of the Attached Text Field editor (if you are working with a text field that is attached to a select-one or check all question).
For example, assume you have a question called CURRENTWEIGHT that asks a participant's current weight. Earlier questions asked for the participant's minimum weight (MINWEIGHT) and maximum weight (MAXWEIGHT) over the past 12 months. If you want to ensure that the participant enters a current weight that is between his minimum weight and maximum weight, you would set the Lower Bound of CURRENTWEIGHT to {Value:MINWEIGHT} and the Upper Bound to {Value:MAXWEIGHT}.
When the participant is taking the survey, Illume substitutes the participant's answers to the MINWEIGHT and MAXWEIGHT questions for the {Value:MINWEIGHT} and {Value:MAXWEIGHT} tags. There is some risk in doing this: if the participant did not answer MINWEIGHT or MAXWEIGHT, or if the answers to those questions were not numeric, Illume will not try to validate the answer. If you are going to take advantage of dynamic bounds, you should adhere to the following practices:
Dynamic default values work just like dynamic bounds: you can pipe a participant response using the {Value:QuestionId} tag, data from the participant list using the {UserData:FieldName} tag, or a survey parameter using the {ParamValue:FieldName} tag.
As with dynamic bounds, there are a few things to keep in mind when piping one question's response into the default value of another question:
If a question uses response options and no default option is set, the option that will be selected when a participant first sees the question is the "unanswered" option. You can set the text of the "unanswered" option on the Data tab of the Survey Preferences editor. See Customizing Labels for Unanswered Items. The "unanswered" option exists only when the text for the unanswered option is not empty. To remove the default value, simply delete whatever is typed into the default field.
To add text, HTML, or images to your survey, or to embed items like Flash animations, movies, Java applets or sound clips, use the HTML editor.
To add any of these elements to your survey:
You'll notice that the Text/HTML editor includes a Data Dictionary tab. While you can give the Text/HTML item a unique name and a description, this information does not actually go into the data dictionary. The information is simply for your own reference.
Text/HTML items will be shown to all participants, appearing in the same order in which they appear in the Survey Designer. That is, if the Text/HTML item appears after the question called "INCOME" in the Survey Designer, it will appear after the question called "INCOME" in the participant's survey.
You can move a Text/HTML item to any location in your survey by simply dragging it from its current location and dropping it into the desired location. Moving the item up will cause it to be displayed earlier; moving it down will cause it to be displayed later.
You can also apply show-if conditions to a Text/HTML item, so that it will be displayed only when the conditions you describe are met. For information on how to create Show-if conditions, see Setting Show-if Conditions.
Illume's HTML editor enables you to create HTML pages, or parts of pages, without any knowledge of HTML.
Except for parameters and built-in survey variables, any content you create in the HTML editor will appear in a participant's browser exactly as it appears in the editor.
In the HTML editor, survey parameters and built-in variables appear as variable names enclosed in curly braces, such as the built-ins {PercentComplete} and {ProgressBar}. When a survey is running, Illume automatically calculates and displays the values of these parameters, so that survey participants see an actual progress bar and their current completion status. While {PercentComplete} and {ProgressBar} are built in to all Illume surveys, you can define other parameters as you please. See the section on Parameters for more information.
The HTML editor works like a word processor. For example, to set the font of a section of text, first highlight the text by clicking and dragging the mouse across it. Then choose the font, color, size, justification, or other attributes you wish to apply. Click once anywhere in the editable area to deselect the text, and you will see that the formatting has been applied.
Note: If you are working on a multilingual survey, and you have translation tools enabled, you will see a list of languages at the bottom of the Text/HTML editor. Choose a language to edit the Text/HTML for that specific translation. Any changes you make the Text/HTML, or to the Description (on the Data Dictionary tab) will apply only to the selected translation. Any changes you make to the unique name of the Text/HTML item, or the the show-if conditions, will apply to ALL translations.
To add an HTML table, move the cursor to where you want the table to be, and click the Insert table button on the toolbar. Currently, the editor supports only tables consisting of a single row and a single column. If you understand HTML, you can create more complex tables by editing the HTML directly, as described below.
To add an image to your HTML, follow these steps:
You can define the following image attributes:
To delete an image in the HTML editor, simply click on the image and press the delete key.
To add a link to your HTML, follow these steps:
Note that when a participant clicks on a link, the page will load in the participant's current browser window. This means that if the URL is not part of your survey, the participant will leave your survey when he or she clicks on the link!
For this reason, you may want to add external links only to the Survey End Page.
You can force the URL to load into a separate browser window by editing the HTML directly (see below). To do this, locate the link in the HTML, and add the attribute target="_blank".
That is, you would change this markup:
to this markup:
To edit a link:
To delete a link:
You can copy and paste text directly from Microsoft Word into the HTML editor, and your formatting will be preserved. You can also highlight a section of a Word document and drag this highlighted text into the HTML editor. This has the same effect as copying and pasting, bringing both the text and formatting from Word.
To edit HTML directly, click on the WYSIWYG/HTML button, on the right side of the toolbar. You can switch back to WYSIWYG mode by clicking on the button again.
Illume automatically determines where page breaks are required, and creates them while the survey is running. For example, if question number 10 asks a participant's age and question 11 should ask the participant's employment status only if the participant is between 18 and 65 , then Illume will create a page break between questions 10 and 11, because it cannot know whether to present question 11 until after it receives the response to question 10.
In these situations, you cannot prevent Illume from creating page breaks. You can, however, insert your own page breaks wherever you please. To insert a page break:
The page break appears after the item you selected. You can move it to another location by dragging and dropping it.
You may add resources such as images, videos, Flash files, and sound files to your survey. The first step is to upload the resource into the survey:
Follow these steps to add a resource to your survey:
Image resources appear in the preview pane. Simply click on the name of an image in the Survey Resources list to make it appear.
To preview a text or HTML resource, click the name of the item in the list, then click the Show Text/HTML button. This button appears in the preview pane only when you've selected a text or HTML resource.
Once a resource is included in your survey, use the HTML Editor to make the resource appear where you want it to appear. See Using the HTML Editor for more information.
If you need to change the name of an existing survey resource, or upload a newer version of the resource, follow these steps:
Follow these steps to delete a resource from your survey:
Text from uploaded resources will appear in translation packages only if the uploaded resource is text-based. For example, an HTML page uploaded as a resource will become part of a translation package. Text appearing in binary resources, such as images and Flash files, will not become part of a translation package.
You can preview your entire survey at any time. When you preview a survey, you will see the survey almost exactly as a participant will see it. The only differences between what you see and what a participant will see are 1) your preview appears in a special preview window, rather than in a full browser window, and 2) the previewer puts a "Comments" icon next to each question.
The preview version of the survey also behaves exactly as the participant's will behave. All of the response requirements are enforced, all of the response validation messages work, and all of the show-if conditions apply.
To preview a survey, simply click on the Preview icon 
in the toolbar. Your survey will appear in the preview window. If your survey includes more than one language, use the language list in the lower right corner of the previewer to choose which language to display.
Click on the Comments icon next to any question, and the comments editor will appear. The comments editor displays a description of the question and any existing comments. It provides a space for you to add new comments.
Simply type your comments and click OK to add them to the question. The comment icon will appear next to this question in the Survey Designer, and the comments you typed will be available for review to anyone editing the survey.
Check this box if you want to see the entire survey at once, complete with page breaks. Checking this box presents the same view you see when you select the Preview Survey Layout option from the Survey Designer's File menu. This mode displays jumps and show-if conditions, along with the logic attached to each.
The Print Preview button at the bottom of the Preview window displays the current survey page as it would appear when printed on paper.
The Print button at the bottom of the Preview window sends the current survey page directly to your printer.
Click the Reload button to go back to the first page of the survey.
Click the Done button to close the Preview window.
To preview a survey that you have not checked out:
This preview shows the survey in print mode, rather than in interactive mode. That is, the entire survey appears on a single scrolling page, complete with question ids and comments.
If the survey includes more than one language, use the list in the lower left corner of the previewer to choose which language to display.
You can preview any question or Text/HTML item in your survey:
from the toolbar.
Note that when you preview an individual item, the previewer does not substitute actual parameter values for parameter value placeholders. It simply displays the placeholders. If you want to preview the item with the actual parameter value instead of the placeholder, you must preview the entire survey. See "Previewing a Survey" for details.
You can preview all survey pages at once by selecting Preview Survey Layout... from the Survey Editor's File menu. This presents all of the items in your survey, and displays where all page breaks will occur. Note that automatically generated page breaks are labeled "Auto-Pagebreak," while those you added manually are labeled "Pagebreak."
Unlike the regular Survey Preview, the Layout Preview does not apply show-if conditions or validate response requirements. It does however display jumps and show-if conditions, along with the logic attached to each. The purpose of this preview is to display all questions in order, and to provide a means of printing out all of the questions in a single document.
As in the normal preview mode, you can add comments to questions.
The Print Preview button presents a preview of a printout of all survey questions, in order.
The Print button prints the entire survey, as it appears in the print previewer.
The Reload button reloads the survey into the Preview window.
The Done button closes the Previewer.
To view a published survey:
To print an entire survey to paper:
Note that the printed version of the survey will differ from the browser-based version in the following ways:
You can print any individual question or Text/HTML item in your survey by following these steps:
Illume is designed so that survey objects can be easily reused. There are three ways to reuse questions, question blocks and Text/HTML objects. Note, however, that the second method has some distinct advantages.
One way is to copy items from one survey to another. Simply open both surveys and drag the item you want to reuse from one survey into the other.
You may also drag items out of the repository into your survey. If the item you want to use exists in the repository, this is the preferred method of reuse.
The major advantage of reusing items from the repository is that repository items permit cross-survey queries. You'll find more detailed information about this in the Repository Overview.
Note that if a repository item appears with red text, it has not yet been approved for reuse, and you will not be able to drag it into your survey. Only approved repository items (those appearing in black) may be reused.
You may drag an item out of an existing survey and drop it into the text of an email. When you do this, Illume inserts an XML description of the object into your message.
The recipient of the message can highlight the XML, then drag it into his or her own Illume survey. The Survey Designer will read the XML description and create an exact copy of the object inside the new survey.
If your survey requires special symbols, accented letters, or characters that do not belong to the Latin alphabet, use Microsoft's built-in character map to add the characters to your survey.
Note: You can paste special characters into almost any Windows application using this method.
Illume Surveys are stored as XML documents in C:\Documents and Settings\YOUR_USER_NAME\Application Data\DatStat\Survey Cache\localhost. (Substitute your Windows login name for YOUR_USER_NAME.)
Open the XML file in any text editor to edit the XML by hand. You should not edit the XML file if the Survey Designer is open, because your text editor and the Survey Designer may try to save conflicting changes to the same file.
If want to edit only a single survey item, you can drag the item from the Survey Designer into a text editor, and the XML will appear in the editor. After editing, select all of the XML and drag it back into the Survey Designer. The Survey Designer may ask you to give a new name to the item you are dragging in.
If you edit any Survey XML by hand, be sure to validate the survey before you start editing it again the Survey Designer. See Validating a Survey.
To check whether a survey is valid, choose Tools > Validate Survey... from the Survey Designer menu. If the Survey Validator finds any problems, it will explain them.
A survey may become invalid when any of the following occur:
This article describes how to create hidden variables in your Illume survey. Hidden variables store data that can be used for calculations, and can be saved with a participant's submitted survey.
Participants do not explicitly answer questions to set the value of hidden variables. Instead, data for hidden variables comes from one of three places:
Participant Lists include a list of all the participants invited to take your survey, along with a unique id for each participant and optional additional information. It may be useful at times to preload data from the participant list into a participant's survey. For example, if you want your survey to greet each participant by name, you can preload the name and display it when the participant logs in. Sometimes you may want to pre-load data that will never be displayed to the participant, but that will end up in the data that is submitted with the participant's survey. To preload data from a participant list into a survey, follow these steps:
NOTE: There is only a need for one column in the Participant list for this variable if you are filling it with data from the Participant List.
Disable this preload - This disables the preload without deleting. This may be useful for temporarily turning off a preload.
Automatically generate a scale as unique values are discovered - This option is useful if you know ahead of time that the number of possible values for this variable will be limited. For example, if you are preloading the US state in which a participant lives, there are only 51 possible values (including DC). The scale that Illume generates appears in the Web Console's Data Dictionary. In the Web Console, items with scales can be included in cross-tab queries and summary statistic results. This is one of the most common reasons for generating scales for preloaded data.
If the number of possible values is very large, checking this option may cause Web Console queries to run slowly.
Runtime only (do not store the value of this item) - This option makes the preloaded value available while the survey is running, but does not submit the value to the database when the participant submits the survey. This can be useful for data that are required for calculations, show-if conditions, or run-time display but that should otherwise be kept separate from results.
Illume will not preload data if either of the following conditions are true:
You can pre-load data by embedding it in the URL a participant uses to access your survey. For details, see Passing Data though the Survey URL. There are two things to keep in mind pre-loading data through the URL:
Like all Preload/Hidden Variables, it is possible to pass the information directly from a Query string into the variable.
Use the name that you added in the Multi-Value Preload/Hidden Variable Userdata field and the Scale Values separated by commas. If the Scale value is not passed it will be assumed to be not selected.
In the example Query String, the Multi-Value Preload/Hidden Variable CRITERIA will be Yes for OPTION1 and OPTION2 and No for OPTION3
Example: http://lorien/46Test-collector/Survey.ashx?Name=MVPreloadTest&LoginID=123455&CRITERIA=OPTION1,OPTION2
Again, see Passing Data though the Survey URL for more details.An Illume survey can capture any data passed in through the query string of the survey URL. These data are treated as if they came from the participant list. Participant list data and data that come in through the query string of the survey URL have the following characteristics:
Assume you have a survey with 2 different email invitations: one invitation offers participants a free music CD for completing your survey, and the other invitation offers participants a $10 check. You want to know which invitation has the higher response rate. The first invitation includes the following survey URL: https://www.datstat.com/Collector/Collector.ashx?LoginId=abc123&INCENTIVE=FREECD The second invitation includes this URL: https://www.datstat.com/Collector/Collector.ashx?LoginId=abc123&INCENTIVE=CHECK&CRITERIA=OPTION1,OPTION2 Anyone accessing the survey through either of these links causes a UserData variable called INCENTIVE to be created as well as a Multi-Value variable called CRITERIA with OPTION1 and OPTION2 set to Yes. You can get the values of these variables anywhere in your survey by typing {UserData:Incentive} or {UserData:Criteria.OPTION1}. (The case of the letters does not matter. The curly braces do!) You can create a question in your survey that asks which music CD the participant would like to receive, and you can set a show-if condition on that question so that it appears only when {UserData:Incentive} equals "FREECD". While variable names in the URL are case-sensitive in most web-based applications, variable names in the URL of an Illume survey are not case sensitive. The Illume server does not differentiate between INCENTIVE=CHECK and incentive=CHECK.
Like data from the participant list, data from the query string are not automatically saved with the participant's responses. If you wanted to save the Incentive data from the example above, follow these steps:
The query string portion of a URL consists of everything after the first question mark in the URL. In the example below, the query string appears in bold italics: https://www.datstat.com/Collector/Collector.ashx?product=gadget&incentive=freecd&source=yahoo+shopping This query string includes 3 variables: product (this might indicate the type of product the participant purchased), incentive (which may indicate the type of payment the participant has been promised) and source (which may indicate the page or web site on which the link to your survey appeared). Each variable is represented by the variable name, followed by an equal sign =, followed by the variable's value. Each name-value pair in the query string is separated by an ampersand &. Variable names should include only letters, numbers and underscores. Spaces in variable values must be represented by a plus sign +. (Notice that the source in the URL above, yahoo shopping, appears as yahoo+shopping.)
The following variable names are reserved for use by the Illume server. You cannot use these variable names in your URL:
The following words have special meaning in the URL. You may use them, but you should understand first what they do.
If the URL used to access a survey includes TESTDATA=1 in the query string, the data from that survey will be marked as test data. For example, in a survey that uses the variable customid to authenticate participants, the following survey URL would give participant 9999 access to the survey: https://www.datstat.com/Collector/Collector.ashx?customid=9999 When the participant submits the survey that he or she accessed through this link, the data will be saved as normal response data. For testing purposes, the participant could access the survey through this URL: https://www.datstat.com/Collector/Collector.ashx?customid=9999&TESTDATA=1 Any data the participant submits after accessing the survey with this URL will be treated as test data. The Web Console separates normal participant data and test data so that test data does not skew actual results.
Note Each participant can only take an authenticated survey once, unless this participant is a test participant or the survey session is marked as a test session by appending "&TESTDATA=1" to the URL.
Avoid using real participants to submit test data, because doing so could prevent the participant from being able to take a survey and will possibly skew your non-test data.
A jump causes a participant to jump from one part of a survey to another, skipping everything in between. Jumps can be conditional, occurring only when a participant meets certain criteria, or unconditional, in which case they always happen for all participants. A jump can move a participant forward or backward through a survey. Each survey can contain multiple jumps.
While jumps are convenient, they can make a survey excessively complex, difficult to test, and difficult to maintain. In general, you should use show-if conditions rather than jumps, for these reasons:
There are two particular cases in which jumps are preferable to show-if conditions:
To add a jump to your survey, follow these steps:
This article describes how to set up Save and Restore on unauthenticated surveys. Save and Restore enables survey participants to save a survey in progress and resume work on it later.
Authenticated surveys are surveys that are associated with one or more participant lists. Only participants on the lists can take the surveys, and Illume keeps track of which survey belongs to which participant.
Authenticated surveys always have the restore feature enabled, so there is no need to set it up. When a participant comes to your authenticated survey, Illume always checks first to see if the participant has a survey in progress. If so, Illume gives the participant the option to restore the survey in progress, or to start over.
You can customize the Restore and Start Over buttons. See Customizing Survey Buttons for details.
You may want to add the Save button even for authenticated surveys for two reasons: its presence lets participants know that they can save the survey and resume it later, and it enables them to save responses on a page they've only partially completed. Without the save button, Illume saves only the participant's last completed page. (The last page on which they clicked the Next button.)
Unauthenticated surveys are open to the public. They do not need to have an associated participant list. They simply grant access to everyone.
You must set up Save and Restore for Illume to be able to reconnect an unauthenticated participant with the survey he or she had been working on.
To set up Save and Restore for your unauthenticated survey, follow these steps:
When a participant clicks the Save button, they will see a page like the one below.
If the participant chooses to have the URL emailed, Illume will attempt to send the email immediately.
Illume includes some special customizable messages for the Save Email.
Click on the Error Messages tab of the Survey Preferences editor to set the text of these messages.
From the Error message for list, you set text for any of the following items pertaining to the Save page.
The email address entered on the Save page is invalid. This message appears if the participant enters an invalid email address. Illume will not try to send an email if the address is invalid. Notice that the message above uses the special tag {SavePageEmailAddress}. In the actual error message, this will be replaced with the email address that the participant entered.
There was a problem sending an email to the participant from the Save page. This message appears after the participant clicks the Send Email button if Illume was not able to send the email.
An email was sent successfully to the participant from the Save page. Illume displays this message to confirm that the email was sent.
Illume can perform calculations while a survey is in progress, and can store the result of the calculation with the rest of the survey data it collects. Calculated variables are particularly useful for identifying whether a respondent fits a particular profile.
For example, in a survey on depression, respondents may receive a certain number of points for each question to which they answer yes. A calculated variable can keep track of the points as the survey progresses, adding them all together to produce a sum that indicates the respondent's overall level of depression.
To implement this type of logic, you must first create a calculated variable, as described below. Then you would create a question (or collection of questions) with a show-if condition that tests your calculated variable. See Setting Show-if Conditions for more information about how to set the conditions under which questions or collections will appear.
Participants may be required to answer (or allowed to skip) questions or entire sections of a survey based on calculated variables. Continuing the example above, respondents whose calculated depression scores are beyond a given threshold may be required to answer follow-up questions that those with lower calculated scores may skip.
To define a calculated variable, follow these steps:
For each calculation, Illume creates a variable with the same name as the calculation. Illume attempts to evaluate all of the calculations in the survey each time a participant moves from one page to the next.
Illume substitutes the value of the named variable for each of the {Value} tags. For example, if a participant entered "200" in response to the question named WEIGHT that asked "What is your weight (in pounds)?", Illume substitutes 200 for the tag {Value:WEIGHT}.
Illume will perform value substitutions on any variables for which it has data. It does not matter whether that data came from a participant response, from a variable appended to the survey URL, or from data that was pre-loaded from the participant list. (See the articles on Preloading Participant Data for details on how to get data from your participant list into your survey. See Passing Data Through the Survey URL for information on how to pass in survey data through a link.)
If Illume cannot perform the calculation, the value of the calculation will be the default value you set for the calculation in the Survey Calculations Editor. There are three conditions under which Illume cannot perform a calculation:
The calculation itself is a JScript.NET expression, or a series of JScript.NET statements. Illume evaluates the JScript.NET using the eval() function and sets the value of the calculated variable to whatever eval() returns. There are two things to note about eval() in JScript.NET:
The following calculation determines the total price for a quantity of some material, then applies a discount of 5%:
var weightInGrams = {Value:KILOGRAMS} * 1000;
var pricePerGram = 0.13;
var totalPrice = weightInGrams * pricePerGram;
var discount = 0.05;
totalPrice * (1 - discount);
Notice that the value to be returned is expressed on the last line as totalPrice * (1 - discount), and that there is no return statement. Because JScript's eval() returns the value of the last expression, the result of your calculation will be the value of the last expression in the calculation.
The following operators are available for calculated variables:
Though you can use JScript date objects in calculations, date and time calculations can be tricky. Calculations that use the current time must take into account the fact that Illume re-calculates calculated variables every time participants move from one page to the next. This means that if you are not careful, the calculation will change every time the participant goes to a new page.
For an example of a time calculation that averts this problem, see How can I time a participant's progress through portions of my survey?
Date calculations are tricky because programmers often make incorrect assumptions about units of time. For example, because the JScript date object uses milliseconds as its unit of time, you might think it's easy to measure a span of years by converting years to milliseconds and performing simple arithmetic on the milliseconds. This may lead to incorrect calculations, since leap years are longer than standard years.
Months are notoriously irregular. They can have 30 days, or 31, or 28, or in some cases, 29.
Days irregular as well. In most parts of the US, the first Sunday in April is a 23-hour day, and the last Sunday in October is a 25-hour day.
The following JScript calculates a participant's age on the date of the survey. This calculation assumes that the variable BIRTHDATE is a variable of type Date:
var today = new Date();
var dob = new Date({Value:BIRTHDATE});
var yearDiff = today.getFullYear() - dob.getFullYear();
var monthDiff = today.getMonth() - dob.getMonth();
var dayDiff = today.getDate() - dob.getDate();
if(monthDiff < 0 || (monthDiff == 0 && dayDiff < 0))
yearDiff--;
yearDiff;
If BIRTHDATE were a text variable, and had the format mm/dd/yyyy, the calculation would be as follows:
var today = new Date();
var dob = {Value:BIRTHDATE} + "";
var dateParts = dob.split(/\D/);
var month = parseInt(dateParts[0], 10);
var day = parseInt(dateParts[1], 10);
var year = parseInt(dateParts[2], 10);
if(year < 100)
year += 1900;
var yearDiff = today.getFullYear() - year;
var monthDiff = today.getMonth() - ( month - 1);
var dayDiff = today.getDate() - day;
if(monthDiff < 0 || (monthDiff == 0 && dayDiff < 0))
yearDiff--;
yearDiff;
Note that the value of the value of the calculated variable is set to the value of the last expression evaluated in the JScript. In the examples above, that is the variable yeardiff. Keep in mind that because Illume uses eval() to evaluate the JScript in calculated variables, you do not need a return at the end of the script.
While the {Value} tag yields a question's selected response value, the {RScore} tag yields the reverse score.
To get a question's reverse score, use the {RScore} with the question id. For example, to get the reverse score of the question SATISFACTION, use the tag {RScore:Satisfaction}.
Reverse scoring is generally used on questions that have both negative and positive items in the scale, though Illume permits reverse scoring of any items.
For questions with numeric scales, the reverse score is the score in the same position at the opposite end of the scale. The following tables illustrate reverse scores for items with numeric scales.
| Score | Reverse Score |
| -1 | 1 |
| 0 | 0 |
| 1 | -1 |
| Score | Reverse Score |
| 1 | 4 |
| 2 | 3 |
| 3 | 2 |
| 4 | 1 |
For Check all that apply questions, the {Score} tag gives the number of items checked. The {RScore} tag gives the number of items NOT checked.
For individual checkboxes, the {Score} tag yields a value of 1 if the item is checked and 0 if the item is not checked. The {RScore} yields the opposite values.
For non-question items (such as calculations and pre-loaded variables), the {Score} tag yields the item's value. The {RScore} tag always yeilds one of the "not set" values described below.
If a question has not been answered, or has no value, the {RScore} will return one of the following values, depending on the item's data type:
Illume calculations use parentheses to determine which parts of a calculation should be evaluated first. If your calculation uses only addition and subtraction, parentheses do not matter. If your calculation uses multiplication or division, parentheses matter very much.
Illume will scan a calculation from right to left (that's the opposite of the direction in which most Western languages are read), evaluating all expressions in parentheses, followed by all multiplication operations, then all division operations, then all addition operations, and finally all subtraction operations.
Note the following examples:
When using multiplication or division, use parentheses to explicitly define the order in which your calculation should be evaluated!
You can use calculations to test and assemble text values. The following expression tests whether someone typed "California" in response to question Q2: {Value:Q2} == "California" This expression returns a whole number: 1 if the value does equal "California" and 0 if the value does not equal California. Beginning in Illume 3.0, text calculations are not case sensitive!
This means the calculation above will be true whether the participant typed California, california, or CALIFORNIA.
The expression below creates an email address by adding @company.com to whatever the user typed in response to the LASTNAME question: {Value:LASTNAME} + "@company.com" This expression returns a Text value that ends with @company.com
Illume supports complex expressions that use the ?: operator. This operator tests an expression and returns one of two values, based on whether the expression is true or false. If the expression before the question mark is true, the expression returns the value before the colon. If it is false, it returns the value after the colon. For example, the following expression returns the value "yes" because the expression before the question mark is true: (10 > 5) ? "yes" : "no"; This expression returns "no" because the expression before the question mark is false: (5 > 10) ? "yes" : "no";
You may include multiple complex expressions within a single calculation, as in this example, which calculates the cost of an order as the number of items times the cost per item, plus a fixed rate of either $20 or $12 or $8, based on the type of shipping: {Value:NumberOfItems} * {Value:CostPerItem} + ({Value:Shipping} == "Overnight" ? 20 : 0) + ({Value:Shipping} == "3-day" ? 12 : 0) + ({Value:Shipping} == "USPS" ? 8 : 0) Assuming that the Shipping question is required and that participants can choose only one shipping option, one of the three complex expressions will be true, and the other two will be false. The true expression will add either 20 or 12 or 8 to the value of the calculation. The two false expressions will both add 0 to the calculation. Complex expressions are especially useful in calculations that must be applied differently to different participants. For example, calculations of lean body weight and blood alcohol content use different constants for men and women.
See Microsoft's JScript Language Reference for more information about JScript.
If you check "Disable this calculation," the calculation will not be performed. This option is provided in case you want to disable a calculation that you may need to re-enable later.
If you do not want the result of the calculation to be stored with the results of the survey, check the "Runtime only" option. The results of the calculation will be available while the survey runs, and will be discarded when the participant submits the survey.
The survey calculation DatStat object is new in version 4.7 and it consists of many very useful methods that can be called from survey calculations that were formally only exposed using the SDK. These methods allow for more capability and flexibility within a survey calculation, and in some cases, problems can be solved by just using a survey calculation where previously it would have required use of the runtime SDK.
Limitations
The survey calculation editor does not currently color code any of the DatStat object methods. Variable name references used in the DatStat object methods will not be updated when using the survey rename capability unlike the tags (e.g. {Value:GENDER}).
Almost all of the DatStat object methods exposed share the same signatures as those used by our runtime SDK. To make a call just prefix the method or property with “DatStat.” (case sensitive). The methods are also type aware so make sure you pass variables of the proper type to them (eg if the method is expecting an integer, do not pass a string to it).
| Method Name | Returns | Description |
| GetHttpFormElement(name : String) | String | This method retrieves the name of an Http form element. |
| var val = DatStat.GetHttpFormElement(‘MYHIDDEN’); | ||
| GetParameter(parameterName : String) | String | This method signature is equivalent to the HookContext.GetParameter() method. It retrieves a survey parameter string value. |
| var parameter_text = DatStat.GetParameter(‘MYPARAM’); | ||
| GetRandomizationMap(variableName : String) | String | This method retrieves the randomization map for a specific variable that is randomized. The value returned is a comma delimited list of ordinals (e.g. 3,1,0,2). |
| var order = DatStat.GetRandomizationMap(‘CUSTOMER_EVAL’); | ||
| GetResponse(variableName : String) | Object | This method signature is equivalent to the HookContext.GetResponse() method. This method retrieves the response code and is equivalent to using a {Value} tag. |
| var val = DatStat.GetResponse(‘Q55’); | ||
| GetResponseLabel(variableName : String) | String | This method signature is equivalent to the HookContext.GetResponseLabel() method. This method retrieves the response label. |
| var theResponse = DatStat.GetResponseLabel('Q55'); | ||
| GetUserData(dataName : String) | String | This method signature is equivalent to the HookContext.GetUserData() method. It will return the value for the specified piece of User Data from a participant list. |
| var userData= DatStat.GetUserData(‘LOCATION’); | ||
| IsOnPage(variableName : String) | Boolean | This method will return true if the item identified by the variableName parameter appears on the page of the set of responses that are being currently processed. |
| if(DatStat.IsOnPage('Q55')) { // do something } | ||
| PageItemNames() | String[] | This method returns an array of variable names that appear on the page of the set of responses that are currently being processed. |
| var items : String[] = DatStat.PageItemNames(); | ||
| QuotaCountGet(quotaName : String) | int | This method returns the current count for the specified quota. |
| var count = DatStat.QuotaCountGet('MALE'); | ||
| QuotaLimitGet(quotaName : String) | int | This method returns the quota limit defined for the specified quota. If the current survey session happens to be a test participant then the test data quota limit is returned. |
| var limit = DatStat.QuotaLimitGet('MALE'); | ||
| QuotaStatusGet(quotaName : String) | int | This method returns a ‘0’ or ‘1’ that designates the quota status for the sepecified quota. A value of ‘0’ means that the specified quota hasn’t yet met the limit. A value of ‘1’ means that the specified quota has met or exceeded the quota limit. |
| var status = DatStat.QuotaStatusGet('MALE'); | ||
| ResponseReplacement(input : String) | String | This method signature is equivalent to the HookContext.ResponseReplacement() method. This method replaces all tags to their proper values. |
| var surveyName = DatStat.ResponseReplacement(‘{SurveyName}’); | ||
| SetResponseData(variableName : String, responseValue : Object) | Boolean | This method signature is equivalent to the HookContext.SetResponseData() method. This method sets a specific variable to a particular value. A value of true is returned if the variable was set properly, otherwise a value of false is returned. Setting a value to ‘null’ is equivalent to clearing the value. |
| DatStat.SetResponseData(‘Q1’, myvar); | ||
| SetUserData(dataName : String, dataValue : String) | void | This method signature is equivalent to the HookContext.SetUserData() method. This method sets a user data field to a particular string value. |
| if ( DatStat.GetResponse(‘GENDER’) == 1 ) DatStat.SetUserData(‘PRONOUN’, ‘his’); else DatStat.SetUserData(‘PRONOUN’, ‘her’); | ||
Ranking validation requires survey participants to enter sequential numeric responses for a minimum and/or maximum number of question items. Here is an example of a ranking question:
Sum check validation requires survey participants to enter numeric values for a group of questions whose sum equals some value or is between some specified minimum and maximum values. JavaScript code can also be supplied to update a running total that is displayed in the survey. Here is an example of a sum check question:
Ranking and sum check validation is normally performed using a group of questions which are normally part of a question table. Ranking and sum check validation requires that the data type of the questions be “Whole Numbers” or “Whole Numbers >= 0” and the display type of the questions be “Text Field”, “Select One – Poplist”, or “Select One – Radio Button”.
In order to use Ranking/Sum Check validation, Multi-Control component validation, or other custom client validation,
a survey must have originated from a version 4.7 survey template or the following conditions must be true:
<script type="text/javascript">
// Include ClientValidation.js only if the DatStat object is defined
//
if (typeof(DatStat) != "undefined")
{
document.write('<script type="text/javascript" src="SurveyResource/ClientValidation.js"><\/script>');
}
</script>
The following example demonstrates how to add ranking validation:
The RankingValidation parameters are separated by commas and must appear in the order as listed below.
This value should be a comma-delimited list of single-quoted text values that are the form element names of the questions to be ranked all enclosed between beginning and end brackets ('[' and ']'). The {FormElement:
Example: ['{FormElement:Q1}', '{FormElement:Q2}', '{FormElement:Q3}' ]
This is a text message enclosed in single-quotes. It is displayed if the user fails to uniquely rank the minimum and maximum number of items.
This is the minimum number of items that are required to be ranked. This number is adjusted to the number of question items displayed on the page if that number is less than the minimum. An error message will be displayed it the survey participant fails to uniquely rank this minimum number of items.
This is the maximum number of items that can be ranked. An error message will be displayed if the survey participant ranks more than this specified maximum.
This is a true/false option. Set this option to true if you require ranking values to be sequential numbers starting with 1. This option is especially important if the ranking questions are of display type text field.
The following example demonstrates how to add sum check validation. In this example, let's assume we want the sum of these questions to add up to 100.
Click the Source tab of the Text/HTML object created in the previous step and insert the following content:
<script type="text/javascript">
function setTotal(total, ok)
{
var display = document.getElementById("TOTAL");
if(!display || typeof display == 'undefined')
return;
display.innerHTML = total + "%";
if(ok)
display.style.color = 'green';
else
display.style.color = 'red';
}
DatStat.addClientValidationCheck(new DatStat.SumCheckValidation(
['{FormElement:Q1}', '{FormElement:Q2}', '{FormElement:Q3}','{FormElement:Q4}',
'{FormElement:Q5}'], /* Question array list */
100, /* Minimum sum */
100, /* Maximum sum */
setTotal, /* Callback function */
'Total must equal 100. Current total is {0}.' /* Error Message */
));
</script>
The SumCheckValidation parameters are separated by commas and must appear in the order as listed below.
This value should be a comma-delimited list of single-quoted text values that are the form element names of the questions to be ranked all enclosed between beginning and end brackets ('[' and ']'). The {FormElement:
Example: ['{FormElement:Q1}', '{FormElement:Q2}', '{FormElement:Q3}' ]
This is a numeric value that is the minimum allowed by the sum check validation code. This value should be less than or equal to the maximum allowed sum (i.e. the next parameter).
This is a numeric value that is the maximum allowed by the sum check validation code. This value should be greater than or equal to the minimum allowed sum (i.e. the previous parameter).
This is an optional argument. If not set to null, this argument should be a JavaScript function object that accepts 2 arguments: 1) the current running ‘total’; and 2) whether or not this value is ‘ok’ and fulfills the sum check minimum/maximum requirements. This function is called whenever the sum of the questions changes.
This is a text message enclosed in single-quotes. It is displayed if the sum of the responses isn’t between the required minimum/maximum values. This error message can contain the following tag: {0} which will be replaced with the current total.
The Multi-Control Component allows for complex questions and question tables containing multiple UI controls to be easily created. For single questions this component allows for a more flexible layout of the controls and allows them to be placed either on the same line or different lines. For question tables this component allows for multiple controls to be displayed in columns of the same table as well as row header elements and text fields within the prompt column.
NOTE: You do not need to have purchased the Software Development Kit (SDK) in order to utilize the Multi-Control tool. Even though you may not have the SDK, you will see an SDK Menu item (Add Runtime Content...) in the Survey Designer which will allow you to create Multi-Control questions and question tables.
Here is the Runtime Content Editor window:
NOTE: If you plan on localizing your survey into multiple languages (through the use of a Translation Package), you should not enter text directly into the various elements of MultiControl questions. Rather, replace the text with {ParamValue:param1} and set the associated parameters in Edit-->Preferences-->Parameters. The parameters are included in a translation package whereas Runtime Content Hooks are not.
The Runtime Content Object uses a Run-if statement instead of Show-if, but the logic functions the same.
If you want to use the response for a Multi-Control Question in Show-If Logic, you will have to link it to the Preloaded variable that you created for the specific field.
NOTE: XML is case sensitive so be very careful in how you are entering your elements and information.
When using the Multi-Control component, you must specify XML data using a specific XML grammar in the Hook Data field of the Runtime Content editor. It is a good idea to preview your surveys in the Survey Designer for testing purposes, because details of any syntax errors are displayed when in preview mode.
If you haven’t used XML before you need to adhere to a few simple rules:
This section details the XML grammar required for a single question multi-control component.
The Question element consists of 1 or more Row elements. The Question element MUST appear on the first line of the Hook Data.
| Attribute Name | Required | Values |
| xmlns | Yes | This value must be: http://www.datstat.com/2008/MultiControl.xsd |
The "Row" element consists of 0 or more "Data" elements. Use of this element will create a "tr" (or row) tag within an HTML table.
| Attribute Name | Required | Values |
| style | No | Contains CSS Styles |
The "Data" element consists of 0 or more "Prompt", "TextField", "Checkbox", or "Poplist" elements. Use of this element will create a "td" (or data cell) tag within an HTML table and facilitates different layout options and control.
| Attribute Name | Required | Values |
| colspan | No | A numeric value that corresponds to the colspan attribute of the "td" tags in HTML tables. |
| style | No | Contains CSS Styles |
The "Prompt" element is most often used in the first row of the question.
| Attribute Name | Required | Values |
| value | Yes | A text value to be displayed as the prompt. |
| style | No | Contains CSS Styles |
The "TextField" element displays a text field control and can contain 0 or more "RequiredValidation", "NumericValidation", or "TextValidation" elements.
| Attribute Name | Required | Values |
| variableName | Yes | Refers to a variable defined in the Survey as a preload hidden. |
| size | No | The size of the text field. |
| maxLength | No | The maximum number of characters that can be entered in this text field. |
| style | No | Contains CSS Styles. |
| labelBefore | No | Text value that precedes the text field control. |
| labelAfter | No | Text value that follows the text field control. |
The "Checkbox" element consists of zero or more "RequiredValidation" elements. Use of this element will create a single checkbox control.
| Attribute Name | Required | Values |
| variableName | Yes | Refers to a variable defined in the Survey as a preload hidden. |
| style | No | Contains CSS Styles. |
| labelBefore | No | Text value that precedes the text field control. |
| labelAfter | No | Text value that follows the text field control. |
The "Poplist" element consists of zero or more "PoplistOption" elements followed by zero or more "RequiredValidation" elements. If the "Poplist" element does not contain any "PoplistOption" elements, then the options are created by reading the scale values of the hidden variable.
| Attribute Name | Required | Values |
| variableName | Yes | Refers to a variable defined in the Survey as a preload hidden. |
| unansweredResponse | No | The name or label given to an unanswered response in the poplist control. |
| style | No | Contains CSS Styles. |
| labelBefore | No | Text value that precedes the text field control. |
| labelAfter | No | Text value that follows the text field control. |
Optional elements contained within "Poplist" elements.
| Attribute Name | Required | Values |
| code | Yes | This value should be the same response code as defined in the hidden question used in this "Poplist" control. |
| response | Yes | This is the poplist option value viewed by the survey respondent. |
Use of the "RequiredValidation" tag will enforce input validation rules using javascript on the control in which this tag is contained within. In this case a response to a particular parent control will be required.
| Attribute Name | Required | Values |
| errorMessage | Yes | Error message displayed to the user if the input constraints are violated. |
Use of the "NumericValidation" tag will enforce numeric input validation rules using javascript on the control in which this tag is contained within.
| Attribute Name | Required | Values |
| errorMessage | Yes | Error message displayed to the user if the input constraints are violated. |
| required | No | This value can be either “true” or “false”. |
| minValue | No | This is a numeric value that is the minimum value allowed in the parent control. |
| maxValue | No | This is a numeric value that is the maximum value allowed in the parent control. |
Use of the "TextValidation" tag will enforce text input validation rules using javascript on the control in which this tag is contained within.
| Attribute Name | Required | Values |
| errorMessage | Yes | Error message displayed to the user if the input constraints are violated. |
| required | No | This value can be either “true” or “false”. |
| minLength | No | This is a numeric value that is the minimum length of the input entered. |
| maxLength | No | This is a numeric value that is the maximum length of the input entered. |
| regEx | No | A regular expression value that the input value must match. |
The "QuestionTable" element consists of an "Instruction" element, followed by 1 or more control elements ("TextField", "RadioGroup", "CheckAll", "Checkbox", "Poplist", or "Empty"), followed by 1 or more row elements ("Row", "RowHeader", or "RowTextField"). The "QuestionTable" element MUST appear on the first line of the Hook Data.
| Attribute Name | Required | Values |
| xmlns | Yes | This value must be: "http://www.datstat.com/2008/MultiControl.xsd" |
| width | No | Set the width of this QuestionTable. |
| numbering | No | A text phrase can be entered. “{0}” will be replaced with the alpha row number (e.g. “a.”, “b.”, etc…) and “{1}” will be replaced with the numeric row number (e.g. “1.”, “2.”, etc…) |
| promptHeader | No | Contains an optional text phrase that is used in the prompt header position of the question table. |
| randMethod | No |
Accepts one of the following arguments: ‘all’, ‘reverse’, ‘previous’ Note: ‘all’ randomizes ALL items, ‘reverse’ randomly displays the items either in the same order OR in reverse order, and ‘previous’ displays the items in the same order as a previous survey object whose items have been randomized. |
| randArgs | No | Only valid if ‘randMethod’ is set to ‘previous’. When the ‘randMethod’ is set to ‘previous’, set the randArgs attribute to the name of a previous Question or Collection object that is randomized. |
This element contains text instructions that are displayed before the question table.
The "TextField" element displays a text field control and can contain 0 or more "RequiredValidation", "NumericValidation", or "TextValidation" elements.
| Attribute Name | Required | Values |
| variablePrefix | Yes | The prefix used along with the row number ordinal to form the name of the variable used to store the response for this particular row/column. |
| heading | No | Text displayed in the heading of this control |
| columnWidth | No | Width of this control column |
| size | No | The size or width of this text field control. |
| maxLength | No | The maximum number of characters that can be typed in this text field. |
| labelBefore | No | Text to be displayed before the control. E.g. “$” |
| labelAfter | No | Text to be displayed before the control. E.g. “$” |
The "RadioGroup" element displays a group of radio buttons and contains zero or more "RadioOption" elements followed by zero or more "RequiredValidation" elements. If the "RadioGroup" element does not contain any "RadioOption" elements, then the options are created by reading the scale values of the hidden variable.
| Attribute Name | Required | Values |
| variablePrefix | Yes | The prefix used along with the row number ordinal to form the name of the variable used to store the response for this particular row/column. |
| heading | No | Text displayed in the heading of this control |
| columnWidth | No | Width of this control column |
| randMethod | No |
Accepts one of the following arguments: ‘all’, ‘reverse’, ‘previous’ Note: ‘all’ randomizes ALL items, ‘reverse’ randomly displays the items either in the same order OR in reverse order, and ‘previous’ displays the items in the same order as a previous survey object whose items have been randomized. |
| randArgs | No | Only valid if ‘randMethod’ is set to ‘previous’. When the ‘randMethod’ is set to ‘previous’, set the randArgs attribute to the name of a previous Question or Collection object that is randomized. |
Optional elements contained within "RadioGroup" elements.
| Attribute Name | Required | Values |
| code | Yes | The response code defined in the hidden question used with this Radio button control. |
| heading | Yes | Text displayed in the heading of this specific radio button control. |
This element is used to display a single checkbox. It can contain zero or more "RequiredValidation" elements.
| Attribute Name | Required | Values |
| variablePrefix | Yes | The prefix used along with the row number ordinal to form the name of the variable used to store the response for this particular row/column. |
| heading | No | Text displayed in the heading of this control |
| columnWidth | No | Width of this control column |
This element is used to display a grouping of checkboxes so that multiple selections can be made. It contains zero or more "CheckAllOption" elements followed by zero or more "CheckAllValidation" elements (order is important if both types of elements are specified). If the "CheckAll" element does not contain any "CheckAllOption" elements, then the check box options are created by reading the scale values of the hidden variable.
| Attribute Name | Required | Values |
| variablePrefix | Yes | The prefix used along with the row number ordinal to form the name of the variable used to store the response for this particular row/column. |
| heading | No | Text displayed in the heading of this control |
| columnWidth | No | Width of this control column |
| style | No | CSS style |
| randMethod | No |
Accepts one of the following arguments: ‘all’, ‘reverse’, ‘previous’ Note: ‘all’ randomizes ALL items, ‘reverse’ randomly displays the items either in the same order OR in reverse order, and ‘previous’ displays the items in the same order as a previous survey object whose items have been randomized. |
| randArgs | No | Only valid if ‘randMethod’ is set to ‘previous’. When the ‘randMethod’ is set to ‘previous’, set the randArgs attribute to the name of a previous Question or Collection object that is randomized. |
Optional elements contained within "CheckAll" elements.
| Attribute Name | Required | Values |
| heading | Yes | Text displayed in the heading of this specific checkbox control. |
| name | Yes | This value is the response name of the checkbox as defined in the hidden questions used by this CheckAll or “Select all that apply” question. |
This element is used to display a poplist control. It contains 1 or more "PoplistOption" elements followed by zero or more "RequiredValidation" elements. If the "Poplist" element does not contain any "PoplistOption" elements, then the options are created by reading the scale values of the hidden variable.
| Attribute Name | Required | Values |
| variablePrefix | Yes | The prefix used along with the row number ordinal to form the name of the variable used to store the response for this particular row/column. |
| heading | No | Text displayed in the heading of this control |
| columnWidth | No | Width of this control column |
| unansweredResponse | No | Text that is displayed in the poplist control when no value is selected. |
| randMethod | No |
Accepts one of the following arguments: ‘all’, ‘reverse’, ‘previous’ Note: ‘all’ randomizes ALL items, ‘reverse’ randomly displays the items either in the same order OR in reverse order, and ‘previous’ displays the items in the same order as a previous survey object whose items have been randomized. |
| randArgs | No | Only valid if ‘randMethod’ is set to ‘previous’. When the ‘randMethod’ is set to ‘previous’, set the randArgs attribute to the name of a previous Question or Collection object that is randomized. |
Optional elements contained within "Poplist" elements.
| Attribute Name | Required | Values |
| code | Yes | The response code defined in the hidden question used with this poplist control. |
| response | Yes | Text displayed in the poplist control for this response. |
This element is used to add an empty column in the question table.
| Attribute Name | Required | Values |
| heading | No | Text displayed in the heading of this control |
| columnWidth | No | Width of this control column |
| headingStyle | No | CSS style applied to the header of the "Empty" element. |
| cellStyle | No | CSS style applied to each of the TD cells of an "Empty" element. |
Use of the "RequiredValidation" tag will enforce input validation rules using javascript on the control in which this tag is contained within. In this case a response to a particular parent control will be required.
| Attribute Name | Required | Values |
| errorMessage | Yes | Error message displayed to the user if the input constraints are violated. |
Use of the "NumericValidation" tag will enforce numeric input validation rules using javascript on the control in which this tag is contained within.
| Attribute Name | Required | Values |
| errorMessage | Yes | Error message displayed to the user if the input constraints are violated. |
| required | No | This value can be either “true” or “false”. |
| minValue | No | This is a numeric value that is the minimum value allowed in the parent control. |
| maxValue | No | This is a numeric value that is the maximum value allowed in the parent control. |
Use of the "TextValidation" tag will enforce text input validation rules using javascript on the control in which this tag is contained within.
| Attribute Name | Required | Values |
| errorMessage | Yes | Error message displayed to the user if the input constraints are violated. |
| required | No | This value can be either “true” or “false”. |
| minLength | No | This is a numeric value that is the minimum number of characters allowed in the parent control. |
| maxLength | No | This is a numeric value that is the maximum number of characters allowed in the parent control. |
| regEx | No | A regular expression value that the input value must match. |
This element will enforce “check all that apply” input validation rules using javascript.
| Attribute Name | Required | Values |
| errorMessage | Yes | Error message displayed to the user if the input constraints are violated. |
| minRequired | No | The minimum number of checkbox selections allowed. |
| maxRequired | No | The maximum number of checkbox selections allowed. |
This element will add a “normal” row to the question table. This row contains a prompt followed by controls.
| Attribute Name | Required | Values |
| prompt | No | Value displayed in the prompt column. |
| showIf | No |
This is a simple ShowIf expression of the form:
"variable" "op" "value" Where: "variable" is the name of a survey variable "op" is any of the following operators: ‘_eq_’ is equals ‘_ne_’ is not equals ‘_lt_’ is less than ‘_gt_’ is greater than ‘_lteq_’ is less than or equals ‘_gteq_’ is greater than or equals ‘_ans_’ is answered ‘_nans_’ is not answered "value" is a required value except if the _ans_ or _nans_ operators are used. Example: GENDER _eq_ 1 |
| maxRequired | No | The maximum number of checkbox selections allowed. |
This element will add a content row to the question table. This row will not contain any controls.
| Attribute Name | Required | Values |
| value | No | Value displayed in the row. |
| style | No | CSS style applied to the row header. |
| showIf | No |
This is a simple ShowIf expression of the form:
"variable" "op" "value" Where: "variable" is the name of a survey variable "op" is any of the following operators: ‘_eq_’ is equals ‘_ne_’ is not equals ‘_lt_’ is less than ‘_gt_’ is greater than ‘_lteq_’ is less than or equals ‘_gteq_’ is greater than or equals ‘_ans_’ is answered ‘_nans_’ is not answered "value" is a required value except if the _ans_ or _nans_ operators are used. Example: GENDER _eq_ 1 |
| maxRequired | No | The maximum number of checkbox selections allowed. |
This element will add a text field control in the prompt column.
| Attribute Name | Required | Values |
| prompt | No | Value displayed in the prompt column. |
| variableName | Yes | Variable name used by this text field control. |
| size | No | Size of the text field control. |
| maxLength | No | Maximum number of characters that can be entered in the text field control. |
| labelBefore | No | Text value displayed before the text field control. |
| labelAfter | No | Text value displayed after the text field control. |
| showIf | No |
This is a simple ShowIf expression of the form:
"variable" "op" "value" Where: "variable" is the name of a survey variable "op" is any of the following operators: ‘_eq_’ is equals ‘_ne_’ is not equals ‘_lt_’ is less than ‘_gt_’ is greater than ‘_lteq_’ is less than or equals ‘_gteq_’ is greater than or equals ‘_ans_’ is answered ‘_nans_’ is not answered "value" is a required value except if the _ans_ or _nans_ operators are used. Example: GENDER _eq_ 1 |
The following example creates a simple question that asks for a survey respondent's height in feet and inches.
Hook Data
<Question xmlns="http://www.datstat.com/2008/MultiControl.xsd">
<Row>
<Data>
<Prompt value="Enter your height:" />
</Data>
</Row>
<Row>
<Data>
<TextField variableName="HEIGHT_FEET" labelAfter="feet" size="4" >
<NumericValidation errorMessage="A numeric value between 3 and 8 for the height in feet is required." required="true" minValue="3" maxValue="8"/>
</TextField>
<TextField variableName="HEIGHT_INCHES" labelAfter="inches" size="4" >
<NumericValidation errorMessage="A numeric value between 0 and 11 for the height in inches is required." required="true" minValue="0" maxValue="11"/>
</TextField>
</Data>
</Row>
</Question>
Notes about this Example
The following example is a different variation of the previous example that asks for the respondent’s height in feet and inches. Instead of text field controls, this question uses poplist controls:
Hook Data
<Question xmlns="http://www.datstat.com/2008/MultiControl.xsd" >
<Row>
<Data>
<Prompt value="Enter your height:" />
</Data>
<Data>
<Poplist variableName="HEIGHT_FEET" style="text-align:left;width:180px" unansweredResponse="--Select Height in Feet--" >
<RequiredValidation errorMessage="Please select a response for your height in feet."/>
</Poplist>
</Data>
</Row>
<Row>
<Data>
<Poplist variableName="HEIGHT_INCHES" style="text-align:left;width:180px" unansweredResponse="--Select Height in Inches--" >
<RequiredValidation errorMessage="Please select a response for your height in inches."/>
</Poplist>
</Data>
</Row>
</Question>
Notes about this Example
The following example is a different variation of the previous example that asks for the respondent’s height in feet and inches. It uses a mix of text field control, poplist and a checkbox:
Hook Data
<question xmlns="http://www.datstat.com/2008/MultiControl.xsd">
<row>
<data>
<prompt value="Enter (and choose) your height:" />
</data>
</row>
<row >
<data>
<textfield size="4" variablename="HEIGHT_FEET_ALLFIELDS" labelafter="feet">
<numericvalidation required="true" errormessage="A numeric value between 1 and 7 for the height in feet is required." minvalue="1" maxvalue="7" />
</textfield>
<poplist style="FONT-WEIGHT: bold; WIDTH: 150px; TEXT-ALIGN: left" variablename="HEIGHT_INCHES_ALLFIELDS" labelafter="inches" unansweredresponse="--Inches--">
<requiredvalidation errormessage="Please select a certain amount of inches for your height" />
</poplist>
<checkbox variablename="HEIGHT_CHECK_OPTOUT" labelafter="I like my height">
</data>
</row>
</question>
The following example attempts to demonstrate all of the possible controls within a question table:
Hook Data
<QuestionTable xmlns="http://www.datstat.com/2008/MultiControl.xsd" width="1000px" numbering="({1})" promptHeader="Prompt Header">
<Instructions>Instructions</Instructions>
<TextField variablePrefix="TFCOM_" heading="TextField Heading" size="5" maxLength="5" columnWidth="80px" >
<TextValidation required="true" minLength="1" maxLength="2" errorMessage="Text field response must be 1 or 2 characters in length."/>
</TextField>
<RadioGroup variablePrefix="RGCOM_" heading="Radio Column Heading" columnWidth="80px" >
<RadioOption code="0" heading="Radio 1 Heading" />
<RadioOption code="1" heading="Radio 2 Heading" />
<RadioOption code="2" heading="Radio 3 Heading" />
<RequiredValidation errorMessage="A radio button response is required." />
</RadioGroup>
<Empty columnWidth="50" heading="This is a Space" headingStyle="border-bottom:none;border-top:none;" cellStyle="border-bottom:none;"/>
<CheckAll variablePrefix="CBGCOM_" heading="Checkbox Group Heading" columnWidth="80px" >
<CheckAllOption heading="Check 1" name="0" />
<CheckAllOption heading="Check 2" name="1" />
<CheckAllOption heading="Check 3" name="2" />
<CheckAllValidation errorMessage="You must select between 1 and 3 items in the checkbox group." minRequired="1" maxRequired="3" />
</CheckAll>
<Checkbox variablePrefix="CBCOM_" heading="Checkbox Heading" columnWidth="80px">
<RequiredValidation errorMessage="You must select the single checkbox."/>
</Checkbox>
<Poplist variablePrefix="POPLCOM_" heading="Poplist Group Heading - Pick a Number" columnWidth="175px" unansweredResponse="Please Select a Number">
<RequiredValidation errorMessage="Please select a response for your height in feet."/>
</Poplist>
<Row prompt="Prompt 1"/>
<Row prompt="Prompt 2"/>
<RowHeader value="Row header value" style="background-color:#CCCCCC;border-bottom:none;" />
<Row prompt="Prompt 3"/>
</QuestionTable>
Hook Data Explained
Must be in each XML. The Numbering= determines if you will number or letter your rows
Allows you to write instructions for your Question Table
Each Type of Control will need a Prefix to be defined and then used in the Preload/Hidden Variables that get created. This is the Text Field prefix. There are three Preload/Hidden variables that have been created with this prefix. TF_1, TF_2, TF_3
The RadioGroup needs a Heading for each option and a Preload/Hidden Variable for each.
This will add a space between sections. The Heading was added to explain the gap.
The CheckAll requires that you check the Multi-Value in the Preload/Hidden Variable creation. Scale Values will also need to be added. See The example Multi-Control Example Survey
The Checkbox requires Preload/Hidden Variables that have the Data Type as Yes/No
The Poplist code information can be coded in the XML or can be part of the Scale Values in the Preload/Hidden Variables. In this case it is part of the Preload/Hidden Variable.
This represents 3 Question Prompts with a row header between the 2nd and 3rd Prompt.
Notes about this Example
Survey templates are reusable models upon which surveys can be built. A template may include headers, footers, images, questions, and blocks of HTML.
To create a new template, create a new survey and then designate that survey as a template the first time you check it in. See Checking in a Survey for details on templates and the check in process.
If you have already checked in an item as a survey and want to change the item to a template, clone the existing survey and check in the clone as a template.
Any new surveys you build from the template will include the template's header, footer, stylesheet, and other survey-wide preferences, as well as its questions.
Every Illume survey contains a Login Collection which cannot be deleted. Items in the Login Collection will be presented to participants before they have logged in to the survey. In fact, the purpose of the login collection is to ask participants for credentials to log in. Generally, a Login Collection might include a welcome message, and one or more questions. These will be the first things a participant sees when he or she comes to your survey.
If your survey requires participants to log in, there are two things you need to do to set up participant authentication: First, use the Illume Web Console to upload a list of eligible participants. Then create questions in the Login Collection that Illume can use to authenticate participants. When you upload a list of participants, your list can include any fields you choose. For example, you may upload a participant list containing the first and last names of all participants, along with their email addresses and employee ID numbers. Let's assume these fields in your participant list are named FIRSTNAME, LASTNAME, EMAIL, and EMPID. Let's also assume you want participants to log in using their email address and employee id number. To do this, you would create two questions in the Login Collection: one name EMAIL that asks for the participant's email address, and another named EMPID that asks for employee id. The unique ids of these two questions must match the name of the columns in your participant list. When a participant types in his or her email address and employee id, Illume looks for an entry in the participant list with the given email address and employee id. If it finds a matching entry in the list, the participant starts the survey. If there is no matching entry in the list, the participant cannot start the survey.
You may use any field or combination of fields in your participant list to authenticate participants. For each field you want to use, add a question to the Login Collection and make sure the question's unique id matches the desired field name in the participant list.
If you want participants to be able to take your survey without having to log in, do not put any questions in the Login Collection. You may still include Text/HTML items in the Login Collection to display a welcome message.
This option applies only to unauthenticated surveys and prevents multiple submissions (or “stuffing the ballot box”) by the same computer and allows users to resume survey sessions for unauthenticated surveys. Multiple submissions are prevented unless cookies are deleted from the survey participant’s computer.
This option is not recommended in situations where a fairly high percentage of survey participants are expected to use computers in the same shared computing environments. This is often the case in academic environments.
To enable this option, select Edit > Preferences and then the Advanced tab. Check the box entitled: Use browser cookies to track unauthenticated survey sessions. Note that this check box will appear grey and be disabled if the survey is authenticated, i.e. there are one or more questions in the LOGIN collection.
If you do not want to create unique ids for all of your participants, but you do want to ensure that only people on your participant list can take your survey, follow these steps to use Illume's internal system-generated IDs:
Do not include duplicate entries in your participant list. For example, if you are requiring participants to provide an email address and employee id to access your survey, do not include in your participant list more than one participant with the same combination of email address and employee id, even if other data for these two participants differs. When a participant logs in, Illume looks for a unique participant in the list who matches the supplied credentials. If Illume cannot find a unique entry matching the credentials, the participant will not be allowed in. Do not include questions in the Login Collection whose unique ids are not column names in the participant list. The example above used EMAIL and EMPID as the unique names of questions in the Login Collection. These matched the EMAIL and EMPID fields in the participant list. If the EMPID question had been named EMPLOYEEID, no participants would be able to log in, because the participant list contains no EMPLOYEEID column.
