Oracle Analytics - 1. Creating a Custom Visualization on MacOS

Oracle Analytics gives you the freedom to explore new and innovative solutions for any business application using data analytics. One of its many features includes the ability for users to make their own custom plugin visualizations using the Oracle Data Visualization SDK.

For examples on different plugin visualizations that have already been created, check out the Extensions section under the Oracle Analytics Library.

These instructions demonstrate how to set up the environment for creating plug-in visualizations in Oracle Data Visualization for Desktop on MacOS, as well as explain how to create a basic plug-in. For the Wind ows tutorial series, click here.

1. Installing Oracle Data Visualization Desktop

If you don’t already have it, download the latest version of Oracle Data Visualization Desktop. You will need to log into an Oracle Cloud Account.

For this MacOS tutorial, we are downloading version 12c 12.2.5.3.0 and selecting Apple Mac OS X (Intel) (64-bit) under Platforms / Languages. Select Continue to proceed.

Accept the License Agreements and on the landing page, select download to open the download manager. Alternatively, you may select the zip file next to the check box to automatically download the file into your Downloads folder.

After opening the zip file in your download directory, open the DVDesktop_MacInstaller pkg file and proceed to install. You should see two new applications in your Applications folder, Oracle Data Visualization for Desktop and Oracle Data Visualization for Desktop Configure Python.

2. Setting Up the Plug-In Dev Environment

You will need to install Java JDK 8u201 in order to run this environment. As of June 2019, no later version of JDK is supported. To check your current version, enter this in terminal:

$	java -version

If it displays a newer version than 8u201, then you will need to remove the recent version(s) by entering this in terminal:

$	sudo rm -rf /Library/Java/JavaVirtualMachines/jdk<version>.jdk

For the scripts, you will need Gradle installed as well. As of August 2019, the most up to date version of Gradle 5 is currently working with Data Visualization, although keep in mind that the product was fully tested with Gradle 1.12.

To set up the environment, determine where to set up your Gradle scripts and plug-ins. For this tutorial, we’ll define the plug-in directory to be /Users/<username>/Documents/dv-custom-plugins and create it as an environment variable.

To set up environment variables, open terminal and edit .bash_profile in the user directory by calling:

$	nano ~/.bash_profile

If you don't have permissions to do this, try the same line as administrator by preceding with sudo in the terminal, like so:

$	sudo nano ~/.bash_profile

When the editing window opens, add the following lines:

export DVDESKTOP_SDK_HOME=/Applications/dvdesktop.app/Contents/Resources/app.nw

export PLUGIN_DEV_DIR=/Users/<username>/Documents/dv-custom-plugins

export PATH=${DVDESKTOP_SDK_HOME}/tools/bin:$PATH

export PATH=/opt/gradle/gradle-5.4.1/bin:$PATH

Remember to fill the <username> field with whatever your user id is. The final line is to set up whatever version of gradle you have downloaded into the path. Write out the lines with Control(^)-O, press Return to save changes, then exit with Control(^)-X.

Alternatively, you could edit .bash_profile in your text editor of choice; the resulting file should look like this:

If you have not done so already, create to the plugin directory with a line in the Terminal:

$	mkdir $PLUGIN_DEV_DIR

Finally, navigate to the directory and run the script bicreateenv to start the environment:

$	cd $PLUGIN_DEV_DIR

$	bicreateenv

This should create the following files in the directory:

Open build.gradle in an IDE of your choice and check line 54. If the argument “-pluginDevDir” has capital letters, change them to lower case. The line should look like this:

args '-sdk', "-plugindevdir=${projectDir}${File.separator}src"

3. Creating & Running a Skeleton Plug-In Visualization

There are multiple types of plug-ins to choose from when creating a new visualization; for an explanation of these types as well as other scripts and options you can run in this environment, check out the Data Visualization SDK Reference. For this tutorial, we’ll be creating a skeleton of subtype embeddableDataviz because it has the most functionality.

While in the plug-in directory, run the bicreateplugin script in the terminal with the following options, including whatever name you’d like to put as the id option:

$	cd $PLUGIN_DEV_DIR

$	bicreateplugin viz -subType embeddableDataviz -id <company.yourVizName>

Under the src/customviz folder, a new folder should have been created with the plug-in id as its name. Inside this folder, the files useful for customizing the plug-in will appear:

Editing these files will change how the plugin behaves and appears. For instance, the <yourVizName>.js file controls how the visualization displays input data. In the next tutorial blog, I'll demonstrate how to edit the rendering logic in this file specifically.

To run the SDK mode, use this command to open Data Visualization Desktop:

$	./gradlew run

You will be able to select your plug-in id as a Custom Visualization; Using the Sample Order Lines example dataset (included in the Oracle Data Visualization for Desktop), this is what dragging “Profit” into Values looks like:

You can also drag other features into other options in the Grammar panel, such as attributes under Trellis Columns and Rows. Plugins with subType "embeddableDataviz" automatically include trellis capacity to divide the data in rows and repeat the visualization like so:

If you're not familiar with Oracle Analytics, check out our Udemy course on how to create projects in Data Visualization: https://www.udemy.com/augmented-analytics/

At this point, you can easily observe any changes you make to the plugin files in the developer console for your browser. To close the environment, use ctrl-C in the terminal.

Other Plugin Notes

If you need to delete any plugins you’ve created, use the bideleteplugin script in terminal and identify the original plugin’s id:

$	bideleteplugin viz -id <company.yourVizName>

NOTE: A documented issue on MacOS occurs when restarting the environment while background processes are still running. This will cause data values to not appear and projects to have multiple errors while loading. If this happens, you may need to kill the processes with the following command before restarting your environment again:

$	sudo kill $(ps -ef | grep [d]vdesktop.app | awk '{print $2}')

NOTE: If you run into any issues with setting up your environment during the plugin development process, consider using a previous version of Gradle. Specifically, Gradle 1.12 is the version that DV was tested with.

Next tutorial: 2. Rendering a Custom Pivot Visualization