Page Comparison

...

The options for each composed widget depend on the widget type. If a widget requires one or more facets to visualize, the facets configuration should be passed in as shown in example above.

Utils

Utilities are provided in the Utils global space. They are present in the context of the widget JavaScript file, but not in the template context by default (that can easily be remedied by returning it as part of getCustomTemplateParams though).

queryParam

A utility for handling query string parameters.

parse()

Utils.queryParam.parse(/* no arguments */)

...

Dashboard State

The dashboard state is accessible in the widget using the widget.dashboard.state property. This model is the recommended way for custom widgets to talk to each-other. The dashboard state is a Backbone.js model though without persistence.

Custom widgets should implement the onStateChange method to listen for changes to the state.

Architecture

A good example for when to use the state is when there are two widgets on a dashboard that have to communicate with each-other.

For example a navigation widget can be implemented which presents the user with a number of menu options. When clicking on one of the options, the state is updated by setting a attribute. A second widget reacts to that state value and changes the content to be displayed depending on the set attribute.

Methods

get()

state.get(attribute)

Get the current value of the state attribute.

var params = Utils.queryParam.parseonStateChange: function (); // returns a hash of parameters, example:
// {"q": "Apple"}
console.log(params.q);

Dashboard State

The dashboard state is accessible in the widget using the widget.dashboard.state property. This model is the recommended way for custom widgets to talk to each-other. The dashboard state is a Backbone.js model though without persistence.

Custom widgets should implement the onStateChange method to listen for changes to the state.

Architecture

A good example for when to use the state is when there are two widgets on a dashboard that have to communicate with each-other.

For example a navigation widget can be implemented which presents the user with a number of menu options. When clicking on one of the options, the state is updated by setting a attribute. A second widget reacts to that state value and changes the content to be displayed depending on the set attribute.

Methods

get()

state.get(attribute)

Get the current value of the state attribute.

{
    if (this.dashboard.state.get('additionalInfo')) {
        this.$el.addClass('additional-info-requested');
    }
},

set()

state.set(attribute, value)
state.set(attributes)

Set one attribute to the given value or - in the secondary form - update all the key/value pairs from the hash.

If any attribute changes, a change event is triggered. The easiest way to subscribe to those in the widget is by implementing the onStateChange method.

onStateChangeonRowClicked: function () {
    if (this.dashboard.state.getset({'additionalInfo')) {
        this.$el.addClass('additional-info-requested': true});
    }
},

set()

state.set(attribute, value)
state.set(attributes)

Set one attribute to the given value or - in the secondary form - update all the key/value pairs from the hash.

If any attribute changes, a change event is triggered. The easiest way to subscribe to those in the widget is by implementing the onStateChange method.

onRowClicked: function () {
    this.dashboard.state.set({'additionalInfo': true});
},

Property Pages

Most widgets require configuration to function correctly. The widget configuration panels are exposed in the API, and can be leveraged and/or extended freely. To define a custom property panel, add a config.js file to the custom widget, and use the widget upload tool to bundle it.

The property page configuration file is a JavaScript file which is expected to return an extension on one of the objects in globally scoped object Pages.

Simplest form of the file would just return an existing configuration page (from one of the basic widgets), like so:

// Use the property page of Result List widget
return Pages.Search;

Extending the property page is done in same fashion as extending the base widget views.

The extended property page can implement any (or both) of two properties, customNormal and customAdvanced - depending which configuration section should be extended.

Each of the two properties is an array of objects, one per defined property. The objects are expected to contain the properties 'view' and 'config', The 'config' property should contain at minimum, 'inputName' and 'infoText', plus can define additional options, some global (available for all properties), some available for selected properties only.

...

• Defines a checkbox.
• Serializes to a boolean model property type.

...

• Defines a colorpicker.
• Serializes to a string model property type containing the color hashcode.

...

• Defines a control allowing to customize the format of a data.
• Serializes to a string model property containing the date formatting string.

...

• Defines a dynamic key/value pair picker control.
• Serializes to an object model property containing the chosen values.

...

