Embed Oracle Analytics Content With the JavaScript Embedding Framework

The topics in this section explain how to use the JavaScript embedding framework to embed Oracle Analytics content into applications and web pages.

Topics:

Typical Workflow to Use the JavaScript Embedding Framework

If you're using the JavaScript embedding framework to embed analytics content into an application or web page, then follow these tasks as a guide.

Note:

You can also embed analytics content using the analytic content item's URL. Typically this method uses an iFrame. See Embed Oracle Analytics Content With iFrames.

Task	Description	More Information
Add safe domains	Use the Console to register as safe the development, production, and test environments domains.	Register an Application as a Safe Domain
Create the HTML page	Create the HTML page where you'll embed analytics content. Steps include: reference the embedding.js JavaScript source and the embedded workbook's URL, specify filters, and specify how to refresh data.	Prepare the HTML Page for Embedded Oracle Analytics Content Pass Filters to the HTML Page for Embedded Oracle Analytics Content Refresh Data in the HTML Page for Embedded Oracle Analytics Content
Specify the embedding mode	Your application uses JET or another technology to embed analytics content.	Embed Oracle Analytics Content into a Custom Application that Uses Oracle JET Embed Oracle Analytics Content into a Custom Application That Doesn’t Use Oracle JET
Understand authentication	Learn about login prompt authentication and how to customize the login message that users see.	Use Login Prompt Authentication With Embedded Oracle Analytics Content

Get Started Embedding Analytics Content With the JavaScript Embedding Framework

Use the topics in this section to gather required information, perform prerequisite tasks, and begin creating the HTML page to embed analytics content into.

Note:

Before you perform the tasks in this section, confirm that you've registered the development, production, and test environments as safe domains. See Register an Application as a Safe Domain.

Topics:

Enable Oracle Analytics Developer Options

Enable the developer's options to access the Oracle Analytics Developer's page. Use the Developer's page to find the <script> tag, HTML, and column's expression that you need to embed Oracle Analytics content into an application or web page.

Go to the top toolbar and click your user name.
Click Profile and in the Profile window, click Advanced.
Click the Enable Developer Options icon and click Save.

Find the Javascript and HTML for the Embedding Analytics Content

Oracle Analytics generates the analytics content's <script> tag and HTML for you to copy and paste in to your custom application or portal web page's HTML page.

If the Developer option isn't displayed in the workbook's Menu, then you need to enable it. See Enable Oracle Analytics Developer Options.

Go to Oracle Analytics and open the workbook containing the analytics content you want to embed.
Click the workbook's Menu and then click Developer.
In the Developer window, click the Embed tab.
Locate the Embedding Script to Include field and click Copy to copy the <script> tag to paste in to the HTML page.
Optional: If you want the embedded workbook to show the workbook's default view, then locate the Default field, click Copy to copy the HTML, and paste it in to the HTML page.
Optional: If you want the embedded workbook to show an item such as a specific canvas, then locate the item's field, click Copy to copy the HTML, and paste it in to the HTML page.

Prepare the HTML Page for Embedded Oracle Analytics Content

To embed Oracle Analytics content, you must create or update the HTML page to include the required DOCTYPE declaration, dir global attribute, and reference the embedding.js JavaScript source and the embedded workbook's URL. You must also specify the embedding mode (JET or standalone), an authentication method, and add any attributes.

This topic contains the following information:

Doctype Declaration

Set the doctype declaration to <!DOCTYPE html>. Unpredictable behavior such as the page not rendering properly results if you use a doctype declaration other than <!DOCTYPE html>, or if you forget to include a doctype declaration.

Dir Global Attribute

Set the dir global attribute as required by the web page's locale. The dir global attribute indicates the embedded analytics content's layout direction.

Note:

If you need to support multiple locales, then use JavaScript to set the attribute.

The attribute's value options are:

rtl - Use for right to left layout direction.
ltr - Use for left to right layout direction.
auto - Don't use. This value isn't supported by Oracle Analytics.

Note:

Oracle Analytics generates the <script> tag and JavaScript source's URL that you need to include.

Add a <script> tag that references embedding.js to your HTML page.

The JavaScript source's URL structure is:

