Page History

...

The JavaScript API (JS API) is a tool that allows third party developers to embed and manipulate Yellowfin content. Generally when someone refers to the JS API they are referring to the embedding functionality. 

The JavaScript bundling changes made in Yellowfin 9, when we introduced Dashboards, allowed us to create a means to more easily use the same code for internal and external JavaScript objects. The JS API is made up of a lot of parts. There are two broad API types that objects fall into when talking about the JS API — Loading APIs and Content APIs. 

...

Internal vs external JS API

What does this mean?

...

When using the term “Internal JS API” this refers to the tools used by

...

a developer who is logged into Yellowfin, using Yellowfin code mode

...

, a custom header or JavaScript Charts. 

The term “External JS API” is used to reference refers to the tools used by a developer embedding Yellowfin content into an external page.  

There are effectively two Yellowfin JS APIs. 

The external JS API is our offering for developers who embed Yellowfin content into an external page. We provide details of the external JS API on our external wiki. 

The internal JS API is used by the Yellowfin development team. Third-party developers unknowingly use this version of the JS API when accessing code via Yellowfin code mode or a custom header. 

Both JS APIs are explained in more detail below.

External JS API

Prior to Yellowfin 9.7, the two APIs provided different toolsets. From Yellowfin 9.7 on, most of the JS API functionality is available to users who are logged into Yellowfin. 

Both JS APIs  give When using the JS API externally it gives you access to all of the Yellowfin Loading APIs and Content APIs . Which means so you can load any piece of content you wish, provided you know the content’s UUID. 

In most cases, you can create a report or dashboard listing service can be created using Yellowfin webservices to fetch YF Yellowfin content objects, and then use the UUIDs provided from those objects to load the object in the JS API. This makes it possible to build a completely custom UI while using Yellowfin reports, dashboards, stories and stories Guided NLQ within them, so the content building can be done by non-developers.  

Considerations

Authentication can sometimes be problematic because the Yellowfin server is treated as a third-party application. Browsers that reject third-party cookies on a site therefore reject the Yellowfin JS API (Safari and Chrome in Incognito mode). In addition, security changes around the “Same Site” Flag makes it difficult to configure a web server to accept all the cookies that are required. 

The other issue is differences in how functionality works. The following table provides a list of features that work differently or are not yet enabled within the external JS API.

...

Functionality

...

Internal JS API behaviour

...

External JS API behaviour

...

Dashboard & Presentation toolbars

...

Create broadcast.

...

–

...

Dashboard & Presentation toolbars

...

Share and see users who have favourited content in the toolbar which appears in the top right of these pieces of content).

...

–

...

Report drill through (when not using the drill through pop up)

...

Drill through will redirect the user to the report output page.

...

Drill through will simply replace the parent report with the child report.

...

Open report from dashboard 

...

It’s possible to open a report from an embedded dashboard.

...

–

...

Embed signal widgets on dashboard

...

Signal widgets can be embedded — with links that work.

...

Signal widgets can be embedded, but any links within them won’t work.

...

Embed story widgets on dashboard API

...

Story widgets can be embedded — with links that work.

...

Story widgets can be embedded, but any links within them won’t work.

In addition, only the External JS API provides the following functions: 

• logoff()
• newSession() 
• init()

Note that the Internal JS API does not require init() because it can be fully loaded when a Yellowfin page loads.

How do I access the internal JS API?

When loading a page within the Yellowfin Application, a JsAPI object is added to the page’s window object. Developers can then access this using Custom Headers, Code Mode or JavaScript Charts. 

For example:

window.JsAPI
//Or Simply
JsAPI

This can be then used to load other content.

Load a report

Load Report options can be found on the Advanced API wiki page.

JsAPI.loadReport({
     reportUUID: 'the-uuid-to-load',
     element: document.querySelector('#myInternalReport')
});

Load a dashboard 

Options for loadDashboard can be found on the Advanced API wiki page.

JsAPI.loadDashboard({
     dashboardUUID: 'dashboard-uuid-to-load',
     element: document.querySelector('#myInternalDashboard')
});

