Differences

This shows you the differences between two versions of the page.

--- en:create:databank [16.01.2015 10:34] – admin
+++ en:create:databank [21.04.2024 20:21] (current) – admin
@@ Line 6: / Line 6: @@
   * 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
+  * 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 ''[[: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()''. The keys available can be listed with the command ''[[:en:create:functions:dbkeys|dbKeys()]]''.
+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.
@@ Line 40: / Line 40: @@
 ===== Import Data =====
-First of all, the data has to be stored in a table, e.g. in excel or Open Office Calac:
+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
@@ Line 76: / Line 76: @@
-===== Example 1: Extensive Test Material =====
+===== Download the Data =====
+You may update the "Database for Contents" during data collection, using ''[[:en:create:functions:dbset]]''. If necessary, you can download the database contents as CSV file at any time:
+**Special Features** -> **Database for Contents** -> Button "Download"
+===== Examples of Use =====
+==== 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.
@@ Line 106: / Line 115: @@
-===== Example 2: Exchange Data Between Two Questionnaires =====
+==== 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.
+**Note:** If the e-mail address is only collected in the first questionnaire ([[:en:survey:opt-in-live]]), 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):
@@ Line 128: / Line 139: @@
 </code>
+**Important:** ''dbGet()'' always returns an array -- even if you only store a single value with ''dbSet()''.
-===== Example 3: Relay Analysis  =====
+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]'').
+<code php>
+$group = value('RG01');
+ $key = 'RG-'.caseSerial();  // Again, a prefix is used for the database entry to keep all options open
+dbSet($key, $group);
+</code>
+<code php>
+ $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);
+ 	 }
+</code>
+The PHP code for the second questionnaire also provides for the case that no matching entry is found in the content database.
+==== 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.
@@ Line 173: / Line 212: @@
-===== Example 4: Relay A Priori Data =====
+==== 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.
+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.
@@ Line 183: / Line 222: @@
 |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 code is transferred as the access 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.
@@ Line 200: / Line 239: @@
 question('ST01');
 </code>
+==== Complement an Entry ====
+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 ''[[:en:create:functions:value]]'')
+<code php>
+$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);
+</code>
+==== Restrict Selection Options Successively ====
+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:
+  - 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".
+  - 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.
+  - 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:
+<code>
+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
+</code>
+Now two questions of type [[:en:create:questions:extselect]] are created in the question catalog. The options are to get these two questions [[:en:create:questions:extselect#options_from_the_database|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 [[:en:create:questions:suggest]]. 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 ''[[:en:create:functions: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.
+<code php>
+// 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);
+</code>
+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'%%''.