”https://<instance>/public/dv/v1/embedding/<embeddingMode>/embedding.js”. The examples in this document use this URL.
For older deployments, use: "http://<instance>/ui/dv/v1/embedding/<embeddingMode>/embedding.js".

Where <embeddingMode> must be either jet or standalone:

Use jet if you're embedding analytics content within an existing Oracle JET application. If you use jet, then the version of Oracle JET that the application uses must match the same major version of Oracle JET that Oracle Analytics uses. For example, if Oracle Analytics uses JET 11.0.0, then your custom application must use JET 11.0.0 or 11.1.0. Oracle Analytics uses Oracle JET version 11.1.10.
To find the version of JET that Oracle Analytics uses, log into Oracle Analytics, open the browser console, and run this command:
```
requirejs('ojs/ojcore').version
```
If the embedding application uses Oracle JET, Oracle Analytics extends the application with the components it needs. See Embed Oracle Analytics Content into a Custom Application that Uses Oracle JET.

Oracle JET is a set of Javascript-based libraries used for the Oracle Analytics user interface.
Use standalone when embedding visualization content in a generic application that doesn’t use Oracle JET.

If the embedding application doesn't use Oracle JET, then Oracle Analytics brings its JET distribution to the page with additional components. See Embed Oracle Analytics Content into a Custom Application That Doesn’t Use Oracle JET.

Authentication

You need an authenticated session to view the embedded analytics content. See Use Login Prompt Authentication With Embedded Oracle Analytics Content.

<oracle-dv> Element

To embed a workbook, you must add the following HTML snippet with attribute values inside an appropriately sized element. Oracle Analytics generates the HTML that you need to include.

<oracle-dv project-path="" 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.

Note:

See Embed Oracle Analytics Content into a Custom Application That Doesn’t Use Oracle JET for an example of binding these attributes to a Knockout model.

project-path: Specifies the path of the workbook that you want to render.
active-page: (Optional) Specifies whether an insight other than the default is rendered. When you specify active-page, you also use active-tab-id to specify the exact Present canvas that you’re showing. Valid value is insight.

Note:
The active-page value canvas is deprecated. Oracle recommends that you modify your embedding code that uses canvas to insight. Existing embedded analytics content that uses canvas will continue to work and a warning displays in the browser console.
active-tab-id: (Optional) Specifies the ID of the Visualize canvas or Present canvas that you’re showing.
filters: (Optional) Allows the programmatic passing of filter values to an embedded workbook.
project-options: (Optional) In this attribute, project refers to workbook. 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.
- showCanvasNavigation: Shows or hides the canvases in the workbook according to the canvas navigation setting in the workbook's Present tab. 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 saved workbook. 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.
compatability-mode: Use when different major versions of Oracle JET are present. This creates an iFrame at runtime to sandbox the embedded analytics content. Value should be the string yes, no, or auto.
Note:
To find the version of JET that Oracle Analytics uses, log into Oracle Analytics, open the browser console, and run this command:
```
requirejs('ojs/ojcore').version
```
- yes: Use when you always want to sandbox the analytics embedded content. This is useful when embedding into Oracle APEX applications.
- no: Default. Use when you don't want to create an iFrame.
- auto: Use to automatically detect major differences in Oracle JET version between the host embedding application and Oracle Analytics. You can use this when embedding into Oracle APEX.

Example

In this example, all instances of project refer to workbook.

<!DOCTYPE html>
<html dir="ltr">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
        <title>Embedded Oracle Analytics Workbook Example</title>
        <script src="https://<instance>/public/dv/v1/embedding/<embedding mode>/embedding.js" type="application/javascript">
        </script>

    </head>
    <body>
        <h1>Embedded Oracle Analytics Workbook</h1>
        <div style="border:1px solid black;position: absolute; width: calc(100% - 40px); height: calc(100% - 120px)" >
            <!--
            The following <oracle-dv> tag is the tag that will embed the specified workbook.
            -->
            <oracle-dv
               project-path="<project path>"
               active-page="insight"
               active-tab-id="snapshot!canvas!1">
            </oracle-dv>
        </div>
        <!--
        Apply Knockout bindings after DV workbook is fully loaded.  This should be executed in a body onload handler or in a <script> tag after the <oracle-dv> tag.
        -->
        <script>
        requirejs(['knockout', 'ojs/ojcore', 'ojs/ojknockout', 'ojs/ojcomposite', 'jet-composites/oracle-dv/loader'], function(ko) {
        ko.applyBindings();
        });
        </script>
    </body>
