Software notice: This article describes how to add and edit content with the Edit applet for software releases prior to r9. If this is your first time using the Edit applet, see Getting started with the Edit applet (Survey Editor) before proceeding.
Survey Programmers (SPs) have many options available to them when creating survey code, from writing code directly into the Survey Editor, to copying and pasting into the editor, or even starting in IntelliBuilder and then switching the editor mode. Whichever method the SP uses may come down to personal preference or what is best for the particular survey at that time.
If you have already finished this step and are ready to submit and publish your survey, read Submitting and publishing survey content with the Edit applet.
Best practices
Only one one user should edit the survey source code at a time. There is no mechanism for reconciling multiple, concurrent updates. Users attempting to edit a survey's code while another SP has the code open will see a dialog box informing them that the code is being updated by another user.
Additionally, special care should be taken when editing surveys which have had or presently have actual respondents in progress. If you find yourself in this situation, please read Editing live surveys for more information.
To increase efficiency, there are a few best practices we encourage SPs to employ to facilitate writing and editing code. Our best-practice approach for creating your "base code" (initial SPL source code) is to:
- Always modify the Word document directly and save it so you have a backup copy available.
- First, remove all unnecessary instructions or spacing, anything that will not be used in the final survey. For example, if you want the text to be red when it is displayed on screen, leave it red; but if the red text is only for internal purposes, remove it.
- Then, use the Clean Word utility to add HTML around rich text elements, e.g., bold, underlined, etc., and to adjust lists with lettered options to use numbered options instead. Lists with numbers will be easier to reference later on.
- Next, copy the processed questionnaire document from the Clean Word utility and paste it directly into the Survey Editor or your external text editor, wherever you prefer to work.
- Finally, replace question descriptors (instructions) like 'single select', '[SC]', etc. with the appropriate SPL tags. We'll cover this in more detail below.
Overview of the software's text editor
IntelliSurvey features a text editor designed to allow SPs to type survey source code directly into the interface. For software versions prior to r9, this is an externally maintained code editor called Ace. This editor features line numbering, syntax highlighting, as well as brace-matching capabilities, among other functionalities. While it is generally preferable to work in an outside text editor when programming larger projects from scratch, the Ace editor provides a clean, robust interface to view and edit survey code. For an in-depth look at Ace's capabilities, please visit their website.
Auto-completing tags and widgets
The Ace editor recognizes many shortcut key combinations, including an "auto-complete" feature for adding tags (e.g., type:
checkbox
), widgets (e.g., start table
), and other SPL syntax. To view a list of compatible completions, press Ctrl+Space (PC) or control+space (Mac) with the cursor adjacent to the last typed character in the phrase, or press Ctrl+Space and begin to type. Use the mouse or arrow keys to move between suggestions, then click the item, or press Tab or Enter, to choose the selected item.
In the example below, suppose the SP wants to find the randomize
tag. The SP types "rand" and sees the closest results first in the list - those that match the spelling precisely. This is followed by other options that are less exact. The name of the snippet appears in bold font, e.g., randomize, and the code that would be inserted into the source code is displayed beneath it, e.g., randomize:y
.
Note that in some cases, the auto-complete option will not just finish the word, but will also demonstrate the correct syntax. There are several pre-loaded examples for you to try. For instance, the table_example
will insert a "simple table" with inline rows and an optsfrom
listcall. There are placeholders denoted by the '$' and curly brackets. Once inserted into the code, the cursor will default to the first placeholder for you to easily insert the desired question/table ID. Then, press Tab to move to the next placeholder to write the list name, and so on.
Using the auto-complete feature is also a great way to learn more about IntelliSurvey's SPL. There are a few example sets of questions which you can insert into your source code to use as a reference for the most common question types. Follow the steps below.
Using the example set shown above, the following code would be added to the survey.
Keyboard shortcuts
Notable Ace editor shortcuts that work within the Survey Editor areas are listed in the article Keyboard shortcuts. Most standard navigation shortcuts work as well; the table highlights mainly unfamiliar mappings and functionalities.
Note that all applets in the software interface allow users to access this same article via the keyboard icon (
) in the bottom right hand corner of each page. Clicking the icon will open this article in a new tab within the interface.Advanced coding tip
For parts of the survey that are more complicated or that will be worked on later, use comments. Comments are ignored by the IntelliSurvey code parser. In the code editor, the lines are automatically recognized and grayed out. Single lines are commented out with a '#' at the line start; block comments start with '/*' before the first line and end with '*/'.
Referencing sheets
Spreadsheets can be used with surveys to provide list options for questions and tables, or with variables and quotas to match respondent input to. For example, a sheet "look up" could automatically determine if a respondent who lives in a specific ZIP code falls within the Tier 1 or Tier 2 zone of a particular store. Sheets that are attached "locally" to a survey are known as survey spreadsheets, whereas sheets that are located on a server are known as system spreadsheets. Survey spreadsheets are generally referenced as "survey_name.sheet_name," allowing for SPs to utilize sheets from other surveys on the same server, while system spreadsheets generally are referenced as "system.sheet_name." Surveys may also reference their own attached sheets as just "sheet_name".
In the example below, the autocomplete survey has a sheet called "ani_ids." The "ani_ids" sheet could be referenced as either autocomplete.ani_ids
, as shown below in the code, or ani_ids
since it is attached directly to the autocomplete survey.
If a survey contains references to either survey spreadsheets or system spreadsheets, the sheet reference will be shown underlined and in a blue font. To view a spreadsheet from the source code, hover over the sheet name and press Ctrl+click (PC) or ⌘+click (Mac). This will open a new tab in which the sheet may be viewed. Survey sheet links will bring the user to the Survey Spreadsheets applet, whereas system sheet links will bring the user to the System Spreadsheets applet.
Tip! Sheet references that do not begin with either the survey name or "system" do not allow the Ctrl+click functionality.
Adding images
The IntelliSurvey platform allows SPs to add and reference images in a survey in multiple ways. Images may be added to a survey's images directory/folder in the File Manager applet, then referenced in the code via links provided by the File Manager, or they can be directly added to source code in the Edit Survey applet via drag and drop or copying and pasting. Adding an image directly to source code automatically adds the file to that survey's images subfolder as well.
For more information on using the File Manager read Survey files. We also recommend reading Adding images to a survey for a more detailed look at all methods.
Adding images using the Survey Editor
Images may also be directly uploaded into survey source code via one of two methods - drag and drop, or cut and paste. For the drag and drop method, simply click on the desired image to select it wherever it is located on your device, then drag it into the Survey Editor. To cut and paste an image into the source, press Ctrl+C (or ⌘+C for Macs). Then, click in the source code in the Edit applet and hit Ctrl+V (or ⌘+V). A dialog will appear, showing the upload progress. A notification will then let the SP know the file was successfully added, and the image's URL will be added to the code.
The URL for the image will be pasted in the editor as an HTML string, using the format:
<img src="/s/<survey_id>/images/<imagename>"/>
When an image is pasted into source code, the file will automatically be added to the survey's images subfolder in r8.3+. For surveys on earlier software versions, any drag and dropped images will be added to the _s folder.
Next steps
Once you have content in your source code, you can either save a draft or "commit" your changes. Committing changes means to submit the source code to the server to be parsed (built and processed).
What's the difference? Saving a draft permits users to save source code in the application without the need to actually commit it. When a draft is saved in this manner, there is no need to address any errors, and it is accessible to all other users who have permission to open the Edit applet. However, the survey is not built, and it is not testable. If you wish to merge your edits to a Dev version of the survey and begin testing, then you should submit and compile your survey. Committing your changes will also create a new saved draft, overwriting any previously saved draft.
To move onto the next step of submitting and publishing your survey, read Submitting and publishing survey content with the Edit applet.
Comments
0 comments
Please sign in to leave a comment.