Load a Story

Options for loadStory can be found on the Advanced API wiki page. 

JsAPI.loadStory({
    storyUUID: 'story-uuid-to-load',
    Element: document.querySelector('#myInternalStory')
});

Load Guided NLQ

Options for loadNLQ can be found on the Advanced API wiki page. 

JsAPI.loadNLQ();

OR

JsAPI.loadNLQ({
element: document.querySelector('#myNLQContainer')
});

...

Examples

Example 1: slide-out dashboards

Below is an example for loading a dashboard when a button is clicked on the dashboard.

HTML

<canvas-area xmlns="http://www.w3.org/1999/xhtml" canvas-uuid="e3db80a5-5f8f-4ae9-887d-f26ed1fecc2d">
    <text-title publish-uuid="906b4057-e4c6-4913-8624-84c2f6596c26" width="959" height="141" left="25" top="9" line-spacing="normal" character-spacing="0" rotation="0" name="Title" on-click="none" style="z-index: 2;"><div>Example Dashboard that demonstrates opening the Sales Performance Dashboard in a slide out</div></text-title>
    <canvas-button publish-uuid="9c97e800-3dbb-477a-9cc4-398194ab6888" width="222" height="102" top="150" left="35" plugin-name="com.hof.mi.widgetcanvas.widgettemplate.CodeButtonTemplate" text-color="#333740" name="DashboardButton" on-click="none" style="background-color: rgb(219, 221, 229); border-radius: 0px; border: 2px solid rgb(219, 221, 229); z-index: 2; opacity: 1.0;"></canvas-button>
</canvas-area>

CSS

* div.embeddedDashboard {
    width:600px;
    height:100%;
    position:fixed;
    top:0;
    right:0;
    overflow:auto;
    background:white;
    padding-top:50px;
    z-index:100;
}

* div.embeddedDashboard div.closeIcon {
    position:absolute;
    right:0;
    top:0;
    width:50px;
    height:50px;
    z-index:10000;
    background-image: url('images/close_popup_grey.svg');
    background-repeat: no-repeat;
    background-position: center;
    cursor:pointer;
}

JavaScript

let canvas = this.apis.canvas;

//In this example the dashboard is Sales Performance, this can be changed to whatever dashboard is required.
let Dashboard_To_Load = 'e7409ff2-f846-44e1-a603-b78ec51b20b9';


this.onRender = function () {
    //Get the Canvas Button from the Page.
    let button = canvas.select('DashboardButton');
   
    //Add an event listener so when it is clicked, we can display the Dashboard_To_Load
    $(button).on('click', () => {
       
        //Create a Dashboard Element
        let $dash = $('<div/>').addClass('embeddedDashboard');
       
        let $closeIcon = $('<div/>').addClass('closeIcon');
        $dash.append($closeIcon);
        $closeIcon.on('click.closeDashboard', function() {
            $dash.remove();
            $closeIcon.off('closeDashboard');
        });
        $('body').append($dash);
       
        JsAPI.loadDashboard({
            element: $dash[0],
            dashboardUUID: Dashboard_To_Load
        });
    });
};

/**
* Called when the canvas and all its child elements are removed from the page.
*/
this.onRemove = function () {
    // Insert your code here. This is an ideal place for removing event listeners
};

Internal JS API

The Yellowfin JS API currently has no access to any of the Loading APIs that are present within the external JS API. This means that for any piece of content to be loaded it must be done via a Yellowfin action. Which means that third-party developers don’t have as much control over how they could display reports or other content. As it all needs to be loaded (and in most cases) rendered, by Yellowfin first. 

All Yellowfin content and its individual features are generally available to the Content APIs and the content being rendered internally. As the way we generally build the functionality internally first, and then attempt to get it to work externally. 

Considerations

Content APIs are only available via Code Mode. There are no loading APIs. 

This makes it challenging to create a customized app experience. Code Mode lets you customize a dashboard heavily, but you can’t load extra dashboards from within that dashboard, nor reports that haven’t been added.

...

...