zhongyw/react-dag

This is a base implementation of wrapping jsplumb with react + redux to be more usable in a react based environment

React-dag

React wrapper for jsplumb. Helps in rendering a Directed Acyclic Graph.

A demo of this module being used can be found here Demo.

Install

npm install react-dag

Usage

  import ReactDAG from "react-dag";
  class MyComponent extends Component {
    ...
    render() {
      return (
        <ReactDAG
          nodes={cloneDeep(this.state.nodes)}
          connections={cloneDeep(this.state.connections)}
          jsPlumbSettings={defaultSettings}
          connectionDecoders={[
            transformConnectionDecoder,
            conditionConnectionDecoder,
          ]}
          connectionEncoders={[
            transformConnectionEncoder,
            conditionConnectionEncoder,
          ]}
          onChange={({
            nodes: n,
            connections: c,
          }: {
            nodes: INode[];
            connections: IConnectionParams[];
          }) => {
            this.setState({ nodes: n, connections: c });
          }}
          eventListeners={eventListeners}
          registerTypes={registerTypes}
          zoom={this.state.zoom}
        >
          {this.state.nodes.map((node, i) => {
            const Component = getComponent(node.config ? node.config.type : "");
            return <Component key={i} id={node.id} />;
          })}
        </ReactDAG>
      );
    }
  }

Older version docs:

For older version (version 1.x) please follow the readme here README. Since this is a re-write the API is completely different and includes for a lot of additional functionality not available in the previous version

Props

• settings - Settings to be used for JsPlumb. Check out dag-settings.ts for base settings that are available.

  Note

  The settings prop is used as argument while creating a jsplumb instance. For individual nodes to use specific settings please import the same in each node module.

• nodes: Set of nodes to be rendered in the DAG. A node in the nodes array takes the type of INode - type.

  • Every node has to have an id to be uniquely identified
  • And an optional config that is needed for individual nodes

• connections: The set of connections are the rules for connecting the above nodes. A connection in the connections array takes the type of IConnectionParams type

  • Every connection MUST have a sourceId and a targetId.
  • Optionally it can have other information too. The extra information should be evident when using encoders and decoders for connections.

• connectionDecoders: A connection decoder is nothing but a pure function that accepts a connection parameter and the set of nodes. This decoder helps in decoding a connection that has information about, say its endoint, to something more generic.

  An example would be,

  • Lets say we have two nodes. NodeA with two endpoints (left and right) and NodeB with only one endpoint (a source) and the entire node acts as a target (meaning it can accept incoming connections anywhere on its left side).
  • Now the right end point from NodeA connects to NodeB.

  When that happens jsPlumb returns a connection that is of the form,

    {
      sourceId: "NodeA-right-endpoint",
      targetId: "NodeB"
    }

  (if we chose to name the end points of NodeA as NodeA-right-endpoint and NodeA-left-endpoint)

  In order to decode this to be,

    {
      sourceId: "NodeA",
      targetId: "NodeB"
    }

  a decoder function is used. The list of decoders are passed a connection object (current connection), jsplumb instance and the list of nodes. Each function has logic to convert the incoming connection to what is desired. And it returns the modified connection object. The same is passed to subsequent decoders to decode the connection objects for different nodes.

  The reduce logic of decoders looks like this,

  const newConnObj = encoders.reduce(
    (prev, curr) => curr(prev, this.state.jsPlumbInstance, this.props.nodes),
    { ...connObj }
  );

• connectionEncoders: As the name mentions a connection decoder converts a connection object from jsplumb to the one desired.

  An example of a encoder and a decoder can be found here

• eventListeners: Is a key-value map where key represents the event and the value represents the callback to call when the event occurs. This is useful if you want to bind to specific events in jsplumb instance. For a list of possible events please check jsplumb docs here

• registerTypes: Is a key-value map where the key represents the type name and the value represents the paint style object. This is useful if you want to set types in jsplumb instance that you can use to style nodes/connections while drawing the graph. jsplumb docs for registerConnection/registerEndpoint types can be found here

• zoom: Is an integer that represents the zoom level of the entire graph.

• onChange: Every time there is a change in the state of the graph (nodes/connections), the onChange callback is called back. This is similar to onChange in any input type html elements.

• children: The children should be an array of different types of nodes that needs to be rendered. Each child needs to have a unique id to be identified.

  ReactDAG accepts the children and wraps with extra properties that it needs to initialize and render itself. In addition to the id prop provided as part of the node, ReactDAG also provides the following props,

  • config: a config object if provided as part of the node in the nodes array.

  • initNode: a initializing function. Every node that needs to be rendered in the DAG MUST call this.props.initNode function. The function accepts 4 parameters in this order,

    • nodeId: the unique node identifier passed initially.
    • endPointParams: A list of endpoints to be added to the node. This endpointParam type reference can be found here. The endpoint param is the same object that you would pass to addEndpoint function in jsplumb. It accepts an element, params and referenceParams
    • makeSourceParams: is the same object passed to makeSource function in jsplumb. This is to make the entire node a source (or part of it based on the paramters). A doc reference for makeSource can be found here
    • makeTargetParams: Similar to makeSource. A doc reference for makeTarget in jsplumb can be found here

• onDelete: A callback function when deleting a node. This function has to be called if the DAG has to be re-rendered.