This translation is older than the original page and might be outdated. See what has changed.
Translations of this page:
 

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

The PHP function prepare_input() is used place input fields freely. The chapter Placing Input Fields Freely describes the use of placeholders in this case.

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

PlaceholderDescriptionVariable in DataPHP Function
%caseNumber%Ongoing Questionnaire NumberCASEcaseNumber()
%caseSerial%Questionnaire Authorization Code SERIALcaseSerial()
%caseToken%Internal Questionnaire ID-caseToken()
%reference%Reference Given to the QuestionnaireREFreference()

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.

PlaceholderDescriptionExample
%i.n.%Position of the item within the question plus point and blank1.
%i.a)%Position of the item (lower case letter) plus bracketa)
%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 question5

The following placeholders are designated for use exclusively in the HTML template of a layout.

PlaceholderDescription
%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 Code and experience with variables) is required.

In the following example one of three possible brands (code 1, 2 oder 3) is selected from an urn (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"

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

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.
en/create/placeholders.txt · Last modified: 20.08.2016 11:16 by admin
 
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
Driven by DokuWiki