Table of Contents
qMadLib - Fill-in-the-blank, MadLib, or Cloze type questions
This function converts a Qualtrics Side-by-Side question or a series of Text Entry and Drop-down questions into a fill-in-the-blank style question. The 'blanks' can be a mix of text inputs or drop-downs. For example:
The qMadlib function does contact forms too!
Functionality includes:
- Supports any mix of text input and drop-downs
- Produces highly usable response data
- All configuration through HTML (no JavaScript knowledge necessary)
- Supports using either a single Side-by-Side question or a series of Text Entry and/or Drop-down questions
- Auto-sizing of input boxes. Text inputs are sized as the respondent types!
- Searchable drop-downs
- Supports text and number inputs
- Supports translations and all languages
- Supports Qualtrics validation
- Supports word completion questions
- On-the-fly input masking and formatting
- Basic
- Whole numbers (0,1,2,etc.)
- Integers (…,-1,0,1,…)
- Decimals (-1.5,0.025,1.75,etc.)
- Advanced (using cleave.js)
- Phone numbers
- Dates
- Times
- Formatted numbers
- Postal codes
- General (blocks, prefixes, delimeters)
- Date/time picker integration (using flatpickr)
This function is available for a reasonable fee. Contact TomG on the Qualtrics Community to learn more.
Set-up Instructions
Survey Header
JavaScript Libraries
Depending on what MabLibs functionality you need, the function integrates with the following JS libraries:
- select2 for drop-downs
- cleave.js for advanced input masks (dates, times, formatted numbers, telephone numbers, postal codes, etc.)
- flatpickr for pop-up date and time picking
If any of above are needed, their JS and stylesheet, if applicable (select2 and flatpickr), must be added the survey header. They can all be loaded from jsdelivr.com.
To add the libraries to the survey header, go to Look & Feel → General → Header edit → and paste the html from jsdelivr. The following html will load all three:
<link href="https://cdn.jsdelivr.net/combine/npm/select2@4/dist/css/select2.min.css,npm/flatpickr@4/dist/flatpickr.min.css" rel="stylesheet" /> <script src="https://cdn.jsdelivr.net/combine/npm/select2@4/dist/js/select2.full.min.js,npm/cleave.js@1,npm/flatpickr@4"></script>
qMadLib function
The qMadLib function must also be added to the survey header. This will make the function available to any question in the survey. Go to Look & Feel → General → Header edit → and paste the provided qMadLib function JS:
<script>/*Paste qMadLib function JS here*/</script>
Alternatively, paste the qMadLib function JS into a question's JS outside the existing Qualtrics functions to make it available to questions on the page.
Custom CSS
CSS styles control the formatting of Madlib questions. Go to Look & Feel → General → Custom CSS edit and add the provided CSS rules.
Side-by-Side Question
The advantages of using a Side-by-side question is that the question is self-contained and you can have multiple Madlib questions on a page.
The Side-by-side question must have the same number of columns (questions) as there will be fill-in-the-blanks in the Madlib. The columns must be in the same order as the fill-in-the-blank inputs (drop downs and text inputs). It will look something like this in the Qualtrics editor:
Drop Down
For drop down columns (questions), add the choices you want to have appear in the drop down. Hint: It is easier to configure a side-by-side drop down by setting it as a Scaled Response - Single Answer to add the choices, then switching it to a Drop Down List.
Text Input
For text input columns (questions), set the type to Open Ended Text. There should be one column answer per column.
Series of Questions
As an alternative to a Side-by-side question, a series of separate questions may be used. The first question must be a Descriptive Text question that contains the Madlib fill-in fields (input and/or select elements). It is followed by Text Entry and/or Multiple Choice Dropdown questions that correspond to the fill-in fields in the Descriptive Text question. The advantages of using a series of questions are that the drop downs are easier to configure, validation is more flexible, and if the Madlib happens to be a screening question, it enables generation of test responses with Q_PopulateResponse (due to a bug in Generate Test Responses Side-by-side questions don't work properly when the answer is specified with Q_PopulateResponse). When using a series of questions, only one Madlib question per page is supported and the Madlib series of questions must be the only answerable questions on the page (other descriptive text questions are allowed).
After the descriptive text question with fill-in elements, add text entry and/or multiple choice dropdown questions to match. There must be the same number of text entry and/or multiple choice dropdown questions as there are fill-in-the-blanks in the Madlib. The questions must be in the same order as the fill-in-the-blank inputs (text inputs and drop downs).
Drop Down
For drop down questions, add the choices you want to have appear in the drop down.
Text Input
For text input questions all that is needed is a single line text entry question.
JavaScript Function Call
Add JS to either the Side-by-Side question or the Descriptive Text question containing fill-in fields as follows:
Qualtrics.SurveyEngine.addOnReady(function() { qMadLib(this); });
To override the default options, specify the desired options in the second function argument as an object. For example:
Qualtrics.SurveyEngine.addOnReady(function() { qMadLib(this,{debug:true}); });
Options
debug
For testing purposes, debug can be set to true to see the Qualtrics question fields being captured.
Default: false
language
Can be set to force the language locale for use with uppercase, lowercase, and proper classes. Defaults to the current language in a translated survey.
Default: ${e://Field/Q_Language}
Question Text HTML
To create the Madlib question text, click on the Question Text and click the HTML View tab. ONLY edit Madlib questions in HTML View. Qualtrics will make unexpected changes to question HTML when edited in other modes.
Style
To hide the question from the respondent while it is being formatted by JS, add an embedded data field to the beginning of the survey flow:
opacity0 = opacity:0;
Then add a <style> tag to the question text:
<style>.Skin { ${e://Field/opacity0} }</style>
An embedded data field is used so opacity style does not impact 'View response' or 'Export to PDF'.
Text Input
To add an open end text field, add an input element with a class of “fillin”, a type of “text”, and optionally a “placeholder” (See Advanced Configuration for other options).
I am a <input type="text" class="fillin" placeholder="age"> year old.
Drop Down
To add a drop down field, add a select element with the class “fillin”, and optionally a “placeholder”.
I have <select class="fillin" placeholder="number of children"></select> under the age of 18 living in my home.
Advanced Configuration
Input Attributes
Configuration of each input in a MadLib question is controlled by the input element's attributes. The list below describes how these attributes can be used.
autocomplete
The autocomplete attribute is optional, but can be very helpful when a MadLib collects contact information. It can be used with text input or drop downs. See https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#autofill for details.
class
The following class names can be used to format or configure a MadLib input. class="fillin" is required for all MadLib input or select (drop down) elements. All other class names are optional.
cleaveRaw
The cleaveRaw class only applies to a cleave field with numeric formatting. When cleaveRaw is included, the raw value instead of the formatted value of the input is saved in Qualtrics. Applies to input elements only.
decimal
The decimal class applies an input mask to an open end Madlib input so only valid decimal values may be entered. decimal is ignored if cleave or flatpickr is used. Applies to input elements only.
fillin
The fillin class is required for all MadLibs input or select elements.
integer
The integer class applies an input mask to an open end Madlib input so only valid integer values may be entered. integer is ignored if cleave or flatpickr is used. Applies to input elements only.
lower
The lower class applies an input mask to an open end Madlib input so all letters are converted to lowercase. lower is ignored if cleave or flatpickr is used. Applies to input elements only.
nospinner
The nospinner class hides the up/down arrows (spinner) associated with type="number" input fields. It ONLY applies when type="number". It has no impact on mouse scroll increment/decrement. Applies to input elements only.
proper
The proper class applies an input mask to an open end Madlib input so the first letter of each word is capitalized. proper is ignored if cleave or flatpickr is used. Applies to input elements only.
s2off
The s2off class disables select2 on select elements. Use of the s2off class does not support the placeholder attribute. Applies to select elements only.
upper
The upper class applies an input mask to an open end Madlib input so all letters are converted to uppercase. upper is ignored if cleave or flatpickr is used. Applies to input elements only.
wholenum
The wholenum class applies an input mask to an open end Madlib input so only valid whole number values may be entered. wholenum is ignored if cleave or flatpickr is used. Applies to input elements only.
data-cleave
The data-cleave attribute specifies that cleave should be used for input masking. It applies to input elements only. The value is a json string that specifies the cleave options that should be used. For example, to capture dollars data-cleave could look like this:
data-cleave='{"numeral":"true","prefix":"$","noImmediatePrefix":"true","rawValueTrimPrefix":"true"}'
data-flatpickr
The data-flatpickr attribute specifies that flatpickr should be used to pick a date and/or time. It applies to input elements only. The value is a json string that specifies the flatpickr options that should be used. For example, to pick a date in month/date/year format data-flatpickr would look like this:
data-flatpickr='{"dateFormat":"m/d/Y"}'
inputmode
The inputmode attribute can be used to specify the type of on-screen keyboard that is shown when a MadLib text input gains focus. For example, inputmode=“numeric” can be added to a numeric input field. Valid values are: text, decimal, numeric, tel, search, email, and url. Applies to input elements only.
maxlength
The maxlength attribute can be used to specify the maximum number of characters for an input field. Applies to input elements only.
placeholder
The placeholder attribute is optional, but important. It contains instructional text that is shown in a MadLib input with a empty value. The length of the text determines the initial size of the input field. Does not apply to select elements with the class s2off.
type
The type attribute is required for input elements. It's value should be text or number. Browser support for other type values is spotty and they don't provide any value beyond the MadLib configuration options provided. Therefore, they are not recommended.
text
type="text" may be used for any MadLib input, and should be used for all Madlib inputs except open-end numeric inputs.
number
type="number" may be used for open-end numeric inputs. type=“number” enables number specific behaviors (mouse scroll to increment/decrement, up/down spinner) and attributes (min, max, step)
Word Completion
The qMadLib function can be used for word completion questions with some minor configuration.
Word Completion HTML
Wrap the beginning of the word and the input in a span tag with the class word and use the input class lowercase as follows:
<span class="word">hea<input class="fillin lowercase" type="text"></span>
Word Completion CSS
Optionally, the MadLib input fields can be changed from boxes to underlined blanks with a grey background using CSS with the following html added to the end of the question text or to Custom CSS:
<style> .Skin input.fillin[type=text] { background-color:#EEE !important; border-style: solid; border-width: 0px 0px 1px 0px; } <style>