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