Create a Plug-In for the BI Publisher Online Template Builder

Have you ever wanted to use D3.js charts or Google charts in your BI Publisher reports? Creating charts with these JavaScript libraries provide nearly endless possibilities. BI Publisher supports adding JavaScript plug-in extensions to the layout editor to add custom components to your reports. When you view the report in interactive mode, the custom components are included in your report. The icon that you define for the plug-in displays in the layout editor’s Insert menu, when you add the plug-in to the layout editor. You can then drag and drop the custom component to the report layout as you do any other component in the layout editor.

This functionality enables you to insert static components to your reports, such as text, images, and video or data-driven components such as new charts.

To implement a plug-in:

1. Code the JavaScript plug-in using the guidelines described below.
2. Place the JavaScript (.js) file in the following location <BI Publisher repository>\Admin\Plugins
3. Reload the Layout Editor. Your plug-in icon appears in the layout editor Insert menu.

The plug-in definition JavaScript object has the following fields:

id

The id is an identification string. Oracle recommends using the reverse domain name to avoid any naming conflicts, for example: “com.example.helloworld”.

component

The following fields comprise the component object:

name

The name of the component. Example: “Hello World”

icon

The icon is the image that displays in the layout editor Insert menu to represent the plug-in. This field takes a URL that points to the icon image. Example: “http://www.example.com/img/smile.gif”

tooltip

The tooltip message to display for the icon image. Example: “Hello World Plugin”.

events

(Optional) Array of the click event definition object.

id

(string) The event identification, for example: “filter” or “showselection”.

source

A true|false flag, when set to true, the click action against the component triggers the filtering of the other components.

target

A true|false flag, when set to true, this plugin component receives the click event.

cssClass

(Optional) Component CSS class selector to identify the plug-in components.

render

The render function renders the plug-in contents. The render function passes the following parameters:

context

Object which contains following information:

id

The id is an assigned instantiated component ID string. The system assures this ID is unique in the same template. Oracle recommends using this ID as a prefix or suffix to the HTML element that the plug-in code generates. This practice prevents ID conflicts.

reportLocale

The locale assigned to the template.

containerElem

The container HTML element. The contents must be set to this element

rows

The data rows array, each item contains another array for the columns.

fields

The assigned xml path.

props

Current properties.

The following JavaScript APIs are available to use in custom plug-ins:

• handleClickEvent Method
  • Captures clicked (selected) field information to send to the system.
• getPixelValue Method
  • Returns the pixel value from the length string value. The system uses 96 dots per inch (dpi), which is the same as most browsers.

for further information about this methods, see the ORACLE documentation.

Example:

How to implement a very simple type of a plug-in is demonstrated in this example. This plug-in provides an icon to the layout editor toolbar in the upper right corner that will insert a company logo into the layout at the insertion point when selected. The JavaScript file for this plug-in that is illustrated below defines everything in a single object.

1. Write the JavaScript for the plug-in.The plug-in definition for this example is:

   {
     id: "com.oracle.xdo.logo",
     component:
     {
       name: "Logo",
       icon: "http://localhost:7001/xmlpserver/logo_icon.gif",
       tooltip: "Oracle Logo Plugin"
     },
     render: function(context, containerElem, rows, fields, props)
     {
       containerElem.innerHTML = '';
     }
   }
   

2. Save the file with the “.js” extension and place it under the <BI Publisher repository>\Admin\Plugins directory.
3. Reload the layout editor application. The logo plug-in displays in the ribbon. Click the “Oracle” icon or drag and drop the item to insert the logo into your layout.
   

   Logo Plug-in Shown in the Layout Editor

    

This is only a simple example and a getting started of the possibilities by using JavaScript with BI Publisher. There are nearly no limits since the JavaScript libraries can be used in the online editor. The libraries can be stored on a local server or called from the web.

HAVE FUN!