Zu Hauptinhalten wechseln

FV Decipher Unterstützung

Alle Themen, Ressourcen für FV Decipher benötigt.

 
decipher

Dynamic Question Style Design and QA Checklist

1:  Overview

Whether you're beginning to design a new dynamic question style or you're peer reviewing a designer's work in QA, the following is a guide to the design process and some important tips to keep in mind.

2:  The Design Process

2.1:  The Beginning

Sketch your new question's overall design on a piece of paper or using a software program (see below) and shortly describe how it’s going to work. Run your design by a few people to get general design/usability feedback. New styles should be mobile compatible, so be sure your design will work well with mouse clicks and touchy fingers.

Wireframe Applications:

Pick a name: 5-10 characters, lowercase letters only and no numbers, underscores, or other punctuation. This will be the name of your directory in lib/local. This will also be the name put in the uses="..." attribute.

Create the files:

  • All files should be placed in the lib/local/yourstyle/v1/ directory because you are writing version 1.
  • Create a meta.xml file with a <meta></meta> tag in it. This is where you’ll put the style title and how it interacts with the survey builder.
  • Create a styles.xml file with a <styles></styles> tag in it. This is where you'll put all style and style variable definitions, just like nstyles but using the newer XML syntax.
  • Create a survey.xml which will be used for manual and automated testing of your style. Keep this demo survey updated as you continue adding new features to your style.
  • Create a static/ subdirectory. This will be home to the Javascript and CSS files private to your style

Example meta.xml Contents:

<meta>
 <title>short title</title>
 <description><![CDATA[
longer description with some HTML, that shows up in builder. Link th the KB page here
]]></description>
 <scope>select</scope>
 <owner>you@decipherinc.com</owner>
 <supports>noanswer</supports>
 <state>dev</state> <!-- https://decipher.fogbugz.com/default.asp?bugnumber-->
 <modifies>controls</modifies>
 <qem name="<row|col|choice>">other variable</qem>
 <rename name="<row|col|choice>">alternative name shown in Builder</rename>
 <require name="attribute">*</require>
 <count name="<row|col|choice>">number (e.g. 2+) or range (e.g. 2-10)</count>
 <template scope="select"><![CDATA[
    <select minRanks="1" label="{x}">
        <row label="r1">ROW 1</row>
        <row label="r2">ROW 2</row>
        <choice label="ch1">CHOICE 1</choice>
        <choice label="ch2">CHOICE 2</choice>
    </select>
    <suspend />
    <radio cond="{x}.r1"></radio>
    <number label="{x}_total"></number>
 ]]></template>
 <compat>required compat number</compat>
</meta>

2.2:  Backend

Select the right question type: in theory, any question can be built on top of <text> element since it provides you with a grid of untyped inputs. However, that would be useless in the report. Here are some good question types to consider:

Question Type Use if...
<radio> you want to assign a named rating to something. Ratings can be made once per row (e.g. grouping="rows") or once per column (e.g. grouping="cols").
<checkbox> you have one row, one column or a grid of boolean variables. Each selection is completely independent. (Not a good choice for rating questions.)
<select> you want to assign a named rating to something. Very flexible and great for rating or categorizing items.
<number> you need to accept positive numeric input. The report will show the mean and standard deviation.
<float> you need to accept any floating, positive or negative numeric input.
<text> you need to accept textual input or none of the question types above will do. Storing data as text is mostly useless in reporting, so consider this the last resort.

Client requirements can make it clear what data type you need to use -- i.e. if you need to make something just like a radio question but with sounds on mouseover, you would start with the radio question to not have to reinvent it.

If you’re still unsure, try to think of the labels and values you will be showing to the user, and build the question type you want with them, run simulated data and view the report.

You may also consider the built-in validation and how it will help or hinder our question.

2.3:  General Structure

So you have your "mystyle" style. What will you override and where will your logic be? So far our questions have followed this structure:

Put a Javascript file in static/mystyle.js in your directory. Your code must be namespaced within a new object:

