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.

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. Use jet when embedding Oracle Analytics content within an existing Oracle JET application. Use standalone when embedding 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 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. The best way to achieve this is to use the same SSO between the external application and Oracle Analytics. When a user connects to the external application they use SSO to authenticate into Oracle Analytics.

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: Specifies the repository path of the project that you want to render. You must specify either project-path or project-json

  • project-json: Specifies a project in the JSON format. You must specify either project-path or project-json.

  • active-page: (Optional) Specifies whether 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: (Optional) Specifies the ID of the canvas or the story page that you’re showing.

  • filters: (Optional) Allows the programmatic passing of filter values to an embedded project. See Pass Filters to Embed in Your HTML Page.

  • project-options: (Optional) Allows you to pass these options:
    • bDisableMobileLayout: Disables or enables the mobile layout. Mobile layout refers to the summary card layout available only on phone devices. Value should be true or false.
    • bShowFilterBar: Shows or hides the filter bar. Value should be true or false.

    For example, <oracle-dv project-path="{{projectPath}}" active-page="canvas" active-tab-id="1" filters="{{filters}}" project-options='{"bDisableMobileLayout":true, "bShowFilterBar":false}'></oracle-dv>

  • brushing-type: Controls how brushing works. The value you specify overrides all other settings, including system defaults and settings in the public project JSON or saved project. Value should be the string on, off, or auto.
    • on: Use to issue brushing queries with normal priority. Brushing queries and visualization queries are mixed and run at the same time.
    • auto: Default. Use to issue brushing queries with low priority. When a user interacts with a visualization, there may be a delay showing marks in other visualizations until the brushing queries complete.

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>
Supported attributes — Each filter object within the filters payload must contain the following attributes:
  • sColFormula: Specifies the three-part formula of the column to filter. The column formula must include three parts.

    If you're unsure of the formula, create a project that uses that column, and then in the Visualize tab, go to Menu and select Developer. In the Developer page, click the JSON tab to view the column's expression. For example, sColFormula": "\"A - Sample Sales\".\"Base Facts\".\"1- Revenue\"" .

  • sColName: (Required) Specifies a unique name for this column.

  • sOperator: Use one of the following: in, notIn, between, less, lessOrEqual, greater, greaterOrequal.
    • in and notIn - Apply to list filters.
    • between, less, lessOrEqual, greater, and greaterOrEqual - Apply to numeric filters.
  • isNumericCol: Specifies if the filter is numeric or list. Use value true or false.

  • isDateCol: (Required) Indicates whether the column is a date column. Value should be true or false. Set to true if the column is a date, but not for year, month, quarter, and so on. If set to true, then specify date or dates in the aDisplayValues attribute.
  • bIsDoubleColumn: Specifies if the column has double column values behind the display values. Value should be true or false.

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

  • bHonorEmptyFilter: (Optional) Indicates whether an empty filter is honored (for example, empty aCodeValues/aDisplayValues based on the bIsDoubleColumn flag). This attribute applies to all column filters: list filters, number range filters, and date range filters. Value should be true or false.
    • If set to true and the user passes empty aCodeValues/aDisplayValues, then all values will be part of the filter.
    • If set to false and user passes empty aCodeValues/aDisplayValues, then the attribute won't be applied and there will be no change in filter values.
    • If this attribute isn't present, then the default value is false.
  • aDisplayValues: When bIsDoubleColumn is false, then this array is used to filter and to display values within the user interface.

    When bIsDoubleColumn is true, then 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. For example, suppose 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.

    If isDateCol attribute is set to true, then specify the aDisplayValues array with dates. If either no time zone in the time stamp or no time stamp is provided, then time is set with the local time zone. Use any of the following formats:

    • mm/dd/yyyy (For example, 12/31/2011.)
    • yyyy-mm-dd (For example, 2011-12-31.)
    • yyyy/mm/dd (For example, 2011/12/31.)
    • mm/dd/yyyy or yyyy/mm/dd, hh:mm:ss (For example, 12/31/2011 or 2011/12/31, 23:23:00.)

      Note: Use a 24 hour format. Separator can be a space.

    • mm/dd/yyyy or yyyy/mm/dd, hh:mm:ss AM/PM (For example, 12/31/2011 or 2011/12/31, 11:23:00 PM.)

      Note: Use a 12 hour format. Separator can be a space.

    • <3 letter month name> dd yyyy (For example, Mar 25 2015.)
    • dd <3 letter month name> yyyy (For example, 25 Mar 2015.)
    • Fri Sep 30 2011 05:30:00 GMT+0530 (India Standard Time)
    • ISO Date Format - 2011-10-05T14:48:00.000Z

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.