Other Survey Objects

To add text to a survey (for welcome pages, consent forms, interviewer instructions, or other communications), or to embed Resources like Flash animations, movies, Java applets or sound clips, use the Text/HTML Item editor.

To add any of these elements to your survey:

1. In the right pane of the Survey Editor, click on the item after which the desired Text/HTML Item is to appear. (If the item is not currently showing in the right pane, click on the collection that contains the item in the left pane of the Survey Editor.)
2. Click the Add Text/HTML icon in the toolbar.
3. Create the HTML in the HTML Editor. See “Using the HTML Editor” for detailed information about how to use the HTML Editor.
4. Click OK to save your work.

Describing Text/HTML Items for the Data Dictionary

The Text/HTML editor includes a General tab where the unique name is entered. While a Text/HTML item can be given a unique name and a description, this information does not actually go into the data dictionary. The information is simply for reference.

Controlling Where and When Text/HTML Items Appear

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.

Text/HTML items can be moved to any location in a 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.

Show-if conditions can also be applied to a Text/HTML item, so that it will be displayed only when the conditions described are met. For information on how to create Show-if conditions, see “Setting Show-if Conditions”.

To preview a Text/HTML item select it in the right pane of the survey editor. Click the Preview selected item… button in toolbar.

Illume’s HTML editor enables the User to create HTML pages, or parts of pages, without any knowledge of HTML.

What You See is What You Get

Except for parameters and built-in survey variables, any content created 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, other parameters can be defined as desired.

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 formatting attributes to apply. Click once anywhere in the editable area to deselect the text to see that the formatting has been applied.

NOTE: When working on a multilingual survey, with the translation tools enabled, a list of languages will be available at the bottom of the Text/HTML editor. Choose a language to edit the Text/HTML for that specific translation. Any changes made to that Text/HTML, or to the Description (on the Data Dictionary tab) will apply only to the selected translation. Any changes made to the unique name of the Text/HTML item, or the show-if conditions, will apply to ALL translations.

Adding Images

To add an image to a Text/HTML item, follow these steps:

1. Move the cursor to the position to insert the image.
2. Click the Insert image button.
3. If the image to insert has already been added to the survey, it will appear in the Select Resource list. Simply click on the name of the image and skip to step 9 below.
4. If the image already exists on a web server that will be available to participants, simply enter the URL of the image. The image will appear in the participant’s survey just like any other image.
5. If the image to insert does not appear in the Select Resource list, click New Resource… to add the image.
6. In the resource editor, click Upload to upload the image into the survey. This brings up a file selection dialog from which to choose the file to upload. Select the appropriate file and click Open. Illume will upload it into the survey resources.

7. The name of the image will appear in the Unique Name field. This can be edited if desired.

NOTE: Once an image is uploaded, it will appear in the “Select Resource” list under its unique name, and will be available for reuse anywhere in the survey.

8. It is possible to add an optional description for the image. A good description can help survey editors determine whether the image is appropriate for use elsewhere in the survey.
9. Click OK.
10. The image now appears in the list of available resources. It is selected, and the width and height are automatically filled in.

11. Set the image attributes as desired. These are described below.
12. Click OK. The image will be added to the document and can be moved to another place in the document by simply dragging and dropping.

Defining Image Attributes

It is possible to define the following image attributes:

• Width – The width of the image, in pixels. Illume sets this automatically to the actual width of the image, but can be reset as desired. See “Constrain width/height” below.
• Height – The height of the image, in pixels. Illume sets this automatically to the actual width of the image, but can be reset as desired. See “Constrain width/height” below.
• Constrain width/height – If this box is checked before changing an image’s width or height attributes, Illume will automatically ensure that the image maintains its original proportions when resized. That is, if the image’s width is reduced by 20%, Illume will automatically reduce the height by 20% as well. This ensures that the image displays correctly after being resized.
• HSpace – This is the horizontal space, measured in pixels, on the left and right sides of the image. If text runs up against the edge of the image, increase the image’s hspace attribute to provide more space. Setting this to 10, for example, will create an empty margin 10 pixels wide on the left and right sides of the image.
• VSpace – This is the vertical space, measured in pixels, that appears above and below the image. Setting this to 10, for example, will create an empty margin 10 pixels high immediately above and below the image.
• Border – This is the thickness of the border, measured in pixels, that surrounds the image. A value of zero means the image will have no border. Most browsers will apply a gray border to images. The only way to override this is to define a different color in a CSS stylesheet.
• Alignment – This determines how the image will be aligned on the page.

Baseline aligns the bottom of the image with the bottom of the line of text that precedes or follows the image.

Left aligns the image on the left side of the page, or on the left side of the table cell, if the image is in a table.

Right aligns the image on the right side of the page, or on the right side of the table cell, if the image is in a table.

Center aligns the image in the center of the page, or in the center of the table cell, if the image is in a table.