Survey.question.mystyle = {
  setup: function(label, options) {
    . . .
  }
}

Include your mystyle.js (and an optional mystyle.css) by adding this to styles.xml:

<include href="mystyle.js"/>
<include href="mystyle.css"/>

This will add the add the correct <script> code to the page <head> element every time your question is displayed. It will link to the right location (because someone could copy your style and put it in a survey directory planning to modify it) and version of the style (so that if you upgrade from v1 to v2, you do not need to adjust all your paths).

You may also include Less stylesheets by adding this to the styles.xml:

<less href="mystyle.less"/>

Now, call your setup function. This will typically be done by emitting Javascript that runs after the question has been displayed:

<style name="question.after" wrap="ready"><![CDATA[
Survey.question.mystyle.setup($(this.label|js), $(this.stylesjs.mystyle));
]]></style>

The <style> tag adds a custom style override just to your question -- all the styles and stylevars get copied into all of the questions that have uses="mystyle" specified. See the XML Style System document for a reference of what is supported by the <style> tag. In general, you will probably use the name, wrap and mode attributes. Others (which are usually ignored) include: with/rows/cols/label/copy/after/before.

In some cases, the cond attribute comes in handy to add multiple style overrides of the same style where one is only applied to mobile browsers.

In the code above, we use wrap="ready" which is a handy shortcut that surrounds our code with jQuery.ready(function() { … }). This means that the code within your style runs as Javascript after the page is ready and all necessary elements have been loaded onto the page. The filter, |js , serializes the string (or any other data structure) as JSON.

The this.stylejs.mystyle call is a shortcut that takes every configurable style variable (introduced using <stylevar>) that starts with mystyle and generates a serialized JSON object from them. This means that if you have a <stylevar name="mystyle:color">, it's specified or default value will be passed in as the second argument to your setup function.

The name, question.after, means that the style is called after every question is displayed, including fused question "slaves".

2.4:  In Your Javascript

Survey.question.mystyle = {
  setup: function(label, options) {
    ...
  }
}

First, find your targeted questions area with the following jQuery selector:

$("#question_" + question_label)

Then...

2.4.1:  Listen for Changes on Form Elements

Collecting accurate data is what matters most, so it’s important to let the form elements drive the design.

Example:

If your question style consisted of respondents clicking on images to toggle selections, then every click to an image would check (or uncheck) one of the hidden input elements. If it was a <checkbox> question, then selecting an image would check/toggle the corresponding checkbox input. De-selecting an image would, adversely, uncheck the corresponding checkbox input.

If you were to let the form elements drive the design in this situation, you would toggle the state of the hidden form element with JavaScript and then pass off the styling by triggering a change on the form element. Triggering the change on the form element would then call your function to add or remove the necessary selection styling.

Code example:

// checkbox change listener (for the hidden checkboxes)
$theQuestion.find(".sq-imageclick-image input[type='checkbox']").change(function() {
    // the checkbox
    var $this = $(this);

    // apply styling to the associated image container
    if ($this.checked) {
        // add selected styling
        ...
    } else {
        // remove selected styling
        ...
    }
});

// image click listener
$theQuestion.find(".sq-imageclick-image").click(function() {
    // the image
    var $this = $(this);

    // the associated checkbox
    var $formElement = $this.find("input[type='checkbox']");

    // if there is a hidden checkbox element inside
    if ($formElement.length) {
        // toggle the checkbox state
        $formElement[0].checked = !$formElement[0].checked;

        // trigger change on the checkbox
        $formElement.trigger("change");
     }
});

Demonstrated in the example above, styling that indicates whether or not an image is selected depends entirely on the state of the underlying form input element.

2.5:  Default & Custom CSS

Put all of your default CSS into mystyle.css, which will be included via <include/> on every page. As shown below, prefix your CSS classes with"sq-yourstylename":

.sq-mystyle-button { font-color: fuchsia; }

If you allow custom override of the CSS for the entire question, use the page.head <style> within styles.xml to generate it. For example, if you have a style variable named mystyle:css which should amend the .sq-mystyle settings:

