Skip to main content
Pentaho Documentation

Introduction to Analyzer JavaScript APIs

Overview

We have exposed a new set of APIs to give OEMs more control over Analyzer when working in an embedded fashion. These APIs allow for more fine-grained interaction with the Analyzer viewer, reports, and data.

How to Access the APIs

You can access the APIs using several methods.

Analyzer within Pentaho User Console (Embedded in an iFrame with the Same Domain)

While using Analyzer inside of PUC, you can execute your custom API code in two ways:  placing the code directly in the parent frame or by including the code within an external resource file.

Within Parent Frame

Inside of the parent html file, add the following script block. It will be executed for each Analyzer report that is either opened or created when Analyzer is initialized.

<script type="text/javascript">
  window.onAnalyzerReady = function(api, frameId) {
      // Perform Analyzer API actions
  };
</script>

Since the onAnalyzerReady code is executed when Analyzer is initialized, api.event.registerInitListener is not available from within this code block.

As External Resource

Additionally, you can achieve the same result by including your custom javascript as an external resource. The only difference is that you do not have to use the "onAnalyzerReady" function since Analyzer is already loading this file at the appropriate time. Inside of your own plugin.xml file, add a path to your custom javascript file, which will be executed when Analyzer is loading:

 <file context="analyzer">path/to/your/javascript/ExternalFile.js</file>

See Create a Pentaho BA Server Plug-in for more details about creating your own plugin.xml file.

The same code that is in the first javascript block is the same, but without using the "onAnalyzerReady" function. Instead, you will require the API using RequireJS

require([ "analyzer/cv_api" ], function(api) {
  api.event.registerInitListener(function(e, cv) {
    // Perform Analyzer API actions
  });
});

Analyzer Embedded in an iFrame on a Different Domain

The APIs are exposed in the global scope of each Analyzer iFrame. The Analyzer iFrame looks for an onAnalyzerReady function attached to the parent window. Due to cross-site scripting issues, you must configure the iFrame in which Analyzer is embedded. You can do this by adding an external resource file to any plugin's plugin.xml file. It is common to use the default-plugin for adding such scripts. It is is located in pentaho-solutions/system/default-plugin/.

Inside of the plugin.xml file, you will add a path to your own javascript file which will be executed when Analyzer is loading.

Plugin.xml:

<file context="analyzer">path/to/your/global/javascript/GlobalFile.js</file>

Inside of your external javascript file, you must set a custom domain property on the window of the Analyzer iFrame.

ExternalFile.js:

// iFrame source = "http://example.company.org:8080/pentaho/api/repos/xanalyzer/editor"
window.customDomain = "company.org";

Additionally, you must set the document.domain inside of the parent page or frame where you will be embedding Analyzer. When you are embedding the Analyzer iFrame into your page, you can bind an onAnalyzerReady function to the window. Analyzer will automatically look for this function and execute the function once the API has been loaded and made available.

www.company.org/index.html:

 <html>
  <head>
    <script type="text/javascript">
	  document.domain = "company.org"

      window.onAnalyzerReady = function(api, frameId) {
        // Perform Analyzer API actions
      };
    </script>
  </head>

  <body>
    <iframe id="analyzer-frame" src="http://example.company.org:8080/pentaho/api/repos/xanalyzer/editor"></iframe>
  </body>
</html>

When Analyzer loads, you will have access to the API and the frameId of which frame is calling your code, so that you can customize each frame appropriately. Analyzer executes the onAnalyzerReady code for each frame located in the page, therefore, the frameId will be different for each frame, and the API you receive will be related to that frame. 

window.onAnalyzerReady = function(api, frameId) {
  // Perform Analyzer API actions
};

Example:

//Example calls into namespaced functions
api.report.setLayoutFields("test”);
api.report.getLayoutFields();

Direct URL

To access the API when Analyzer is loaded directly by its URL, you will need to use the "As External Resource" approach, seen above.