• Alternate Text – The alternate text property provides a description of the image. Normally, participants see this description when they mouse over the image, or when their browser is waiting to load the image. If a participant’s browser cannot display images, it will display the image’s alternate text instead.

NOTE: The alternate text attribute is important for visually impaired participants, whose computers may read the survey pages aloud to them.

Because the computer cannot “read” an image aloud, it reads the description of the image contained in the alternate text attribute.

If creating a survey aimed at government employees, or funded by the Federal government, the US Government’s Section 508 Usability guidelines require surveys to provide an alternate text description with all images. Find out more about the Section 508 guidelines at http://usability.gov/

Deleting an Image

To delete an image in the HTML editor, simply click on the image and press the delete key.

Adding Links

To add a link to the Text/ HTML item, follow these steps:

1. Select the text or image to which to attach the link. (If nothing is selected, the HTML editor will automatically insert the link’s URL as the text of the link.).  In the screenshot below, the text CLICK HERE was highlighted
2. Click the Insert Link button.
3. Type in the link’s URL. For example, to link to DatStat, type in “http://www.datstat.com” as the URL.
4. Click OK.

NOTE: When adding a link to an external location, Illume will automatically insert “target=blank” to the URL.  This will force this link to open in a separate browser window so the survey session is not lost.

Editing Links

To edit a link:

1. Select the text or image to which the link is attached.
2. Click on the Insert Link button.
3. Change the URL as needed.
4. Click OK.

Deleting Links

To delete a link:

1. Select the text or image to which the link is attached.
2. Click on the Insert Link button.
3. Delete the entire URL.
4. Click OK.

Copying and Pasting from Microsoft Word

It is possible to copy and paste text directly from Microsoft Word into the HTML editor, and the formatting will be preserved. It is also possible to 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.

1. Click on the Text/HTML icon in the Survey Designer toolbar.
2. Highlight the text in the Word document to copy.
3. Press Control-C to copy the text from Word.
4. Click in the HTML editor and press Control-V to paste the copied text.
5. Click OK to save the HTML.

NOTE: When pasting text from a Word document into the HTML tab of the HTML editor, the text pasted will retain the formatting from the Word document. When pasting the text into the Source tab of the HTML editor, the text will lose all of its Word formatting. This second option is preferable for the text to conform to the survey styles set up or to remove the extra Word formatting that may cause unexpected behaviors in the rendered survey.

Editing the HTML Directly

To edit HTML directly, click on the Source tab, on the bottom left of the field. Switch back by clicking the HTML tab again.

HTML Tab

Source Tab

Users control when to insert page breaks by inserting page breaks in desired locations.  It is not possible to set a survey-wide setting such as “the page should break after each question” – rather, users manually insert page breaks.

The one exception to the manual insertion of page breaks is in the situation of a question whose show state depends on the response to a prior question.   For example, if question number 10 asks a participant’s age and question 11 asks 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, the page break is automatic and cannot be prevented.  The page break will not be visible within the designer – you will see the page break when you preview the survey.  You may want to manually insert your own page break after question 10 in this example, so that you remember that question 10 and 11 will not appear on the same page.

It is possible to also insert page breaks wherever desired.

To insert a page break:

1. In the right pane of the Survey Editor, click on the item after which the desired page break is to appear. (If the item is not currently showing in the right pane, click on the collection that contains the item in the left pane of the Survey Editor.)
2. Click the Add a page break… icon in the toolbar.

The page break appears after the item selected. Page breaks can be moved to another location by dragging and dropping them.

Page breaks can be deleted by right-clicking on them and selecting cut:

In general it is recommend to insert page breaks after every 3-4 items, to prevent your respondents or interviewers from having to vertically scroll to see all of the items on the page.  The number of items after which a page break should be inserted will therefore be somewhat dependent on the overall size of the items on the page.

An Illume survey can capture any data passed in through the query string of the survey URL. This data is treated as if it came from the participant list. Participant list data and data that comes in through the query string of the survey URL have the following characteristics:

• The data are NOT saved with the participants’ responses, unless it is explicitly made to happen (see Saving Data From the Query String below)
• The data are available throughout the survey for use in piping, calculations, and show-if conditions.

NOTE: Information passed in a Query String is NOT encrypted.

A Practical Example

Assume there is 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.

The first invitation includes the following survey URL:

 https://www.datstat.com/Collector/Collector.ashx?Name=SurveyName&LoginId={userdata:LOGINID}&INCENTIVE=FREECD

The second invitation includes this URL:

https://www.datstat.com/Collector/Collector.ashx?Name=SurveyName&LoginId={userdata:LOGINID}&INCENTIVE=CHECK

It is possible to get the values of these variables anywhere in a survey by typing {UserData:Incentive} or {UserData:Criteria.OPTION1}. (The case of the letters does not matter. The curly braces do!)

