Prepare the HTML Page for Embedded Oracle Analytics Content

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 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.
compatibility-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:

When setting this attribute, note these two items:

If using compatibility mode, confirm that Allow Frames is selected for the application your administrator registered as a safe domain. See Register an Application as a Safe Domain.
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.

You can get the exact URL of the embedding.js file from the Embed tab in the Developer window of the 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>