Client

Client

A Client service that provides widgets that can be embedded into views.

Constructor

new Client()

Source:
Copyright:
  • (c) 2021 TLF Research Ltd.

Methods

(static) deleteCookie(name)

Source:

Function to delete a cookie by name.

Parameters:
Name Type Description
name string

Name of the cookie to delete.

(static) getCookie(name)

Source:

Function to get a cookie by name.

Parameters:
Name Type Description
name string

Name of the cookie value to retrieve.

(static) init(onReady)

Source:

Sets up the standard client environment.

Parameters:
Name Type Description
onReady function

method to be invoked when the middleware layer has initialised.

(static) setCookie(name, value)

Source:

Function to set a cookie by name.

Parameters:
Name Type Description
name string

Name of the cookie value to set.
value string

New value.

(static) widgetSimpleDataSource()

Source:

Defines a standard Kendo dataSource that can be used by most widgets

_addKendoWidgetFromSurveyVar(widgetName, widgetOptions, project, name, varName, isPageFilteropt, onChangeopt, placeholderopt, groupVaropt, popupContaineropt, orderopt, suppressFilterEventsopt, omitFromFiltersopt) → {object}

Source:

Creates a new Kendo UI dropdown-style widget and populates it with all the distinct values of the given survey variable. This is the common factory method for addDropdownFromSurveyVar and addComboBoxFromSurveyVar.

Parameters:
Name Type Attributes Description
widgetName string

The name of the Kendo widget to create (e.g., 'kendoDropDownList', 'kendoComboBox').
widgetOptions object

The widget-specific configuration options.
project object

Project to use
name string

Name of the widget (must be unique on a page)
varName string

Name of the survey variable to use
isPageFilter boolean <optional>

True if this widget is a page filter
onChange function <optional>

Method to call when the widget value changes
placeholder string <optional>

Placeholder text
groupVar string <optional>

Name(s) of the variable to group the results by
popupContainer string <optional>

CSS selector of the element to append the popup containers to.
order array <optional>

Order of the dropdown items.
suppressFilterEvents boolean <optional>

When true updates to this widget will not generate filterChanged events.
omitFromFilters boolean <optional>

When true the dropdown will not add its value to the page filters.
Returns:
Type
object

addAnimatedNumber(name, options) → {object}

Source:

Creates a new Animated Number widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options

Options specific to this widget:

Option Type Default Comment
autoBind boolean false When true the widget will bind to a data source during initialization.
valueFormat string 'p0' Kendo format to use for the displayed values - @see https://docs.telerik.com/kendo-ui/globalization/intl/numberformatting.
speed number 1000 Animation speed.
Returns:
Type
object

addAssistant(name, options) → {object}

Source:

Creates a new Research Assistant widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Example
const project = client.Globals.projects.find((project) => project.name === 'My Project');

client.addAssistant('my-assistant-container', {project});
Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options -

Options specific to this widget:

Option Type Default Comment
project Project none Project to inspect (Mandatory).
Returns:
Type
object

addAutocompleteDropdownFromSurveyVar(project, name, varName, isPageFilteropt, onChangeopt, height, placeholderopt, groupVaropt, popupContaineropt, suppressFilterEventsopt, omitFromFiltersopt) → {object}

Source:

Creates a new dropdown autocomplete list widget and populates it with all the distinct values of the given survey variable. Expects a DOM input element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Attributes Description
project object

Project to use
name string

Name of the widget (must be unique on a page)
varName string

Name of the survey variable to use
isPageFilter boolean <optional>

True if this widget is a page filter
onChange function <optional>

Method to call when the widget value changes
height number

Height of the dropdown
placeholder string <optional>

Placeholder value
groupVar string <optional>

Name(s) of the variable to group the results by
popupContainer string <optional>

CSS selector of the element to append the (hidden) popup containers to.
suppressFilterEvents boolean <optional>

When true updates to this widget will not generate filterChanged events.
omitFromFilters boolean <optional>

When true the dropdown will not add its value to the page filters.
Returns:
Type
object

addBar(name, options) → {object}

Source:

Adds a Bar widget. Expects a DOM element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Options to control the appearance and behaviour of the Bar:

Option Type Default Comment
animate boolean false When true the bar expands out to its value.
reverse boolean false When false the bar grows to the right; when true to the left.
color string 'grey' Color of the value text.
value number 0 Value of the bar.
count number 0 A 'count' associated with the value of the bar e.g. a survey base that is shown in the tooltip.
format string 'p1' The Kendo format string used to format the bar's value for display - @see https://docs.telerik.com/kendo-ui/globalization/intl/numberformatting.
height number 22 The height of the bar in pixels.
category object {} Describes the category associated with the Bar's value. Supports the following subkeys: color (string): color of the category text. (default: 'grey'); position (string): position of the category text relative to the bar - one of 'outside-top', 'outside-bottom', 'outside-end', 'inside-end', 'inside-start'. (default: 'outside-top'); value (strong): the category text (default: null)
label object {} Describes the label used to display the Bar's value. Supports the following subkey: color (string): color of the value's label text. (default: 'white')
Returns:

Bar instance.

Type
object

addCalendar(name, options) → {object}

Source:
See:

Creates a new Calendar widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options
Returns:
Type
object

addCategories(name, options) → {object}

Source:

Creates a new Categories widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options

