How to Read External Data into a webSurvent Study

There are three primary ways to read external data into webSurvent at the start of the survey. Each method has its pros and cons.

1) JavaScript via parse_query() – Stores information from a URL


This method relies on JavaScript being enabled and reads the data from the URL. This is generally a quick method for pulling values such as panel sample variables into a survey.

Usage: Insert a script at the bottom of the page (before the end grid). This script needs to contain two matched arrays: one for parsing the URL query string and one for the question labels to store the questions in, and a call to the parse_query function.

Index page setup: There is nothing extra needed in the index.html file.

The question setup: All questions used for storage must be VARIABLE type questions. They do not need to be hidden using a VARIABLE,GET_FROM_HTML_VARIABLE but it is recommended. Make sure the questions are large enough to store the data for each element from the URL.

Example:

{ QGRIDQ1:Welcome to the survey. We've gathered the information you passed and it will be displayed on the next screen.!GRID,BLANK_OK }{ QRESPNAME:!VARIABLE,GET_FROM_HTML_VARIABLE,40,0 }{ QAGE:!VARIABLE,GET_FROM_HTML_VARIABLE,2,0 }{ QGENDER:!VARIABLE,GET_FROM_HTML_VARIABLE,1,0 }{ QOTHER:!VARIABLE,GET_FROM_HTML_VARIABLE,2,0 }


The script setup: There are two arrays that must be created by the programmer: one for reading in data from the URL, the other to tell the script where to store each item of data. These arrays must have the same number of elements and the elements order should match. The first item in the URL array will write to the first question in the VARIABLE array.

General array rules:

  1. Each array element must be in quotes followed by a comma.
  2. The last array element must be followed by a close parentheses and a semi-colon.
  3. Quotation marks are NOT ALLOWED within an array element.

The URL array: There are two ways provided for getting information from the URL, by name and by location. Which you choose to use will be defined, in part, by what the query in the URL looks like. You set this by changing the value of the variable GET_BY.

var get_by = “name”; //set as location or name.
var get_by = “location”; //set as location or name.

In order to use the name option, the URL must contain a name for each data element you wish to read in, and each item must be separated with an &. Make sure that the case you use matches the case in the URL.

In the name example, the query part of the URL (everything after the ?) looks like:

?name=<username>&password=<password>&respname=Charlie&age=45&gender=1;other=ab

<script type=“text/javascript”>
var get_by = “name”; //set as location or name.
var urllist = new Array(
“respname”,”age”,”gender”,”other”);

In using the location option, you can write the entire string into data and parse it later. For each item, you need to provide a starting location followed by a length, separated by a period. In determining the starting location, keep in mind that JavaScript always starts counting at zero, not one.

In the location example provided, the query part of the URL looks like:

?Chazz451ab&name=<username>&password=<password>

var get_by = “location”; //set as location or name.
var urllist = new Array(“0.5″,”5.2″,”7.1″,”8.2”);

The var array: Contains the names of the VARIABLE question labels being used.

var varlist = new Array(“qrespname”,”qage”,”qgender”,”qother”);

As the last part of the script, call the function with parse_query(); The full script would look like:

{<script type=“text/javascript”>var get_by = "name"; //set as location or name.var urllist = new Array("respname","age","gender","other");var varlist = new Array("qrespname","qage","qgender","qother");parse_query();</script>!DISPLAY }{!ENDGRID }


2) Login page user_data –Storing information from USER_DATA

In the log in page (e.g. index.php ) you can set a hidden variable called user_data. This information will be read into the survey by Survent.There are two ways to get this information.

A) User_data variable
WebSurvent will pass the string contained in the hidden input USER_DATA into the survey. This hidden input is automatically written on every page of the survey if it is defined. USER_DATA can only have up to 120 characters.The JavaScript function parse_query reads the strings and puts it into the data. This function is only usable on the first page of the survey.

Usage: Insert the script at the bottom of the page (before the end grid). This script needs to be just the call to parse_query function. You’ll need to pass the name of the var question to store data in to the function.

Index page setup: You need to place the following in the index page for the study.

<input type=”hidden” name=”USER_DATA” value=”this is user data”/>

The question setup: The question used for storage must be a var type question. It does not need to be hidden using a VARIABLE,GET_FROM_HTML_VARIABLEbut it is recommended. Make sure the question is large enough to store the data coming from USER_DATA.

Example:

{ QGRID1:!GRID }{ QUSERDATA: !VARIABLE,GET_FROM_HTML_VARIABLE,40,0 }{<script type=“text/javascript”