Usage

The Sankey Chart Pro plug-in allows developers to integrate advanced flow and relationship visualizations into Oracle APEX applications. This document provides a comprehensive guide on how to use the plug-in, including configuration, example data, public JavaScript APIs, and customization options.

Installation and Setup

Please refer to the Installation guide for detailed instructions on how to install and set up the Sankey Chart Pro plug-in in your Oracle APEX application.

Region Attributes

Key Attributes

Data Source: The SQL query providing the nodes and links for the diagram.
Node Label Column: The column specifying the label for each node.
Link Source/Target Columns: The columns specifying the source and target nodes for each link.
Link Value Column: The column specifying the value/weight of each link.
Color Scheme: Choose from built-in or custom color palettes for nodes and links.
Tooltip Format: Customize the information shown in tooltips for nodes and links.
Responsive Layout: Enable automatic resizing for different screen sizes.
Event Triggers: Configure actions for node/link clicks and hovers.
Export Options: Enable export to PNG.

Example SQL Data Structure

The Sankey Chart expects data from a SQL query with the following columns:

Column	Type	Description
from	VARCHAR2	The label of the source node.
to	VARCHAR2	The label of the target node.
weight	NUMBER	The value/weight of the link.
tooltip	VARCHAR2	Optional tooltip text for the link.
color_source	VARCHAR2	Optional color for the source node.
color_target	VARCHAR2	Optional color for the target node.
color_link	VARCHAR2	Optional color for the link.

Example:

with emp_colored as (
    select empno,
           mgr,
           ename,
           case job
               when 'MANAGER' then '#ad78cd'
               when 'CLERK' then '#27a2fd'
               when 'ANALYST' then '#da2211'
               else null
           end as color,
           job
      from emp
)

select emp.ename as source,
       emp.color as source_color,
       mgr.ename as target,
       mgr.color as target_color,
       ( select count(1) from emp e where e.mgr = mgr.empno ) as weight,
       emp.job   as link_tooltip,
       emp.ename || ' - ' || emp.job as source_tooltip,
       mgr.ename || ' - ' || mgr.job as target_tooltip
  from emp_colored emp
  left join emp_colored mgr
    on emp.mgr = mgr.empno
 where mgr.mgr is not null

Result: Image from assets Alt text

Public JavaScript APIs

The plug-in exposes JavaScript APIs for advanced interactions, such as updating data, refreshing the chart, or handling events. The following public methods are available:

`.addData(from, to, weight, url, tooltip, color)`

Adds a new row to the chart.

from (string): Source node label
to (string): Target node label
weight (number): Value/weight of the link
url (string, optional): URL for the link
tooltip (string, optional): Tooltip text for the link
color (string, optional): Color for the link

`.removeData(from, to)`

Removes a row from the chart based on the source and target labels.

from (string): Source node label
to (string): Target node label

`.clearData()`

Removes all data from the chart.

`.refresh()`

Refreshes the chart data from the server via AJAX (re-executes the SQL query).

`.version()`

Returns an object with the plugin and Plotly version information.

Node Selection and Interactability

Important:
To enable node selection events in the Sankey Chart, you must set the Node Interactability attribute to Fixed.

When Node Interactability is set to Fixed, users can select nodes and the corresponding selection events will be triggered.

If Node Interactability is set to Freeform or any other mode, only link selection events are available—node selection will be unavailable.

Make sure to configure this attribute appropriately if you want to catch node selection events in your application logic or dynamic actions.

Customization

Node/Link Styling: Adjust colors, thickness, and label formatting.
Layout Options: Control spacing, orientation, and alignment.
Accessibility: Enable ARIA attributes and keyboard navigation.

Debugging

Enable debugging by setting the Debug level to option to Application Trace. Debug messages will appear in the APEX debug logs.

Best Practices

Use lazy loading for large images to improve performance.
Define a robust save procedure to handle image updates securely.
Customize the theme to match your application’s design.

For further assistance, see support