<style name="page.head"><![CDATA[
<style>
#question_$(this.label) .sq-mystyle {
     $(this.styles.mystyle.css);
}
<style>
]]></style>

Using specific style selectors, we can target individual elements for a particular question. Try not to use !important when creating CSS so that additional multiple mystyle questions are not impossible to overwrite.

Question specific CSS goes here and the default styling should be placed in your style's static/ directory in mystyle.css.

2.6:  Accessing Theme Colors

Within your dynamic question style, you can check whether aqtheme is defined. If it is available, the following color variables will be accessible:

The primary colors (inherited from the button background color in Theme Builder)
    ${aqtheme.primary}
    ${aqtheme.primary_selected}
    ${aqtheme.primary_disabled}

The secondary colors (inherited from the button foreground color in Theme Builder)
    ${aqtheme.secondary}
    ${aqtheme.secondary_selected}
    ${aqtheme.secondary_disabled}

The aqtheme variable is only available if there is a valid theme.css file to reference.

Themed Styles XML Example:

<style name="page.head"><![CDATA[
<style>
/* btn */
#question_$(this.label) .sq-atm1d-btn {
@if aqtheme
    background-color: ${aqtheme.primary};
    color: ${aqtheme.secondary};
@endif
    $(this.styles.atm1d.btn_css)
}

/* btn selected */
#question_$(this.label) .sq-atm1d-btn-selected,
#question_$(this.label) .sq-atm1d-btn-hover {
@if aqtheme
    background-color: ${aqtheme.primary_selected};
    color: ${aqtheme.secondary_selected};
@endif
    $(this.styles.atm1d.btn_selected_css)
}

/* btn disabled */
#question_$(this.label) .sq-atm1d-btn-disabled {
@if aqtheme
   background-color: ${aqtheme.primary_disabled};
   color: ${aqtheme.secondary_disabled};
@endif
   $(this.styles.atm1d.btn_disabled_css)
}

It is also possible to tweak these colors:

  • ${aqtheme.primary_selected.lighten(10)} will lighten a color
  • ${aqtheme.primary_selected.darken(10)} will darken a color

2.7:  In Your styles.xml

It is common to mix overrides to question elements with Javascript code that enhances their functionality. Question overrides may change the structure of the element's HTML and classes, but the behaviour will be added purely via Javascript.

Each style override looks like this (see XML Style System for more info):

<style name="el.radio" mode="before/instead/after" wrap="ready"><![CDATA[
    <input type="radio" name="$(name)" value="$(value)" $(checked)/>
]]></style>

Currently, some question style designers use style overrides to modify the structure of HTML elements while others perform similar modifications using solely Javascript. There are pros and cons to each approach. Typically you will target:

Style Target Description
question.after Enables you to add code following the question being shown. This is a great area to place additional Javascript code, so the attribute wrap="ready" is almost always specified.
page.head Enables you to add code in the page's <head> section. The attribute mode="after" is implicitly added.
el.SOMETHING Allows you to modify the structure of a particular element.
See XML Style Blocks for a list of modifiable elements.

By default, each style override will have mode="instead" specified, replacing the default structure entirely. You may specify mode="after" to add your code after the original style or mode="before" to add your code before the style.

The attribute wrap="ready" is very convenient, adding your content in between to <script> tags and a jQuery ready function. This allows you to skip that process and write Javascript code more quickly.

In general, you shouldn't need to use style overrides extensively. Add the basic structure, classes and any row/col specific styling and do the rest using Javascript.

Use mode="before" and arg:text, as seen in the leftright style:

<style name="question.left" cond="row in p.get('shuffleLeftRight',{}).get(this,{})" mode="before" arg:text='${row.qaText(row.pers.rightLegend)}'/>

2.7.1:  Style Variables

Configurable style variables are defined in the styles.xml file. For example:

<stylevar name="atmtable:row_dividers" title="Show row dividers?" type="bool">0</stylevar>

