====== 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:\\
{{::qmadlib.mp4?695|}}

The qMadlib function does contact forms too!\\
{{::madlib_example2.png?600|}}

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 **[[madlibs#Word_Completion|word completion questions]]**
  * On-the-fly input masking and formatting
    * Basic
      * **[[madlibs#lower|Lowercase]]**
      * **[[madlibs#upper|Uppercase]]**
      * **[[madlibs#proper|Proper names]]**
      * **[[madlibs#wholenum|Whole numbers]]** (0,1,2,etc.)
      * **[[madlibs#integer|Integers]]** (...,-1,0,1,...)
      * **[[madlibs#decimal|Decimals]]** (-1.5,0.025,1.75,etc.)
    * **[[madlibs#data-cleave|Advanced]]** (using cleave.js)
      * Phone numbers
      * Dates
      * Times
      * Formatted numbers
      * Postal codes
      * General (blocks, prefixes, delimeters)
  * **[[madlibs#data-flatpickr|Date/time picker integration]]** (using flatpickr) 

This function is available for a reasonable fee. Contact **[[https://community.qualtrics.com/inbox/conversation?with=373|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:
  * [[https://select2.org|select2]] for drop-downs
  * [[https://nosir.github.io/cleave.js/|cleave.js]] for advanced input masks (dates, times, formatted numbers, telephone numbers, postal codes, etc.)
  * [[https://flatpickr.js.org|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 [[https://www.jsdelivr.com|jsdelivr.com]].

To add the libraries to the survey header, go to Look & Feel -> General -> Header edit -> {{::icon_source.jpg?20|}}  and paste the html from jsdelivr. The following html will load all three:
<code>
<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>
</code> 

=== 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 -> {{::icon_source.jpg?20|}} and paste the provided qMadLib function JS:
<code>
<script>/*Paste qMadLib function JS here*/</script>
</code>
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:\\
{{ ::madlib_editor.png?800 |}}

=== 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 Text/Graphic 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 Text/Graphic 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 Text/Graphic questions are allowed).

After the Text/Graphic 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 Text/Graphic question containing fill-in fields as follows:
<code>
Qualtrics.SurveyEngine.addOnReady(function() {
	qMadLib(this);
});
</code>

To override the default options, specify the desired options in the second function argument as an object. For example:
<code>
Qualtrics.SurveyEngine.addOnReady(function() {
	qMadLib(this,{debug:true});
});
</code>

=== 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 **[[madlibs#uppercase|uppercase]]**, **[[madlibs#lowercase|lowercase]]**, and **[[madlibs#proper|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:
<code>
opacity0 = opacity:0;
</code>
Then add a <style> tag to the question text: <code>
<style>.Skin { ${e://Field/opacity0} }</style>
</code>
An embedded data field is used so opacity style does not impact survey editing. Add the following to a question later in the survey so that 'View response' or 'Export to PDF' are not impacted:<code>
<style>.Skin { opacity:1; }</style>
</code>

=== 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 **[[madlibs#advanced_configuration|Advanced Configuration]]** for other options).
<code>
I am a <input type="text" class="fillin" placeholder="age"> year old.
</code> 

=== Drop Down ===
To add a drop down field, add a select element with the class "fillin", and optionally a "placeholder".
<code>
I have <select class="fillin" placeholder="number of children"></select> under the age of 18 living in my home.
</code>

===== 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 [[https://github.com/nosir/cleave.js/blob/master/doc/options.md|cleave options]] that should be used. For example, to capture dollars data-cleave could look like this:
<code>
data-cleave='{"numeral":"true","prefix":"$","noImmediatePrefix":"true","rawValueTrimPrefix":"true"}'
</code>

=== 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 [[https://flatpickr.js.org/options/|flatpickr options]] that should be used. For example, to pick a date in month/date/year format data-flatpickr would look like this:
<code>
data-flatpickr='{"dateFormat":"m/d/Y"}'
</code>

=== 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 **[[madlibs#s2off|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:
<code>
<span class="word">hea<input class="fillin lowercase" type="text"></span>
</code>
=== 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:
<code>
<style>
.Skin input.fillin[type=text] {
 	background-color:#EEE !important;
  	border-style: solid;
	border-width: 0px 0px 1px 0px;
}
<style>
</code>
====== Qualtrics Wiki ======
[[start|Qualtrics Wiki]]