Interface

The Javascript component has the following interface:

Properties

• data: Initial graph data
• settings: Settings to configure graph layout, page size, etc.
• styles: Configuration of vertex / edge appearance
• featureFlags: Hierarchical flags to hide specified features or group of features
• paginate: Callback to retrieve given page of graph data
• expand: Callback to retrieve n-hops neighbors of specified vertices
• eventHandlers: Callbacks to handle events fired by graph entities (vertices/edges)
• persist: Callback to save a modification applied on the graph to a datasource
• fetchActions: Callback to retrieve actions(from a datasource) to apply on the graph on first load

Events

• 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;
  // Labels associate with entity
  labels?: string[];
}

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;
  // Filters correspond to Legend entries that also controls visiblity/styling highlights
  filters: Filter[];
  // Smart groups settings
  smartGroup: SmartGroup;
  // Smart expand settings
  smartExpand: SmartExpand;
}

export interface Filter extends FromTemplate {
  // Marks if Styling is enabled for a filter item and the vertices/edges that it controls
  stylingEnabled?: boolean;
  // Marks if Visibility is enabled for a filter item and the vertices/edges that it controls
  visibilityEnabled?: boolean;
  // Conditions deciding which vertices/edges will be affected by the filter item
  conditions?: Conditions<FilterCondition>;
  // The component (eg vertex/edge) for which the filter is defined
  component: FilterComponent;
  // The target on which this filter applies (vertex, source, target, edge, ingoing, outgoing)
  target: ApplyTarget;
  // The various properties (like colors, icons, image, animations) of a vertex/edge that this filter's state can affect
  properties: FilterProperties;
  // Marks if aggregation is enabled for a filter item, based on which computation is performed
  aggregationEnabled?: boolean;
  // The various aggregation properties configured on this filter
  aggregation?: PropertyAggregation[];
  // Marks whether styling is configured for this filter
  stylingConfigured?: boolean;
  // The properties and range on which interpolation will apply
  interpolation?: FilterInterpolation;
}

// Graph animations are applied within the filter properties
export interface GraphAnimation {
  // The type of animation that is desired, two animation types are supported, flashing and pulsating
  animationType: 'flashing' | 'pulsating';
  // The duration in seconds that the animation loop shoud last
  duration: number;
}

export interface LegendEntry extends Filter {
  // The title of the legend entry when the filter is shown in the legend area
  legendTitle?: string[];
  // Marks if the legend entry is visible in the legend area
  legendEntryVisible: boolean;
  // The style of legend entry in the legend area
  style: Partial<VertexStyle> | Partial<EdgeStyle>;
  // The veritces / edges on which this legend entry has influence
  filteredNodes: Vertex[] | Edge[];
}

export interface FilterInterpolation {
  // The property on which interpolation is applied
  property: string;
  // The minimum range for interpolation
  min?: number;
  // The maximum range for interpolation
  max?: number;
}

// Different types of aggregation functions supported
export type AggregationType = 'average' | 'min' | 'max' | 'sum' | 'count' | 'distinctCount';

export interface PropertyAggregation {
  // The property of vertex or edge on which aggregation is computed
  source: string;
  // The type of aggregation function used for computation
  type: AggregationType;
}

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)
}

// When selecting grid layout, if neither rows or columns are defined, the graph will be displayed in a square grid
// If rows are selected, it will be displayed in a grid with that many rows
// If columns are selected it will be displayed in a grid witht that many columns
// If both rows and columns are selected, only the rows will be taken into consideration
interface GridLayoutSettings extends BaseLayoutSettings, SpacingLayoutSettings {
  type: 'grid';
  rows?: number;
  columns?: number;
}

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;
  };
  // When turned on, network evolution will keep the original vertex positions of the graph
  // when vertices and edges unfold during playback
  preservePositions: boolean;
}

interface ExpandCondition extends FilterCondition {
  component: FilterComponent;
}

type SmartExplorerType = 'expand' | 'group';

interface SmartExplorer extends FromTemplate {
  readonly type: SmartExplorerType;
  name: string;
}

interface SmartExpand extends SmartExplorer {
  readonly type: 'expand';
  numberOfHops: Optional<number>;
  navigation: Conditions<ExpandCondition>;
  destination: Conditions<ExpandCondition>;
}

interface SmartGroup extends SmartExplorer {
  readonly type: 'group';
  automatic: boolean;
  enabled: boolean;
  groupBy?: string;
  conditions: Conditions<ExpandCondition>;
}

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.

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 size

Rule Expressions

Rule 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 / edge
• modifier := 'hover' | 'selected' | 'unselected' | 'group'
• conditionExpression: JavaScript expression that can access any property of evaluated vertex / edge.

Example rules:

• *: applies to all elements
• vertex: applies to all vertices
• edge: applies to all edges
• .example: applies to all elements with example class specified
• vertex.example: applies to all vertices with example class
• vertex:selected: applies to all selected vertices
• vertex[id > 10]: applies to all vertices with id > 10
• vertex[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[]>;