The Oracle Graph Visualization Library has the following interface:
graph
: Current state of the graph (triggered on any graph change)selection
: Currently selected vertices and edges (triggered on any selection change)data
interface Graph {
// Graph vertices
vertices: Vertex[];
// Graph edges
edges: Edge[];
// Number of results used for pagination
numResults?: number;
}
declare type Id = string | number;
interface Entity {
// Entity id
id: Id;
// Arbitrary entity properties
properties?: TypedMap<string | number | boolean>;
// Entity classes used for styling
classes?: string[];
// Inline style
style?: Style;
}
interface Vertex extends Entity {}
interface Edge extends Entity {
// Source vertex id
source: Id;
// Target vertex id
target: Id;
}
settings
interface Settings {
// Size of pagination page (default 100)
pageSize: number;
// Whether to group edges with the same source and target (default false)
groupEdges: boolean;
// Layout type or LayoutSettings (default force)
layout: string | LayoutSettings;
// Network Evolution configuration
evolution: Evolution;
}
type LayoutSettings =
| CircleLayoutSettings
| ConcentricLayoutSettings
| ForceLayoutSettings
| GridLayoutSettings
| HierarchicalLayoutSettings
| PresetLayoutSettings
| RadialLayoutSettings
| RandomLayoutSettings;
type LayoutType = 'circle' | 'concentric' | 'force' | 'grid' | 'hierarchical' | 'preset' | 'radial' | 'random';
interface BaseLayoutSettings {
type: LayoutType;
}
interface SpacingLayoutSettings {
// Spacing among vertices in multiples of vertex radius
spacing: number;
}
interface CircleLayoutSettings extends BaseLayoutSettings, SpacingLayoutSettings {
type: 'circle';
}
interface ConcentricLayoutSettings extends BaseLayoutSettings, SpacingLayoutSettings {
type: 'concentric';
}
interface ForceLayoutSettings extends BaseLayoutSettings, SpacingLayoutSettings {
type: 'force';
alphaDecay: number; // (default 0.01)
velocityDecay: number; // (default 0.1)
edgeDistance: number; // (default 100)
vertexCharge: number; // (default -60)
}
interface GridLayoutSettings extends BaseLayoutSettings, SpacingLayoutSettings {
type: 'grid';
}
type HierarchicalRankDirection =
| 'UL' // Up to left
| 'UR' // Up to right
| 'DL' // Down to left
| 'DR' // Down to right
| 'TB' // Top to bottom
| 'BT' // Bottom to top
| 'LR' // Left to right
| 'RL'; // Right to left
type HierarchicalRanker = 'network-simplex' | 'tight-tree' | 'longest-path';
interface HierarchicalLayoutSettings extends BaseLayoutSettings {
type: 'hierarchical';
// (default 'TB')
rankDirection: HierarchicalRankDirection;
// (default 'network-simplex')
ranker: HierarchicalRanker;
vertexSeparation?: number;
edgeSeparation?: number;
rankSeparation?: number;
}
interface PresetLayoutSettings extends BaseLayoutSettings {
type: 'preset';
// Property of the vertex used as x coordinate
x: string;
// Property of the vertex used as y coordinate
y: string;
}
interface RadialLayoutSettings extends BaseLayoutSettings, SpacingLayoutSettings {
type: 'radial';
}
interface RandomLayoutSettings extends BaseLayoutSettings {
type: 'random';
}
interface EvolutionEntity {
// Start property
start: string;
// End property
end?: string;
}
interface Evolution {
// Height of the UI component (default 100)
height: number;
// Type of the chart (default 'bar')
chart: 'bar' | 'line';
// Aggregation granularity in given unit (default 1)
granularity: number;
// Time unit or undefined for numbers (default undefined)
unit?: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year';
// Vertex Evolution properties (or just string specifying Start property)
vertex?: string | EvolutionEntity;
// Edge Evolution properties (or just string specifying Start property)
edge?: string | EvolutionEntity;
// Defines exlusion of values
exclude: {
// Array of excluded values
values: (string | number)[];
// Whether to always show or hide excluded values (default false)
show: boolean;
};
// Playback options
playback: {
// Number of vertex / edge changes per step
step: number;
// Number of milliseconds between steps
timeout: number;
};
}
All the properties in settings are optional and have their defaults.
styles
type Styles = TypedMap<VertexStyle | EdgeStyle>;
interface Style extends ElementPosition {
// (default vertex: lightgray, edge: #C0C0C0)
color: string;
// (default 1)
opacity: number;
// Css filter (default none)
filter: string;
// Label settings or just label text or null for no label
label: LabelStyle | string | null;
// Legend style or just legend text or null for no legend
legend: Style | string | null;
// Definitions of child elements (e.g. vertex / edge badges)
children: TypedMap<VertexStyle> | null;
}
interface VertexStyle extends Style {
// Vertex radius (default 8)
size: number;
// Background image settings or just url or null for no background
image:
| string
| {
// Image url (default undefined)
url: string;
// Image scale (default 1)
scale?: number;
}
| null;
// Vertex border settings or just color or null for no border
border:
| string
| {
// Border width (default 1)
width?: number;
// Border color (default #404040)
color?: string;
}
| null;
// Vertex icon settings or just class or null for no icon
icon:
| string
| {
// Icon class e.g. fa-bell (default undefined)
class: string;
// Icon text color (default white)
color?: string;
}
| null;
}
interface EdgeStyle extends Style {
// Edge width (default 2)
width: number;
// Fill pattern (default undefined)
dasharray: string;
}
// Position of the label or child vertex
interface ElementPosition {
// Angle position in degrees on the vertex range or null to position into
// center
angle?: number | null;
// Position on the edge, value between -1 (edge start) and 1 (edge end)
position?: number;
// Offset from: vertex radius (> 0: outside, < 0: inside) or edge path
// (> 0: above, < 0: under)
d: number;
}
interface LabelStyle {
// Label text
text: string;
// Color (default rgba(0, 0, 0, 0.8))
color: string;
// Label max length (default 15), the whole label is displayed in tooltip
maxLength: number;
font: {
// Font size (default 10)
size?: number;
// Font family (default inherited)
family?: string;
// Font style (default inherited)
style?: string;
// Font weight (default inherited)
weight?: string;
};
}
Styling is defined as an object, where keys are the rule expressions
and values are VertexStyle
or EdgeStyle
. For
each style, all the properties are optional and have their defaults. Besides specifying constant value for given style
property it is also possible to use style expressions
.
These expressions can access anything from the ExpressionContext
which extends Entity
so also all the properties of
the vertex / edge that is styled.
interface ExpressionContext extends Entity {
// Helper function for value interpolation
// path: path to the ExpressionContext property that will be interpolated
// (e.g. 'id', 'properties.someProperty')
// min: minimum interpolation result value
// max: maximum interpolation result value
interpolate: (path: string, min: number, max: number) => number;
// Previous value of evaluated property
previous?: number | string;
}
Context is accessed through ${accessor}
syntax (aka JavaScript template literals). Example expressions:
https://flagcdn.com/40x30/${properties.code}.png
: constructs url using given property${previous + 4}
: returns bigger value. Could be used e.g. to make vertices / edges bigger on hover${interpolate("group.size", 8, 16)
: interpolation based on the grouped vertex sizeRule expressions are used to specify the target element into which given style will be applied. It has the following form:
elementName(.className)*(:modifier)*([conditionExpression])? (> elementName(.className)*)
elementName := * | 'vertex' | 'edge'
className
: any className specified in classes
array of input vertex / edgemodifier := 'hover' | 'selected' | 'unselected' | 'group'
conditionExpression
: JavaScript expression that can access any property of evaluated vertex / edge.Example rules:
*
: applies to all elementsvertex
: applies to all verticesedge
: applies to all edges.example
: applies to all elements with example
class specifiedvertex.example
: applies to all vertices with example
classvertex:selected
: applies to all selected verticesvertex[id > 10]
: applies to all vertices with id > 10vertex[properties.some === 'value']
: applies to all vertices that have some
property with value value
featureFlags
type FeatureFlags =
| false
| NestedFlags<{
// false to hide the whole exploration
exploration: {
// false to hide expand
expand: boolean;
focus: boolean;
group: boolean;
ungroup: boolean;
drop: boolean;
undo: boolean;
redo: boolean;
reset: boolean;
};
// false to hide all modes
modes: {
// false to hide interaction mode
interaction: boolean;
fitToScreen: boolean;
sticky: boolean;
};
// false to hide pagination
pagination: boolean;
}>;
type NestedFlags<T> = {
readonly [P in keyof T]?: T[P] extends object ? false | NestedFlags<T[P]> : T[P];
};
paginate
// start: starting index of the pagination
// size: page size (from settings.pageSize)
// Returns Graph of given page
(start: number, size: number) => Promise<Graph>
If provided, data
does not have to be set and graph visualization will automatically fetch the first page on initial
render. If not provided, pagination is hidden.
expand
// ids: ids of the selected vertices to expand from
// hops: number of hops to fetch from selected vertices
// Returns expanded Graph
(ids: Id[], hops: number) => Promise<Graph>
If not provided, expand / focus is hidden.
eventHandlers
// id: id of the child vertex targeted with the event(if any)
// entity: the entity or parent of the vertex(identified by the id parameter) targeted with the event
type EntityEventCallback = (event: Event, id: Optional<string>, entity: Entity) => void;
// eventType: supported <g> element event attributes without the -on- prefix
// children: event handlers for child entities
interface _EntityEventHandlers {
[eventType: string]: EntityEventCallback | _EntityEventHandlers;
children?: EntityEventHandlers;
}
type EntityEventHandlers = Optional<_EntityEventHandlers>;
// vertex: callbacks that handle events fired by vertices
// edge: callbacks that handle events fired by edges
interface _AllEventHandlers {
vertex: EntityEventHandlers;
edge: EntityEventHandlers;
}
type AllEventHandlers = Partial<_AllEventHandlers>;
persist
type GraphActionType = 'drop' | 'expand' | 'focus' | 'group' | 'ungroup' | 'undo' | 'redo' | 'reset';
// vertexIds: ids of the vertices targeted with the action
// edgeIds: ids of the edges targeted with the action
interface GraphAction {
type: GraphActionType;
vertexIds?: NonEmptyArray<Id>;
edgeIds?: NonEmptyArray<Id>;
}
// action: the graph action to persist to a datasource
type Persist = (action: GraphAction) => Promise<void>;
fetchActions
// Gets executed only once when the graph loads for the first time
// Contains code to retrieve graph actions to apply on the graph initially
type FetchActions = () => Promise<GraphAction[]>;