ruclib-data-flow

A highly configurable component for creating interactive data flow diagrams and canvases. It allows users to visually represent relationships between different data entities, tables, or process steps, and connect them with customizable links.

Features

• Dynamic Canvas: Create a workspace where users can add, move, and arrange containers or nodes.
• Customizable Nodes: Define the appearance and behavior of nodes using a flexible HTML markup structure.
• Element Palette: Optionally display a palette of predefined elements that can be dragged onto the canvas.
• Interactive Connections: Draw different types of connection lines (e.g., Arrowed, Dotted, Plain) between nodes.
• In-place Editing: Double-click on nodes or table rows to edit attributes directly.
• Context Menus: Access a customizable action menu by double-clicking on a node.
• Grid Layout: Toggle between a free-form canvas and a structured grid view.
• Search Functionality: Search for specific content within tables on the canvas.
• Theming: Apply custom theme classes for tailored styling.

Installation Guide

Install the Entire Library

npm install @uxpractice/ruc-lib

Install Individual Component

If you only need the Data Flow component:

npm install @ruc-lib/data-flow

Usage

1. Import Styles

In your global styles.scss file, import the necessary CSS from jointjs and the component's own styles. The path may vary based on your project setup.

// Required for layout and diagramming
@import "jointjs/css/layout.css";

// For Complete Library
@import "@uxpractice/ruc-lib/data-flow/lib/data-flow.scss";

// For Individual Package
@import "@ruc-lib/data-flow/lib/data-flow.scss";

2. Import the Module

In your Angular module file (e.g., app.module.ts), import the RuclibDataFlowModule:

// For Complete Library
import { RuclibDataFlowModule } from '@uxpractice/ruc-lib/data-flow';

// For Individual Package
import { RuclibDataFlowModule } from '@ruc-lib/data-flow';

import { AppComponent } from './app.component';
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    RuclibDataFlowModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule {}

3. Use the Component

In your component's template, use the <uxp-ruclib-data-flow> selector:

<uxp-ruclib-data-flow
    [rucInputData]="dataFlowInput"
    [customTheme]="customTheme"
    (rucEvent)="handleDataFlowEvents($event)">
</uxp-ruclib-data-flow>

API Reference

Component Inputs

Input	Type	Description
rucInputData	IRucDataFlow	The main configuration object for the data flow.
customTheme	string	An optional CSS class for custom theming.

Component Outputs

Output	Type	Description
`ruc
rucEvent	any	Emits events when changes occur in the data flow component (e.g., node added, link created).

rucInputData (IRucDataFlow)

This is the main configuration object for the Data Flow component.

Property	Type	Description
title	string	The main title displayed for the data flow component.
defaultCellHeader	string	Default header text for new containers/tables added to the canvas.
line	ILine	Configuration object for the connection lines. See ILine table below.
drawGrid	boolean	If true, a grid pattern is drawn on the canvas background. Default is false.
showMenuOnDoubleClick	boolean	If true, a context menu appears when a node is double-clicked. Default is false.
fieldValues	object	An object containing default values for the dynamic fields defined in htmlMarkup.
htmlMarkup	IHTMLMarkup	A structured object that defines the HTML template for each node on the canvas. See IHTMLMarkup table.
hasElements	boolean	If true, displays a palette of predefined elements that can be dragged onto the canvas. Default is false.
elements	IElement[]	An array of element configurations for the palette. Used when hasElements is true. See IElement table.
attributes	IAttributes	An object to control global attributes of the nodes, like size. See IAttributes table below.
menuOptions	any[]	An array of options to display in the context menu.

ILine

Property	Type	Description
type	ELineType	The style of the connection line. Can be ELineType.Plain, ELineType.Arrowed, ELineType.Dotted, etc.

IElement

Property	Type	Description
icon	string	Path to the default icon for the element in the palette.
activeIcon	string	Path to the icon used when the element is active or selected.
title	string	The label displayed for the element in the palette.

IAttributes

Property	Type	Description
width	number	The width of the nodes on the canvas.
height	number	The height of the nodes on the canvas.
titleCharacterLimit	number	The maximum number of characters to display for a node's title.

IHTMLMarkup

This object defines the structure of a custom node.

Property	Type	Description
tagName	string	The HTML tag for the element (e.g., 'div', 'p', 'img').
selector	string	A unique identifier for this part of the markup within the node.
groupSelector	string	Groups elements together. Used for applying fieldValues.
className	string	CSS class name(s) to apply to the element.
style	object	An object of CSS styles to apply to the element.
attributes	object	HTML attributes to apply (e.g., {'data-attribute': 'title'}).
textContent	string	The static text content for the element.
children	IHTMLMarkup[]	An array of child markup objects, allowing for nested structures.

Example Configuration

Here's an example of how to configure the Data Flow component in your component's TypeScript file.

import { Component } from '@angular/core';

// For Complete Library
import { IRucDataFlow, ELineType } from '@uxpractice/ruc-lib/data-flow';

// For Individual Package
// import { IRucDataFlow, ELineType } from '@ruc-lib/data-flow';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
  customTheme = 'ruc-dark-theme';

  dataFlowInput: IRucDataFlow = {
    title: 'Data Flow Pipeline',
    defaultCellHeader: 'New Step',
    line: {
      type: ELineType.Arrowed,
    },
    drawGrid: true,
    showMenuOnDoubleClick: true,
    hasElements: true,
    attributes: {
      width: 65,
      height: 65,
      titleCharacterLimit: 12,
    },
    fieldValues: {
      icon: '../assets/pipeline/generic.png',
      title: 'Generic',
      isMenuOpen: 'false',
      activeIcon: '../assets/pipeline/active/generic.png',
    },
    elements: [
      {
        icon: '../assets/pipeline/migration.png',
        activeIcon: '../assets/pipeline/active/migration.png',
        title: 'Migration',
      },
      {
        icon: '../assets/pipeline/validation.png',
        activeIcon: '../assets/pipeline/active/validation.png',
        title: 'Validation',
      },
      // ... more elements
    ],
    htmlMarkup: {
      tagName: 'div',
      selector: 'htmlRoot',
      className: 'canvas__element',
      children: [
        {
          tagName: 'div',
          className: 'canvas__element--icon',
          selector: 'iconWrapper',
          children: [
            {
              tagName: 'img',
              groupSelector: 'field',
              attributes: { 'data-attribute': 'icon' },
            },
          ],
        },
        {
          tagName: 'p',
          className: 'canvas__element--title',
          groupSelector: 'field',
          textContent: 'Node',
          attributes: { 'data-attribute': 'title' },
        },
      ],
    },
    menuOptions: [
        { label: 'Properties', action: 'properties' },
        { label: 'Delete', action: 'delete' }
    ],
  };

  handleDataFlowEvents(event: any) {
    console.log('Data Flow Event:', event);
    // Example: if(event.type === 'delete') { ... }
  }
}

Contribution

Contributions are welcome! Feel free to open issues or pull requests for any enhancements or fixes.

Acknowledgements

Thank you for choosing the Data Flow Component Library. If you have any feedback or suggestions, please let us know!