Accessible-ueq NPM

Accessible UEQ(S) WebComponent

A more accessible version of the UEQ-S through usage with emotional bonding (Publication). This widget uses smileys as an approach to link emotions to the UEQ tiers. The development focused on the UEQ-S, so the full UEQ is not yet implemented.

You can use the accessible UEQ-S in any web application as a WebComponent. All you need to do is import the javascript file and use the custom HTML element.

This WebComponent implements the ElementInternals interface to allow for using the element in classic HTML forms. There is of course also a plain javascript API exposed.

Getting started

Using a CDN

You can use the accessible UEQ-S on your website without installing anything using jsDelivr:

Include and use it in your HTML

...
<head>
    <script type="module" src="https://cdn.jsdelivr.net/npm/accessible-ueq/dist/ueq-emotion.webcomponent.mjs"></script>
</head>
...
<body>
...
    <ueq-emotion name="form-element-name"></ueq-emotion>
...
</body>

Using `npm`

Install via npm: npm i accessible-ueq
Import and use in your html:

...
<head>
    <script type="module" src="./node_modules/accessible-ueq/dist/ueq-emotion.webcomponent.mjs"></script>
</head>
...
<body>
...
    <ueq-emotion name="form-element-name"></ueq-emotion>
...
</body>

Receiving data

Classic HTML

You can use the element inside any HTML <form>-element, like an <input>. The provided values will be submitted as JSON-encoded string in the form

{
  "support": <number>,
  "ease": <number>,
  "efficiency": <number>,
  "clarity": <number>,
  "excitement": <number>,
  "interest": <number>,
  "invention": <number>,
  "novelty": <number>
}

with numbers from 1 - 7 depending on the selection.

Access via Javascript

If you want to access the values via javascript rather than submitting a html form, the value property will return a javascript object rather than a JSON string.

function getUeqValues() {
  const data = document.querySelector('ueq-emotion[name="form-element-name"]').value;
  // data is provided as Javascript object
  console.log(data);
}

Live Example

<ueq-emotion name="ueq-sample" locale="de_LS"></ueq-emotion>

Attributes

There is a set of attributes you can use to personalize your ueq-s

Attribute	Mandatory	Type	Default	Description
`name`	yes	string	-	Name of the form element. Must conform `name` attribute specifications for `input` elements.
`locale`	no	string	en_US	Locale to be used for translation. Currently available: `en_US`, `de_DE`, `de_LS` (German simple language)
`value`	no	string	{}	Set initial value of the element. Must be a JSON-object
`multi-field`	no	bool	false	Activates Multi-Field setting
`type`	no	string	'Short'	Selects if the UEQ-Short should be used or the full UEQ (not implemented)

Multi-Field

The default behaviour converts all questions into a single form-field, which contains all values as JSON-string. If you want to get the single values as separate form fields, you can simply use the multi-field attribute:

 <ueq-emotion name="my-ueq" multi-field></ueq-emotion>

This will submit every modality as a single form value in the format:

my-ueq[support] = <number>
my-ueq[ease] = <number>
my-ueq[efficiency] = <number>
my-ueq[clarity] = <number>
my-ueq[excitement] = <number>
my-ueq[interest] = <number>
my-ueq[invention] = <number>
my-ueq[novelty] = <number>

Accessing the value through javascript will however still deliver a JS-object in the default format.

Styling

The accessible UEQ-S is designed to be accessible as far as possible, even from color schemes. However, for some applications, it may be necessary to change sizes or colors. This can be done by setting the elements' css variables. This is even possible per element:

<style>
    /* setting global style */
    ueq-emotion {
        /* Size of an individual smiley face. All sizes will be calculated based on this. */
        --ueq-face-size: 2em; /* default: 4em */
        
        /* Border color of the smiley face. */
        --ueq-border-normal: maroon; /* default: #000000 */
        
        /* Border color of the selected smiley face. */
        --ueq-border-highlight: green; /* default: #0000ff */
        
        /* Background color of the full element if not valid */
        --ueq-error-highlight: red; /* default: none */
    }
    .giant-faces {
        --ueq-face-size: 100px;
    }
</style>

<!-- Using global styles -->
<ueq-emotion></ueq-emotion>

<!-- Using "giant-faces" class style -->
<ueq-emotion class="giant-faces"></ueq-emotion>

Deprecated Usage with angular

Usage as SurveyJS custom element for Angular. The general usage of custom elements is displayed on SurveyJS Angular CLI.

Originally developed towards usage with Angular only, the WebComponent is now leading the developemnt. As soon as stable, there will be a new Angular component developed, using the WebComponent internally.

To add the accessible UEQ-S to you survey, just add this project to your components folder and edit your survey.component.ts:

...
import * as Survey from 'survey-angular';
import {init as initUeqWidget} from './accessible-ueq/ueq-emotion.widget';
import {UeqEmotionType} from './accessible-ueq/ueq-emotion.contents';
...
initUeqWidget(Survey, {
  type: UeqEmotionType.Short,
  lang: 'en_US',
});

Now you can simply add the widget to your survey's HTML:

<survey [json]="json"></survey>

and Typescript:

  json = {
    title: 'My accessible survey',
    pages: [
      {
        questions: [
          {
            type: 'ueq-emotion',
            name: 'my-emotional-ueqs',
            title: 'Please rate the system you just have been showed',
            validators: [
              {
                type: 'expression',
                text: 'Please provide a rating for every line',
                expression: 'UeqEmotionAspectsCheckedValidator({my-emotional-ueqs}, Short)'
              }
            ]
          }
        ]
      }
    ]
  };