Version 0.9

Skip to end of metadata
Go to start of metadata

Sisense.js is a JavaScript library that enables you to embed Sisense components in web pages without the use of iFrames.

By embedding the SisenseJS library into your webpage, you can:

  • Load Sisense runtime anywhere, without iFrames

  • Load dashboards dashboards in runtime

  • Render all/part/new widgets in any DOM container

This page describes the SisenseJS library’s functionality and how you can leverage it to embed widgets into your site or application.

Limitations

SisenseJS includes the following limitations: 

  • Sisense.js overrides the "Date" prototype with the "toISOString" function.

Dependencies

SisenseJS has the following dependencies 

  • Highcharts
  • D3
  • JQuery

Overview

A widget is a dynamic visualization of your data with its own unique ID. Through the SisenseJS library, you define which widgets appear in the dashboard. In Sisense, a dashboard is a collection of one or more widgets that visualize the data that you select and design. However, in SisenseJS, the dashboard represents a JavaScript object that you can embed into your site or application.

The dashboard object is a container for widget objects. As a container of dashboards, and not a dashboard itself, it provides you with more flexibility by allowing you to add existing widgets from various dashboards to the dashboard object you embed on your site. After including the SisenseJS library into your site or application, you embed dashboard objects and populate those objects with your widgets.

Prerequisites

CORS

As the application in which you are embedding Sisense elements most likely resides on a different domain than where Sisense is installed, you must enable CORS (Cross-Origin Resource Sharing) to access the JavaScript resources needed.

To enable CORS

  1. From the Sisense REST API, send a POST request to the settings/system API.


  2. In the CORS object, set enabled to true

  3. In the allowedOrigins array, enter every domain from which you might make a request to Sisense. 

    Enabling all origins  Expand source
  4. Click Run


Read more about the settings API here | Read more about CORS here

Including the Sisense.js Library

You must include the sisense.js runtime file in your page as defined below where  localhost  should be your Sisense installation's URL and port.

AngularJS Support in SisenseJS

In Sisense version 6.4 and later, Sisense.js supports Angular 2.x.

In Sisense version 6.5 and later, Sisense.js supports Angular 1.x and 2.x.

Angular 2.x heavily emphasizes loading templates asynchronously, which means some HTML content is loaded until later on. For Sisense.js to work, this HTML content should be loaded prior to connecting to the Sisense server through the sisense.connect function.

Sisense.js bootstraps a div element with the ID "sisenseApp"  to ensure the sisenseApp element and other container elements are loaded before using the sisense.connect function.

 

Encapsulation

 

Connecting to Sisense

After you have included the Sisense.js library in your site, you must connect to Sisense.

The connect(url) method is a static method of the Sisense.js library that takes the URL of your dashboard as an argument.

The then() method returns the app object as a promise. The app objects contains your dashboards and defines how your widgets are embedded.

Embedding Dashboards

There are two ways to embed dashboards through the SisenseJS library. You can create an empty dashboard object in which you add existing widgets to the dashboard object. The second way is to embed an existing dashboard where you retrieve the existing dashboard with its filters and embed them into the page.

Retrieving Dashboard and Widget IDs

Regardless of how you embed your dashboard, you will need to provide the IDs of dashboards and widgets. These IDs are visible in the URL when you are viewing a dashboard or widget.

To view the full URL structure, open the relevant widget in Edit mode:

http://localhost/app/main#/dashboards/ {dashboard_id} /widgets/ {widget_id}

Example:

http://localhost/app/main#/dashboards/ 574eb8cd92be9b504b000006 /widgets/ 574eb8d892be9b504b000009

Creating a New Dashboard

To create a new dashboard, you construct a dashboard object, which is an empty container for widgets. After constructing the dashboard object, you can load existing widgets that you have defined in the Sisense Web Application to your new dashboard.

You can create an empty dashboard object through the Dashboard() object constructor:

To embed the new dashboard object, add it to your site through the add() method:

Once you have added your dashboard to the site, you can add existing widgets to the dashboard object using the load() method:

When you have added all your widgets to the dashboard object, you need to render it to display the widgets in your site through the refresh() method:

Embedding an Existing Dashboard

If you already have an existing dashboard and you want to embed it, you can load the existing dashboard through the load() method. The load() method takes the dashboard ID as an argument.

After loading the dashboard, all of your existing widgets are loaded into memory. You can use the get() method to retrieve and display the widget.

