React Flow Perspective Module

Breaking change in v2.0.0

The module ID was renamed from com.bwdesigngroup.reactflow to dev.bwdesigngroup.perspective.libraries.ReactFlow to align with Ignition's reverse-DNS convention. Gateways with v0.3.0 or earlier installed must uninstall the old module before installing v2.0.0 — the gateway sees the new ID as a separate module. The Java package path was renamed alongside it for consistency.

A custom React Flow integration for Inductive Automation's Ignition Perspective platform that adds a component for interactive flow diagrams with embedded Perspective views.

Overview

This module provides a React Flow-based component that can render flow diagrams with nodes and edges, supporting embedded Perspective views and interactive events. It's designed to integrate seamlessly with Ignition's Perspective module system.

Version Strategy

This module is maintained across multiple Ignition versions with the following release strategy:

Version 1.x (main branch): For Ignition 8.3+ - Active development with new features ✨ You are here
Version 0.x (legacy/8.1 branch): For Ignition 8.1.x - Maintenance and critical fixes only

When installing, choose the version that matches your Ignition platform:

Ignition 8.3+: Download the latest v1.x.x release
Ignition 8.1.x: Download the latest v0.x.x release

See Releases for available versions.

Features

Flow Diagrams: Create interactive node-edge diagrams using React Flow v12
Perspective View Embedding: Embed Perspective views directly inside nodes with full parameter support
Multiple Node Types: Support for default (labeled), view (embedded), and group (container) node types
Interactive Events: Comprehensive event system for node/edge clicks, additions, and removals
Dynamic Updates: Real-time updates when nodes/edges change via property bindings
Customizable Styling: Full CSS class and inline style support for nodes, edges, and backgrounds
Connection Management: Interactive edge creation/deletion with handle-based connections
Zoom-Based Visibility: Show/hide nodes at specific zoom levels for performance and clarity
Performance Optimizations: Render only visible elements for large diagrams (100+ nodes)
Background Patterns: Grid patterns (dots, lines, cross) with customizable appearance
Navigation Controls: Optional minimap and zoom/fit-view controls
Viewport Control: Programmatic pan and zoom with smooth animations
Snap to Grid: Optional grid snapping for precise node positioning
Theme Support: Light, dark, and system theme modes
Flexible Interactions: Granular control over dragging, connecting, selecting, and focusing

Quick Start

Installation

Download the .modl file from Releases
Install via Ignition Gateway Config → Modules → Install or Upgrade Module
Restart the gateway
The "React Flow" component will appear in the Perspective Designer component palette

Basic Usage

Create a simple flow diagram with two connected nodes:

{
  "nodes": [
    {
      "id": "node1",
      "type": "default",
      "data": { "label": "Start Process" },
      "position": { "x": 50, "y": 100 },
      "handles": [
        { "id": "out1", "type": "source", "position": "right" }
      ],
      "style": { "classes": "" }
    },
    {
      "id": "node2",
      "type": "default",
      "data": { "label": "End Process" },
      "position": { "x": 300, "y": 100 },
      "handles": [
        { "id": "in1", "type": "target", "position": "left" }
      ],
      "style": { "classes": "" }
    }
  ],
  "edges": [
    {
      "id": "edge1",
      "source": "node1",
      "target": "node2",
      "sourceHandle": "out1",
      "targetHandle": "in1",
      "type": "smoothstep",
      "animated": false,
      "style": { "classes": "" }
    }
  ]
}

Embedding a Perspective View

Use view nodes to embed Perspective views:

{
  "id": "viewNode1",
  "type": "view",
  "position": { "x": 100, "y": 100 },
  "view": {
    "viewPath": "ProcessControl/ValveControl",
    "viewParams": { "tagPath": "[default]Line1/Valve_001" },
    "useDefaultWidth": true,
    "useDefaultHeight": true,
    "rootStyle": { "classes": "" }
  },
  "handles": [
    { "id": "in", "type": "target", "position": "left" },
    { "id": "out", "type": "source", "position": "right" }
  ],
  "style": { "classes": "" }
}

Node Types

Default Node

Simple labeled nodes for basic flow elements. Display text via the data.label property.

Use cases: Process steps, decision points, status indicators

View Node

Embeds a Perspective view inside the node with full parameter support. Configure view path, parameters, and sizing options.

Use cases: Equipment controls, live data displays, interactive forms

Sizing options:

useDefaultWidth/Height: Use view's default dimensions or set custom size
useDefaultMinWidth/MinHeight: Control minimum dimensions
rootStyle: Apply custom CSS to the embedded view container

Group Node

Container nodes that can hold other nodes. Child nodes use parentId to reference the group and extent: "parent" to stay within bounds.

Use cases: Organizing complex flows, creating hierarchical diagrams, grouping related processes

Advanced Features

Zoom-Based Node Visibility

Control which nodes appear at different zoom levels for better performance and user experience:

{
  "id": "detailNode",
  "type": "default",
  "data": { "label": "Detail View (shows when zoomed in)" },
  "position": { "x": 0, "y": 0 },
  "visibility": {
    "minZoom": 1.5,  // Only visible when zoomed in to 150% or more
    "maxZoom": null  // No maximum (always visible when zoomed in)
  }
}

Use cases:

Show overview nodes when zoomed out, detail nodes when zoomed in
Improve performance by hiding decorative nodes at low zoom
Create multi-level diagrams with different levels of detail

Performance Optimization

For large diagrams with 100+ nodes, enable performance mode:

{
  "onlyRenderVisibleElements": true
}

This renders only nodes/edges currently visible in the viewport, significantly improving performance.

Viewport Control

Programmatically control pan and zoom with smooth animations:

