JavaScript SDK

Introduction

This SDK allows to integrate Squirro into any web enabled framework, and works especially well with modern development libraries like React.js. It allows embedding Squirro dashboards, both in desktop and mobile environments.

Prerequisites

a Squirro instance, to serve the dashboards and data
a JavaScript application, framework agnostic

How does it work

The SDK exposes a jQuery extension, which can be used to load dashboards. Sample usage basically falls down to calling the jQuery method, passing options containing the Squirro instance URL, the project and dashboard ids, and authentication. The last is done either via Squirro token, or over SSO. Additional setup is required to set up the SSO component.

import 'squirro-sdk.en.js'
import 'squirro-sdk-styles.en.js'

...

// $domElement is a jQuery element
$domElement.squirro({
    server: '',
    project_id: '',
    dashboard_id: '',
    tenant: '', // Required if non-SSO authentication
    userId: '', // Required if non-SSO authentication
    token: '',  // Required if non-SSO authentication
});

Dependencies

jQuery

Squirro SDK comes prebundled with jQuery, which can potentially cause conflicts if a much different version of jQuery is used already in the embedding environment. Such conflicts are however rare, and it is planned to support conditional loading of jQuery in the future.

Highcharts

Squirro requires Highcharts 6.1 to be loaded separately, if Highcharts based widgets are to be functional. The package is obtainable easily via a number of public repositories, but it can also be loaded locally.

<script src="https://code.highcharts.com/6.1/highcharts.js"></script>
<script src="https://code.highcharts.com/6.1/highcharts-more.js"></script>
<script src="https://code.highcharts.com/6.1/modules/stock.js"></script>
<script src="https://code.highcharts.com/6.1/modules/heatmap.js"></script>
<script src="https://code.highcharts.com/6.1/modules/tilemap.js"></script>
<script src="https://code.highcharts.com/6.1/modules/wordcloud.js"></script>

D3

Squirro requies D3 5.0 to be loaded sepately, if D3 based widgets are to be functional. The package is obtainable easily via a number of public repositories, but it can also be loaded locally.

 <script src="https://cdnjs.cloudflare.com/ajax/libs/d3/5.0.0/d3.min.js"></script>

Fonts and icons

Squirro requires Google’s Material Icons set to be loaded, as well as the Roboto font. The package is obtainable easily via a number of public repositories, but it can also be loaded locally.

  <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
  <link href="https://fonts.googleapis.com/css?family=Roboto" rel="stylesheet">

Deployment

Squirro SDK is available on npm package manager, under @squirro/sdk

Frameworks

React

Squirro SDK integrates well into the React framework. On top of being available on npm, which is what React uses as well, it plays well with React component state, and integrating jQuery extensions into React is a well known and tested technique. Consider the example below for a sample of the bidirectional communication achievable with this close form of integration.

React Integration Example

/*global $*/
import React, { Component } from 'react'
import 'squirro-sdk.en.js'
import 'squirro-sdk-styles.en.js'

class App extends Component {
    constructor(props) {
        super(props);

        this.state = {
            squirroSearch: {},
            squirroStore: {},
        };
    }

    componentDidMount() {
        this._reloadSquirro();
    }

    _reloadSquirro() {
        this._initSquirro().then(() => {
            this._attachEvents();
        });
    }

    _initSquirro() {
        return $(this.el).squirro({
            server: '',
            project_id: '',
            dashboard_id: '',
            tenant: '',
            userId: '',
            token: '',
        });
    }

    _logout() {
        $(this.el).squirro('destroy').then(() => {
            console.log('Squirro destroyed');
        });
    }

    _attachEvents() {
        const search = this._getSquirroSearch();
        search.on('change:query change:time', () => this.setState({ squirroSearch: search.toJSON() }));

        const store = this._getSquirroDashboard().store;
        store.on('change', () => this.setState({ squirroStore: store.toJSON() }));
    }

    _select(section) {
        const search = this._getSquirroSearch();
        search.removeFacet('Section', 'World');
        search.removeFacet('Section', 'Sports');
        search.addFacet('Section', section);
    }

    _getSquirroSearch() {
        return $(this.el).squirro('get_search');
    }

    _getSquirroDashboard() {
        return $(this.el).squirro('get_dashboard');
    }

    render() {
        return (
            <div className="App squirro-body">
                <h3 className="App-header">
                    Squirro React SPA Integration
                </h3>
                <div className="Left-panel">
                    <h3>React Panel</h3>
                    <ul>
                        <li>Squirro Query: {this.state.squirroSearch.query}</li>
                        <li>Created Before: {this.state.squirroSearch.created_before}</li>
                        <li>Created After: {this.state.squirroSearch.created_after}</li>
                        <li>Squirro Store: {JSON.stringify(this.state.squirroStore)}</li>
                    </ul>
                    <ul>
                        <li onClick={this._select.bind(this, 'World')}>World</li>
                        <li onClick={this._select.bind(this, 'Sports')}>Sports</li>
                    </ul>
                    <ul>
                        <li onClick={this._reloadSquirro.bind(this)}>Reload Squirro</li>
                        <li onClick={this._logout.bind(this)}>Logout</li>
                    </ul>
                </div>
                <div className="Squirro-main" ref={el => this.el = el}/>
                <h3 className="App-header">
                    Squirro React SPA Integration
                </h3>
            </div>
        );
    }
}

export default App;

Compatibility / Notes

Webpack version family 2.x and below is no longer supported since Squirro 3.0. Webpack 4.x is recommended.