• Defines a multi-facet selector control, which allows selecting one of the facets defined in the system.
• Serializes to an array of strings model property, corresponding to the names of facets chosen.
• Property specific options:
  • min
    • Defines how many facets minimum should the property allow to configure and serialize under one model property.
  • max
    • Defines how many facets maximum should the property allow to configure and serialize under one model property.
  • colorPicker
    • Whether the control should allow choosing a color for each facet, by integrating a colorpicker control.
  • typeRestriction
    • Restricts type of facets which should appear in the control.
  • aggregate
    • Whether to provide aggregation options for the facet.
  • aggregateFunctions
    • Which mathematical functions to allow aggregation over. By default, min, max, sum and avg (average) are exposed.

...

• Defines a language control, which allows selecting a language from all languages list.
• Serializes to a string model property containing the language identifier.

...

Property Pages

Most widgets require configuration to function correctly. The widget configuration panels are exposed in the API, and can be leveraged and/or extended freely. To define a custom property panel, add a config.js file to the custom widget, and use the widget upload tool to bundle it.

The property page configuration file is a JavaScript file which is expected to return an extension on one of the objects in globally scoped object Pages.

Simplest form of the file would just return an existing configuration page (from one of the basic widgets), like so:

// Use the property page of Result List widget
return Pages.Search;

Extending the property page is done in same fashion as extending the base widget views.

The extended property page can implement any (or both) of two properties, customNormal and customAdvanced - depending which configuration section should be extended.

Each of the two properties is an array of objects, one per defined property. The objects are expected to contain the properties 'view' and 'config', The 'config' property should contain at minimum, 'inputName' and 'infoText', plus can define additional options, some global (available for all properties), some available for selected properties only.

• view
  • Specifies the type of property and is represented in the type of property view used. The properties available are exposed under the globally scoped 'Property' object:
    • Property.Bool
      • Defines a checkbox.
      • Serializes to a boolean model property type.
    • Property.Color
      • Defines a colorpicker.
      • Serializes to a string model property type containing the color hashcode.
    • Property.DateFormat
      • Defines a control allowing to customize the format of a data.
      • Serializes to a string model property containing the date formatting string.
    • Property.Dictionary
      • Defines a dynamic key/value pair picker control.
      • Serializes to an object model property containing the chosen values.
    • Property.Facet
      • Defines a multi-facet selector control, which allows selecting one of the facets defined in the system.
      • Serializes to an array of strings model property, corresponding to the names of facets chosen.
      • Property specific options:
        • min
          • Defines how many facets minimum should the property allow to configure and serialize under one model property.
        • max
          • Defines how many facets maximum should the property allow to configure and serialize under one model property.
        • colorPicker
          • Whether the control should allow choosing a color for each facet, by integrating a colorpicker control.
        • typeRestriction
          • Restricts type of facets which should appear in the control.
        • aggregate
          • Whether to provide aggregation options for the facet.
        • aggregateFunctions
          • Which mathematical functions to allow aggregation over. By default, min, max, sum and avg (average) are exposed.
    • Property.Language
      • Defines a language control, which allows selecting a language from all languages list.
      • Serializes to a string model property containing the language identifier.
    • Property.MultilineText
      • Defines a multiline text input control.
      • Serializes to a string model property containing the text.
      • Property specific options:
        • maxLines
          • Defines how many lines of text should the control allow.
    • Property.Multiselect
      • Defines a radio control.
      • Serializes to a string model property containing the selected value.
      • Property specific options:
        • options
          • Defines the options for the radio control
          • Is an array of objects, each containing at least string properties label and value, as well as optionally boolean property default.
    • Property.Number
      • Defines a number input control.
      • Serializes to an integer model property containing the selected number.
      • Property specific options:
        • min
          • Defines the minimum number that can be selected
        • max
          • Defines the maximum number that can be selected
    • Property.Percentage
      • Defines a percentage slider control.
      • Serializes to an integer model property containing the selected percentage.
    • Property.Text
      • Defines a singleline text input control.
      • Serializes to a string model property containing contaning the text.
    • Property specific options:maxLinesDefines how many lines of text should the control allow.Trend
      • Defines a trend entity picker control.
      • Serializes to a string containing the trend entity id.
    • Property.MultiselectURL
      • Defines a radio URL input control.
      • Serializes to a string model property containing the selected valueURL.
      • Property specific options:
        • optionshideDocs
          • Defines Hides the options for the radio control
          • Is an array of objects, each containing at least string properties label and value, as well as optionally boolean property default.
    • Property.Number
      • Defines a number input control.
      • Serializes to an integer model property containing the selected number.
      • Property specific options:
        • min
          • Defines the minimum number that can be selected
        • max
          • Defines the maximum number that can be selected
    • Property.Percentage
      • Defines a percentage slider control.
      • Serializes to an integer model property containing the selected percentage.
    • Property.Text
      • Defines a singleline text input control.
      • Serializes to a string model property contaning the text.
    • Property.Trend
      • Defines a trend entity picker control.
      • Serializes to a string containing the trend entity id.
    • Property.URL
      • Defines a URL input control.
      • Serializes to a string containing the URL.
      • Property specific options:
        • hideDocs
          • Hides the section explaning the usage of URLs within Squirro widgets
