Embed Visualizations in Web Pages

You can embed your visualizations in a web page.

JavaScript Source and API Attributes to Embed in Your HTML Page

You must include a reference to the embedding.js JavaScript source file in your HTML page.

You must place the embedding.js file in the HEAD section of the HTML page but before the <oracle-dv> tag.

For example, <script src="http://<dv-server-name>:<dv-server-port>/dv/ui/api/v1/plugins/embedding/<embedding-mode>/embedding.js" type="text/javascript"></script>

The value that you use for embedding-mode must be either jet or standalone. You use "jet" when embedding Oracle Analytics content within an existing Oracle JET application, and you use "standalone" where you embed visualization content in a generic application that doesn’t use Oracle JET. Also if you use "jet", the version of Oracle JET that’s used by the application must match the version of Oracle JET used by Oracle Analytics.

Oracle JET is a set of Javascript-based libraries used for the Oracle Analytics Cloud user interface. See http://www.oracle.com/technetwork/developer-tools/jet/overview/index.html.

Single Sign-on (SSO) must be enabled between the embedding page and the server. Before you can embed an object in an external web page, you must have an authenticated session into Oracle Analytics Cloud. The best way to achieve this is to use the same SSO between the external application and Oracle Analytics Cloud. When a user connects to the external application they use SSO to authenticate into Oracle Analytics Cloud.

You must add the following snippet with appropriate attribute values in your web page where you want to embed the visualization:

<oracle-dv project-path="" project-json="" active-page="" active-tab-id="" filters=""></oracle—dv>

Supported attributes — These attributes support static strings and properties defined within a Knockout model (Knockout is a technology used in Oracle JET).
  • project-path: If you’ve saved the project, then you can specify the path in the repository to the project that you want to render.

  • project-json: If you’ve a project in the JSON format in Oracle Analytics, you can enter it here. You must specify either project-path or project-json.

  • active-page: This is optional. You use this attribute if a canvas or insight other than the default is rendered. When you specify active-page, you also use active-tab-id to specify the exact canvas or story page that you’re showing. Valid values are canvas and insight.

  • active-tab-id: This is optional. You use this attribute to specify the id of the canvas or the story page that you’re showing.

  • filters: This is optional.

See Embed Visualizations in Web Pages When the Embedding Application Doesn’t Use Oracle JET for an example of binding these attributes to a Knockout model.

Pass Filters to Embed in Your HTML Page

Embedding supports Numeric filters and List filters. Using any one of these, any type of data can be filtered.

The filters payload is a Javascript array containing one filter Javascript object per array item.

Rendering a project while applying filters looks like this:

<oracle-dv project-path="{{projectPath}}" filters="{{filters}}">
</oracle-dv>
 
<script> 
requirejs(['knockout', 'ojs/ojcore', 'ojs/ojknockout', 'ojs/ojcomposite', 'jet-composites/oracle-dv/loader'], function(ko) {
   function MyProject() {
      var self = this;
      self.projectPath =  ko.observable("/users/weblogic/EmbeddingStory");
      self.filters = ko.observableArray([{
         "sColFormula": "\"A - Sample Sales\".\"Products\".\"P2  Product Type\"",
         "sColName": "P2  Product Type",
         "sOperator": "in", /* One of in, notIn, between, less, lessOrEqual, greater, greaterOrequal */
         "isNumericCol": false,
         "bIsDoubleColumn": false,
         "aCodeValues": [],
         "aDisplayValues": ['Audio', 'Camera', 'LCD']
      },{
         "sColFormula": "\"A - Sample Sales\".\"Base Facts\".\"1- Revenue\"",
         "sColName": "Rev",
         "sOperator": "between", /* One of in, notIn, between, less, lessOrEqual, greater, greaterOrequal */
         "isNumericCol": true,
         "bIsDoubleColumn": false,
         "aCodeValues": [],
         "aDisplayValues": [0, 2400000] /* Because the operator is "between", this results in values between 0 and 2400000 *
/
  }]);
}
   ko.applyBindings(MyProject);
});
</script>
Filter supported attributes — Each filter object within the filters payload must contain the following attributes:
  • sColFormula: The three part column formula of the column you want to filter. This must be three parts. If you don't know what this is, create a project within Data Visualization using the column, then go to the Debug menu item and look up the column formula there.

  • sColName: A unique name for this column. This must not be empty.

  • sOperator: One of in, notIn, between, less, lessOrEqual, greater, greaterOrequalin and notIn apply to list filters. between, less, lessOrEqual, greater, andgreaterOrEqual apply to numeric filters

  • isNumericCol: Whether or not this is a numeric filter or a list filter. Values should betrue or false.

  • bIsDoubleColumn: Whether or not this column has double column values behind the display values.   Values should be true or false.

  • aCodeValues: When bIsDoubleColumn is true, this array is used.

  • aDisplayValues: When bIsDoubleColumn is false, this array is used to filter and to display values within the user interface. When bIsDoubleColumn is true, the values in this array are used for display in the user interface while the values in aCodeValues are used for filtering. When bIsDoubleColumn is true, there must be the same number of entries in this array as there are in the aCodeValues array, and the values must line up.  That is, if aCodeValues has two values, '1', and '2', then aDisplayValues must have two values 'a', and 'b', where '1' is the code value for 'a', and '2' is the code value for 'b'.

Refresh Data in Embedded HTML Pages

When you embed content in a project, that project likely accesses an underlying data set whose data may change so the project needs refreshing. You can configure the refresh of data embedded in an HTML page in a project.

Every embedded project (defined with the <oracle-dv> element) provides a refreshData method that you can invoke when the data shown in the embedded project should be refreshed.

The code to refresh data for a single project embedded in an HTML page looks like this:

<oracle-dv id="project1" project-path="{{projectPath}}">
</oracle-dv>
 
<script> 
   function refreshProject() {
      $('#project1')
  [0].refreshData();
}
</script>

The code to refresh data for multiple projects embedded in an HTML page looks like this:


<script> 
   function refreshProject()
   {
      $('oracle-dv').each(function() {
         this.refreshData();
         });
}
</script>

Any data changes that you refresh in a project are reflected in the embedded HTML page when you invoke the method to refresh the data.

Find the Javascript and HTML to Embed a Specific Visualization Project

The Javascript and canvas HTML that embeds a project in an external web page is automatically generated and exposed through the Embed tab when editing the project. You can copy and paste this code to your external web page to embed the data visualization content.

  1. Display a project.
  2. Click Developer in the project Menu.
  3. Display the Embed page.
  4. Click Copy to copy the code for each Embedding Script, Project HTML, or Canvas HTML that you want to embed.
The following sections are displayed on the Embed page:
  • Embedding Script To Include — Script to embed for this instance.
  • Default — HTML to embed for the current project.
  • Canvas "<Name_of_Canvas>" — HTML to embed one or more specific canvases of the current project - For example, Canvas "C1 Polygon", Canvas "C2 Cluster", and so on for each canvas that you want to embed from the current project.