Options specific to this widget: project {object} The project to fetch category data from codingVar {string} The coding variable name (default: 'coding') dateVar {string} The date variable name (defaults to project.dateVar)

The server fixes the columns it returns, so codingVar and dateVar only name the keys to read from each row - they do not change what is fetched.

Bar length and the right-hand figure are the percentage of coded respondents who mention the category. A respondent counts once however many comment questions they answered, and respondents are multi-coded, so these do not sum to 100%. The sentiment colours within a bar are shares of that category's mentions, which is a different denominator - a respondent tagged both positively and negatively counts once in the bar length but twice there.
Returns:
Type
object

addChart(name, options) → {object}

Source:
See:

Creates a new chart widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options
Returns:
Type
object

addComboBoxFromSurveyVar()

Source:

Creates a new combobox widget and populates it with all the distinct values of the given survey variable.

addComparison(name, options) → {object}

Source:

Creates a new comparison widget that allows the user to compare survey variables side-by-side by creating up to 6 "personas". Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options:

Option Type Default Comment
project object none The Project used in the comparison.
vars array none Array of Survey Variables to show in the comparison.
filter string none An optional base filter that is always applied to all personas.
personaLabel array none The root name used for each persona. Each person is numbered so e.g. if personaLabel = "tenant" then the first persona will be "tenant 1".
personaAttributes array none An array describing the attributes that may be set for each persona.

An example:

const project = client.Globals.projects.find((project) => project.name === 'My Project'); const datePresets = { 'YearEnd 2024': client.Globals.datePreset.twoYearsAgoFinancialYear, 'YearEnd 2025': client.Globals.datePreset.lastFinancialYear, 'YearEnd 2026': client.Globals.datePreset.thisFinancialYear, }

client.addComparison( 'comparison2', { project:, vars: client.getProjectVarsByCategory(project, 'compare', ['name', 'caption']), filter: '{tenant_type}="LCRA"', personaLabel: 'tenant', personaAttributes: [ { name: project.dateVar, label: 'Dates', type: 'daterange', defaultFromFilter: 'departure', presets: datePresets }, { name: 'tenure_type', label: 'Tenure', type: 'dropdown' }, { name: 'age_group', label: 'Age Group', type: 'dropdown' }, { name: 'region', label: 'Region', type: 'dropdown' }, { name: 'had_repair', label: 'Had a Repair', type: 'dropdown' }, ] })

In personaAttributes: "name" is the name of the variable. "label" is the label to use for the persona. "type" is the type of control to show for the persona. It can be one of: - dropdown - daterange "defaultFromFilter" is optional, and if present will cause the persona's attribute to be initialized from the current page filter for that variable (if any). "presets" is optional, and only works for dateranges. It defines a set of date presets that can be used to set the persona's date range.
Returns:
Type
object

addDataValue(name, options) → {object}

Source:

Creates a new data container. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options options

Custom widget options - NOTE: Only options.filterChanged is supported
Returns:
Type
object

addDatePicker(name, varName, optionsopt, isPageFilteropt, onChangeopt, suppressFilterEventsopt) → {object}

Source:
See:

Creates a new date picker widget. Expects a DOM input element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Attributes Description
name string

Name of the widget (must be unique on a page)
varName string

Name of the survey variable associated with this widget.
options object <optional>

Custom widget options
isPageFilter boolean <optional>

True if this widget is a page filter
onChange function <optional>

Method to call when the widget value changes
suppressFilterEvents boolean <optional>

When true updates to this widget will not generate filterChanged events.
Returns:
Type
object

addDateRange(name, varName, optionsopt, isPageFilteropt, onChangeopt, suppressFilterEventsopt) → {object}

Source:
See:
  • addDatePicker for options.

Creates a new date range widget. Expects two DOM input elements with an id that matches the given name plus '-from' and '-to' to use as the base for the widget.

Pickers that select a whole period rather than a specific date (i.e. any depth coarser than "month") have their values snapped to the start of that period for the 'from' picker and to the end of it for the 'to' picker, so that the generated BETWEEN filter covers the whole of the selected 'to' period. Any change handler passed in options runs first and cannot leave a half-open range behind - @see _getPeriodSnap.

Parameters:
Name Type Attributes Description
name string

Name of the widget (must be unique on a page)
varName string

Name of the survey variable associated with this widget.
options object <optional>

Custom widget options
isPageFilter boolean <optional>

True if this widget is a page filter
onChange function <optional>

Method to call when the widget value changes
suppressFilterEvents boolean <optional>

When true updates to this widget will not generate filterChanged events.
Returns:
Type
object

addDoughnut(name, options) → {object}

Source:
See:

Creates a new doughnut widget (based on a Kendo chart). Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options
Returns:
Type
object

addDropdownFromData(name, data, valueProp, textPropopt, placeholderopt, isPageFilteropt, onChangeopt, popupContaineropt, suppressFilterEventsopt, omitFromFiltersopt, multiVaropt) → {object}

Source:

Creates a new dropdown list widget and populates it with the given data. Expects a DOM input element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Attributes Description
name string

Name of the widget (must be unique on a page)
data array

The widget's datasource
valueProp string

Datasource property to use for each list item's form value
textProp string <optional>

Datasource property to use for each list item's displayed text
placeholder string <optional>

Placeholder value
isPageFilter boolean <optional>