You must specify a name and it must start with "mystyle:". The name is what appears in the XML when setting the attribute.

You must specify a type and it must be one of the following types: bool (0 or 1), string, enum, css, int or res.

The enum type creates a drop down list in the survey builder's style manager window pane. You must specify a comma-separated list of values and a default option (e.g. "left,center,right").

For example:

<stylevar name="mystyle:align" type="enum" title="Alignment of the text" values="left,center,right">center</stylevar>

The res type allows the text to appear in translation files. 

If a value is not provided in the survey XML, the default value (e.g. "center") will be used.

You can restrict what kind of elements the style variable may be applied to using the tag attribute (e.g. col, row or choice). For example, tag="row" makes the style variable only available to <row> elements.

Specify multiline="1" for any <stylevar/> that you wish to display in the survey builder as a textarea instead of a single-line text input. This is often used for style variables of type string, css or res.

Some example style variables to consider:

  • Should a certain element be visible? (e.g. row divider, special line, special feature, etc...)
  • Should any of the elements' styles be overridable with CSS styling?
  • Allow for additional style customization when a button is selected, deselected or disabled?
  • What should elements look like when an error is presented?
  • Overall size of the question's container or style elements?

Avoid variables that are a subset of a more general CSS rule (e.g. mystyle:button_font_size). Instead, just use a general CSS style variable (e.g. mystyle:button_css).

Some variable naming guidelines:

  • mystyle:css -- main CSS override for the style
  • mystyle:element_css -- CSS for that element (e.g. table, row, legend, button)
  • mystyle:element_selected_css -- additional CSS when that element is selected
  • mystyle:element_disabled_css -- additional CSS when that element is disabled
  • mystyle:element_text -- some text relevant to that element (e.g. legend text)

2.8:  QA Mode

How do I ensure my style works with QA mode?

  • Make sure the "answer for me" function works. If your question style listens to form element changes, then you should be good to go.
  • Add appropriate QA flag using the information included in ${jsexport()} (e.g. optional, open-ended, exclusive, etc...)

2.9:  Support vs. Private Libraries

All Javascript/CSS files that were created by your or are useful only to your project belong in the static/ directory of your style.

All Javascript/CSS files that may seem useful and possibly referenced by others should be placed in the static/support/ directory in v2 (e.g. /static/support/mystyle/common.script.js).

2.10:  Common Question Attributes

Your question style should support (or at least not break) with as many standard question attributes as possible. If your question won't support specific values, force the value that your question style does support. Consider the following:

  • grouping: this is most important if your underlying question is a <radio> as it determines whether there’s one variable per column. For other question types it may affect validation: for example for a <checkbox> with exactly="3" the 3 will be per row if grouping="rows" is set, or per column if grouping="cols" is set.
  • shuffle: the rows, cols and choices of your question can appear in random order. Avoid digging into the list of them from the question (by using e.g. this.cols in the styles code).
  • conditional logic: the rows/cols/choices may be disabled because of a cond=".." attribute or hidden entirely using where="none". Thus you may only see 1 row, even if len(this.rows) is 3.
  • validate: the user may add extra error message to the question; so always assume your question can be re-displayed with errors
  • exclusive: set on a row or column within a <checkbox>. It’s expected to clear and disable all the other options within that row/column (depending on grouping).

If there are any attributes that must have a certain value to work in your question style, then force the value within the meta.xml file. For example:

   <require name="grouping">rows</require>

2.11:  Compatibility

It’s important that dynamic questions are hard to break. Several features and elements are disabled by default, but ideally, your new style should work with as many of them as possible:

<noanswer> elements: one or more of these can be added to any question type to display a checkbox which should clear and disable the rest of the question. The <noanswer> element is an opt-out option. For example, if you are asked to rate 5 movies, there may be an opt-out option with the text, "I don't watch movies" or "I’m blind".

To enable the <noanswer> element in your question style, set <supports>noanswer</supports> in your project's meta.xml file and verify that the behavior is working correctly:

  • clicking the element removes all selected answers and disables the data in your question
  • multiple <noanswer> elements may be placed in the question

 

