Embed 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.

Typical Workflow to Use the JavaScript Embedding Framework

If you're embedding analytics content into an application or web page, then follow these tasks as a guide.

Note:

You can also embed content using the content item's URL. Typically this method uses an iFrame. See Embed Analytics Content into Applications and Web Pages.
Task Description More Information
Add safe domains Use the Console to register as safe the development, production, and test environments domains.

Register the Embedding Environment 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 project's URL, specify filters, and specify how to refresh data.

Prepare the HTML Page

Pass Filters to the HTML Page

Refresh Data in the HTML Page

Specify the embedding mode Your application uses JET or another technology to embed content.

Embed into a Custom Application that Uses Oracle JET

Embed into a Custom Application that Doesn’t Use Oracle JET

Determine the authentication method You can configure logon prompt, 3-Legged OAuth, or token authentication.

Use Logon Authentication

Use 3Legged-OAuth Authentication

Use Token Authentication

Get Started Embedding 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.

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 the Embedding Environment as a Safe Domain.

Find the Content's Javascript and HTML

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

  1. Go to Oracle Analytics and open the project containing the content you want to embed.
  2. Click Options and then click Developer.
  3. Click the Embed tab.
  4. Locate the Embedding Script to Include field and click Copy to copy the <script> tag to paste in to the HTML page.
  5. Optional: If you want the embedded project to show the project's default view, then locate the Default field, click Copy to copy the HTML, and paste it in to the HTML page.
  6. Optional: If you want the embedded project 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

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

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

<script> Tag and JavaScript Source Reference

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.

Depending upon your version of Oracle Analytics, the JavaScript source's URL structure could be either of the following:
  • For the most recent versions: ”https://<instance>.analytics.ocp.oraclecloud.com/public/dv/v1/embedding/<embeddingMode>/embedding.js”. The examples in this document use this URL.
  • For older versions: "http://<instance>.analytics.ocp.oraclecloud.com/ui/dv/v1/embedding/<embeddingMode>/embedding.js".

Where <embeddingMode> must be either jet or standalone:

  • Use jet if you're embedding content within an existing Oracle JET application. If you use jet, then the version of Oracle JET that’s used by the application must match the version of Oracle JET used by Oracle Analytics.

    If the embedding application uses JET, Oracle Analytics extends the application with the components it needs. See Embed 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 JET, then Oracle Analytics brings its JET distribution to the page with additional components. See Embed into a Custom Application that Doesn’t Use Oracle JET.

Authentication

You need an authenticated session to view the embedded content. You can use logon prompt or 3-Legged OAuth authentication. See Add Authentication.

<oracle-dv> Element

To embed a project, 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 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 repository path of the project that you want to render.

  • 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.

  • 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 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.

Example

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

    </head>
    <body>
        <h1>Embeded Oracle Analytics Project</h1>
        <div style="border:1px solid black;position: absolute; width: calc(100% - 40px); height: calc(100% - 120px)" >
            <!--
            The following tag is the tag that will embed the specified project.
            Veryfy the project-path is the same as the server you are hosting this project on.
            -->
            <oracle-dv
               project-path="<project path>"
               active-page="canvas"
               active-tab-id="1">
            </oracle-dv>
        </div>
        <!--
        Apply Knockout bindings after DV project 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

You can pass numeric and list filters to the HTML page. 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.

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 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

Refresh Data in the HTML Page

You can configure how to refresh the embedded project's data.

To refresh data without reloading a project, 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 project.

<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 projects.


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

Embed into a Custom Application that Uses Oracle JET

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

For information about creating an Oracle JET quick start application where you'll embed content, see Oracle JET Get Started.
This procedure uses an example embedding application named OACJETAPP.
  1. Follow the instructions to install the Oracle JET quickstart application and name the embedding application OACJETAPP using --template=navdrawer.
  2. Edit the index.HTML file of the embedding application (for example, OACJETAPP/src/index.html) and include embedding.js.
    <script src="https://<instance>.analytics.ocp.oraclecloud.com/public/dv/v1/embedding/jet/embedding.js" type="text/javascript">
    </script>
  3. Include <oracle-dv> in the appropriate section (for example OACJETAPP/src/js/views/dashboard.html).
    <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>
  4. Run the quick start application using these commands.
    ojet build
    ojet serve