True if this widget is a page filter
onChange function <optional>

Method to call when the widget value changes
popupContainer string <optional>

CSS selector of the element to append the popup containers to.
suppressFilterEvents boolean <optional>

When true updates to this widget will not generate filterChanged events.
omitFromFilters boolean <optional>

When true the dropdown will not add its value to the page filters.
multiVar boolean <optional>

When true the dropdown is given a list of variables to choose from.
Returns:
Type
object

addDropdownFromDivisions(project, name, varName, divisions, extend, isPageFilteropt, onChangeopt, placeholderopt, popupContaineropt, suppressFilterEventsopt, omitFromFiltersopt) → {object}

Source:

Creates a new dropdown list widget and populates it with a ist of ranges based on the given divisions. Expects a DOM input element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Attributes Description
project object

Project to use
name string

Name of the widget (must be unique on a page)
varName string

Name of the survey variable to apply the given ranges to
divisions array

Divisions that separate each range
extend bool

If true the generated ranges include 'catch-all' ranges before and after the specified divisions
isPageFilter boolean <optional>

True if this widget is a page filter
onChange function <optional>

Method to call when the widget value changes
placeholder string <optional>

Placeholder text
popupContainer string <optional>

CSS selector of the element to append the (hidden) popup containers to.
suppressFilterEvents boolean <optional>

When true updates to this widget will not generate filterChanged events.
omitFromFilters boolean <optional>

When true the dropdown will not add its value to the page filters.
Returns:
Type
object

addDropdownFromSurveyVar()

Source:

Creates a new dropdown list widget and populates it with all the distinct values of the given survey variable.

addDropdownFromSurveyVarCategory(project, name, categoryName, placeholderopt, isPageFilteropt, onChangeopt, popupContaineropt, suppressFilterEventsopt, omitFromFiltersopt) → {object}

Source:
See:

Creates a new dropdown widget and populates it with all the distinct values from all the survey variables in the given variable category. Expects a DOM input element with an id that matches the given name to use as the base for the widget.

NOTE: Each variable in the category is expected to be a nullable boolean value.

Parameters:
Name Type Attributes Description
project object

Project to use
name string

Name of the widget (must be unique on a page)
categoryName string

Name of the survey variable category to use
placeholder string <optional>

Placeholder value
isPageFilter boolean <optional>

True if this widget is a page filter
onChange function <optional>

Method to call when the widget value changes
popupContainer string <optional>

CSS selector of the element to append the popup containers to.
suppressFilterEvents boolean <optional>

When true updates to this widget will not generate filterChanged events.
omitFromFilters boolean <optional>

When true the dropdown will not add its value to the page filters.
Returns:
Type
object

addDropdownTreeFromData(name, data, valueProp, textPropopt, isPageFilteropt, optionsopt, onChangeopt, suppressFilterEventsopt, omitFromFiltersopt) → {object}

Source:

Creates a new dropdowntree widget and populates it with the given data. Expects a DOM input element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Attributes Description
name string

Name of the widget (must be unique on a page)
data array

Data to display
valueProp string

Property to use as the list value
textProp string <optional>

Property to use as the list text
isPageFilter boolean <optional>

True if this widget is a page filter
options object <optional>

Custom widget options
onChange function <optional>

Method to call when the widget value changes
suppressFilterEvents boolean <optional>

When true updates to this widget will not generate filterChanged events.
omitFromFilters boolean <optional>

When true the dropdown will not add its value to the page filters.
Returns:
Type
object

addFiltersHook(name, hook)

Source:

Adds a new filter hook method to the list.

Parameters:
Name Type Description
name string

Name of the filter hook
hook function

Hook function to be called when a filter is to be applied

addGlobals(glob)

Source:

Adds additional Global variables

Parameters:
Name Type Description
glob object

Additional variables to be added to the client.Globals object.

addGrid(name, options) → {object}

Source:
See:

Creates a new grid widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options
Returns:
Type
object

addHeatmap(name, options) → {object}

Source:

Creates a new Heatmap widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Example
const project = client.Globals.projects[0];
const vars = client.getProjectVarsByCategory(project, "var-category", ['id', 'name', 'label']);

// Classify each question by section
const sections = {
    'hostel': ['hadprob2', 'hadprob3', 'hadprob5', 'hadprob6', 'hadprob10', 'hadprob12'],
    'guests': ['hadprob8'],
    'service': ['hadprob1', 'hadprob4', 'hadprob7', 'hadprob9', 'hadprob11'],
    'other': ['hadprob13'],
}

// Custom formatter for each row that prepends the section name to the variable label
const rowHeaderFormatter = v => {
    // Find which section header the given variable name belongs to
    for (const section in sections) {
        if (sections[section].includes(v.name)) {
            // Prepend the section name to the returned header
            return `<span class="section-header section-header-${section}">${section}</span><span>${v.label}</span>`;
        }
    }

    // If no section header was found, just return the variable label
    return v.label;
};

client.addHeatmap('heatmap-id', {
    project,  
    vars,                                           
    aggr: 'prop',                                   
    aggrBase: '{hadprob}=1',                        
    caption: 'Had a problem',                       
    scaleMode: 'GRID',                              
    scale: [
        {
            type: 'Min',                            
        },
        {
            type: 'Percentile',                     
            value: 50,                              
        },
        {
            type: 'Max',
        }
    ],
    invertScale: ['hadprob10'],                     
    rowHeaderFormatter                              
});

