Dashboard/Widget Query Parametrisation

Templated widget and dashboard queries can use several objects to inject parameters. Most notably, they use the Dashboard Store.

Using those objects guarantees that the affected widgets/dashboard will re-render whenever those objects change. In other words, dashboards and widgets become reactive to changes on those objects.

Templating Language

To construct a parametrized (templated) query, Squirro uses the Underscore.js template language.

To quote the documentation:

Template functions can both interpolate values, using <%= ... %>, as well as execute arbitrary JavaScript code, with <% ... %>. If you wish to interpolate a value, and have it be HTML-escaped, use <%- ... %>.

For almost all cases, <%= ... %> will be the preferred usage (since the templated function is expected to return a value, and HTML escaping can mess some special characters like the "" marks).

The templated blocks can be freely combined with free text parts, so a query of foo <%= store.key %>, would resolve to foo bar, if store.key === 'bar'.

Objects Available in Templated Functions

• Reducers, such as the sanitizer, are particularly useful when using entries containing facet values.

• On dashboard load, the object entries will be evaluated before the dashboard/widgets load, allowing very efficient preselecting widgets.

• The object entries will be resolved via the provided key and injected into the query in place of the template.

• Dashboard Store

  • Usage: store.key, where key is a custom key name (a unique identifier).

  • Shorthand: s.key

  • What to expect:

    • Whenever store changes, the dashboard/widgets will reevaluate the queries and if the store change caused the query to change, the dashboard/widgets will re-render.

• Global Search and Query Context

  • Usage: searchbar.value and searchbar.empty, where value is the current value of global search query and empty is a boolean indicating if value is empty or not.

  • Result of query processing can be accessed via queryContext variable. See context parameters section for more information what can be accessed.

• User Preferences

  • Usage: pref.key, where key is a custom user preference key name (a unique identifier).

  • What to expect:

    • Whenever user preferences change, the dashboard/widgets will reevaluate the queries and if the preference change caused the query to change, the dashboard/widgets will re-render.

    • Use this in combination with the User Preferences widget.

• URL Params

  • Usage: params.key, where key is a URL parameter key (?parameter=value).

• Local Storage

  • Usage: localStorage.key, where key is a browser local storage key.

  • Shorthand: ls.key

Warning

If the key contains a -, use ls.getItem(key) instead.

• Reducers

  • Usage: reducers.name, where name is the reducer name.

  • Shorthand: r.name

  • More information on reducers in the paragraph below.

Query context parameters

• queryContext.like: string | null - concept search query

• queryContext.searchbar_query: string | null - global search user input

• queryContext.parsed includes the following data:

File	Typescript Type	Explanation
facet_filters	string[]	Filters applied to the query, like: facets, entities, time increments, comparisons.
id	string | null	Id of the query. Currently hardcoded to the query` value.
language	string | null	Detected language of the provided query.
pos_mutations	Record<string, string>	Mapping between token and it’s replacement used to boost and clean tokens based on the POS tags.
query	string | null	Final query as the result of query processing.
query_length	number | null	Length of the query.
original_query	string | null	Original query provided by the user.
type	string | null	Type of the query, which can be useful for classifying and analyzing different types of queries.
user_terms_str	string | null	Normal user query terms.
lemma_map	Record<string, string>	Mapping between the original words in the query and their respective lemmas (base forms).
_chunks | string[] | null		Noun chunks.
_pos | [string, string][] | null		Part of speech (POS) tags associated with each token in the query.
_ner | [string, string][] | null		Named entity recognition (NER) tags associated with each token in the query.

Reducers

Reducers are a handy way to isolate common template logic and move it out of the query definitions.

Reducers are essentially JavaScript functions, which can be used in the template language. They take a number of arguments and return a value, which is injected into the template in place of the reducer.

Squirro predefines several reducer functions that can be used on any Squirro installation.

Built-in Reducers

• $sanitize

  • Usage: reducers.$sanitize(value), where value is a string.

  • Shorthand: r.$s(value)

  • What to expect:

    • Ensures the provided value is in escaped according to Squirro query language format.

    • Wraps the provided value in “” marks, if it contains whitespaces.

• $makeTag

  • Usage: reducers.$makeTag(facet, value), where facet and value are strings.

  • Shorthand: r.$mt(facet, value)

  • What to expect:

    • Creates a Squirro query language compatible facet value selector.

    • Wraps both facet and value in “” marks, if they contain whitespaces.

• $arrayToQuery

  • Usage: reducers.$arrayToQuery(array, operator), where array is a User Preference Array or an normal array of values and operator is a Squirro syntax operator for example ‘AND’ or ‘OR’.

  • Shorthand: r.$atq(array, operator)

  • What to expect:

    • Returns a Squirro Query from an Array of terms with a Squirro join operator.

  • Simple example:

    • <%= reducers.$arrayToQuery(pref.pred, 'OR') %>
      

  • Complex example, combine multiple User Preferences:

    • <%= reducers.$atq([reducers.$atq(pref.pred, 'OR'), reducers.$atq(pref.string), 'my hardcoded string'], 'AND') %>
      

Additionally, it is possible to define custom reducers.

Custom Reducers

Since custom reducers are JavaScript functions, to define them, a Dashboard Loader must be used, which will contain the reducers code and expose them to the store.

The technique is similar to defining jQuery extension functions. The code below demonstrates how to use a loader to define a custom reducer, capitalize (which capitalizes the string passed into it).

return Loaders.Base.extend({
    customLoad: function () {
        this.dashboard.store.reducers.capitalize = function (value) {
            return _.capitalize(value);
        };
    },
})

A reducer defined in this way can be subsequently used in the templated query fields, like so:

• <%= reducers.capitalize(store.key) %>

  • For a store key of foo, would return Foo.