contribute-custom-tool.adoc

How to contribute custom tool to a Diagram palette

This document shows the steps needed for an application to contribute its own custom tools.

An example of a simple tool is available on Papaya::OperationalActivity node to illustrate (see PapayaOperationActivityLabelDetailToolContribution.tsx and EditProjectView.tsx).

The tool component

By contributing a new custom tool, you add a React component to the palette. This component must use as props DiagramPaletteToolContributionComponentProps. To avoid inconsistency palette representation, we encourage the use of a simple icon, but by definition, you can contribute what you want as a React component. If needed, this icon can open a modal with more complex UI.

This component can perform some GraphQL queries and mutations. To retrieve the editingContextId and the representationId, you can use the following code in your component:

const { projectId: editingContextId, representationId } = useParams<EditProjectViewParams>();

Contribution

Once the component has been developed, we need to contribute it to the DiagramPaletteToolContext.Provider. To do this, you need to add a DiagramPaletteToolContribution to the DiagramPaletteToolContextValue array pasted to the provider. The DiagramPaletteToolContribution need two props, the component and a canHandle function, this function will be called each time we create a palette on the diagram. It must return true only for the palette where the custom tool needs to be added. To compute that, this function has two parameters the diagramId and the diagramElementId, note that for the diagram palette diagramId = diagramElementId. To retrieve the node metadata, you can use the hook useNodes and filter all the node by the diagramElementId.

Specify a reference position

Depending on the tool purpose, the click coordinates may be necessary for the result action. For example, when the tool creates a new element on the diagram. To achieve this, we’ve added a new API IDiagramInputReferencePositionProvider. Where it’s possible to define the way the reference position must be retrieved depending on the input.

public interface IDiagramInputReferencePositionProvider {

    boolean canHandle(IInput diagramInput);

    ReferencePosition getReferencePosition(IInput diagramInput, IDiagramContext diagramContext);
}

For the generic tool used in sirius-component, the provider is specified in the service GenericDiagramToolReferencePositionProvider.

The basic case is to use the position of the pallet as a reference position. These coordinates are available in the props DiagramPaletteToolContributionComponentProps.