@hanica-dwa/sijs-diagram-renderer

Diagram Renderer Module

The Diagram Renderer Module is responsible for actually rendering the diagram. It contains two main files called the DiagramRenderer.tsx and the DiagramRenderModuleApi.ts. It also contains a folder called 'helperFunctions' which holds three files, those files will be explained in further detail later in the readme.

The diagram renderer module supports a few default shapes such as text and lines, if the user wants more shapes he can do so by registering a custom module on the renderer.

Developing

This module depends on the DiagramManipulator module.

1. Install the dependencies.
   npm i
2. Run the tests.
   npm run test
3. Build the module
   npm run build
4. Publish the module.

DiagramRenderer.tsx

We will look at how to register a custom manipulation module so the user can use their own diagram module, and take a deeper look at the functions the renderer uses in order to work.

constructor()

In order for the renderer to work a new instance of the diagramRenderer class has to be created. The diagramRenderers' constructor takes 5 (of which one is optional) parameters. The first parameter is the defaultRenderingModule which contains default shapes such as text and lines. It also takes a projectSaveFunction, in order to save the changes made in the project, and a selectShapeFunction which makes shapes selectable for the user. Finally it also requires a currentUserRetrieveFunction which is used to display the user working on the diagram.

registerModule()

After creating the new instance of the renderer the user can register a module which can be done by calling the registerModule() method on the renderer. This method requires a custom module render API as a parameter and after registering the module the user will be able to create a diagram of the registered module type.

Usage

Simply call the 'registerModule()' method on the renderer and pass it a parameter of type DiagramManipulatorModuleAPI. If using a custom manipulator module, it NEEDS to extend from a class that in it's turn extends DiagramManipulatorModuleAPI.

  newRenderer.registerModule(new BlockDiagramRenderAPI());

render()

After registering the module the 'render()' method can be called on the instance of the renderer. This method takes one parameter of type Project. The Project type will be explained in the diagramManipulator readme.

After calling the 'render()' method with a correct Project datastructure, the render() method will try and find the supporting module by calling the method 'findSupportingModule()' which takes the diagram type defined in the project as a parameter. If the module is found the 'render()' method will return a new canvas and render the different SVG elements on the canvas for that specific diagramType. If the module is not found it will simply state 'No module found that supports this datatype'.

Usage

      renderer.render(project)

renderShape() and renderLine()

The renderShape and renderLine methods are used to render a Shape or a Line. Based on the diagramType passed as a parameter the methods will use the diagramType's module to render the Shape/Line, or if not supported, use the default rendering module.

Usage

In the example below we call the renderShape method and pass in a diagramType. We also get an example shape and pass it to the method so it can start to render the actual shape based on the dataObject provided. This works the same for a Line.

              {renderer.renderShape(
                diagramType,
                renderer.getExampleShape(diagramType, shapeType)
              )}

DiagramRenderModuleApi.ts

The DiagramRenderModuleApi does nothing else then exporting an interface. This interface contains the methods 'renderShape()' and 'renderLine()'. These are used in the DiagramRenderer and make sure the methods are implemented. It is important for custom render modules that they implement this interface.

helperFunctions

The diagramRenderer module also contains a folder called 'helperFunctions'. This folder contains 3 files.

The first file is a file called 'BasicNoFillRectangle.tsx' which simply returns a rect based on the props given to the function. This method can be used by custom Shapes to display users that have selected a Shape. For more info check the tutorial on the wiki

A second file called 'DragAndDropHelper.tsx' which should be imported into ALL the shapes the user desires to be drag- and drop-able.

The function dragMove() is passed as a parameter in the setTimeOut which applies the drag and drop mechanism to the svg element.

To make a Shape drag and droppable the DragAndDropHelper should be called inside the render method of the Shape. The user needs to pass in the dataObject of the Shape, a ref (created by Reacts' useRef method) and the manipulationCallbacks for this shape. More detail is given in the tutorial 'Creating your own custom shape' on the wiki

  DragAndDropHelper(dataObject, ref, manipulationCallbacks);

The third file is 'SelectorHelper.tsx' which simply returns a function if a shape is selectable. This method is used by shapes in their onClick method in order to select a shape, after which their properties can be edited such as their color, width or height. This method needs to be called inside the onClick attribute of the Shape in their respective render method.

Usage

      <rect
        id={dataObject.uuid}
        key={dataObject.uuid}
        x={dataObject.x}
        y={dataObject.y}
        width={dataObject.width}
        height={dataObject.height}
        fill={dataObject.color}
        data-testid="block"
        onClick={SelectorHelper(dataObject, manipulationCallbacks)} <--- onClick the SelectorHelper will be called.
        ref={ref as React.RefObject<SVGRectElement>}
      />