@collboard/modules-sdk

Collboard modules SDK

Modules SDK toolkit for Collboard.com. Here is the sample of very simple module. And here you can read full manual.

How to develop your first module in 4 steps

1) To start install the @collboard/modules-sdk first:

npm install @collboard/modules-sdk

2) Then create package.json file with link to main file:

{
    "version": "1.0.0",
    "main": "./src/sampleButtonModule.tsx",
    "scripts": {
        "start": "colldev"
    },
    "dependencies": {
        "@collboard/modules-sdk": "^11.2.2-1"
    }
}

3) Create the main file

It can be either TypeScript or JavaScript. It can import other files or node modules (colldev internally uses webpack with ts-loader).

import { declareModule, ExtraJsxPlace, makeExtrajsxModule } from '@collboard/modules-sdk';
import * as React from 'react';

declareModule(
    makeExtrajsxModule({
        manifest: {
            name: 'MyFirstModule',
        },
        place: ExtraJsxPlace.EdgeRight,
        createExtraJsx({
            routingSystem,
            translationsSystem,
            apiClient,
            materialArtVersioningSystem: { cornerstoneArts },
        }) {
            return (
                <button
                    onClick={async () => {
                        alert(`Hello from Collboard modules!`);
                    }}
                    className="button button-primary button-vertical"
                >
                    <span>Hello World!</span>
                </button>
            );
        },
    }),
);

4) And you can start to develop your first module!

# Linux, WSL
colldev

# Windows, PowerShell
npx colldev

# Or by NPM
npm start

# You can also run full command
# Note: "colldev" is just shortcut for "colldev develop"
colldev develop

# And disable to open browser on dev.collboard.com
colldev develop --open false

5) Create gitignore file (optional if using git)

Create file .gitignore and ignore temporary files and modules.

.colldev
node_modules

How it works under the hood?

Colldev will automatically look into your package.json, finds main entry (it can be typescript or javascript file). And watch, build and serve changes to Collboard in development mode.

Then you open Collboard in developer mode - dev.collboard.com and there you will see modules that you are working on.

Most of the modules make sense on the board (not the homepage) so you will probably need to create a new board.

These modules will be automatically installed & hot reloaded (uninstalled+installed) as you go.

Notice that boards+its contents created under development mode will be automatically erased after some time.

Publishing the module

Run colldev commant with publish modifier. This will send module to Collboard server as a release candidate to authorize. Please provide contact to author in package.json if there is some problem with the module to contact you and solve it.

When you are updating, please provide new version in package json.

# Linux, WSL
colldev publish

# Windows, PowerShell
npx colldev publish

Tip: You can also setup postversion command to publish automatically.

Systems

In setup function you are interacting with Collboard systems. Theese are something like APIs each controlling some part of collboard app.

Typically you are registering something under theese sytems. This will returns you destroyable which you can directly return from your setup function.

ApiClient

ApiClient provides API calls to the remote server.

BoardApiClient

AppState

AppState is not quite a system but an object representing the state of the Collboard app.

MaterialArtVersioningSystem

ArtVersionSystem synchronizes the arts with the remote server.

VirtualArtVersioningSystem

AttributesSystem

AttributesSystem manages shared art attributes and modules capable of selecting from them. It auto-install/uninstall attribute modules.

ClosePreventionSystem

CollSpace

CollSpace manages 3D objects rendered by WebGL (BABYLON JS) and provides all the tooling around the 3D scene, positioning, textures, materials, etc.

CreateSystem

CreateSystem allows importing which allows to import/create arts from other sources. Note: CreateSystem - for individual arts, GenerateSystem - for whole board Note: CreateSystem+GenerateSystem and ExportSystem are in some kind opposites.

ExportSystem

ExportSystem creates other files from the board or the part of it. Note: CreateSystem+GenerateSystem and ExportSystem are in some kind opposites. Note: This system is not just for exporting but also saves to native format.

ImportSystem

Import system makes support for files which are dragged onto board, imporded or pasted It auto-install/uninstall file support modules.

ExtraJsxSystem

ExtraJsxSystem can register and manage additional JSX Note: ExtraJSXSystem is for JSX (HTML) vs. StyleSystem is for CSS styles

FocusSystem

FocusSystem can register and manage unique focuses and icons which there are.

IdentitySystem

IdentitySystem identifies the User by a pseudonym.

ModuleStore

ModuleStore unites all module store connectors into one API, so consumer have same way how to get internal or external module

NotificationSystem

RoutingSystem

RoutingSystem provides for core, other systems and modules registration of routes and hashtag routes. @see https://github.com/collboard/collboard/issues/97

Serializer

Serializer can serialize/deserialize objects. Primarily it is serialized arts.

ShortcutsSystem

ShortcutsSystem can register and manage keyboard shortcuts like Ctrl + C by modules (or maybe other systems).

StyleSystem

StyleSystem can register and manage additional CSS styles for modules. It can scope CSS so it will do not affect others.

Note: ExtraJSXSystem is for JSX (HTML) vs. StyleSystem is for CSS styles

ToolbarSystem

ToolbarSystem can register and manage toolbars and icons which there are.

TranslationsSystem

TranslationsSystem manages messages across core, systems and modules.

Makers

Makers are helpers which helps to create an module. Maker is a pure function that transforms a simpler form of module definition to module definition which will be accepted by declareModule. So you still need to call declareModule.

makeArtModule

makeAttributeModule

makeExtrajsxModule

makeIconModule

makeIconModuleOnModule

makeIconModuleOnRoute

makeModalModule

makeMultiModule