Embed into a Custom Application that Doesn’t Use Oracle JET

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

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

    For example:

    <div style="position: absolute; width: calc(100% - 40px); height: calc(100% - 120px)">
        <oracle-dv project-path="/@Catalog/users/admin/project_name">
        </oracle-dv>
    </div>
  3. 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

<!DOCTYPE html>
<html dir="ltr">
   <head>
      <title>AJAX Standalone Demo</title>
      <script src="https://<instance>.analytics.ocp.oraclecloud.com/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

Add Authentication

Use the topics in this section to add an authentication method to your web application or portal web page that contains embedded Oracle Analytics content.

Use Login Prompt Authentication

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

When users access embedded 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 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.

Use 3-Legged OAuth Authentication

Use the 3-Legged OAuth authentication method when embedding Oracle Analytics content into a portal or web application that already uses its own method of authentication.

For a seamless user experience, the custom web page and Oracle Analytics must use the same authentication provider. So in the case of a third-party web application, it would either need to use the same Oracle Identity Cloud Service instance as Oracle Analytics, or Oracle Analytics needs to be federated to the third-party authentication provider. 

To allow for proper authentication, you must specify the 3-Legged OAuth parameter for all server requests.

  1. Set the IDCS_OAUTH3LEGGED parameter to true in the embedding.js script reference.
  2. Specify the security configuration type of oauth_3legged to the application using the setSecurityConfig function.

Example

<!DOCTYPE html>
<html dir="ltr">
    <head>
        <script src=""https://<instance>.analytics.ocp.oraclecloud.com/public/dv/v1/embedding/<embedding_method>/embedding.js?IDCS_OAUTH3LEGGED=true" type="application/javascript">
        </script>
    </head>
    <body>
        <div style="position: absolute; width: calc(100% - 40px); height: calc(100% - 120px)" >
            <oracle-dv project-path="/shared/Embed/Embed Samples">
            </oracle-dv>
        </div>
    <script>
      requirejs(['jquery', 'knockout', 'obitech-application/application', 'jet-composites/oracle-dv/loader'], function($, ko, application) {
      application.setSecurityConfig("oauth_3legged");
      ko.applyBindings();
      });
     </script>
    </body>
</html>

Use Token Authentication

Use the token authentication method when you want to authenticate to Oracle Analytics in the background, but don't want to use 3-Legged OAuth.

Update the HTML page to allow for proper token authentication. For information about how to generate tokens, see Securing Authorizations in Oracle Cloud.

  1. In the HTML page, set the TOKEN parameter to true in the embedding.js script reference.
  2. Specify the security configuration type of token. Add the functions to retrieve the token to the application using the setSecurityConfig function. See the example below.

Example

This example uses an API to obtain the token. If your HTML page uses an API to obtain the token, then you must make the required API available.

<!DOCTYPE html>
<html dir="ltr">
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
     <title>Standalone DV Embed Demo Using Token</title>
     <script src="https://<instance>.analytics.ocp.oraclecloud.com/public/dv/v1/embedding/<embedding mode>/embedding.js?TOKEN=true" type="application/javascript">
     </script>
   </head>
   <body>
     <B>Standalone embedded project test</B>
      <div style="width: calc(50% - 40px); height: 50%; border: 1px solid black; padding: 10px;" >
         <oracle-dv
            project-path="/@Catalog/shared/Embed/Embed Samples"
            active-page="canvas"
            active-tab-id="1">
         </oracle-dv>
      </div>

      <script>
         var token = “<token from IDCS API>";
         requirejs(['jquery', 'knockout', 'obitech-application/application', 'jet-composites/oracle-dv/loader'],
  	    function($, ko, application) {
               application.setSecurityConfig("token", {tokenAuthFunction:
                  function(){
                     return token;
                  }
               });
               ko.applyBindings();
            }
	);
      </script>
   </body>
</html>