• inputName
  • Specifies the name of model property to which the value should be serialized.
  • Can be accessed in the custom widget code by this.model.get(inputName).
• infoText
  • Specifies the information text (title) that is displayed just above the property, providing additional instructions or description of the parameter to the user.

Additional options all properties support:

• defaultValue
  • Specifies the default value the property should use (for example when widget has been freshly added to the dashboard and thus not configured yet).
  • Value type depending on the property type.
• denyValidate
  • Allows to skip validation on fields. By default basic form validation is performed, depending on the property type.

// Use the base (empty) property page and extend it with new fields
return Pages.Base.extend({
	customNormal: [
		{
			view: Properties.Number,
			config: {
				inputName: 'myNumber',
				infoText: 'Select a number from 3 to 7',
				min: 3,
				max: 7,
				defaultValue: 5,
			},
		},
	],
});

Utils

queryParam

A utility for handling query string parameters.

facetParser

...

• • • • • • section explaning the usage of URLs within Squirro widgets
• inputName
  • Specifies the name of model property to which the value should be serialized.
  • Can be accessed in the custom widget code by this.model.get(inputName).
• infoText
  • Specifies the information text (title) that is displayed just above the property, providing additional instructions or description of the parameter to the user.

Additional options all properties support:

• defaultValue
  • Specifies the default value the property should use (for example when widget has been freshly added to the dashboard and thus not configured yet).
  • Value type depending on the property type.
• denyValidate
  • Allows to skip validation on fields. By default basic form validation is performed, depending on the property type.

// Use the base (empty) property page and extend it with new fields
return Pages.Base.extend({
	customNormal: [
		{
			view: Properties.Number,
			config: {
				inputName: 'myNumber',
				infoText: 'Select a number from 3 to 7',
				min: 3,
				max: 7,
				defaultValue: 5,
			},
		},
	],
});

Utils

queryParam

A utility for handling query string parameters.

parse()

Utils.queryParam.parse(/* no arguments */)

Returns a hash of all the query string parameters in the current URL.

var params = Utils.queryParam.parse();
// returns a hash of parameters, example:
// {"q": "Apple"}
console.log(params.q);

facetParser

A utility for parsing arbitrary query strings into key/value facet/value pairs.

Factories

Factories expose an additional level of control over the internal Squirro objects. They can be used to mock, and create arbitrary data collections.

Collections

Items

Creates a Squirro Items collection.

Factories.Collections.Items.create(search, project)

getCollection: function () {
	return Factories.Collections.Items.create(this.options.search, this.options.project)
},

Facets

Creates a Squirro Facets collection.

Factories.Collections.Items.create(search, project, options)

getCollection: function () {
	return Factories.Collections.Facets.create(this.options.search, this.options.project, {
		facet_fields: [ 'custom_facet' ], // custom facets to fetch
		nof_facets: 100, // maximum number of facet values returned
		itemsCollection: Factories.Collections.Items.create(this.options.search, this.options.project), // associate (optionally) a custom Items collection
	});
},

MockItems

Creates a Squirro Items collection. It is possible to throw a JSON object with mocked items at it, to be used as an alternative data source to Squirro backend.

Factories.Collections.MockItems.create(search, project, items)

return Widgets.Search.extend({
    _feedItems: function () {
        return [{
            'created_at': '2016-10-17T11:02:11',
            'title': 'Custom Title',
            'abstract': 'Custom Abstract',
        }];
    },
    getCollection: function () {
        return Factories.Collections.MockItems.create(this.options.search, this.options.project, this._feedItems());
    },
});