Oracle Analytics Desktop SDK Reference

Oracle Analytics Desktop SDK

The SDK provides a development environment where you can create and develop custom visualization plug-ins and deploy them to your Oracle Analytics Desktop installation.

Topics:

Scripts

Your installation includes the scripts that you use to create a development environment and create skeleton visualization plug-ins.

The scripts are located in this directory: <your_installation_directory>\Oracle Analytics Desktop\tools\bin.

For example, C:\Program Files\Oracle Analytics Desktop\tools\bin

Note the following script names and descriptions:

bicreateenv - Run this script to create the development environment where you develop your plug-ins.
bicreateplugin - Run this script to create a skeleton visualization to quickly get started on developing your custom plug-in.
bideleteplugin - Run this script to delete a plug-in from your development environment.
bivalidate - Run this script with the gradlew validate command to call the bivalidate script. The bivalidate script validates whether the JSON configuration files are properly formatted and contain appropriate visualization configuration.

Other Resources

You can use resources other than scripts to develop your custom visualization plug-ins.

Note the following available resources:

circlePack sample - The circlePack sample is included in your development environment. You can deploy and use this sample immediately. However, the sample is designed for you to use with the provided tutorial to learn how to develop a visualization plug-in. You can also copy the sample and use it as a template for the visualization plug-ins that you want to create.

The circlePack sample is located in <your_development_directory>\src\sampleviz\sample-circlepack

For example, C:\OracleDVDev\src\sampleviz\sample-circlepack
Other visualization plug-in samples - You can download plug-in examples from the Oracle Analytics Library.
JS API documentation - This documentation contains JavaScript reference information that you need to develop a visualization plug-in. See Oracle Analytics Desktop SDK JavaScript Reference.

Create the Visualization Plug-in Development Environment

You need to set the PATH environment variable and create the development environment before you can create visualization plug-ins.

Using the command prompt, create an empty development directory. For example, C:\OracleAnalyticsDev.

Set the PATH environment variable. For example,

set ANALYTICSDESKTOP_SDK_HOME="C:\Program Files\Oracle Analytics Desktop"
set PLUGIN_DEV_DIR=C:\OracleAnalyticsDev
REM add tools\bin to path: 
set PATH=%ANALYTICSDESKTOP_SDK_HOME%\tools\bin;%PATH%

Run the bicreateenv script included in your installation to create the development environment in the empty directory. For example,
```
cd C:\OracleAnalyticsDev
bicreateenv
```
For information about the options available for running this script, see the script's command-line help. For example,

C:\OracleAnalyticsDev>bicreateenv -help

The complete development environment, including build.gradle and gradlew, is created in the directory that you specified.
Optional: If you’re working behind a web proxy, then you need to set gradle.properties to point to your proxy. The gradle.properties are located in your development environment, for example C:\OracleAnalyticsDev\gradle.properties.
Use the following example to set your gradle.properties:
```
systemProp.https.proxyHost=www-proxy.somecompany.com
systemProp.https.proxyPort=80
systemProp.https.nonProxyHosts=*.somecompany.com|*.companyaltname.com
```

Create a Skeleton Visualization Plug-in

After you create a skeleton visualization plug-in in your development environment, you then develop it into a robust visualization plug-in and deploy it to your Oracle Analytics Desktop environment.

Run the bicreateplugin script included in your installation to create a skeleton visualization. Use the following syntax:
bicreateplugin viz -<subType> -<id> -<name>
- <subType> is the type of visualization that you want to create. Your choices are:
  - basic - Use this option to create a visualization that doesn’t use any data from Oracle Analytics Desktop or use any data model mapping. This is like the Image and Text visualization types delivered with Oracle Analytics Desktop. For example, you can use this visualization type to show an image or some text that’s coded into the plug-in or from a configuration. You can use this type of visualization to improve formatting.
  - dataviz -This type renders data from data sources registered with Oracle Analytics Desktop into a chart or table or some other representation on the screen. It also respond to marking events from other visualizations on the same canvas and publish interaction events to affect other visualizations on the same canvas.
  - embeddableDataviz - This type renders data from data sources registered with Oracle Analytics Desktop into the cells of a trellis visualization. It also responds to marking events from other visualizations on the same canvas and publish interaction events to affect other visualizations on the same canvas.
- <id> is your domain and the name that you want to give the visualization directory and components in your development environment. For example, com-company.basicviz.
- <name> is the name of the visualization plug-in that you test, deploy, and use in workbooks.
For example to create a basic visualization, name its development directory com-company-basicviz, and name the visualization plug-in helloViz, enter and run the following command:
C:\OracleDevDir>bicreateplugin viz –subType basic –id com.company.basicviz —name helloViz
Optional: Open the script's command-line help for information about the options available for running this script. For example, C:\OracleDVDev> bicreateplugin -help

