Tools

Tools are a way for users to interact with the pages. There are several pre-implemented tools that can be extended if additional functionality is needed. A tool consists of its functionality and a representation in the toolbar.

The design is intentionally generic to allow for easy customizability.

Currently implemented tools include move, doodle, text, and others, all located in their respective directories.

Register a new tool

To implement a new tool can be a a bit tricky especially if you are not fully invested into the codebase. The following steps should help you to get started if you want to implement some custom functionality.

First of all lets have a look of the structure of the tools folder (apps/fullstack/components/editor):

tools/
├── toolbar.tsx
├── toolsFactory.tsx
├── types.ts
├── [tool_dirs]

To create a new tool we have to register it at multiple places. First of we create add a type identifier in the types.ts file.

// types.ts
export type Tool =
    | "interaction"
    | "movePage"
    | "doodle"
    | "snipEditor"
    | "text"
    | "image"
    | "placement"
    | "MY NEW TOOL HERE";

In the same file as you might have already seen a ToolComponent needs to comply to the following types:

export type ToolComponents = {
    name: Tool;
    Toggle: React.ComponentType<ToolToggleProps>;
    Help: React.ComponentType;
    Submenu?: React.ComponentType<ToolSubmenuProps>;

    /** An overlay allows to render any
     * additional information if a tool is active.
     * E.g. for text
     *
     * Can only be shown on a single page
     * at the time.
     */
    Overlay?: React.ComponentType;
    ContextProvider?: React.ComponentType<ToolContextProps>;
};

As long as our tool component complies with the ToolComponents type, you can proceed to register it in the toolsFactory.tsx file.

// toolsFactory.tsx
import { MY_NEW_TOOL_HERE_comp } from './tools/MY_NEW_TOOL_HERE';

export function getToolComponents(tool: Tool): ToolComponents {
    switch (tool) {
        case "movePage":
            return MoveTool;
        case "interaction":
            return InteractionTool;
        case "doodle":
            return DoodleTool;
        case "text":
            return TextTool;
        case "image":
            return ImageTool;
        case "placement":
            return PlacementTool;
        case "MY NEW TOOL HERE":
            return MY_NEW_TOOL_HERE_comp;
        default:
            throw new Error("Unknown tool");
    }
}

Finally you have to define under which conditions the tool should be enabled. This can be done in the apps/fullstack/components/editor/index.tsx file. Here you just need to add your tool in the getAllowedTools function:

function getAllowedTools(perms: Perms) {
    const tools: Tool[] = ["interaction", "movePage"];

    if (perms.pWrite) {
        tools.push("doodle");
        tools.push("text");
        tools.push("placement");
        tools.push("image");
    }
    tools.push("MY_NEW_TOOL_HERE")

    return tools;
}

Implementing a Tool Component

For details on how to implement a tool component please check the already implemented tools. The placement tool should be a good start.