Differences

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

--- en:create:functions:question [12.07.2016 20:15] – admin
+++ en:create:functions:question [05.09.2023 22:39] – swissel.uni-mannheim
@@ Line 1: / Line 1: @@
 ====== question() ======
-''void **question**(string //questionID//, array|string //items//, [string //options//])''
+''void **question**(string|array //QuestionIdentifier//, array|string //Items//, [string //Options//])''
-Shows the question with the specified //questionID// in the questionnaire. The function ''question()'' is mainly used with [[:en:create:filters|Filters and Conditional Questions]].
+Displays the question with the specified //questionIdentifier// in the questionnaire. The function ''question()'' is mainly used in conjunction with [[:en:create:filters|Filters and filter questions]].
-  * //questionID//\\ The four-digit ID is composed of the ID of the section and the question (both two-digit) and must be given in quotation marks (single or double), e.g. '''XY01'''.
+  * //QuestionIdentifier//
-  * //items//\\ The second parameter can optionally be used to specify which items in the question should be shown and/or in what order this occurs. The item IDs are either specified as an array (''array(2,4,6,8)'') or separated with a comma as a string ('''2,4,6,8''').  In order to describe items 1, 3, 5, 6, 7, 8, 9 and 10, number ranges can also be specified in the item list, e.g. '''1,3,5-10''' or ''array(1,3,'5-10')''.
+    * (string) The four-digit identifier is composed of the identifier of the rubric and question (two digits each) and must be enclosed in quotation marks (single or double), e.g. '''XY01'''.
-  * //options//\\ There is a large range of options available for fine-tuning. Any number of options can be specified for each ''question()'' command. Put each option in quotation marks (single or double) and separate multiple options with commas (see example below).
+    * (array) An array with multiple question identifiers can also be specified. These will then be represented as [[:en:create:combine|combined question]], just as when using the ''combine=...'' parameter.
-    * '''show-title=no'''\\ Question title is not shown, numbering is suspended
+  * //Items//\\ Optionally, the second parameter can be used to specify which items of the question are to be shown and/or in which order this is done. The identifiers of the items are specified either as an array (''array(2,4,6,8)'') or separated by a comma as a string ('''2,4,6,8''). Numerical ranges can also be specified in the item list, e.g., '''1,3,5-10''' or ''array(1,3,'5-10')'' to describe items 1, 3, 5, 6, 7, 8, 9, and 10.
-    * '''show-explanation=no'''\\ Explanation/instructions are not shown.
+  * //Options//\\ A whole set of options is available for fine tuning. For each ''question()'' command any number of options can be specified. Put each option in quotes (single or double) and separate multiple options with commas (see examples below).
-    * '''show-items=no'''\\ Items are not shown.
+    * ''%%'show-title=no'%%''\\ Question text is not displayed, numbering is suspended.
-    * '''spacing=<n>'''\\ Spacing beneath the question in pixels.
+    * ''%%'show-explanation=no'%%''\\ The explanation/instructions are not displayed.
-    * '''number=<n>'''\\ Shows the number  <n> before the question instead of automatically incrementing or hides the number completely with "number=no".\\ **Tip:** You can also turn off numbering in the questionnaire in general (**Compose Questionnaire** -> //Settings//). You can then give individual questions a number with the option ''number=<n>'' or ''number=yes''.
+    * ''%%'show-items=no'%%''\\ The items or dodge options are not displayed.
-    * '''anchor=<number>'''\\ Repeats the anchor (lead text, graphic, numeric and verbal anchor) in a scale or a polarity profile every <number> of items. Sensible for questions with a large number of items.
+    * ''%%'spacing=<n>'%%''\\ Distance under the question in pixels.
-    * '''anchor=none'''\\ Completely hides the anchor (lead text, graphic, numeric and verbal anchor) in a scale or a polarity profile.
+    * ''%%'number=<n>'%%''\\ Displays the number <n> before the question instead of counting up automatically or hides the number completely with "number=no".\ **Tip:** By the way, you can also generally switch off the numbering in the questionnaire (**Create questionnaire** -> //Settings//). With the option ''number=<n>'' or ''number=yes'' you can then assign a number to individual questions.
-    * '''random'''\\ Items in a question are output in a random order. This parameter overwrites the setting for item sorting in the question dynamically.
+    * '''anchor=<amount>'''\\ Repeat the anchoring (prefix, graphical, numerical, and verbal) of a scale or polarity profile every <number> items. Useful for questions with numerous items.
-    * '''random=<n>'''\\ <n> items are selected at random and output in a random order.
+    * '''anchor=none'''\\ Hides the anchoring (leader, graphical, numerical and verbal anchoring) of a scale or polarity profile completely.
-    * '''combine=<ID of a different question>''' \\ Creates a combined question.  ([[:en:create:combine]]).
+    * '''random'''\\ The items of the question are output in random order. This parameter dynamically overrides the item sorting setting in the question.
-    * '''gap=<specification>'''\\ Spacing between the input fields in a combined question in pixels (e.g. '''gap=20''').
+    * '''random=<n>'''\\ <n> Items are randomly selected and displayed in random order.
-    * '''gap=line'''\\ Display a line between the combined questions. The space or the line is displayed equally between all combined questions.
+    * '''combine=<Identifier other question>'''\ Create a combined question ([[:en:create:combine|combined questions]]).
-  * //options//\\ Some options are intended to dynamically overwrite the question's settings:
+    * '''gap=<value>'''\ gap between the input fields of a combined question in pixels (e.g. '''gap=20''').
-    * '''filter=<specification>'''\\ Prefix for the database key in a question type "Extended Selection" or "Suggesting Text Input" (e.g. '''filter=country''' to show all database entries whose key begins with "country"). To allow the correct encoding of a response in the suggesting text input, at least a part of the prefix mus be set in the question itself as //prefix//. The parameter in ''question()'' can then narrow down these options.
+    * '''gap=line'''\\ Show a line between the combined questions. The distance or line is displayed equally between all combined questions.
-    * '''direction=<up|down>'''\\ Arrange selection options in a scale or in a horizontal selection in ascending (''up'') or descending (''down'') order.
+  * //Options//\\ Some options allow to dynamically override settings in the question:
-    * '''composition=<default|extended|dense>'''\\ Customize setting for //Composition of a Question// .
+    * '''filter=<value>'''\\ Prefix for database key in a question of type "extended selection" or "text input with selection recommendation" (e.g. '''filter=country''' to display all database entries whose key starts with "country"). For the encoding of an answer to work correctly with the selection recommendation, at least part of the prefix must be entered in the question itself as //prefix for database key//. By means of ''question()'' a narrowing down can then be done. vorgenommen werden.
-    * '''align-labels=<center|inside|outside|eachline>'''\\ Customize alignment of the verbal anchor in a scale with only the extremes labeled. This parameter overwrites the respective setting in the question dynamically.
+    * '''direction=<up|down>'''\\ Arrange selection options of a scale or horizontal selection in ascending (''up'') or descending (''down'') order.
-    * '''shading=<auto|none|start-shaded|start-unshaded|all-shaded|all-unshaded>'''\\ Item shading.
+    * '''composition=<default|extended|dense>'''\\ Adjust setting for //Assignment of a question//. This parameter dynamically overwrites the corresponding setting in the question.
+    * '''align-labels=<center|inside|outside|eachline>'''\\ Align verbal anchoring in a scale that labels only the extremes.
+    * '''shading=<auto|none|start-shaded|start-unshaded|all-shaded|all-unshaded>'''\\ Shading of the items.
+    * '''flip-inputs'''\\ In most questions you can set whether the input fields (e.g. boxes to check) should be on the left or on the right of the labels. With this parameter you can invert the setting.
-===== Tips =====
+===== Notes =====
-**Note:** Calling up the function ''question()'' is equivalent to the drag & drop of a question into the questionnaire. If you integrate the command ''question()'' into a question (e.g. in a filter) make sure that the same question is not put on the page again via drag & drop. Otherwise, the question appears twice.
+**Important:** A call to the function ''question()'' is equivalent to dragging and dropping a question into the questionnaire. If you include a question with the ''question()'' command (e.g. in a filter), then make sure that the same question was not additionally placed on the page by dragging it in. Otherwise the question will appear twice.
-**Note:** SoSci Survey differentiates between upper and low case for the ID and all options.
+**Important:** SoSci Survey distinguishes between upper and lower case letters in the identifier and all options.
-**Note:** Both the ID as well as other options must be quoted as a string; as a rule in quotation marks (single or double). Please see examples.
+**Note:** Both the identifier and other options must be written as a string, usually in single or double quotation marks (see examples).
+**Tip:** You can dynamically display only those items that the participant has selected in another question. For more information see [[:en:create:filter-items|Transfer items to another question]].
-**Tip:** You can only show items dynamically that the participant selected in another question. For more details please see [[:en:create:filter-items|Use Selected Items in Another Question]].
+**Tip:** You do not have to type the ''question()'' command by hand. You can also simply drag a question into a //PHP-code// element, see [[:en:create:php#more_convenient_programming_questions_and_texts|Introduction to PHP code: Programming more conveniently (questions and texts)].
-**Tip:** You do not have to type the ''question()'' command by hand. You can just drag & drop a question into a //PHP code//  element. See [[:en:create:php#comfortable_programming_questions_and_texts|Introduction to PHP Code: Comfortable Programming (Questions and Texts)]].
 ===== Examples =====
 <code php>
-question('BS10');  // Daily television use
+question('BS10'); // Daily television usage.
-question('BS01', '2,1,4,5');  // items 2, 1, 4 and 5 are called up
+question('BS01', '2,1,4,5'); // Items 2, 1, 4 and 5 are asked here.
-question('NH02', 'random=3');  // 3 items selected at random
+question('NH02', 'random=3'); // 3 items are randomly selected
-question('AA01', 'show-title=no');  // hide question title
+question('AA01', 'show-title=no'); // hide question text
-// The following three lines each show items 1 to 4 and 6 in question BS07
+// The following three lines show items 1 to 4 and 6 of question BS07 respectively
 question('BS07', array(1,2,3,4,6));
 question('BS07', array('1-4',6));
 question('BS07', '1-4,6');
-question('SK01', 'spacing=4');  // Display a scale and directly beneath ...
+question('SK01', 'spacing=4');  // Show a scale and directly below it ...
-question('SK02', '1', 'show-title=no');  // ... the first item of a free text input "Other: ___"
+question('SK02', '1', 'show-title=no');  // ... the first item of an open text entry "Other: ___".
 </code>