{
  "viewport": {
    "x": 100,      // Pan horizontally
    "y": 50,       // Pan vertically
    "zoom": 1.5    // Zoom level (1 = 100%, 0.5 = 50%, 2 = 200%)
  }
}

Bind these properties to control the view programmatically or read them to track user navigation.

Snap to Grid

Enable grid snapping for precise node positioning:

{
  "interactionConfig": {
    "snapToGrid": true,
    "snapGrid": [15, 15]  // [horizontal spacing, vertical spacing] in pixels
  }
}

Edge Types and Animation

Choose from multiple edge rendering styles:

{
  "id": "animatedEdge",
  "source": "node1",
  "target": "node2",
  "type": "smoothstep",  // Options: straight, step, smoothstep, bezier
  "animated": true,      // Animated flow indicator
  "label": "Active",     // Optional edge label
  "style": { "classes": "custom-edge" }
}

Configuration Reference

Component Props

Property	Type	Description
`nodes`	Array	Node configurations (id, type, position, data, handles, style, visibility)
`edges`	Array	Edge configurations (id, source, target, type, animated, label, style)
`viewport`	Object	Current viewport position and zoom (x, y, zoom)
`background`	Object	Background styling and grid pattern configuration
`theme`	String	Color scheme: "light", "dark", or "system"
`interactionConfig`	Object	User interaction settings (see below)
`zoomConfig`	Object	Zoom limits and controls (minZoom, maxZoom, zoomOnScroll, zoomOnPinch, zoomOnDoubleClick)
`onlyRenderVisibleElements`	Boolean	Performance mode: only render visible elements
`showMiniMap`	Boolean	Display minimap overview
`showControls`	Boolean	Display zoom and fit-view controls
`style`	Object	Component container styling

Interaction Config

Control how users interact with the diagram:

Property	Type	Default	Description
`nodesDraggable`	Boolean	true	Allow dragging nodes
`nodesConnectable`	Boolean	true	Allow creating connections between nodes
`nodesFocusable`	Boolean	true	Enable Tab key navigation between nodes
`edgesFocusable`	Boolean	true	Enable Tab key navigation between edges
`panOnDrag`	Boolean	true	Click and drag to pan the viewport
`fitView`	Boolean	true	Auto-fit nodes to viewport on mount/update
`snapToGrid`	Boolean	false	Snap nodes to grid when dragging
`snapGrid`	Array	[15, 15]	Grid spacing for snapping [x, y]

Events

Event	Payload	Description
`onNodeClicked`	`{ nodeId, node }`	User clicked a node
`onEdgeClicked`	`{ edgeId, edge }`	User clicked an edge
`onEdgeAdded`	`{ edgeId, edge }`	New connection created
`onEdgeRemoved`	`{ edge }`	Connection deleted (Backspace/Delete key)
`onNodeRemoved`	`{}`	One or more nodes removed
`onViewportChange`	`{ x, y, zoom }`	Viewport panned or zoomed

Examples

Multi-Level Diagram with Zoom Visibility

{
  "nodes": [
    {
      "id": "overview",
      "type": "default",
      "data": { "label": "System Overview" },
      "position": { "x": 100, "y": 100 },
      "visibility": { "minZoom": null, "maxZoom": 1.0 }
    },
    {
      "id": "detail1",
      "type": "view",
      "view": { "viewPath": "Details/Subsystem1" },
      "position": { "x": 100, "y": 100 },
      "visibility": { "minZoom": 1.0, "maxZoom": null }
    }
  ]
}

Grouped Nodes

{
  "nodes": [
    {
      "id": "group1",
      "type": "group",
      "data": { "label": "Process Group" },
      "position": { "x": 0, "y": 0 },
      "style": { "classes": "process-group" }
    },
    {
      "id": "child1",
      "type": "default",
      "parentId": "group1",
      "extent": "parent",
      "data": { "label": "Step 1" },
      "position": { "x": 20, "y": 20 }
    }
  ]
}

Development

This component is built using:

React Flow v12 (@xyflow/react)
TypeScript 5.2+
React 18
Ignition Perspective SDK 2.1.47+
Tailwind CSS for styling

Building from Source

# Install dependencies
cd web && npm install

# Development mode (watch for changes)
npm run dev

# Production build
npm run build

# Build complete module
cd ..
./gradlew build

# Deploy to gateway
./gradlew deployModl -PhostGateway=localhost:8080

Project Structure

├── common/          # Shared Java code and constants
├── gateway/         # Gateway hook and component registration
├── designer/        # Designer tools and utilities
├── web/             # TypeScript/React frontend
│   ├── src/
│   │   ├── components/   # React Flow component implementation
│   │   ├── schemas/      # Component metadata and prop schemas
│   │   └── css/          # Tailwind styles
└── docker/          # Docker Compose for development

Documentation

For detailed API documentation, refer to:

Component property descriptions in Perspective Designer
TypeScript interfaces in web/src/components/reactflow/
Meta configuration in web/src/components/reactflow/meta/ReactFlowComponent.meta.ts

License

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome! Please follow the standard GitHub flow:

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Create a pull request

Bugs and Feature Requests

Please report bugs and request features using the GitHub Issues. If this implementation is missing a feature you need that is available in the React Flow Library, please open an issue to discuss adding it.

Acknowledgements

This project uses React Flow, a powerful library for building interactive flow diagrams in React applications. Special thanks to the React Flow team for their excellent work.

Name		Name	Last commit message	Last commit date
common		common
designer		designer
gateway		gateway
gradle		gradle
web		web
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE.txt		LICENSE.txt
README.md		README.md
build.gradle.kts		build.gradle.kts
gradle.properties.template		gradle.properties.template
gradlew		gradlew
gradlew.bat		gradlew.bat
settings.gradle.kts		settings.gradle.kts

Latest commit

History

Folders and files

Repository files navigation