For each widget, you must have a div element with an ID, for example, "widget1" in your page. This DIV that contains your widget must have the height, width, and position defined for the widget to render correctly.  

You can also use libraries like jQuery to make DOM manipulation and querying easier.

If you want to add widgets that are not associated with the existing dashboard, you can load the widgets from the server through the load() method.

When you have added all your widgets to the dashboard object, you need to render it to display the widgets in your site through the refresh() method:

Adding Filters

After you have loaded a dashboard, you can load its filters through the renderFilters() method.

Note : A dashboard object can only contain filters if it's datasource property is set. When loading existing dashboards, they are always loaded with a datasource. When creating a new object, you must set it yourself.

SSO and SisenseJS

When embedding Sisense.JS into your site, you should implement Single Sign On. Sisense implements SSO by redirecting users to a script/application that creates a login token for the user, and redirects them back to the destination or resource they were trying to access. If the resource requested is a dashboard, that's where the user will be redirected back to.  For Sisense.JS the resource requested will be a JavaScript file, so you need to ensure the redirect takes you back to this file.  When Sisense redirects your customers to your login script, Sisense passes a return_to parameter in the URL. This parameter defines the page that Sisense redirects your customer after authenticating them. For example:

  1. A customer visits your site opens a dashboard embedded through an iFrame.

  2. Sisense recognizes that the user is not authenticated.

  3. Sisense redirects the user to:

 

All your script needs to do, is take the return_to value from the invoked URL and pass it back to Sisense when submitting the JWT token. In other words, upon authentication on your side, your script redirects the user to:

For more information regarding SSO and Sisense, click here.

SisenseJS Reference

Application

Properties

Property

Type

Description

serverUrl

String

Contains the full URL for the Sisense instance.

dashboards

Object

Entry point for accessing Sisense dashboards, representing a collection of the dashboard objects currently loaded to memory.

Contains the following methods :

Method

Arguments

Returns

Description

add()

  

Adds the dashboard object to an enumerable collection on the page which can be then retrieved by numerical index using get().

get(idx)

Idx : An int value that represents the index of a dashboard to get from the collection.

 

Gets a dashboard object that was already loaded into memory (using either add() or load()).

load(dashboard_id)

dashboard_id: A string value that is the ID of the dashboard to be loaded.

Promise

Loads an existing dashboard by Id.


Dashboard

Properties

Property

Type

Description

datasource

Object

Contains an object representing the dashboard's data source.

id

String

Contains the full dashboard ID.

refreshing

Boolean

True when the dashboard is currently refreshing, or false when it is not.

widgets

Object

Entry point for accessing a dashboard's widgets, representing a collection of the widget objects currently loaded to memory for a given dashboard object.

Contains the following methods:

Method

Arguments

Returns

Description

get()

oid : String value that is the ID of the widget to get from the collection.

 

Gets a widget object that was already loaded into memory (using either add() or load()).

load(dashboard_id)

dashboard_id : A string value that is the ID of the dashboard to be loaded.

Promise

Loads an existing dashboard by ID.

Methods

Method

Arguments

Returns

Description

on( event, callback )

event: A string value of the event name.

callback: The callback function to execute when the event is triggered.

 

R egisters dashboard events. For more information, see the D ashboard API reference.

refresh()

  

Refreshes the dashboard updating all embedded widgets.

renderFilter(element)

element : The DOM element that acts as a container for rendering the filters panel.

 

Renders the dashboard's filters panel for the element provided.

Widget

Properties

Property

Type

Description

metadata

Object

Contains an object representing the widget's metadata.

type

String

Contains the widget's primary type.

subtype

String

Contains the widget's sub-type.

affectDashboardFilters

Boolean

Contains true if the widget is a selector (clicking it will create a filter), false otherwise.

refreshing

Boolean

Contains true if widget is currently refreshing, false otherwise.

container

DOM Element

Contains the DOM element where the widget is rendered.

id

String

Contains the widget's ID.

queryResult

Object

Contains the data returned for the widget's query from Sisense.

title

String

Contains the widget's title.

Methods

Method

Arguments

Returns

Description

on()

event : A string value of the event name.

callback : The callback function to execute when the event is triggered.

 

Registers any widget events. For more information, see the W idget API reference.

refresh()

  

Refreshes the widget.

  • No labels