1. Visualizing Data in Oracle Analytics Server
  2. Visualize Data
  3. Create Custom Data Action Plug-ins
  4. Data Action Plug-in File Reference

Data Action Plug-in File Reference

Each data action plug-in requires a plugin.xml file and each plugin.xml file can contain any number of data actions.

Topics:

Data Action plugin.xml File Example

The plugin.xml file has three main sections, tns:obiplugin, tns:resources, and tns:extension.

Example plugin.xml

This example shows a typical plugin.xml file for one data action.

1 <?xml version="1.0" encoding="UTF-8"?>
2 <tns:obiplugin xmlns:tns="http://plugin.frameworks.tech.bi.oracle"
3                id="obitech-currencyconversion"
4                name="Oracle BI Currency Conversion"
5                version="0.1.0.@qualifier@"
6                optimizable="true"
7                optimized="false">
8 
9 
10   <tns:resources>
11      <tns:resource id="currencyconversion" path="scripts/currencyconversion.js" type="script" optimizedGroup="base"/>
12      <tns:resource-folder id="nls" path="resources/nls" optimizable="true">
13         <tns:extensions>
14            <tns:extension name="js" resource-type="script"/>
15         </tns:extensions>
16      </tns:resource-folder>
17   </tns:resources>
18  
19 
20   <tns:extensions>
21      <tns:extension id="oracle.bi.tech.currencyconversiondataaction" point-id="oracle.bi.tech.plugin.dataaction" version="1.0.0">
22         <tns:configuration>
23         {
24            "host": { "module": "obitech-currencyconversion/currencyconversion" },
25            "resourceBundle": "obitech-currencyconversion/nls/messages",
26            "properties":
27            {
28               "className": "obitech-currencyconversion/currencyconversion.CurrencyConversionDataAction",
29               "displayName": { "key" : "CURRENCY_CONVERSION", "default" : "Currency Conversion" },
30               "order": 100
31            }
32         }
33         </tns:configuration>
34      </tns:extension>
35   </tns:extensions>
36 
37 </tns:obiplugin>

Data Action plugin.xml File Properties Section - tns:obiplugin

The tns:obiplugin section defines properties common to all types of plug-ins.

Plug-in Properties

The tns:obiplugin section defines properties common to all types of plug-ins. 

1 <?xml version="1.0" encoding="UTF-8"?>
2 <tns:obiplugin xmlns:tns="http://plugin.frameworks.tech.bi.oracle"
3                id="obitech-currencyconversion"
4                name="Oracle BI Currency Conversion"
5                version="0.1.0.@qualifier@"
6                optimizable="true"
7                optimized="false">
  • Line 1: The XML declaration.
  • Line 2: The opening tag for the plug-in's root XMLElement and the declaration for the tns namespace that's used throughout plugin.xml files.
  • Line 3: The plug-in's unique ID.
  • Line 4: The plug-in's default display name (used when a localized version isn't available).
  • Line 5: The plug-in's version number.
  • Line 6: A boolean indicating whether or not the JS/CSS can be optimized (compressed).
  • Line 7: A boolean indicating whether or not the JS/CSS has been optimized (compressed).

Data Action plugin.xml File Resources Section - tns:resources

The tns:resources section registers all of the files that contribute to your plug-in.

Resources


1 <tns:resources>
2    <tns:resource id="currencyconversion" path="scripts/currencyconversion.js" type="script" optimizedGroup="base"/>
3    <tns:resource-folder id="nls" path="resources/nls" optimizable="true">
4       <tns:extensions>
5          <tns:extension name="js" resource-type="script"/>
6       </tns:extensions>
7    </tns:resource-folder>
8 </tns:resources>

You need to register each JavaScript, CSS, Image, and Translation Resource File here. The section is contained within the <tns:resources> element and contains any number of the following elements:

  • <tns:resource>

    These elements are used to register a single file (for example, a JavaScript or CSS file).

  • <tns:resource-folder>

    These elements are used to register all the files under a specified folder at the same time. For example, an image folder or the folder containing the resource files for Native Language Support.

More information on how to register each type of file is provided in the following sections.

JavaScript Files

Each JavaScript file in your plug-in must be registered with a line similar to the one shown below.

<tns:resource id="currencyconversion" path="scripts/currencyconversion.js" type="script" optimizedGroup="base"/>

Where:

  • id is the ID given to the file.

    Set the ID to match the JavaScript filename without the .js extension.

  • path is the relative path to the JavaScript file from the plugin.xml file. JavaScript files should be stored under your plug-in's scripts directory.

    Use all lowercase for your JavaScript files with no special characters (for example, underscore, hyphen).

  • type is the type of file being registered. It must be set to script for JavaScript files.
  • optimizedGroup groups multiple JavaScript files into a single compressed file. Third-party plug-ins must leave this set to base.

