Database for Contents

A Database for Contents can be found in the Special Features. This is an internal project miniature database (non-relational), stored in the data for use in the questionnaire, or can even be changed during the questionnaire. This leads to a number of different possibilities, e.g.

• Effectively manage a larger number of text fragments
• Transfer values to subsequent questionnaires
• Manage data across multiple questionnaires (e.g. count quotas, rotate stimuli systematically) i.e. exchange data between questionnaires
• Show personalized data (relay data in the questionnaire) using the participant key (access code) or the reference
• Preset customized input fields in the questionnaire (in combination with preset())

In addition to this, the question types Extended Selection and Suggesting Text Input offer the possibility to access the database. This enables the programming of very extensive and/or dynamic selection questions.

The commands dbGet() and dbSet() are used to access the database through PHP code. The data is read to a key with dbGet() and data can be written to the database with dbSet(). Available keys can be listed with the command dbKeys().

Note: Please note: when the project is exported, the data in the Database for Contents will not be exported yet. When a project is archived, the data will be deleted rather than archived. Changing this is planned in the next version of the programme.

In the Database for Contents, pairs made up of one key each (an ID) and data can be stored.

• The key can be a number or a short text (max. 64 characters).
  • If keys are required for different categories, a letter can just be put in front of the numeric code, e.g. A1, A2 and A3 for category 1 and B1, B2, B3 and B4 for category 2.
  • The key cannot contain blank spaces at the beginning or the end (these will be cut off). Control characters (tab key and the like) will be removed. On the other hand, blank spaces and special characters are allowed.
• The data is always combinations (arrays) of one or several texts and/or numbers. Numbers are treated like text and presented later on in the questionnaire as text (e.g. '1'). Control characters (e.g.) line breaks are not possible in the text – of course, HTML tags are.

The data stored can be called up in the questionnaire by using the key. As depicted below, a database could contain the following pairs of keys and data:

First of all, the data has to be stored in a table, e.g. in excel or Open Office Calc:

• the first column must contain the key
• the other columns contain the data
• there can be no headings in the first row: the table must begin with data immediately.

In order to generate the database entries described above, your table would look as follows:

Save this table in a CSV (Character Separated Values) format. This is nothing more than a text file in which the values are listed in a row and are separated by a given character (e.g. tab).

Now select the CSV file in Special Features → Database for Contents → Import Data (CSV) and confirm with OK. In the following window, a few more details will be queried – normally, SoSci Survey recognises the correct format settings for the file automatically.

If you are working in a multilingual project, you can store different data for different language versions. The programme always checks, whether a separate entry exists for the current language version – and when not, uses the entry from the base language (Multilingual Surveys).

Note: Every line in the table must have at least 2 columns. Lines that only contain one key, or no data at all, are ignored during the import.

If you want to change the data, import a new/another CSV file. Duplicated keys are updated (overwritten) correspondingly. Apart from this, existing keys are not changed.

In order to delete entires, you can either remove individual entires or delete the entire database (all entries) in the “Delete Entries” tab.

Using the function dbSet(), entries in the Database for Contents can also be changed or deleted during the questionnaire.

You may update the “Database for Contents” during data collection, using dbSet(). If necessary, you can download the database contents as CSV file at any time:

Special Features → Database for Contents → Button “Download”

In a study, 500 newspaper articles written by different people should be assessed. The articles come from an electronic database and are already available in tabular form. In order to ensure that each article is assessed equally often, randomization using urns is used. However, it would be extremely inefficient to create 500 individual text elements.

First of all, the articles must be imported into the internal project database. In order to do this, a table with the 500 articles is created in a spreadsheet as follows:

The table is saved as a CSV file. The first row here is only used for labeling – the CSV should not include this. The CSV file is imported into the project in Special Features → Database for Contents.

The numbers 1 to 500 (one number per line) are in the “article” urn. Please see Randomization Using Urns for details regarding urn draws.

