DRAFT - Version 1 Decipher Survey Integration Documentation

NOTE: This integration requires knowledge of the JavaScript programming language.

Introduction

This describes how to embed the morphii technology into a Decipher survey. This integration encapsulates most of the the coding needed. Note that this is not the only way to integrate morphii into a Decipher survey, but this document focuses on using the integration.

Limitations

The integration does have limitations. This does not mean that these things cannot be done, just they are limitations for this integration implementation.

Marking morphii questions as required is not supported.

Requiring comments for morphii questions is not supported.

The integration only supported on modern browsers. No support for old browsers such as IE8.

Integration

Morphii Questions

Decipher survey questions that are associated with the morphii widget should be Comment (cm) type questions.

Edit XML

You can also add morphii questions via the Edit XML section.

Loading Integration Script

Add the Decipher integration and Widget JavaScript source location to the top of the survey definition. Use the Decipher directive ss:includeJS. If you already have JavaScript listed in a ss:includeJS then add the 2 links below to your existing links.

JavaScript

The integration requires that JavaScript be added to the Decipher survey. This JavaScript should be contained in a <style mode="after" name="respview.client.js"> tag.

NOTE: This JavaScript is executed for every page load. So if you have a multi-page survey, each time the user advances to the next page this JavaScript will execute if a morphii question is on the page that is loading.

Below is canned JavaScript. There are multiple properties that need to be modified in the following code.

Preview

When testing your Decipher survey, it is best to set the preview property in the JavaScript to true. This will mark reaction results as testing and omit them in final analysis results. Do not forget to remove this property or set it to false before going live with your survey. When this flag is set to true you will see the following message output in the console: INFO: Morphii integration is currently in PREVIEW mode.

Questions Array

The questions array contains objects that define the morphiis to use for specific questions.

varquestions=[{id:'cm5',comment:{show:true,maxlength:512,label:{en:'Want to explain that feeling?'}},slider:{show_animation:true},morphii_ids:[{id:'6202184382145363968',name:{en:'Excited'}},{id:'6362666072115564544',name:{en:'Delighted'}},{id:'6363734358316589056',name:{en:'Frustrated'}},{id:'6363735117617217536',name:{en:'Disgusted'}},{id:'6363735353273270272',name:{en:'Worried'}},{id:'6363488681244622848',name:{en:'Disappointed'}},{id:'6202184384594837504',name:{en:'Meh'}}],hidden_action_ids:{id:'cm5_morphii_id',intensity:'cm5_morphii_intensity',name:'cm5_morphii_name',question:'cm5_morphii_question',comment:'cm5_morphii_comment'}},{id:'cm7',comment:{show:true,maxlength:512,label:{en:'Want to explain that feeling?'}},morphii_ids:[{id:'6202184382145363968',name:{en:'Excited'}},{id:'6362666072115564544',name:{en:'Happy'}},{id:'6363488681244622848',name:{en:'Sad'}},{id:'6363734358316589056',name:{en:'Angry'}},{id:'6363735353273270272',name:{en:'Anxious'}},{id:'6202184384594837504',name:{en:'Meh'}}],hidden_action_ids:{id:'cm7_morphii_id',intensity:'cm7_morphii_intensity',name:'cm7_morphii_name',question:'cm7_morphii_question',comment:'cm7_morphii_comment'}}];

id

The id property is the label of the comment Decipher element. This can be found in the Edit Survey or XML area of the Build menu.

comment

The comment property is used to configure the comment field. It contains 3 properties:

show: Flag to display the morphii comment field or not. Default: false

maxlength: The max character length of the comment field. Default: 512

label: The property that holds the text in each supported language. The label above the comment field. Each translation is defined separately. The en version of the label is required if any other language is declared. Default: Please leave a comment

slider

The slider property is used to configure the the initial intensity and if the slider should animate when a morphii is selected.

initial_intensity: The initial intensity of the morphii when selected. The number must be between 0 and 1. Default: 0.2

show_animation: Flag to animated the slider/morphii when selected. Default: false

Example:

varslider={initial_intensity:0.2,show_animation:true};

morphii_ids

The morphii_ids property is an array of morphii objects to use for the question. The object contains the following properties:

id: This property is required. It is the unique id of the morphii.

name: The property that holds the morphii name for each supported language. Each translation is defined separately. The en translation of the name is required if any other language is declared. If omitted the default morphii name will be used.

weight: An arbitrary integer value assigned to this morphii. If omitted the value will be 0. Setting this property is helpful if using the morphii selection callback.

The id for the hidden input element can be found in the Edit Survey or XML area of the Build menu. These are defined using Decipher text elements. It is recommended that the text element labels use the pattern: (comment element label) + _morphii_id. For example, the morphii question that is associated with the comment element cm5 would be:

cm5_morphii_id

cm5_morphii_intensity

cm5_morphii_name

cm5_morphii_comment

cm5_morphii_question

Each of these text elements can be defined in the survey XML. These elements must be defined on the same page as the morphii question.

Morphii Selection Change Callback

The onMorphiiSelectionChange function is for custom logic when a morphii is selected. The function is passed the morphii selection event. This data contains properties to identify which morphii was select/unselected and which target the morphii is associated with.

selection_required_valid: This property indicates that all selection requirements have been met across all morphii widgets on the page.

type: The type of event. This value will be selection_changed.

widget: Information about the specific widget firing the event.

id: The unique id of the widget. This property is not valid for this survey integration implementation.

target_id: The id of the target associated with this widget. For this implementation this will the label of the Decipher comment element associated with the widget. For example, cm5.

morphii: Information about the specific morphii in the widget.

selected: A flag if the morphii is selected or not.

weight: The weight value assigned to this morphii in the Morphii Ids section. This value will help determine which morphii was selected/unselected in the list.

Morphii Comment Change Callback

The onMorphiiCommentChange function is for custom logic when a user changes text in the morphii widget comment field. The function is passed the morphii comment changed event. This data contains properties to identify the change to the comment text and which target the morphii is associated with.

comment_required_valid: This property indicates that all selection requirement have been met across all morphii widgets on the page.

type: The type of event. This value will be comment_changed.

widget: Information about the specific widget firing the event.

id: The unique id of the widget. This property is not valid for this survey integration wrapper implementation.

target_id: The id of the target associated with this widget. For this implementation this will the label of the Decipher comment element associated with the widget. For example, cm5.

comment: Information about the specific comment in the widget.

required: A flag indicating if the comment field was required or not.

length: The length of the text currently in the comment field.

value: The text value currently in the comment field.

Exporting Survey Data

When exporting Decipher survey data to a CVS, the morphii data will be included in the export. The column names will map to the hidden_action_ids values.

Testing

When testing your Decipher survey, it is best to set the preview property in the JavaScript to true. This will mark reaction results as testing and omit them in final analysis results. Do not forget to remove this property or set it to false before going live with your survey. For example: