Skip to main content
Pentaho Documentation

Pentaho Analyzer External JavaScript API Reference

This API set gives 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 the following embedded iFrame methods:

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 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
  });
});

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's 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.

Service Calls Reference

References for the following categories of JavaScript API service calls are available:

  • Analyzer Module
    Details the methods for analyzer.AnalyzerModule, which allows for the deployment and control of Analyzer in a DOM element.
     
  • Event
    Details the methods for api.event class, which contains all necessary calls for creating and registering Events.
     
  • Operation
    Details the methods for api.operation class, which contains available operation-related API calls.
     
  • Report
    Details the methods for api.report class, which contains the available report-related API calls.
     
  • User Interface
    Details the methods for api.ui class, which contains the available user interface-related API calls.
     
  • Utility
    Details the methods for api.utility class, which contains the available utility-related API calls.