====== 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 (authorization code) or the reference
  * Preset customized input fields in the questionnaire (in combination with ''[[:en:create:functions:preset|preset()]]'')

In addition to this, the question types [[:en:create:questions:extselect|Extended Selection]] and [[:en:create:questions:suggest|Suggesting Text Input]] offer the possibility to access the database. This enables the programming of very extensive and/or dynamic selection questions. 

The commands ''[[:en:create:functions:dbget|dbGet()]]'' and ''[[:en:create:functions:dbset|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 ''[[:en:create:functions:dbkeys|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. 

===== Feature =====

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: 

^Key^Data (Combinations)^
|A1|(apple tree, apples)|
|A2|(pear tree, pears)|
|A3|(clementine tree, clementines)|
|B1|(6)|
|B2|(12)|
|B3|(18)|
|B4|(24)|
|B5|(30)|



===== Import 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:

|A1|apple tree|apples|
|A2|pear tree|pears|
|A3|clementine tree|clementines|
|B1|6| |
|B2|12| |
|B3|18| |
|B4|24| |
|B5|30| |



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 ([[multilang|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. 


===== Change Data =====

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 ''[[:en:create:functions:dbset|dbSet()]]'', entries in the **Database for Contents** can also be changed or deleted during the questionnaire. 


===== Example 1: Extensive Test Material =====

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, [[:en:create:random_urns|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: 


^Key^Title^Text^
|a1|Train Drivers' Strike: Society at Hostage|The freedom to strike is in the constitution for good reason ...|
|a2|The Role of Juncker's Network|President of the EU Commission, Juncker, maintains relations with the main leaders of Europe ...|
|a3|Carsten Maschmeyer Sues Swiss Bank|According to information from the Suddeutsche, the investor Carsten Maschmeyer has ...|

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  [[:en:create:random_urns|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()'':

<code php>
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>
');
</code>


===== Example 2: Exchange Data Between Two Questionnaires =====

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. 

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):

<code php>
$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);
</code>

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: 

<code php>
$key = 'FS-'.caseSerial();
$station = dbGet($key);
question('NU03', $station);
</code>


===== Example 3: Relay Analysis  =====

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 (''[[:en:create:functions:valuemean|valueMean()]]'', [[:en:create:points|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:

<code php>
$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>');
</code>

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:

|X-ABCDEF12|7|19|8|
|X-CDEFG234|24|16|19|
|X-ZU7652AB|15|95|80|

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. 


<code php>
$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>
');
</code>


===== Example 4: Relay A Priori Data =====

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 "Authorization 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.

|12345678ABCD|SoSci Survey GmbH|Marianne-Brandt-Str.|29|80807|Munich|
|9876542UBGAD|Company|Road|7|12345|Town|
|72KU635485UG|MSD-Media GbR|Korbinianstr.|17|||

The code is transferred as the authorization code (''s'') in the personalised [[:en:survey:url|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.

<code php>
$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');
</code>