CSS Files

Each CSS file in your plug-in must be registered with a line similar to the one shown below.

<tns:resource id="currencyconversionstyles" path="resources/currencyconversion.css" type="css"/>

Where:

  • id is the ID given to the file.

    Set the ID to match the CSS filename without the .css extension.

  • path is the relative path to the CSS file from the plugin.xml file. CSS files should be stored under your plug-in's resources directory.

    Use all lowercase for your CSS files with no special characters (for example, underscore, hyphen).

  • type is the type of file being registered. It should always be set to css for CSS files.

Image Folders

If your plug-in has images that you need to refer to from within your JavaScript code, then put them in a resources/images directory within your plug-in's directory structure and add a <tns:resource-folder> element to your plugin.xml as follows: 

<tns:resource-folder id="images" path="resources/images" optimizable="false"/>

If your images are only referenced by your CSS files, then you don't need to add this <tns:resource-folder> element to your plugin.xml file. In this case, you must still add them to the resources/images directory so that you can then refer to them using a relative path from your CSS file.

Native Language Support Resource Folders

Oracle Analytics implements Native Language Support. This requires developers to externalize the strings they display in their user interface into separate JSON resource files. You can then provide different localized versions of those files in a prescribed directory structure and Oracle Analytics automatically uses the correct file for the user's chosen language. You can provide as many translated versions of the resource files as needed. A Native Language Support resource folder points Oracle Analytics to the root of the prescribed Native Language Support directory structure used by your plug-in. All plug-ins that use Native Language Support resource files must have a <tns:resource-folder> entry that looks exactly like the example below. 


1 <tns:resource-folder id="nls" path="resources/nls" optimizable="true">
2    <tns:extensions>
3       <tns:extension name="js" resource-type="script"/>
4    </tns:extensions>
5 </tns:resource-folder>

See Generated Folders and Files for details about the contents of the files and the prescribed directory structure that you should follow.

Data Action plugin.xml File Extensions Section - tns:extension

For each data action you want your plug-in to provide, you must register a data action extension using a <tns:extension> element similar to this: 

<tns:extension id="oracle.bi.tech.currencyconversiondataaction" point-id="oracle.bi.tech.plugin.dataaction" version="1.0.0">
   <tns:configuration>
   {
      "host": { "module": "obitech-currencyconversion/currencyconversion" },
      "resourceBundle": "obitech-currencyconversion/nls/messages",
      "properties":
      {
         "className": "obitech-currencyconversion/currencyconversion.CurrencyConversionDataAction",
         "displayName": { "key" : "CURRENCY_CONVERSION", "default" : "Currency Conversion" },
         "order": 100
      }
   }
   </tns:configuration>
</tns:extension>

Where:

  • id is the unique ID you give to your data action.
  • point-id is the type of extension you want to register. For data action extensions, this must be set to oracle.bi.tech.plugin.dataaction.
  • version is the extension API version that your extension definition uses (leave this set to 1.0.0).

The <tns:configuration> element contains a JSON string that defines:

  • host.module - This is the fully qualified name of the module containing your data action. This fully qualified module name is formulated as %PluginID%/%ModuleName%, where:
    • %PluginID% must be replaced with the plug-in ID you specified in the id attribute of the <tns:obiplugin> element.
    • %ModuleName% must be replaced with the resource ID you specified in the id attribute of the <tns:resource> element for the JavaScript file containing your data action.
  • resourceBundle - This is the Native Language Support path to the resource file that contains this data action's localized resources. If your resource files are named messages.js and stored correctly in the prescribed nls directory structure, then set this property to %PluginID%/nls/messages (where %PluginID% must be replaced with the plug-in ID you specified in the id attribute of the <tns:obiplugin> element at the top of the plugin.xml file).
  • properties.className - This is the fully qualified class name given to the data action you're registering. This fully qualified class name is formulated as %PluginID%/%ModuleName%.%ClassName%, where:
    • %PluginID% must be replaced with the plug-in ID you specified in the id attribute of the <tns:obiplugin> element.
    • %ModuleName% must be replaced with the resource ID you specified in the id attribute of the <tns:resource> element for the JavaScript file containing your data action.
    • %ClassName% must be replaced with the name you gave to the data action class in your JavaScript file.
  • properties.displayName - This property contains an object and two further properties:
    • key is the Native Language Support message key that can be used to lookup the data action's localized display name from within the specified resourceBundle.
    • default is the default display name to use if for some reason the localized version of the display name can't be found.
  • properties.order - This property enables you to provide a hint that's used to determine the position that this data action should appear when shown in a list of data actions. Data actions with lower numbers in their order property appear before data actions with higher numbers. When there's a tie, the data actions are displayed in the order they're loaded by the system.