====== Placeholders ======
SoSci Survey enables the user to make content (e.g. questions or items) variable. In order to do so, placeholders are integrated in the form ''%placeholder%''. Something will then be inserted in the questionnaire as the placeholder -- for example, the participant's response to a previous question, randomly selected content/stimulus or the result of a live analysis.
There are three types of placeholders:
* predefined placeholders,
* user-defined placeholders and
* placeholders for input fields.
**Tip:** Placeholders work in practically all forms of text: from the question itself to items, text elements, HTML code and so on.
**Tip:** If a user-defined placeholder is set up initially with [[:en:create:functions:replace|replace()]], it can then be used in all the following pages of the questionnaire.
===== Outline =====
If you use the following example as a text element in the questionnaire, the serial number of the questionnaire (predefined placeholder ''%caseNumber%'') will be displayed.
The number of your questionnaire is %caseNumber%.
Please quote this number if you would like an analysis of your data.
User-defined placeholders are set up with the [[:en:create:functions:replace|replace()]] function.
replace('%vehicle%', 'AB01', 'response'); // make the answer from AB01 the %vehicle% placeholder
You have just stated that most people travel to work in a %vehicle%.
In addition, there are some predefined placeholders (see below) and the possibility to [[:en:create:inputs-single|freely place input fields]] (from other questions) using placeholders .
===== Placeholders and Filters =====
The following example demonstrates how placeholders can be combined with conditional questions.
In question ''SD01'' the participant's gender is prompted. In other questions, information should be collected as to how the participant responds to people of the opposite gender. To do this, a placeholder ''%person%'' is set up and is replaced in the questionnaire by either "a man" or "a woman". A second placeholder "people" is set up as the plural form.
The following PHP code is placed on the page __after__ question ''SD01''.
if (value('SD01') == 1) {
// respondent is a woman
replace('%person%', 'a man');
replace('%people%', 'men');
} elseif (value('DC02') == 2) {
replace('%person%', 'a woman');
replace('%people%', 'women');
}
The placeholders ''%person%'' and ''%people%'' can now be used in other questions (also on the same page; below the PHP code).
What are the most important characteristics a ''%person%'' must possess in order to take on a leadership role?
Moving on to your experiences: how do you think %people% usually act in a crisis?
===== Predefined Placeholders =====
The following placeholders are automatically available: these IDs are __not__ allowed to be used for user-defined placeholders. The content of the placeholders can be called up for further use by using the PHP function (see column on the right).
^Placeholder^Description^Variable in Data^PHP Function^
|''%caseLanguage%''| Ongoing Questionaire Language [Language-Code] |LANGUAGE|''[[:en:create:functions:getlanguage]]''|
|''%caseNumber%''|Ongoing Questionnaire Number|CASE|''[[:en:create:functions:casenumber|caseNumber()]]''|
|''%caseSerial%''|Questionnaire Access Code |SERIAL|''[[:en:create:functions:caseserial|caseSerial()]]''|
|''%caseToken%''|Internal Questionnaire ID|-|''[[:en:create:functions:casetoken|caseToken()]]''|
|''%reference%''|Reference Given to the Questionnaire|REF|''[[:en:create:functions:reference|reference()]]''|
''%pageNumber.abs%'' as long as no ''[[:en:create:functions:gotopage]]'' is used to jump to another page and a question or other content was displayed there.|||
|''%pageNumber.rel%''|Number of the current page counted since the beginning of the interview (not compatible with ''[[:en:create:functions:gotoquestionnaire]]'', ''[[:create:functions:multileveldown]]'' and the function **Collected Data** -> **Restart an Interview Case**)|||
The following placeholders are available in some (not yet all) error messages, which can be customized under **Text Elements and Labels**. If the affected question has no number, the placeholder is left blank (removed).
^Placeholder^Description^Example^Example^
|''%q.desc%''|Description of the question(s) concerned|question 1|questions 2,3|
|''%(q.desc)%''|Description in brackets|(question 1)|(questions 2,3)|
|''%q.list%''|Number of the question(s) concerned|1|2,3|
The following placeholders are available within an item or option (e.g., in the item text). The numbering helps, e.g., to give randomly rotated options continuous numbers.
^Placeholder^Description^Example^
|''%i.n.%''|Position of the item within the question plus point and blank|1. |
|''%i.a)%''|Position of the item (lower case letter) plus bracket|a) |
|''%i.num%''|Position of the item (numeric)|1|
|''%i.num.a%''|Position of the item (lower case letter)|a|
|''%i.num.A%''|Position of the item (upper case letter)|A|
|''%i.cnt%''|Number of items within the question|5|
The following placeholders are designated for use exclusively in the HTML template of a layout.
^Placeholder^Description^
|''%logo%''|HTML code for the active logo|
|''%imprint%''|HTML code for the footer/contact information|
|''%progress%''|HTML code for the progress bar|
|''%head%''|HTML code for the header in the layout template|
|''%questionnaire%''|HTML code for the content in the layout template|
===== Customized Placeholder Rules =====
If you are using customized placeholders, please take the following ID requirements into consideration:
* A character must follow directly after the first percentage sign (''%'') (no spaces, no number).
* No spaces before the closing percentage sign.
* No other percentage signs can be written between the percentage signs (''%...%'').
* The placeholder ID between the percentage signs
* must contain at least 3 characters (''%plc%'') and
* can be a maximum of 64 characters.
* Letters A-Z (upper-case or lower-case), numbers, full stops, underscores and spaces are allowed as placeholders, but __no__ umlauts.
* There is a strict distinction between upper and lower case in placeholders: ''%person%'' is a different placeholder to ''%Person%''.
===== Placeholder Placement =====
In the following examples each placeholder ID is shown in brackets:
* I find %brand% good ("brand")
* %make of car% looks cheap ("make of car")
* I associate %product brand% with... ("product brand")
* %parts% of words can be replaced by ("parts")
===== Experimental Variations =====
In order to use placeholders efficiently, basic knowledge of PHP programming ([[php|PHP Code]] and experience with [[variables|variables]]) is required.
In the following example one of three possible brands (code 1, 2 oder 3) is selected from an urn ([[:en:create:random_urns|Randomization Using Urns]]). After this, a placeholder is employed to use the brand directly in the question title.
// First of all, different brands are saved in an array
$brands = array(
1 => 'Ammerseebach',
2 => 'Britentyler',
3 => 'Changuella'
);
// One of these brands is chosen at random
urnDraw('urn', 'IV01');
$code = value('IV01_01');
// the label name of the brand is read from the array above with the code (1-3)
// (you could also use a filter here instead of the array)
$brand = $brands[$code];
// the name of the brand is now stored in the placeholder %brand%
replace('%brand%', $brand);
The question title and items are set up as follows:
"Please evaluate the following statements in light of %brand%!"
Item 1: "I find %brand% better than oFb"
Item 2: "%brand% looks more artificial"
{{:de:create:scr.placeholders.example.gif?nolink|Example of Placeholder Use}}
===== Using a Participant's Answers =====
It is fairly simple to follow up on a participant's answer later on in the questionnaire by using placeholders. You just have to be careful to ensure that the questionnaire continues to work correctly if the participant fails to answer the question (or only inputs blank spaces).
==== Text Input ====
The prerequisite for the following example is that a brand name is prompted in the open text field ''TX01_01''. The following PHP code __cannot__ be put on the the same page as the question ''TX01'', but must be put on one of the following pages instead.
// read participant's answer
$brand = value('TX01_01');
// remove blank spaces
$brand = trim($brand);
// respond appropriately if no answer is given
if ($brand == '') {
goToPage('next'); // go to next page
}
// set up placeholder %brand%
replace('%brand%', $brand);
// following questions can now use the placeholder %brand%
If item ''TX01_01'' is a compulsory question and therefore has to be answered (i.e. there can be no missing answer), then [[:en:create:functions:replace|replace()]] can call up the answer directly.
// prepare placeholder %brand%
replace('%brand%', 'TX01_01', 'response');
// following questions can now use the placeholder %brand%
==== Selection Question ====
In the following example, the option which was selected in a selection (single choice or drop-down) should be displayed as text. The prerequisite here was that a type of fruit be chosen in the selection question ''AU01''.
Once again, due to the ''value()'', the PHP code __cannot__ be on the same page as the ''AU01'' question, but must be put on one of the following pages instead.
**Tip:** Please also read the ''[[:en:create:functions:value|value()]]'' function manual.
// first of all, check that something has been selected
if (value('AU01') < 0) {
// go to next page
goToPage('next');
}
// read answer - observe the second parameter 'text'
$text = value('AU01', 'text');
// set up placeholder %fruit%
replace('%fruit%', $text);
// following questions or text can now use the %fruit% placeholder.
[[:en:create:functions:replace|replace()]] also calls up the value directly if ''AU01'' is a compulsory question and therefore a filter would be unnecessary:
// set up placeholder %fruit%
replace('%fruit%', 'AU01', 'response');
// following questions or text can now use the %fruit% placeholder.