Getting started with survey programming (r9)

IntelliSurvey offers two different ways to program surveys:

1. IntelliSurvey's proprietary Survey Programming Language (SPL)
2. IntelliBuilder, a drag and drop editor interface.

In this article, we'll first provide a brief overview of SPL. Then, we have a step-by-step guide to get a survey up and running (example questions are provided). Lastly, we will provide an overview of IntelliBuilder.

For new Survey Programmers (SPs), we recommend starting with SPL. Having familiarity with our SPL will greatly enhance your ability to support IntelliBuilder users.

Overview of Survey Programming Language (SPL) 

IntelliSurvey's SPL is designed to be readable and intuitive. It does not require prior programming knowledge to learn, nor any external tools or software. However, there is a learning curve as with any text-based programming language. With that learning curve comes the ability to create complex, highly customizable surveys quickly. 

Anatomy of SPL

The survey's source code can be thought of as a series of widgets. These are the building blocks of the survey. Widgets encompass every aspect of the survey, both visible content seen by the respondent (e.g., questions, text, images) and the aspects that are hidden (e.g., skip logic, termination points, quotas). 

Lists are fundamental to how the survey's data is organized. If widgets are the building blocks, lists are the floor plans. Lists are created using widgets. They can be defined as part of a question widget, as shown in the example below, or they can also be defined independently using the set list widget. Lists also include the rows and columns in a table, as well as spreadsheets such as a ZIP code database. For more information on lists, see Lists overview.

Tags are added to widgets, one per line, and are used to modify or define the content or behavior of a widget. Decorators can also be included to customize tags or list items.

It is important to have a familiarity of the widgets available for use. When programming a survey, think about which widget is most appropriate for each component of the survey. A good starting point for widgets is to consider commonly used question types. See Question types overview and Table types overview for more information.

Survey pages and respondent paths

The SPL source is interpreted by the software linearly from top to bottom (with a few exceptions for some hidden widgets). When the software builds the survey, it organizes the SPL into a series of numbered pages. The respondent always begins on page 1, and the survey pages are processed in numerical order as the respondent proceeds through the survey.

When the respondent submits a survey page, the software will first check to see if the next page contains skip logic. If it does, and the logic evaluates as "false," the page will be skipped. If the skip logic is "true," or there is no skip logic, the software will then check to see if the page has any visible content. For example, a page may contain only survey variables, which are not shown to the respondent. In that case, the software will designate the page as hidden. Hidden pages are still processed but not displayed to respondents. Otherwise, if the page has visible content, then that page will be displayed. This process is repeated until the respondent finishes the survey. 

The display order of pages may also be randomized using blocks, loops, or by adding an order tag to a group. 

Ending the survey

The survey can end in a few different ways: 

• The respondent reaches the final page of the survey.
  • If the final programmed page has a question or other widget that needs to be processed, the software will add an additional page after it with a default completion message.
• The respondent is terminated by a term point or quota. In this case, they will be routed to a page that is system-generated and distinct from the completion page.
• The respondent reaches a page with the end survey widget. This widget allows for a lot of customization, such as redirecting the respondent to a different web page.

Survey quick start guide

The following guide will help you get a survey up and running quickly. You do not need to have a pre-written survey ready to program — example questions will be provided below. 

Step 1: Creating a new survey

From the Survey Navigator, in the navigation menu on the left, click the New Survey button to create a new survey.

• A survey ID will be automatically generated. Replace this with your preferred survey ID. This ID will show in the distributed links, so be sure to obfuscate any client or survey-specific information.
• Enter a Survey Description. This is the description that will be seen at the top of the screen when navigating the survey's applets.
• Theme, Country, and Language are all preset. Change them as needed.
• The Editor mode defaults to Survey Programming Language (SPL). Keep this selected to begin programming in SPL. The editing mode can be switched to IntelliBuilder at any time.

Step 2: Adding survey content

Once the survey is created, you will be shown the Edit applet in SPL mode and the empty survey source. This is the text-based editor for writing and editing SPL (a.k.a., the "SPL editor"). More information on the SPL editor's features can be found in SPL editor overview.