In this example the scale consists of three color stops:

  First stop: minimum value of the entire grid.
  Second stop: the median value of the entire grid.
  Third stop: the maximum value of the entire grid.

If the scaleMode was set to 'ROW' then the minimum, median and maximum values would be individually calculated for each *row*.
If the scaleMode was set to 'COL' then the minimum, median and maximum values would be individually calculated for each *column*.

No custom colors were specified so the default colors were used (which are the same as those used by Excel's Conditional Formatting feature).
The 'hadprob1' question has a negative sense e.g. 'Something was wrong' so its color scale is inverted (i.e. low is green => high is red).
Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options -

Options specific to this widget:

Option Type Default Comment
project Project none Project to inspect (Mandatory).
aggr string none API aggregator function to use (Mandatory).
aggrBase string none Aggregator base expression (only required for the 'prop' aggregator).
vars Variable[] none Array of Variables to display as grid rows - must have at least the 'id', 'name' and 'label' keys (Mandatory).
group string Project dateVar Grouping variable used to generate columns (Mandatory).
filters string Current page filters Filter to apply to the data.
caption string none The first column header's title - defaults to 'Question'.
scaleMode string none Determines the scope of the Min/Max/Percentile values in the 'scale' key - one of GRID
scale object[] none Array of color stops (Mandatory). Must contain either 2 or 3 members. Each stop is of the form { type: <One of 'Min', 'Max', 'Number' or 'Percentile'>, value: Number (only required if type is 'Number' or 'Percentile'), color: Custom color (optional) as '#RRGGBB' }.
format object[] 'p1' Kendo formatting string to apply to each cell's value
invertScale string[] none Optional names of variables to invert the color scale for.
rowHeaderFormatter string[] none Optional function to format each row's header HTML - it is passed the relevant Variable object.
Returns:
Type
object

addHotAlerts(name, options) → {object}

Source:

Creates a new Hot Alerts widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options

Options specific to this widget:

Option Type Default Comment
author string "Unknown" The name of the author that will be used in the attribution when comments and status changes are made.
filters function client.getPageFilters() Function that must return an array of filters to be used when requesting HAs. The default simply uses any global page filters.
project object None The Project to be used by the widget.
showFilter boolean false When set to true the widget displays a multi-select that can be used to filter the HA grid by one or more statuses.
showStats boolean false When set to true the widget displays counts for each possible HA status.
statuses array ['Open', 'Pending', 'Resolved'] HA statuses to be shown.
Returns:
Type
object

addHouse(name, options) → {object}

Source:

Creates a new House widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options

Options specific to this widget:

Option Type Default Comment
autoBind boolean false When true the widget will bind to a data source during initialization.
valueFormat string 'p0' Kendo format to use for the displayed values - @see https://docs.telerik.com/kendo-ui/globalization/intl/numberformatting.
speed number 1000 Animation speed.
Returns:
Type
object

addInteractiveChart(name, options) → {object}

Source:
See:

Creates a new interactive chart with a UI that allows the user to change the chart. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options
Returns:
Type
object

addInterview(name, options) → {object}

Source:

Creates a new Interview widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options -

Options specific to this widget:

Option Type Default Comment
autoBind boolean false When true the widget will bind to a data source during initialization.
datevar string null Name of the survey variable containing an interview date.
export boolean false When true an 'Export as a PDF' button will be shown.
inline boolean false When true the widget will be displayed inline as part of the page. When false it will be hosted inside a Kendo dialog.
journey object null JSON object whose keys define the label text shown in the widget, and whose values are strings that define participant variables (displayed in the left-hand column of the widget in a Participant section) - e.g. { 'My Name': 'participant_name' }
participant object null JSON object whose keys define the label text shown in the widget, and whose values are objects that define customer journey variables (displayed in the left-hand column of the widget in a Journey section), Boolean variables should be identified via a 'bool': true value - e.g. 'One call' : { name: 'manytimes_bool', bool: true}
project Project null Project associated with this widget.
satindex string 'satindex' Name of the survey variable containing a sat index score.
show function null Function that is called when the widget is shown. It is passed the ID of the displayed response.
showZeroScore boolean true When true the Likert scale ranges for sat scores are set to 0-10. When false it's 1-10.
title string 'Interview' Text to be displayed in the widget's tite bar.
Returns:
Type
object

addJourney(name, options) → {object}

Source:

Creates a new journey widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options
Returns:
Type
object

addMap(name, options) → {object}

Source:

Creates a new map widget (centred on the UK by default). Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options
Returns:
Type
object

addMultiSelectFromData(name, data, valueProp, textPropopt, placeholderopt, isPageFilteropt, optionsopt, onChangeopt, suppressFilterEventsopt) → {object}

Source:
See:

Creates a new multi-select widget and populates it with the given data. Expects a DOM input element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Attributes Description
name string

Name of the widget (must be unique on a page)
data array

Data to display
valueProp string

Property to use as the list value
textProp string <optional>

Property to use as the list text
placeholder string <optional>

Placeholder value
isPageFilter boolean <optional>

True if this widget is a page filter
options object <optional>

Custom widget options
onChange function <optional>

Method to call when the widget value changes
suppressFilterEvents boolean <optional>

When true updates to this widget will not generate filterChanged events.
Returns:
Type
object

addMultiSelectFromSurveyVar(project, name, surveyVarName, placeholderopt, isPageFilteropt, optionsopt, onChangeopt, suppressFilterEventsopt, groupVarNameopt, orderopt) → {object}

Source:
See:

Creates a new multi-select widget and populates it with all the distinct values of the given survey variable. Expects a DOM input element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Attributes Description
project object

Project to use
name string

Name of the widget (must be unique on a page)
surveyVarName string

Name of the survey variable to use
placeholder string <optional>

Placeholder value
isPageFilter boolean <optional>

True if this widget is a page filter
options object <optional>

Custom widget options
onChange function <optional>

Method to call when the widget value changes
suppressFilterEvents boolean <optional>

When true updates to this widget will not generate filterChanged events.
groupVarName string <optional>

Name(s) of the variable to group the results by
order array <optional>

Order of the multiselect items.
Returns:
Type
object

addMultiSelectFromSurveyVarCategory(project, name, categoryName, placeholderopt, isPageFilteropt, optionsopt, onChangeopt) → {object}

Source:
See:

Creates a new multi-select widget and populates it with all the distinct values from all the survey variables in the given variable category. Expects a DOM input element with an id that matches the given name to use as the base for the widget.

NOTE: Each variable in the category is expected to be a nullable boolean value

Parameters:
Name Type Attributes Description
project object

Project to use
name string

Name of the widget (must be unique on a page)
categoryName string

Name of the survey variable category to use
placeholder string <optional>

Placeholder value
isPageFilter boolean <optional>

True if this widget is a page filter
options object <optional>

Custom widget options
onChange function <optional>

Method to call when the widget value changes
Returns:
Type
object

addPerfectExperience(name, options) → {object}

Source:

Adds a Perfect Experience widget. Expects a DOM element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Options to control the appearance and behaviour of the widget.

Options specific to this widget:

Option Type Default Comment
addSummary boolean true When true a summary row will be added at the bottom of the widget to show the clients who said 'Yes' to all questions.
animate boolean true When true charts animate when they are first created.
barHeight number 30 The height of each bar in pixels.
categoryColor string "grey" The color of the category label.
categoryPos string "outside-top" The position of the category label relative to the bar - one of 'outside-top', 'outside-bottom', 'outside-end', 'inside-start', 'inside-end'
customFilter function null Defines a function that may be used to modify the filters used to fetch data from the API
detailSplit string null When set to the name of a variable will generate a bar chart split by the variable. The chart is displayed in the expandable detail row.
detailSplitFilter string null Filter used in the API call when generating the split chart.
detailSplitSort string null Sort used in the API call when generating the split chart.
detailTrend boolean false When set to true the widget displays a trend chart in the expandable detail row.
header boolean true When set to true the widget displays a header row above the main bar charts.
headerScoreTitle string "Sat Score" Text to show in the header for the Sat scores columns (when header is true).
includeDontKnow boolean false When true includes 'Don't Know' answers for Yes/No questions
leftBarColor string "grey" Color to use for the left-hand set of bars.
ovsatAggr string 'avg' API aggregator function to be used to calculate the sat result - one of 'avg or 'nps'
ovsatVar string OVSAT_VAR_NAME config setting Name of the variable to be used to calculate the sat result
project project null Project to use to display the widget. MANDATORY
quarterly boolean false When true display the data in quarters (rather than months).
quarterStartMonth number 0 (=January) If the quarters should not start in January specifiy the (zero-based) month number here.
rightBarColor string "silver" Color to use for the right-hand set of bars.
rolling string null The rolling period to apply to the data e.g. 3m(some_var_name).
rollingMode number PE_ROLLING_NONE Which widget elements to apply the rolling period to. One or more of the following constants: PE_ROLLING_NONE, PE_ROLLING_BAR, PE_ROLLING_SAT, PE_ROLLING_TREND, PE_ROLLING_SPLIT, PE_ROLLING_ALL. Combine mutiple options using bitwise OR e.g. `PE_ROLLING_BAR
satFormat string "p1" Kendo format to apply for the displayed Sat scores (applicable when satScores is true) - @see https://docs.telerik.com/kendo-ui/globalization/intl/numberformatting.
satScores boolean true When true show the numeric sat scores at the ends of each bar
swapBarColors array [] An array of one or more question names for which the left and right colors will be swapped.
vars array null List of Yes/No response var names to display. Each variable will generate a new row with its sat scores and a bar chart. MANDATORY
weighted boolean false When true all displayed data will be weighted using the weighting column identified by the variable in the Project's' weight category.
dontWeight object null When the filters key is present as an array of var names weights will not be applied when the widget is filtered by those variables e.g. { filters: ['foo','bar'] }
Returns:

Perfect Experience instance.

Type
object

addPivotAnalyser(name, options) → {object}

Source:

Creates a new Pivot Analyser widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options
Returns:
Type
object

addPodium(name, options) → {object}

Source:

Creates a new podium widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options
Returns:
Type
object

addRadialGauge(name, options) → {object}

Source:
See:

Creates a new radial gauge widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options
Returns:
Type
object

addRangeSlider(name, options) → {object}

Source:
See:

Creates a new range slider widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options
Returns:
Type
object

addRings(name, options) → {object}

Source:

Creates a new Rings widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options

Options specific to this widget:

Option Type Default Comment
animate string 'ease-out 2s' CSS Animation string.
autoBind boolean false When true the widget will bind to a data source during initialization.
closed boolean true When true the rings on the widget are closed i.e. are complete circles.
field string null Name of the variable to display in the widget.
labelField string null Name of the variable whose value is displayed at the top of the widget.
transform function null Method that is called with the value of the widget. Must return the value to be displayed.
width string '2' Width of the rings.
Returns:
Type
object

addSlider(name, options) → {object}

Source:
See:

Creates a new slider widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options
Returns:
Type
object

addSoftFilters(filters)

Source:

Adds any user claims that start with 'filter_' to the given filters object and returns a new filter object including the new filters. The original filters are not modified.

Parameters:
Name Type Description
filters object

Original filters object. They are not modified.

addSparkline(name, options) → {object}

Source:
See:

Creates a new sparkline widget i.e a simple chart with no axis, legend or tooltips. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options
Returns:
Type
object

addSphere(name, options) → {object}

Source:

Creates a new Sphere widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options

Options specific to this widget:

Option Type Default Comment
autoBind boolean false When true the widget will bind to a data source during initialization.
baseColor string '#808080' CSS Color to use for the sphere.
speed number 1500 Animation speed.
valueFormat string 'p0' Kendo format to use for the displayed values - @see https://docs.telerik.com/kendo-ui/globalization/intl/numberformatting.
Returns:
Type
object

addStage(name, options) → {object}

Source:

Creates a new stage widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options
Returns:
Type
object

addSurveyInspector(name, options) → {object}

Source:

Creates a new Survey Inspector widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options -

Options specific to this widget:

Option Type Default Comment
Returns:
Type
object

addTabStrip(name, options) → {object}

Source:
See:

Creates a new TabStrip widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options
Returns:
Type
object

addTaskboard(name, options) → {object}

Source:

Creates a new Taskboard widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options

Options specific to this widget:
Returns:
Type
object

addTreeList(name, options, filter) → {object}

Source:
See:

Creates a new TreeList widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Kendo TreeView widget options, plus the following TLF extensions:

Option Type Default Comment
persistExpandedNodes bool false When true the control will remember the expanded state of nodes.
persistScrollPosition bool false When true the control will remember the current scroll position.
filter function undefined A function that will be called with the rows returned by each API request. It may modify them before returning them.
databound function undefined A function that will be called when the treelist's data is bound. It is passed the data array and may modify it before returning it.

Each element in the Kendo columns array may specify any of the Kendo Column options, plus the following TLF extensions:

Key Type Default Comment
hierarchy array undefined Defines the hierarchy to be diplayed in the column. In this case the field option must be set to 'value'.
api object undefined Defines the API call to be used to fetch the column's data e.g. { aggregator: "avg", variable: "ease" }

An example hierarchy object (expanded = true means the node is expanded to show its children on first load) would be:

hierarchy: [ { text: 'Overall', expanded: true }, { varName: 'area', expanded: true }, { varName: 'region' }, { varName: 'company' }, { varName: 'project_manager' }, { varName: 'respondent' } ]
filter function

A filter function that is called when the treelist's data is bound. It is passed the rows array and may modify it before returning it.
Returns:
Type
object

addTreeView(name, options) → {object}

Source:
See:

Creates a new TreeView widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options
Returns:
Type
object

addUser(name, optionsopt) → {object}

Source:

Creates a new logged-in User widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Attributes Description
name string

Name of the widget (must be unique on a page)
options object <optional>

Custom widget options
Returns:
Type
object

addVideo(name, src, options) → {object}

Source:

Adds a video player. Expects a DOM element with an id that matches the given name to use as the base for the player.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
src string

URL of the video file to play
options object

Options to control the appearance and behaviour of the player.

The following options are supported:

clickAnyWhereToPlay (bool): When true the player can be toggled to play/pause by clicking anywhere in the video window.

features (array): Describes the desired playback features - one or more of the following:

'play' - play/pause toggle button 'time' - current time in mm::ss 'volume' - volume control 'skip-start' - button to skip to the start of the video 'skip-backwards' - button to jump back 15 seconds 'skip-forwards' - button to jump forwards 15 seconds 'skip-end' - button to skip to the end of the video

poster (string): path to an image file to show before the video is played (path is subject to CORS policy).

fadeTo (string): either a CSS color value or a path to an image file (path is subject to CORS policy). The color or image is shown after the end of the video.

captions (string): path to a VTT track file for text captions to be displayed while the video is playing (path is subject to CORS policy).

close (bool): When true a close button is displayed to allow the user to hide the video element.
Returns:

Video player instance.

Type
object

addViewFilters(name, options) → {object}

Source:

Creates a new View Filters widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options

Options specific to this widget:

Option Type Default Comment
mode string null Sets a 'mode' string that determines how the filters are displayed.
project Project null Sets the Project associated with the filters.
showNotApplicable boolean false When true all possible project filters are shown by default.
Returns:
Type
object

addWaffle(name, options) → {object}

Source:

Creates a new waffle chart widget. Expects a DOM div element with an id that matches the given name to use as the base for the widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
options object

Custom widget options

Options specific to this widget:

Option Type Default Comment
autoBind boolean false When true the widget will bind to a data source during initialization.
categories array 0 Array of data category names that are used to divide up the waffle squares.
columns number 0 Number of columns to show in the waffle.
height number 200 Height of the waffle in pixels.
layout string 'alternate' How the waffle squares are filled-in:'left-to-right' or 'alternate' i.e like a Snakes and Ladders board
speed number 0 Animation speed.
series array [] Array of objects representing the data series.
valueFormat string 'p0' Kendo format to use for the displayed values - @see https://docs.telerik.com/kendo-ui/globalization/intl/numberformatting.
Returns:
Type
object

buildBucketSeries(data, buckets, categories) → {Array}

Source:

Given some data rows, a set of buckets and a sorted set of categories, returns a set of chart series suitable for a Kendo stacked bar chart.

Parameters:
Name Type Description
data
buckets
categories
Returns:
Type
Array

clean()

Source:

Cleans up the current view

convertFiltersToString(filterMap) → {object}

Source:

Converts the given set of filters into a string.

Parameters:
Name Type Description
filterMap object

Map of filter values to be converted.
Returns:
Type
object

convertKendoFilters(f, nullValueopt) → {string}

Source:

Converts the given set of Kendo filters to a string that is compatible with the data API.

Parameters:
Name Type Attributes Description
f object

Kendo filter to convert
nullValue string <optional>

Optional string value to convert to an 'IS NULL' test
Returns:

An API filter that can be added to a filter collection

Type
string

createPageFilters(filtersID, statusID, proj)

Source:

Creates a set of page filters as defined by the config.PAGE_FILTERS object.

Parameters:
Name Type Description
filtersID string

ID of the parent HTML element for the page filters UI
statusID string

ID of the parent HTML element for the page filter status UI
proj Project

Project to be filtered

downloadAsCSV()

Source:

Downloads the given data as a CSV

escapeHTML()

Source:

escapeHTML allows HTML to be safely emitted by scripts

getAbsMax(a) → {Number}

Source:

Returns the maximum absolute value of all the given array values, ignoring any sign.

Parameters:
Name Type Description
a array
Returns:
Type
Number

getApplicableProjects(projects) → {array}

Source:

Returns the list of Projects that the User is allowed to see, and that are appropriate to this particular portal. It also fetches all the Project variables.

Parameters:
Name Type Description
projects array

an array of the user's Projects
Returns:

Projects that are relevant to the current portal and user

Type
array

getControl(name) → {jQuery}

Source:

Returns the underlying Kendo control for the given widget.

Parameters:
Name Type Description
name string
Returns:
Type
jQuery

getLatestProjectDate(filters, cb) → {Date|null}

Source:

getLatestProjectDate returns the latest date for which there is data across all the public Projects defined in the current portal's config.

Parameters:
Name Type Description
filters object

Filters to apply when searching
cb function

Function to call when the request completes
Returns:
Type
Date | null

getPageFilters(widgetsopt) → {object}

Source:

Returns a map containing current filter values.

Parameters:
Name Type Attributes Description
widgets array <optional>

Widget filter values to return
Returns:
Type
object

getPageFiltersAsString(widgetsopt) → {object}

Source:

Returns the current set of page filters as a string.

Parameters:
Name Type Attributes Description
widgets array <optional>

Widget filter values to return
Returns:
Type
object

getParameterMap() → {function}

Source:

Returns a parameter map needed to support this widget library.

Returns:
Type
function

getProjectVarsByCategory(project, categories, props) → {array}

Source:

Returns a collection of Project Variables properties for variables that are in any of the given categories. If props is a string a sinple array of scalar values is returned, otherwise it's an array of objects.

Parameters:
Name Type Description
project object

Project to inspect
categories array | string

Categories to inspect (null = get all categories)
props array | string

Variable properties to return (the id property is always returned)
Returns:

Project variables in the given categories.

Type
array

getSharedTooltipTemplate(aggregator, categoryVar, dataSource)

Source:

getSharedTooltipTemplate fetches a template that shows the chart series name, the aggregator value and the sample base.

Parameters:
Name Type Description
aggregator string

The name of the aggregator function being used
categoryVar string

The variable name of the category
dataSource string

The variable name of the data source

getValidID()

Source:

getValidID returns a string that can be used as a valid ID for an HTML element

getValueLabel(v) → {string}

Source:

getValueLabel returns a label for the given value

Parameters:
Name Type Description
v any

Data value to inspect
Returns:
Type
string

getWidget(name) → {jQuery}

Source:

Returns the given widget.

Parameters:
Name Type Description
name string

Name of the widget to retrieve
Returns:
Type
jQuery

injectCSS(cssFileUrl, onloadopt, onerroropt)

Source:

Injects the given CSS file into the page.

Parameters:
Name Type Attributes Description
cssFileUrl string

The URL of the CSS file to inject.
onload function <optional>

Method to call when the CSS file has loaded.
onerror function <optional>

Method to call if the CSS file fails to load (default is to ignore the error)

injectScript(id, src, onloadopt)

Source:

Injects the given named script src into the page.

Parameters:
Name Type Attributes Description
id string
src string
onload function <optional>

Method to call when the script has loaded

isAdmin()

Source:

Returns true if the current user is an Admin.

isPageFilter() → {boolean}

Source:

Return true if the given widget is defined as a page filter.

Returns:
Type
boolean

logout()

Source:

Logs the user out.

manageRealm()

Source:

Redirects to the Keycloak console to allow the realm to be managed via the IDP.

manageUsers()

Source:

Loads a view that provides some basic user management features.

modifyLinksIfOnStaging()

Source:

Scans all tags on the page and modifies their href attributes to a '.wr3s' version based on a dynamic set of conditions.

Intended for staging environments where all links to a production domain (e.g., 'client.leadershipfactor.com') should be rewritten to their corresponding staging version (e.g., 'client.wr3s.leadershipfactor.com').

The update happens iff:

  1. The current page's URL (window.location) is already on a '.wr3s' subdomain.
  2. The link's hostname ends with the target base domain (e.g., 'leadershipfactor.com').
  3. The link's hostname does NOT already contain '.wr3s'.

normalizeToArray(val) → {Array}

Source:

Normalizes the given value to an array.

Parameters:
Name Type Description
val
Returns:
Type
Array

onFilterChanged(callback)

Source:

Calls the given function whenever a filter changes. Also calls it immediately if all filters are in the ready state.

Parameters:
Name Type Description
callback function

Callback function.

onPageFilterChanged(callback)

Source:

Calls the given function whenever a filter changes. Also calls it immediately if all filters are in the ready state. Unlike onFilterChanged this is not deactivated when the page view changes.

Parameters:
Name Type Description
callback function

Callback function.

quantise(n, quantum) → {Number|NaN}

Source:

Returns the quantised value of the given number.

Parameters:
Name Type Description
n Number
quantum Number
Returns:
Type
Number | NaN

resetPassword()

Source:

Allows the user to request a password reset.

setControl(name, ctrl)

Source:

Sets the underlying Kendo control for the given widget.

Parameters:
Name Type Description
name string
ctrl jQuery

setDebug()

Source:

Sets debug mode on

setOption(name, value, value)

Source:

Sets a widget's options.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
value string

Option
value *

Option value

setPageFilterNotReady() → {boolean}

Source:

Sets the given page filter state to be not ready.

Returns:
Type
boolean

setWidgetData(name, data)

Source:

Updates the local data in a widget.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
data object

New data to display

setWidgetDataSource(name, data)

Source:

Set a widget's dataSource to a new one containing the given data.

Parameters:
Name Type Description
name string

Name of the widget (must be unique on a page)
data object

New data to display

setWidgetURL(name, url, queryopt, cacheopt)

Source:

Updates the URL used to provide the widget's data.

Parameters:
Name Type Attributes Description
name string

Name of the widget (must be unique on a page)
url string

New remote URL
query object <optional>

Query parameters
cache bool <optional>

When true (=default) the data from the server is cached.

softFilterRows(rows)

Source:

Returns a new set of rows that have been filtered by any user claims that start with 'filter_'.

Parameters:
Name Type Description
rows array

Original rows object. It is not modified.

summariseControlValue(ctrl) → {string|number}

Source:

Summarises the selected values of a widget as a short piece of text.

Parameters:
Name Type Description
ctrl object

A client widget's control
Returns:

Text summary of the widget value.

Type
string | number

suppressAllFilterEvents(suppress) → {object}

Source:

Sets whether ot not to suppress all filter events.

Parameters:
Name Type Description
suppress boolean

When true all filter events are suppressed.
Returns:
Type
object

switchToView(name, titleopt, addToHistoryopt)

Source:

Loads the given view into the Page.

Parameters:
Name Type Attributes Description
name string

Name of the view.
title string <optional>

Title of the view (defaults to the name if not supplied)
addToHistory boolean <optional>

When true (default) add this view to the browser's history

toKebabLowerCase()

Source:

toKebabLowerCase returns a lower cased string in kebab-case

toTitleCase()

Source:

toTitleCase returns a string in Title Case

truncateMiddle(fullStr, strLen, separator) → {string}

Source:

truncateMiddle returns the given string trucated to a maximum of strLen characters. with the separator (default: ...) in the middle.

Parameters:
Name Type Description
fullStr string

String to truncate
strLen number

Maximum lenght of the truncated string
separator string

Separator string to use in the middle of the truncated string.
Returns:
Type
string

(inner) _getPeriodSnap(depthopt, rangeEnd, maxopt) → {function|null}

Source:

Returns a Kendo change handler that snaps a date picker's value to the start or end of whichever period its depth selects - a month at depth "year", a year at depth "decade" or coarser. Returns null for day-granularity pickers (depth "month", Kendo's default) as those select a specific date that must be left alone.

This keeps the "to" end of a date range inclusive of the whole period the user picked, so that a filter ending "23:59:59" covers all of it rather than just its first day. It also works around a bug in the version of Kendo we're using whereby a datepicker in these modes returns a date whose day-of-month value is today's date if it's ever been used to pick a date in the current year.

Parameters:
Name Type Attributes Description
depth string <optional>

Kendo depth of the picker the handler is for
rangeEnd string

Which end of the range the picker represents - either 'start' or 'end'
max date <optional>

Picker's maximum permitted value, if any
Returns:

Change handler, or null if the picker's values need no snapping

Type
function | null

(inner) getDefaultView() → {string}

Source:

getDefaultView returns the first view that the logge-in user is allowed to see.

Returns:
Type
string