Oracle Analytics Summit — How to Create the Custom Application
Contributors: Matt Milella and Mike Durran
Introduction
You may have watched the recent Oracle Analytics June Roadmap Update session as part of the Oracle Analytics Summit 2020 series and wondered how we built the custom analytics application shown as part of the demos.
As a reminder, here is a clip of the relevant part of the demo (use the link above if you’d like to watch the whole webcast — it’s still available to view on demand)..
I’ve covered the basics of embedding Oracle Analytics content in a previous blog as well as tips and tricks on troubleshooting but I thought it would be useful to describe the process and workflow we went through in creating this example of a custom analytics application.
Start with a Theme!
A good starting point when creating a custom web application is a ready built theme. In our case, we took the Bootstrap theme ‘SB Admin 2’ as our starting point (link to live preview of the theme). This theme is described as follows and is perfect for our purposes.
“SB Admin 2 is a free, open source, Bootstrap 4 based admin theme perfect for quickly creating dashboards and web applications. It’s modern design style with subtle shadows and a card-based layout could be described as flat material, and is inspired by the principles of material design along with a simple, attractive color system.”
Designing the Custom Application
Once you’ve obtained a theme that you think represents the kind of application you want to build, then the next step in the process is understanding how to customize the theme to include your own embedded content from Oracle Analytics.
In this case, opening the relevant HTML files will enable you to understand what items to change. A good place to start is index.html.
The whole theme provides a comprehensive set of examples for various pages and utilities which we’re not going use in our custom app example so we can discard those.
In this case, we want to provide a dashboard view showing cards with key metrics and mini charts. Along the base of the dashboard we will have a view of how data is trending over time. We also want to provide the end users with the ability to navigate to some other pages of data using the left hand navigation bar (which also happens to be collapsible).
A key usability requirement is to be able to easily navigate back to our ‘home’ dashboard. We’ve fine tuned the look and feel of the application with a custom image of a plane since the theme of the demo is analysis of air traffic data. Our goal is for our custom app to look like this:
Building the Custom Application Cards
The first item we’re going to customize is one of the dashboard cards. This is how it looks in the theme out of the box:
The code behind this card is as follows:
The important area that we need to change for our own app is the content within the <div class= “card-body”> tag. This is where we will include the usual <oracle-dv> embedding tag reference to the content we wish to see in the application. Let’s look at the source content we wish to include in that card within Oracle Analytics.
One tip is to include each visualization on a separate canvas which is then referenced in the <oracle-dv> embed tag used by each card. We can find the reference we need to embed this visual using the projects ‘Developer’ menu item and the ‘Embed’ tab which shows us the following reference:
Our modified HTML now looks like this:
and the resulting card looks like this:
Before we go through the other customizations, it’s worth remembering the additional ‘housekeeping’ code we need to include in any project where we embed Oracle Analytics content. The first one is the <script> reference to the embedding.js framework and also the <script> reference to the requirejs and knockout bindings (see the getting started blog for details).
In this project, they were included at the bottom of the HTML files that make up this application. Also, don’t forget to include any domains that you’re embedding into in the Oracle Analytics safe domains section of the console.
Building the Navigation Experience
As stated earlier, we want to allow the users of our custom application to be able to navigate to a number of additional canvases. These could provide further detail to complement the main dashboard page or just allow users to see data on related subjects. This is where we really start to reap the benefits of using a template since it offers a collapsible navigation pane out of the box!
The area of the template we’re interested in for this part of the application looks like this out of the box:
and the HTML is as follows:
The first part of this customization involves changing the href of the link to point to the required Oracle Analytics content we wish our app users to see when they click on that particular link. However, we also need to direct the users to a different view of the application. The code we’re using looks like this (h/t Matt Milella for this approach) and as you can see it references a separate HTML file (called canvasloader.html which is essentially the same as the index.html file) and passes the parameters required for the <oracle-dv> embed tag. In this case, it’s passing the active-tab-id , the project-path (both found in the OAC developer, embed menu)and the required header text. Here is the example:
In this case, we’re going to define an id for the <oracle-dv> tag that will show different content depending on which navigation link the user chooses. First, let’s see the code for the <oracle-dv> tag with id=”dv-report”:
[No prizes for guessing which user group conference we were planning to present this at !]
The following code uses JQuery to pass the URL parameters to the value of the header-name and the <oracle-dv> tag (the console.log entries are useful for checking everything is working):
We can ensure that our users can always return to the main dashboard using a link that navigates back to index.html as follows:
The finishing touches were made to our application with assistance from Andrew from the Oracle Analytics UX team who designed an aviation theme navigation sidebar by referencing a suitable image in the application CSS.
Using the Custom Application
At this stage, we’ve designed the custom application and made the necessary code changes to include the analytics content where needed as well as provided a navigation experience.
In terms of how your users can authenticate to the application, the simplest way is to use the standard login prompt that’s provided by the Oracle Analytics embedding framework. This would look like this when a user navigates to the application:
After authenticating, the user would see the data they are entitled to see:
and navigate to perform further analysis using the links:
Summary
This blog has described the main workflow for creating a custom application that embeds Oracle Analytics content into an application theme. The main stages being:
(1) Find a suitable theme to kick start your application development.
(2) Understand how it’s put together in terms of the HTML, CSS and JS.
(3) Make changes to the application that includes the relevant Oracle analytics embedding code.
(4) Make any changes to the look and feel suitable to your requirements.
(5) Roll out to your users !