When you run the bicreateplugin -viz command for the first time, the system creates the customviz directory in the following location. <your_development_environment>\src\customviz

All custom visualization development directories that you create are added to this directory.

For example, C:\OracleDVDev\src\customviz\com-company-basicviz

Create a Skeleton Skin or Unclassified Plug-in

The bicreateplugin -unclassified command creates an empty plug-in with plugin.xml, localization bundles. The bicreateplugin -skin command creates a skeleton skin plug-in.

Run the createplugin script included in your installation to create a skeleton plug-in. Use one of the following syntaxes:
bicreateplugin -skin -<id>

bicreateplugin -unclassified -<id>
- <id> is your domain and the name that you want to give the visualization. For example, com-company.newskin
For example, to create a skin plug-in, enter and run the following command:
C:\OracleDevDir>bicreateplugin skin –id com.company.newskin

Develop a Visualization Plug-in

After you create the skeleton visualization plug-in, you can use resources provided by Oracle to help you develop your plug-in.

The directories for dataviz and embeddableDataviz types include the datamodelhandler.js file, which contains the physical-to-logical data mapping format. This file also determines how Oracle Analytics Desktop renders and passes user interactions to the server.

Use the .JS API documentation to learn how to add dependencies. See Oracle Analytics Desktop SDK JavaScript Reference.

Run in SDK Mode and Test the Plug-in

You can run Oracle Analytics Desktop in SDK mode from your browser when you’re developing your visualization plug-in or when you want to test your visualization plug-in.

Execute the gradlew run command. For example, C:\OracleDevDir>gradlew run
After you run the command, note the following results:
- Oracle Analytics Desktop opens in SDK mode in your default browser. Use the browser's JavaScript debugger to test and debug the application.
- The visualization that you created is available in the Visualizations pane of Oracle Analytics Desktop.
- A system tray is displayed in the operating system's toolbar and includes three links: Launch Browser, which you use to launch or relaunch your default browser to display Oracle Analytics Desktop; Copy URL to Clipboard, which you can use to copy the URL and paste it into a different browser; and Shutdown, which you use to shut down the development browser.
Test your visualization by dragging and dropping it to a workbook’s canvas and adding data elements.
If necessary, continue developing the visualization plug-in. When working in SDK mode in the browser, you can update the .JS definition and refresh the browser to see your changes.

Validate the Visualization Plug-in

After you’ve tested your visualization plug-in and before you can package and deploy it, you must validate it.

Run the gradlew validate command. For example,
```
cd C:\OracleDVDev
.\gradlew validate
```
This step validates whether the JSON configuration files are properly formatted and contain appropriate visualization configuration. If the validation discovers any errors, then the system displays error messages.
To check for errors in the JavaScript source files, use your browser’s development tools.

Build, Package, and Deploy the Visualization Plug-in

After you validate the visualization plug-in, you've to build and package it, and then copy the resulting distributions into your installation directory.

The build and package process runs for all of the visualizations in your development directory, and each plug-in is contained in its own zip file. There’s no way to build and package specific visualizations. If you want to exclude visualizations from the build and package process, then you've to move the visualizations that you want to exclude out of your development directory, or delete them from the directory before you perform the build. See Delete Plug-ins from the Development Environment.

Run the gradlew build command. For example,
```
cd C:\OracleDVDev
.\gradlew clean build
```
A build directory is added to your development environment. For example, C:\OracleDVDev\build\distributions. This directory contains a zip file for each visualization. The zip file’s name is the one that you gave the visualization when you created its skeleton. For example, basicviz.zip.
Copy the zip files to your installation directory. For example, %localappdata%\OracleAnalyticsDesktop\plugins.

Delete Plug-ins from the Development Environment

You can use the bideleteplugin script to delete the unneeded plug-ins from your development environment.

The build and package process includes all of the visualizations contained in your development directory. There is no way to build and package specific visualizations. To exclude any unwanted visualizations from the build, you can delete them before you perform the build and package process.

If you want to delete a visualization plug-in, then run the bideleteplugin command, using the following syntax:
```
cd C:\<your_development_directory>
bideleteplugin viz -id <name_of_your_domain>.<name_of_viz_plugin>
```

If you want to delete an unclassified plug-in, then run the bideleteplugin command, using the following syntax:

cd C:\<your_development_directory>
bideleteplugin unclassified -id <name_of_your_domain>.<name_of_unclassified_plugin>

If you want to delete a skin plug-in, then run the bideleteplugin command, using the following syntax:

cd C:\<your_development_directory>
bideleteplugin skin -id <name_of_your_domain>.<name_of_skin_plugin>