The SPL editor includes a code snippet tool to help you get started. The snippet tool includes example sets of survey questions. To insert these into your survey, follow these steps:

1. With your cursor active in the editor, press Ctrl-Space (PC) or control-space (Mac) to display the list of snippets.
2. Type the word "example" to show only the example snippets.
3. Use the arrow keys on your keyboard to highlight a snippet, and press Enter to insert it, or click on it with the mouse.
4. Once the code is inserted, you may modify it to match your needs.

Feel free to select any of these examples to begin with. The code generated by example_set_1_questions is shown below.

For more information on the snippets and good coding practices, see Creating and editing surveys with SPL.

Select snippet (Ctrl-Space, then type "example")

example_set_1_questions code

# Basic Questions RD. This is a basic radio type: radio 1. Yes 2. No RH. A horizontal scale with headings type: radio hscale: y optsfrom: series[1..10] headings: Left, Right CB. This is a basic checkbox type: checkbox 1. North 2. South 3. West 4. East TE. This is a text input type: text placeholder: Please type here NT. This is a numeric input type: number step: 5 range: 0-100 postfix: % TB. This is a larger text input type: textbox placeholder: Please type here

Step 3: Review and commit changes 

When you are ready, click Save Version in the upper right of the editor. You will be presented with a screen that will highlight the differences between the original source and the new version. New surveys begin with an empty source, so the first submission will show all green text on the right side, indicating additions. When content is removed/deleted in later versions, the removed content will be shown in red. It is good practice to review this page carefully for errors when making changes to the survey source.

To submit the source, select Commit Changes in the upper right. The software will begin parsing the SPL to apply the changes and build the new version of the survey. If any issues are found while attempting to compile the source code, the parser will display them in a list on the next screen.

Depending on the severity of the issues, the survey may not parse until they are fixed. For more information, see Submitting and publishing SPL content.

Step 4: Testing and revisions

If the survey has programming errors, the software will allow you to go back and make any needed changes. If it successfully parses, you will be presented with links to test the survey. Click the Back to Editor button in the upper right to return to the editor if additional edits are required. 

Testing is a crucial step in the survey programming process. It is the best way to make sure all questions are displayed and behave as desired, and to verify the logic is working correctly (skip logic, quotas, terminations, etc.). Testing surveys with multiple paths can be a complex task. IntelliSurvey offers a set of tools to aid in testing. For more information, see Running surveys in Testmode.

In some cases, it is easier to test a survey by reviewing the data it generates. Dummy data is a tool that populates the survey with random data. For new users, dummy data can also make it easier to become familiar with our reports and deliverables.

IntelliSurvey also allows for surveys to be edited without disrupting respondents or others testing the survey. For more information, see Draft and Pub versions.

IntelliBuilder

IntelliBuilder (IB) is a menu-based editor mode intended for any user to jump in and create or edit surveys immediately, without any knowledge of SPL. Surveys may be constructed entirely in IntelliBuilder without ever using the SPL editor mode, with some limitations.

To access IntelliBuilder from the Edit applet, click on Editor Mode in the upper left, then select IntelliBuilder. This will switch the survey's editing mode from SPL to IntelliBuilder. 

In IntelliBuilder, the survey is comprised of a series of elements. These can be visible questions, or structural elements such as standalone text, lists, or quotas. To add an element, click the Add Question button at the top of the survey. The Add Question menu will appear below.

The options in this menu are organized by the type of element. Once an element is selected, the menu transitions to the Element Editor (shown below), where the appropriate input fields for the element type are presented, along with the relevant menus to define various properties and attributes. For more details, see Creating survey elements with IntelliBuilder.

The order of the elements determines the order respondents will see them in the survey. Each element will be shown on a single "page." To reorder elements, click and drag the handle icon in the upper left. Note that question numbers may need to be updated after reordering.

For more detailed breakdowns of all aspects of IntelliBuilder, see Getting started with IntelliBuilder.