In the questionnaire, a ballot is drawn from the urn and the entry read out of the database using dbGet(). Afterwards, the article is shown via html():

urnDraw('article', 'IV01');
$key = 'a'.value('IV01_01');  // write an "a" before the number
$content = dbGet($key);
 
html('
  <h2>'.$content[0].'</h2>
  <div>'.$content[1].'</div>
');

It was asked in the pre-survey of a diary study which television station a person uses. In further enquiries during the diary study, the daily period of use for the respective station was prompted. For this purpose, only the stations that were selected in the pre-survey should be offered in a text input.

SoSci Survey's mailings function is used for the entire diary study. By using caseSerial(), a unique personal code can be generated in every questionnaire.

Note: If the e-mail address is only collected in the first questionnaire (Multi-Wave Surveys with Self-Recruited Respondents), please use value() with the identifier of the opt-in question instead of caseSerial() in this questionnaire.

In the pre-survey, the television channels used are prompted in the multiple-choice “FS01” on page 2 of the questionnaire. The selection is noted in the database on page 3 (or later):

$station = getItems('FS01', 'is', 2);
$key = 'FS-'.caseSerial();  // the mailings number is preceded with a "FS-", so that other content can still be saved in the database.
dbSet($key, $station);

In the daily questionnaires, the period of use for the station is prompted using the text input “NU03”. This question contains the same items in the same order as the multiple selection “FS01”. The following PHP code reads the data from the database and only shows the corresponding input fields:

$key = 'FS-'.caseSerial();
$station = dbGet($key);
question('NU03', $station);

Important: dbGet() always returns an array – even if you only store a single value with dbSet().

If you store a single value in the first questionnaire, you must access the first (and only) array element in the other questionnaire using square brackets ([0]).

$group = value('RG01');
 
 $key = 'RG-'.caseSerial();  // Again, a prefix is used for the database entry to keep all options open
dbSet($key, $group);

 $key = 'RG-'.caseSerial();
$data = dbGet($key);
 if ($data) {
  $group = $data[0];
 // cache the value into an internal variable,
 // to use the value later via value() (optional)
 put('IV01_01', $group);
 } else {
// show error message that something went wrong
show('XY01');
 	 put('IV01_01', -1);
 	 }

The PHP code for the second questionnaire also provides for the case that no matching entry is found in the content database.

In a survey, participants have to fill in several lengthy scales. As a thank-you, they can look at an analysis of their results two weeks later. The analysis cannot be conducted live (valueMean(), Count Points for Answers) because the standard values from the sample have to be determined first of all. To call up their results, the participants have to note down a code because the survey is conducted anonymously.

Therefore, an 8-digit random code is created in the first questionnaire, saved in the database and displayed:

$chars = 'ABCDEFHKLMNPRSTUVWXYZ23456789'; // characters that normally cannot be confused
$code = '';
for ($i=0; $i<8; $i++) {
  $code.= $chars[mt_rand(0, strlen($chars)-1)];
}
// save code in database (preceded with "X-")
put('IV02_01', 'X-'.$code);
// display code
html('<h1>Results</h1><p>Please note down <strong>'.$code.'</strong></p>');

The data is analysed after collection and three result values are calculated for each participant. These are – together with the code from IV02_01 – saved in a table as a CSV file:

In the second questionnaire, the participants have to enter their code first of all (text input “AB01_01”). Then, on the second page, a check is performed as to whether it exists in the database and, when yes, the results are then displayed.

$key = 'X-'.value('AB01_01');  // preceded with X here again
$result = dbGet($key);
// when code is wrong, show code request (previous page) again
if ($result === false) {
  text('wrong code');
  repeatPage();
}
// otherwise, result is shown
html('
  <p>Well-restedness: '.$result[0].'%</p>
  <p>Astuteness: '.$result[1].'%</p>
  <p>Friendliness: '.$result[2].'%</p>
');

In a (non-anonymous) customer survey, some master data is already known – however, it should be updated/completed in the questionnaire. The customers receive personalized links (access “Access Codes”) with a code assigned to each customer beforehand. 12-digit numbers are used for these so that codes belonging to other customers cannot be guessed and their data accessed, which could easily be done if a consecutive customer number was used.

A table is created with the code in the first column and the master data next to it. The table is saved as a CSV file and imported into the internal project database.

The code is transferred as the access code (s) in the personalised URL to the Questionnaire and is therefore available in PHP code via caseSerial().

The text input “ST01” has the following input fields: company (01), street (02), house number (03), ZIP code (04), place (05). By using prepare(), the known data is now entered – if necessary, the customer can adjust this when filling it in.

$key = caseSerial();
$info = dbGet($key);
if ($info !== false) {
  preset('ST01_01', $info[0]);
  preset('ST01_02', $info[1]);
  preset('ST01_03', $info[2]);
  preset('ST01_04', $info[3]);
  preset('ST01_05', $info[4]);
}
// now show the question 
question('ST01');

To add an entry to the database for content during the interview, it must be read out, added and then written again.

For example, under the key “FS-<Serial number>” a-priori data was stored (3 entries per person, i.e. indices 0 to 2). In survey wave 1 a product preference from question PP01 is now to be added as fourth date (index 3). The following PHP code could then be placed on the page after the page with PP01 (see notes on value())

$key = 'FS-'.caseSerial();
// Reading data
$data = dbGet($key);
if ($data === false) {
  // No data found - maybe show warning
  $data = array(-8, -8, -8);  // ... and initialize the data element
}
// Add the answer from PP01
$data[3] = value('PP01');
// save entry again
$data = dbSet($key, $data);

The content database can also be used to gradually narrow down long selection lists. In the following example, a district is to be selected first and then, in the next step, a station within the district.

For this purpose, a list is first created in the content database, which contains the city districts and the stations. It is important to assign suitable database keys. These must meet the following criteria:

1. Districts and stations require a different prefix, which means that the keys must start with different letters, for example. In the example, the keys for districts start with “S” and those for stations with “H”.
2. Stations belonging to a district must use the same additional code after the “H”. All stations in district A would therefore begin with “H01”, for example.
3. It saves work to choose the answer code for the districts so that they match the prefixes of the station keys. So e.g. code 1 for district A and accordingly the prefixes “H01” for the associated station.

The list for the import could look like the following:

S01  1 District A
S02  2 District B
S03  3 District C
...
S50 50 District Zeta
H0101  101 station "Ammersberg" in district A
H0102  102 station "Breitenbach" in district A
H0103  103 station "Clemensstraße" in district A
...
H5017 5015 station "Zwiebelturm" in district Zeta

Now two questions of type Extended Selection are created in the question catalog. The options are to get these two questions from the database. For the prefix in the question for the districts set “S” and for the database prefix for the stop question set “H”. The preview shows now all stations.

Tip: Instead of an extended selection, you can also use a Suggesting Text Input. This is useful if, for example, you have a lot of answer options for the districts.

If the preview of the questions corresponds to your desires (only with the stops still too many indicated), then it goes now and Compose Questionnaire. There you place the questions for the city districts (“AF01” in the example) on one page. On the next page, a little PHP code and the function question() is used to place the question for the stops (“AF02”). The parameter 'filter' is used here to ensure that only the matching stops are displayed.

// First read out the selected district
$district = value('AF01');
// Then create the prefix for the matching stops
$prefix = 'H'.sprintf('%02d', $district);
// Then show the question about the district with the appropriate options.
question('AF02', 'filter='.$prefix);

The function sprintf() ensures that the response code from AF01 is output with two digits (format code %02d). 1 thus becomes the string '01'.

The dot (.) is used in PHP to concatenate strings. So if in the variable $prefix e.g. “H01” is stored, then 'filter='.$prefix becomes 'filter=H01'.