</html>

Pass Filters to the HTML Page for Embedded Oracle Analytics Content

You can pass numeric and list filters to the HTML page where you're embedding Oracle Analytics content. You can filter any type of data with these filter types.

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

In this example, all instances of project refer to workbook. Rendering a workbook 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 workbook that uses that column, and then in the Visualize tab, click the workbook's Menu and then click 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\"" .

If the Developer option isn't displayed in the workbook's Menu, then you need to enable it. See Enable Oracle Analytics Developer Options.
sColName: (Required) Specifies a unique name for this column.
sOperator: Use in, notIn, between, less, lessOrEqual, greater, or 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. Value should be true or false.
isDateCol: (Required) Indicates whether the column is a date column. Value should be true or false. Use 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 are part of the filter.
- If set to false and user passes empty aCodeValues/aDisplayValues, then the attribute won't be applied and there is 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. You can use a space as the separator.
- 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. You can use a space as the separator.
- <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

Pass Parameters to the HTML Page for Embedded Oracle Analytics Content

You can pass parameter values to the HTML page where you're embedding Oracle Analytics content. The parameter values that you pass can be utilized within query expressions and various parts of the product.

The parameters payload is a Javascript Object containing paired attributes of parameter names and values.

In this example, all instances of project refer to workbook. Rendering a project while applying parameters look like this:

<oracle-dv project-path="{{projectPath}}" active-page="canvas" active-tab-id="3" parameters="{{parameters}}" 
project-options='{"bDisableMobileLayout":false, "bShowFilterBar":false}'>
</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.parameters = ko.observable({
         "p1n": "Office",
         "p1v": "Bristol Office",
         "p2n": "Year",
         "p2v": [2023, 2022]
      });
    }
    ko.applyBindings(MyProject);
});
</script>

Supported attributes — Each parameter object within the parameters payload must contain the following attributes:

p <number> n: (Required) Specifies the parameter's name as defined in the workbook. For example, "Office" or "Year".
p <number> v: (Required) Specifies the parameter value that you want to pass. For example "Bluebell Office" or "10" or [2023, 2022].
p <number> d: (Optional) Use with parameters with double columns. Specifies the parameter's display value corresponding to p <number> v. For example, "My Office".

Refresh Data in the HTML Page for Embedded Oracle Analytics Content

In the HTML page where you're embedding Oracle Analytics content, you can specify how to refresh the embedded workbook's data.

To refresh data without reloading a workbook, the refreshData function is attached to all <oracle-dv> elements. Invoking it forces all visualizations under that element to refresh.

This is the code to refresh data for a single embedded workbook. In this code, all instances of project refer to workbook.

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

This is the code to refresh data for multiple embedded workbooks. In this code, all instances of project refer to workbook.


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

Embed Oracle Analytics Content into a Custom Application that Uses Oracle JET

If the custom application uses Oracle JET, then the embedded Oracle Analytics content extends the application with the component it needs.

Before you begin to embed analytics content, confirm that the custom application uses the same major version of JET that Oracle Analytics uses. For example, if Oracle Analytics uses JET 11.0.10, then your custom application must use JET 11.x.x.

To find the version of JET that Oracle Analytics uses, log into Oracle Analytics, open the browser console, and run this command:

requirejs('ojs/ojcore').version

Your JET application must also use the same style that Oracle Analytics uses, which is Alta.

For information about creating an Oracle JET quick start application where you'll embed analytics content, see Oracle JET Get Started.

This procedure uses an example embedding application named OAJETAPP.

Follow the instructions to install the Oracle JET quickstart application and name the embedding application OAJETAPP using --template=navdrawer.
Edit the index.HTML file of the embedding application (for example, OAJETAPP/src/index.html) and include embedding.js.
```
<script src="https://<instance>/public/dv/v1/embedding/jet/embedding.js" type="text/javascript">
</script>
```

Include <oracle-dv> in the appropriate section (for example OACJETAPP/src/js/views/dashboard.html). Here project-path specifies the workbook's path.