Fused questions: this consists of multiple questions that follow each other in the XML and have the same rows/cols that can be arranged immediately next to each other. This is done using the rightOf="QUESTION" or below="QUESTION" attributes. By default, a question with the uses is not allowed to use the rightOf or below attributes. If your question can support these attributes, set <supports>fused</support> in your project's meta.xml file. Before adding fused question support, consider the following:

  • The question with the uses attribute may be the master question or slave question. A master question is a question that is being referenced by another question using either the rightOf or below attribute. A slave question is one that references another question using either the rightOf or below attributes.
  • Not all questions that will appear on the page will have the uses attribute specified. This means that not all questions will have the special styling specified. Verify that everything will look OK even if your question is the only dynamically styled question.

As a general rule-of-thumb, if your Javascript selects a question using the "#question_" identifier, then it should not be fused-question compatible.

open=1: a <row> or <col> element may have open="1" specified. This means that the element will need an extra input supplied to provide additional open-ended information. If your style should not support this attribute, add <conflicts>open</conflicts> in your project's meta.xml file to disable it. Otherwise, your style should support this additional input box.

Groups can be added to group together rows and columns. Verify that your question style looks normal if groups are specified on the question elements. You may disable support for groups by adding <count name="group">0</count> to your project's meta.xml file.

Row/Col Counts: If your question needs at least 2 rows or columns, set <count name="row">2+</count> to require it. If it needs exactly one (including the implicit one) use <count name="row">1</count>.

Multi-style compatibility: if your style modifies what the control elements look like, set <modifies>controls</modifies> in your project's meta.xml file. This means that another style that modifies the same element cannot be used on the same question that your style applies to.

Global styles: some styles can be set on the <survey> tag and affect all questions automatically (e.g. Form Image Replacement). For more information of this topic, see the Styles Library Reference Manual regarding this.modifies.

2.12:  Javascript Best Practices

Avoid global declarations and make sure everything in your Javascript code happens under the Survey.question.mystyle namespace.

Avoid adding Javascript code within your styles.xml and write everything in the static/ directory's mystyle.js.

Make sure to “use strict";

2.13:  Mobile Support

For the best performance on mobile devices, consider the following key tips:

  • Don't rely on the hover event:
  • Support touch events:
    • To be compatible with traditional point-and-click (mouse) designed applications, mobile web browsers fire off more than a handful of events relative to touch interactions. If you don't support native touch-based events, the interface may seem sluggish on mobile devices.
  • Avoid CSS text-shadows
    • It causes delays and slowness.

2.14:  Usability

Review the usability guidelines for some great tips on usability.

Override any unclear error messages using the res.xml file.

2.15:  Demo Survey & Automated Testing

During the creation of the style you should build a demo survey. This should be a survey.xml in the same directory. Be sure to demonstrate all of the available style variables and features in a very illustrative manner. Questions in the survey should have the attribute showSource="1" specified, allowing their source code to display before the question in testing mode.

You are encouraged to add <html> comment elements within the survey that describe what the styles is, does, and any limitations it may have.

Surveys will automatically be tested using Selenium. This means that your examples should be realistic, with probably title and row text that reflect the actual use-case for the question style. For example:

<radio label="Q5" averages="cols" type="rating">
<title>How strongly do you agree with the following statement based on your experience today?</title>
<comment>Select one</comment>
<col label="c1" value="1">Strongly disagree</col>
<col label="c2" value="2">Somewhat disagree</col>
<col label="c3" value="3">Neither agree nor disagree</col>
<col label="c4" value="4">Somewhat agree</col>
<col label="c5" value="5">Strongly agree</col>
<row label="r1">The eBay homepage helped me discover items/products that I did not have in mind when I visited the eBay homepage</row>
</radio>

Here the title is reasonably long (87 characters) and the rows are realistic (27 characters).

2.16:  Documentation

