The explain
tag is applied directly to question, table, and settext
widgets. When used on a question, an "info" icon appears at the end of the question text. Moving the cursor over this icon reveals additional specified content. On settext
widgets, the icon is replaced with a dashed green underline underneath the content of the text, and the entire element reveals the tooltip if moused over.
Using the explain
tag allows Survey Creators (SCs) to include additional information for question or option text without using valuable screen real estate. This can be especially important for respondents that access surveys through a mobile device. While allowing for maximum space on the screen, the explain
texts (or images) then provide an ability for the SC to elaborate on or clarify a topic so the respondent has a clear understanding of what they are asked, hopefully leading to a higher accuracy of responses. CSS or HTML can also be added within an explain
description to help format the explanation/description or image displayed.
Try it!
Syntax
Include the desired content as the input to the explain
tag.
# Within a question, table or 'settext' widget explain: Additional content here # As a decorator for an option 1. This is a question. type: radio, checkbox, etc. 1. Opt 1 {explain: Explanation for Opt 1} 2. Opt 2 {explain: Explanation for Opt 2} 3. etc.
For additional information on using explain
as a decorator, see Explain decorator.
Tags
It is possible to invoke the explain
modifier text when calling a list via an optsfrom/rowsfrom/colsfrom
listcall, as well as to hide the explain icon and text altogether. The following tags allow you to disable explain
if it is present on one or more options, or modify how the tooltips are displayed.
Tag | Description |
---|---|
explain_headings |
Adds an explain icon to table headings as defined by the headings tag. The input to this tag will be the tooltip text. |
showexplain |
Defaults to 'y'; to disable explain in question options, define and set to 'n'. |
showexplaincol |
Defaults to 'y'; to disable explain in table columns, define and set to 'n'. |
showexplainrow |
Defaults to 'y'; to disable explain in table rows, define and set to 'n'. |
dialog |
Displays the explain text as a pop-up/modal instead. Set to 'y' and the underlined text may be clicked upon to display the modal. Click the X in the corner of the modal to close it. |
height |
Use with dialog: y to specify the height of the modal being displayed. Accepts a percentage, or number of pixels or ems as input. |
width |
Use with dialog: y to specify the width of the modal being displayed. Accepts a percentage, or number of pixels or ems as input. |
Note: When viewed on mobile devices, explain
elements act like dialog
modals for accessibility purposes, even if the dialog: y
tag is not present.
Styling and formatting
If styling inline within survey source code, the below pagecss
tag is used with the ui-tooltip class. It may be omitted if styling from survey's /_s/local.css file. A common application of the pagecss
tag is to increase the tooltip size from the default, e.g., { max-width: 600px }
. See below for example.
pagecss: .i-explain-tooltip { custom CSS here }
Explain tooltips can be displayed as either a tooltip (default) or pop-up/dialog box. To change to a pop-up, use dialog: y
. Instead of hovering over the underlined text to activate the explanation, respondents will click on it to make the dialog appear. See below for example. To alter the size of the pop-up displayed when using the dialog
tag, include the height
and/or width
tags.
For additional information on how to override or alter how explains are displayed, see Overrides & Advanced Examples (below).
Examples
Question with text description
When used in a question, the explain
tag creates an icon next to the end of the question. Hovering over this icon provides the respondent with the explain text, elaborating on the question.
Question with option descriptions
In multiple choice questions that use option lists, the explain
tag can be used as an element decorator to provide more information on their option choices. When used in this manner, the information icon will appear next to each option that includes an explain
decorator, as opposed to the question itself. Clicking the information icon will not trigger a selection of the option button.
Question with image for explanation
This example uses CSS to import and style the sizing of an image.
An alternative method of using explain
to display a logo is to implement the dialog
tag. Using the set text
widget, dialog: y
is applied to the variable HERE so that the respondent can click on the text "here" and the image will appear.
If need be, dialog
modals may be formatted with the height
and width
tags. Simply specify a percentage, or number of ems or pixels, for the input to height
and width
.
For more on the set text
widget, see the examples below or the set text page.
List with Element Decorators
To invoke explain
text in a list so it is rendered on the page instead of inside of a tooltip, the explain
modifier can be used within a text modifier in a listcall. This is useful in situations where the items must be displayed with complete definitions at first (as shown in T4), whereas subsequent displays require them to be within the explain
mouseover (Q5).
settext with text explanation
In the following example, the settext
widget is used to create a shortened version of a placeholder for text, and is especially useful if any formatting has been added to the text. By creating the IS variable through set text
, we can later call upon the text with '__IS__' , pulling any formatting forward with it. In this case, we have added the explain
tag to the set text
code so that each time we include the '__IS__' set text
"shortcut," the explanation is automatically available while displaying the desired text.
Notice that the specified text, "IntelliSurvey", is underlined in green instead of using an information icon, and that hovering over the text will allow the explanation to pop up.
settext with image explanation
Similar to the previous example, here we use the settext
widget to establish a text "shortcut" (__IS2__) that will display "IntelliSurvey" underlined in green. In this case, instead of a description or explanation popping up when we hover over the word, a logo will appear instead. The explain
tag pulls in the logo we will use, whereas the CSS included within the text
tag details is used to style the sizing of the logo.
Modifying width of displayed explanation
The following usage of the pagecss
tag and max-width
CSS property on Q3A allows the user to increase the size of the explain/tooltip message (default is 300px). This is particularly useful here as the explanation associated with the set text AN_EXPLAIN is relatively long.
Deactivating explanations
While using the explain
tag is useful for adding more information about items in a list, it is possible that we might not want the explanations to show up for repeated displays of these items. In the following example, for questions Q6 and Q6A, the explanations are active since these are the first times we're introducing the respondents to these pizza types and pizzerias. Since the table immediately follows with the same list items, we have turned off the explanations via the showexplain
and showexplainrow
tags, assuming the respondent will remember the descriptions from previously viewing them.
Overrides and advanced examples
When using the dialog
tag for explains, Survey Programmers (SPs) have the option to override the JavaScript configurations of the modal if need be. The following examples may be applied to either a survey's custom.js file or locally on the page where the question is located.
Adding "OK" button that also closes the modal
I$.addWidgetOverride('SET_TEXT_ID_GOES_HERE', { overrides: function() { return { buttons: [{ text: 'OK', click: function (){ $(this).dialog('close') } }] } } });
Clicked element as a button
For the next few examples, assume we have a set text
called "REVIEW". The following scripts may be added to survey source as is. To add to the survey's custom.js file instead, remove the outer <script> tags.
Simple button
<script> require(['survey','jqueryui'],function(I$){ I$.onWidgetRegistration(function makeButton(){ $('.toclick_REVIEW').button(); }); }) </script>
Button with icon after the text
<script> require(['survey','jqueryui'],function(I$){ I$.onWidgetRegistration(function makeButton(){ $('.toclick_REVIEW').button({icon: 'icon-question-circle', iconPosition: 'end'}); }); }) </script>
Button with icon only
<script> require(['survey','jqueryui'],function(I$){ I$.onWidgetRegistration(function makeButtons(){ $('.toclick_REVIEW').button({icon: 'icon-ellipsis-h'}).button({label: ''}); // Or one could convert all dialog set texts to buttons: $('.i-dialog-targ').button(); }) }) </script>
Convert all settext dialogs to buttons
Add the following to a survey's custom.js file so that all set_text
dialog modals appear as buttons.
require(['survey','jqueryui'],function(I$){ I$.onWidgetRegistration(function makeButtons(){ $('.i-dialog-targ').button(); }) })
Comments
0 comments
Please sign in to leave a comment.