Prepare the HTML Page for Embedded Oracle Analytics Content

This topic contains the following information:

Doctype Declaration

Set the doctype declaration to <!DOCTYPE html>. This page might not render correctly if you use a different doctype declaration or omit the doctype declaration.

Dir Global Attribute

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

Note:

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

The attribute's value are:

rtl - Use for right to left layout direction.
ltr - Use for left to right layout direction.
auto - Don't use. Oracle Analytics doesn't support this value.

Note:

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

Add a <script> tag that references the JavaScript Embedding Framework V2 embedding.js file to your HTML page.

Use the following structure:

<script
  src="https://<instance>.analytics.ocp.oraclecloud.com/public/dv/v2/embedding/<embedding-mode>/embedding.js"
  type="text/javascript"></script>

Specify one of the following values for <embeddingMode>:

jet: Use when the host application uses Oracle JET. Oracle Analytics extends the host application with the components required to embed Oracle Analytics content. See Embed Oracle Analytics Content into a Custom Application that Uses Oracle JET.

The application's Oracle JET version must match the same major version of Oracle JET that Oracle Analytics uses.
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
```
standalone Use when the host application doesn't use Oracle JET. Oracle Analytics loads the implementation and components required to embed Oracle Analytics content. See Embed Oracle Analytics Content into a Custom Application That Doesn’t Use Oracle JET.
auto: Use when you want Oracle Analytics to determine if the host application uses Oracle JET and select the appropriate embedding mode.

Language

Optionally append the lang query parameter to the V2 script URL to specify the language used for embedded user interface elements and messages. Specify the language as an IETF language tag.

If you don't specify lang, Oracle Analytics uses the browser locale.

For example, this script URL requests Canadian French:

<script
  src="https://<instance>.analytics.ocp.oraclecloud.com/public/dv/v2/embedding/auto/embedding.js?lang=fr-CA"
  type="text/javascript"></script>

Authentication

You need an authenticated session to view the embedded analytics content. You can use logon prompt, 3-Legged OAuth authentication, or token authentication.

For V2, configure 3-legged OAuth and token authentication through setEmbeddingConfig() after the framework is ready. Don't use the deprecated IDCS_OAUTH3LEGGED=true or TOKEN=true query parameters in V2 script URLs.

See Add Authentication.

<oracle-dv> Element

To embed a workbook, you must add an <oracle-dv> element with the required 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 —

The <oracle-dv> element supports static attribute values and, where supported, values supplied through the embedding application's binding model.

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

Note:
The canvas value is deprecated. Update existing embedding code to use insight. Existing embeds that use canvas continue to work, but a warning displays in the browser console.
active-tab-id: (Optional) Specifies the ID of the canvas to show.
filters: (Optional) Passes filter values to an embedded workbook. This attribute supports only list, number range, and date filters.

Note:
Oracle recommends that you use the filters-v2 attribute instead of filters. The filters-v2 attribute supports more filter types and doesn't reload the entire workbook when filters are modified.
filters-v2: (Optional) Passes filter values to an embedded workbook without reloading the entire workbook when filter values change. Supports all filter types.
project-options: (Optional) In this attribute, project refers to workbook. Allows you to pass these options:
- bDisableMobileLayout: Enables or disables the mobile layout. Mobile layout refers to the summary card layout available only on phone devices. Specify true or false.
- bShowFilterBar: Shows or hides the filter bar. Specify true or false.
- showCanvasNavigation: Shows or hides the canvases in the workbook according to the canvas navigation setting in the workbook tab of the presentation settings page. Specify true or false.
- showVizToolbar: Shows the floating visualization toolbar when users hover over a visualization on a canvas. Specify true or false. If true, the floating toolbar header bar only displays if it’s enabled in the presentation settings.
- showHeaderBar: Shows the workbook header. Specify true or false. If true, the header bar only displays if it’s enabled in the presentation settings.
brushing-type: Controls brushing behavior. The value you specify overrides all other settings, including system defaults and settings stored in the workbook. Value should be the string on, off, or auto.
- on: Issues brushing queries with normal priority. Brushing queries and visualization queries are mixed and run at the same time.
- auto: Default. Issues 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.

V2 Initialization Guidance

After the <oracle-dv> elements are present in the page, wait for the V2 framework to be ready. Then configure the embedding application as required and call applyBindings().

<script> 
   oracle.oa.embedding.ready().then((application) => {
     application.applyBindings(); 
   });
</script>

With no arguments, applyBindings() processes all <oracle-dv> elements in the document. You can optionally provide a model for bindings or a root element to process only the <oracle-dv> elements beneath that element.

Example

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


<!DOCTYPE html>
<html dir="ltr">
  <head>
    <meta charset="utf-8">
    <title>Embedded Oracle Analytics Workbook Example</title>

    <script
      src="https://<instance>.analytics.ocp.oraclecloud.com/public/dv/v2/embedding/auto/embedding.js?lang=en-US"
      type="text/javascript"></script>
  </head>

  <body>
    <h1>Embedded Oracle Analytics Workbook</h1>

    <div style="border: 1px solid black; width: calc(100% - 40px); height: calc(100vh - 120px)">
      <oracle-dv
        project-path="<project path>"
        active-page="insight"
        active-tab-id="snapshot!canvas!1">
      </oracle-dv>
    </div>

    <script>
      oracle.oa.embedding.ready().then((application) => {
        application.applyBindings();
      });
    </script>
  </body>
</html>
```

For examples that use 3-legged OAuth or token authentication, call setEmbeddingConfig() before applyBindings().