<div class="oj-hybrid-padding" style="position: absolute; width: calc(100% - 40px); height: calc(100% - 120px)">  
 <h3Dashboard Content Area</h3>
  <oracle-dv id="oracle-dv" project-path="/shared/embed/test-embed">
  </oracle-dv>
</div>

Run the quick start application using these commands.
```
ojet build
ojet serve
```

Embed Oracle Analytics Content into a Custom Application That Doesn’t Use Oracle JET

If the custom application uses a technology other than Oracle JET, then the embedded Oracle Analytics content adds its Oracle JET distribution and all additional components into the page.

If the Developer option isn't displayed in the workbook's Menu, then you need to enable it. See Enable Oracle Analytics Developer Options.

Include the standalone version of embedding.js.
<script src=https://<instance>/public/ui/dv/v1/embedding/standalone/embedding.js type="text/javascript"> </script>
Find and include <oracle-dv> under an appropriately sized <div>. To find this tag:
1. Go to Oracle Analytics and open the workbook containing the analytics content you want to embed.
2. Click the workbook's Menu and then click Developer.
3. Click the Embed tab.
4. Locate the item you want to embed and click Copy to copy it.
Example

Here project-path specifies the workbook's path.
```
<div style="position: absolute; width: calc(100% - 40px); height: calc(100% - 120px)">
    <oracle-dv project-path="/@Catalog/users/admin/workbook_name">
    </oracle-dv>
</div>
```
Apply Knockout bindings after the visualization is fully loaded. This should be placed inside of a <script> tag after the <oracle-dv> tag, or executed in an onload body handler.
```
requirejs(['knockout', 'ojs/ojcore', 'ojs/ojknockout', 'ojs/ojcomposite', 'jet-composites/oracle-dv/loader'], function(ko) {
    ko.applyBindings();
});
```

Complete Example

Here project-path specifies the workbook's path.

<!DOCTYPE html>
<html dir="ltr">
   <head>
      <title>AJAX Standalone Demo</title>
      <script src="https://<instance>/public/dv/v1/embedding/standalone/embedding.js""
type="text/javascript">
      </script> 
   </head>
   <body>
      <h1>AJAX Standalone Demo</h1>

      <div style="position: absolute; width: calc(100% - 40px); height: calc(100% - 
120px)" >
         <oracle-dv project-path="/shared/embed/test-embed">
         </oracle-dv>
      </div>

   <script>
requirejs(['knockout', 'ojs/ojcore', 'ojs/ojknockout', 'ojs/ojcomposite', 'jet-composites/oracle-dv/loader'], function(ko) {   ko.applyBindings();
});
      </script
   </body
</html

Use Login Prompt Authentication With Embedded Oracle Analytics Content

Login prompt authentication is the default authentication method for Oracle Analytics content embedded in a web application or portal web page.

When users access embedded analytics content, they're presented with a login screen where they enter login name and password before they can view data. If there is no common identity management between Oracle Analytics and the web application or portal web page, then users are presented with this login screen, even if they've already logged in to the web application or portal web page containing the embedded analytics content

Customize the Login Prompt Authentication Message

Add attributes to the <oracle-dv> tag to customize the login prompt authentication messages. The following attributes are supported:

auth-message-prefix: Specifies the prefix text for the login message. The default value is "Oracle Analytics".
auth-message-link: Specifies the text for the login link. The default value is "Login".
auth-message-suffix: Specifies the suffix text for the login message. The default value is "Required".
auth-needed-message: Specifies the text for the authentication needed message. The default value is "Requires Authentication".
auth-message-prefix-small: Specifies the prefix text for the login message. The default value is "Oracle Analytics". Applicable only if the embedded container size is smaller than 215 pixels.
auth-message-link-small: Specifies the text for the login link. The default value is "Login". Applicable only if the embedded container size is smaller than 215 pixels.
auth-message-suffix-small - Specifies the suffix text for the login message. The default value is the empty string. Applicable only if the embedded container size is smaller than 215 pixels.
auth-needed-message-small: Specifies the text for the authentication needed message. The default value is "Requires Authentication". Applicable only if the embedded container size is smaller than 160 pixels.