A question can be created in the survey that asks which music CD the participant would like to receive, then 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.

Saving Data from the Query String

Like data from the participant list, data from the query string is not automatically saved with the participant’s responses.

To save the Incentive data from the example above, follow these steps:

1. Decide ahead of time what the name of the variable will be! For this example, we will use the variable name INCENTIVE.
2. In the Survey Designer, choose Survey / Preload/Hidden Variables….
3. Click the Add button.
4. Enter a unique name for the data. This name will appear in the Data Dictionary and will be the name of the variable in which the data are stored in the Data Manager. For this example, we will call the variable PAYMENT_TYPE.
5. Choose a data type that matches the data that is expected to be passed in the query string. For the INCENTIVE example above, choose Text.
6. Under Default Value, choose the User data option.
7. In the text box next to User Data type the name of the variable that will appear in the URL. For example, if the variable in the URL is called INCENTIVE, then type INCENTIVE here. This tells Illume to take the data from the INCENTIVE variable in the survey URL and to store them in the variable PAYMENT_TYPE when the participant submits the survey.
8. (Optional) Click the Scale tab and choose a scale option for this variable. A scale can be useful for creating calculated variables, show-if conditions, and data queries. The scale options include: Do not use a scale for this item – This is a good choice when the list of potential values for the variable is large.  Automatically generate a scale as unique values are discovered. This is useful if the variable may include an unknown set of responses within a limited range. For example, if passing the name of a partner site through the URL, it may not be known ahead of time who all the partner sites will be, but it is known that there will not be more than a few dozen of them.  Predefined – Use this if it is known ahead of time all of the possible values that the variable may store.
9. Click OK.

NOTE: The Preload Editor first looks in the participant list for the field named in User data name, and then it looks at the contents of the survey URL. If the participant list already contains a field called INCENTIVE, and a value of INCENTIVE is passed on the URL, then {UserData:Incentive} will contain the value passed in through the URL rather than the value from the participant list. In short, the value from the URL overrides the value from the participant list.

General Notes about URLs and Query Strings

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 the 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.)

Reserved Words

The following variable names are reserved for use by the Illume server. These variable names cannot be used in the URL:

• Name
• Path
• XmlDocument
• LoginId
• PageLayout
• PrintPreview

Words with Special Meaning

The following words have special meaning in the URL. You may use them, but you should understand first what they do.

• TESTDATA – If this is set to 1, the survey will be marked as test data when it is submitted.
• Translation – If this is set to a numeric or character LCID, Illume will attempt to present the survey in the language represented by that LCID.
• LCID – This has the same effect as Translation above.

Adding a Test Data Flag in the Survey URL

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 DATSTAT_ALTPID to authenticate participants, the following survey URL would give participant 9999 access to the survey:https://www.datstat.com/Collector/Collector.ashx?DATSTAT_ALTPID=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?DATSTAT_ALTPID=9999&TESTDATA=1

Any data the participant submits after accessing the survey with this URL will be treated as test data. The Data Manager 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.

Other Query String Parameters

Name                                                    – Name of survey to be taken
LoginId                                                 – Specifies credentials for auto-authentication
Translation                                          – Displays a specific language of survey
TestData                                              – Setting to ‘1’ (e.g. TestData=1) will ensure this is a test survey session
TestSurvey                                         – Allows a test survey to be viewed
_RS_                                                      – Suppresses the  resume survey page from appearing
_LNP_                                                   – Displays launch page of the survey.  Used if chrome-less survey is desired
_LNPD _                                               – Set on the launch page of the survey.  Done with launch page.
PageLayout                                        – Used by Survey Designer when displaying the survey in page layout mode
PrintPreview                                      – Used by Survey Designer when displaying the survey in print preview mode
DATSTAT.RMSPSID                          – Id of scheduled survey for a specific participant in RMS
DATSTAT.INTERVIEWER                – Id of Illume user that is the interviewer for this survey (value is stamped in the survey session)

The Survey Designer is designed so that survey objects can be easily reused.

There are three ways to reuse questions, question blocks and Text/HTML objects.

NOTE: The second method has some distinct advantages.

Copy from Survey to Survey

One way is to copy items from one survey to another. Simply open both surveys and drag the item to reuse from one survey into the other.

Copy Items from the Repository

It is possible to drag items out of the repository into a survey. If the item exists in the repository, this is the preferred method of reuse. You’ll find more detailed information about this in the Repository Overview.

NOTE: If a repository item appears with red text, it has not yet been approved for reuse, it cannot be dragged into a survey. Only approved repository items (those appearing in black) may be reused.

Sharing Survey Objects Through Email

Survey Objects can be dragged out of an existing survey and dropped into the text of an email. When this is done, the Survey Designer inserts an XML description of the object into the message.

The recipient of the message can highlight the XML, and 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.