====== 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.

**Note:** User-defined placeholders do __not__ work on the "last page" of a questionnaire, because background data is removed from the case when the interview is completed (FINISHED=1). If necessary, create an additional second-to-last page with ''[[:en:create:functions:buttonhide]]''.

**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.

<code>
The number of your questionnaire is %caseNumber%.
Please quote this number if you would like an analysis of your data.
</code>

User-defined placeholders are set up with the [[:en:create:functions:replace|replace()]] function.

<code php>
replace('%vehicle%', 'AB01', 'response');  // make the answer from AB01 the %vehicle% placeholder
</code>

<code>
You stated earlier that you mostly travel to work by %vehicle%.
</code>

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 with the plural form. 

The following PHP code is placed on the page __after__ question ''SD01''.

<code php>
if (value('SD01') == 1) {
  // respondent is a woman
  replace('%person%', 'a man');
  replace('%people%', 'men');
} elseif (value('SD01') == 2) {
  replace('%person%', 'a woman');
  replace('%people%', 'women');
}
</code>

The placeholders ''%person%'' and ''%people%'' can now be used in other questions (also on the same page; below the PHP code).

<code>
What are the most important characteristics %person% must possess in order to take on a leadership role?
</code>

<code>
Moving on to your experiences: how do you think %people% usually act in a crisis?
</code>

===== Predefined Placeholders =====

The following placeholders are automatically available; these IDs must __not__ be used for user-defined placeholders. The contents of some placeholders can also be retrieved by a PHP function for further use (right column).

^Placeholder^Description^Variable in Data^PHP Function^
|''%caseLanguage%''|Language of the ongoing interview [language code]|LANGUAGE|''[[:en:create:functions:getlanguage]]''|
|''%caseNumber%''|Serial number of the interview|CASE|''[[:en:create:functions:casenumber]]''|
|''%caseSerial%''|Participation code or personal ID of the interview|SERIAL|''[[:en:create:functions:caseserial|caseSerial()]]''|
|''%caseToken%''|Internal ID of the interview|-|''[[:en:create:functions:casetoken|caseToken()]]''|
|''%reference%''|Reference that was passed to the questionnaire|REF|''[[:en:create:functions:reference|reference()]]''|
|''%pageNumber.abs%''|Number of the current page according to **Compose Questionnaire** (be careful when using filter questions)|||
|''%pageNumber.cnt%''|Number of the page according to **Compose Questionnaire** from which the content of the page originates -- same as ''%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]]'', ''[[:en:create:functions:multileveldown]]'' and the function **Collected Data** -> **Restart an Interview Case**)|||
|''%lang.label%''|Name of the active language version (e.g. "English")|||
|''%lang.short%''|2-letter abbreviation of the active language version (e.g. "EN")|||
|''%year%''|4-digit year (for example, for use in the footer)||''date('Y')''|

The following placeholders are available within items or options (e.g. in the item text). The numbering helps, e.g., to number randomly rotated options consecutively.

^Placeholder^Description^Example^
|''%i.n.%''|Number of the item followed by a period and a space|1. |
|''%i.a)%''|Number of the item followed by a bracket (lower case letter)|a) |
|''%i.num%''|Number of the item within the question (numeric)|1|
|''%i.num.a%''|Number of the item within the question (lower case letter)|a|
|''%i.num.A%''|Number of the item within the question (upper case letter)|A|
|''%i.cnt%''|Number of items within the question|5|

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(s) of the question(s) concerned|1|2,3|

The following placeholders are designated exclusively for use in the HTML template of a layout. Further placeholders for the layout are documented under [[:en:create:layout#full_customization|Questionnaire Layouts: Full Customization]].

^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%''\ ''%%<link type="placeholder" href="head">%%''|HTML code for the header in the layout template\ (HTML compliant variant)|
|''%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 or 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.

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

The question title and items are set up as follows:

<code>
"Please evaluate the following statements in light of %brand%!"
Item 1: "I find %brand% better than SoSci Survey"
Item 2: "%brand% looks more artificial"
</code>

{{: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 same page as the question ''TX01'', but must be put on one of the following pages instead.

<code php>
// 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% 
</code>

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.

<code php>
// prepare placeholder %brand% 
replace('%brand%', 'TX01_01', 'response');
// following questions can now use the placeholder %brand%
</code>


==== 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.

<code php>
// 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.
</code>

[[:en:create:functions:replace|replace()]] also calls up the value directly if ''AU01'' is a compulsory question and therefore a filter would be unnecessary:

<code php>
// set up placeholder %fruit% 
replace('%fruit%', 'AU01', 'response');
// following questions or text can now use the %fruit% placeholder.
</code>