Page Comparison

Templated widget and dashboard queries can use several objects, most notably the dashboard store, to inject parameters.

Using those objects guarantees 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 parametrised (templated) query, Underscore.js template language is used. 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.

• 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

• Reducers

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

  • Shorthand: r.name

  • More information on reducers in the paragraph below.

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, which 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:

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

  • Complex example, combine multiple User Preferences:

    • Code Block
      <%= 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) %>

...

This page can now be found at Dashboard/Widget Query Parametrization on the Squirro Docs site.