You should initially deliver programmer-level documentation. These notes should be added to the milestone release notes as soon as their near a finalized state. The documentation should note:

  • style name and current version (e.g. fancything.1)
  • title and description of the style
  • the question type it applies to
  • available variables that can be configured
  • limitations: does the style run without javascript? does it support noanswer?
  • resources: does it override some language resources via <res>?

Confirm that all variables in the styles.xml are documented and appear in the demo survey.

3:  Survey Editor Support

Survey editor support is optional. This is only necessary if the question style should be usable within the survey editor.

  • meta.xml
    • Set the short <title> and <description>
      • Be consistent with existing elements (available to clients), including capitalization, paragraphs, spacing, etc.
      • The description should include a link to a KB page, so contact Shannon to get the link.
    • Set <builder> to staff/pan accordingly
    • Consider using <rename> to call columns, rows and choices something else
    • Use <qem> to  add editing of other important variables other than the row/col/choice text to the QEM. Those should be variables pretty much required for every instance
    • Use <count name="<row|col|choice>">0</count> to hide rows/colums/choice from the quick editor.
    • Use <template scope="<radio|checkbox|select|number|text>"> to create custom XML that is injected into the project when the DQ is selected from the pan menu. This will enable the DQ to be created in a valid state.
      • If "scope" is not provided, the template will be applied to all question types.
      • If no <title> or <comment> element is specified, the default one will be used.
      • Partial markup is not allowed. (e.g. <radio> without a label)
    • For dynamic questions set the <device> attributes (name and compat). These attributes affect device notification warnings (based on the mobileDevices set in the survey tag) and the compatibility table displayed for an element in the pan menu. 
      • <device name="<desktop|tablet|smartphone|featurephone|mobile>" compat="<optimized|compatible|incompatible>"/>
      • Defaults: desktop, tablet, smartphone: "compatible"
        featurephone, mobile: "incompatible"
      • Compatibility levels:
        • Optimized: Content is optimized for touch based input and content may re-arrange to display properly.
        • Compatible: May work on mobile devices, but are not specifically optimized such that these may incur horizontal scrolling.  Respondents on mobile devices may have difficulty answering these questions.
        • Incompatible: Question will not load correctly for the respondent.
    • As of M19, you can restrict DQ styles to specific directories. If you need to, add <restricted>1</restricted> to your meta.xml and add an allowed.txt file to the root directory of your DQ style. Your allowed.txt file should look similar to this, with each directory listed on its own line:
      • selfserve/53a
      • selfserve/9d3/*
      • With the configuration above, the DQ style will be usable in all surveys directly under /53a, but none of its subdirectories. The DQ style will be usable in all directories and subdirectories under /9d3. No other directory other than the ones listed will be able to use the DQ style -- a fatal error will be shown.
  • styles.xml
    • Make sure the <stylevars> are ordered with the most important first -- that’s what gets displayed first in the builder’s style editor. Give each one a good short title= attribute (no longer than 30 characters!) and desc= for what appears on the right. Those that are advanced settings should be set with where="adv"; those that are only XML editable should be where="none"
    • Any <stylevar> attribute with tag="row|col|choice" and where="builder" specified will appear in the survey builder's options panel for that particular cell type. A DQ-specific options accordion will be added and enable the survey author to modify the attribute's value.
  • Custom Icons
    • As of M19, you can provide custom Pan Menu and/or Tree icons for your DQ. Place images in the .png format in your DQ's /static directory.
      • 25x25 pixel in the Pan Menu
      • 16x16 pixel in the Tree
    • Must obey the following naming convention:
      • /static/builder-panmenu-{scope}.png
        • (e.g. /static/builder-panmenu-radio.png )
      • /static/builder-tree-{scope}.png
        • (e.g. /static/builder-tree-radio.png )
    • If you do not provide a custom icon, the default [] icon will be used.

After any changes, take your style out for a spin using the survey builder.

The focus of dynamic question styles is to get them in the hands of programmers. Focus on making the code rock solid before moving onto supporting the survey builder.

  • War dieser Artikel hilfreich?