Modules SDK toolkit for collaborative whiteboard platform Collboard.com.
- 🖋 Collboard for development
- 👩💻 Collboard on GitHub
- 😻 Modules SDK on GitHub
- 🐇 Modules SDK on NPM
- 🧪 Hello world module
- 🧪 Module with custom tool, art and attribute
- 📓 Full manual of SDK
You can start from scratch in 4 simple steps, clone some of our templates or look at miscellaneous Collboard modules on GitHub.
1) To start install the @collboard/modules-sdk first:
npm install --save-dev @collboard/modules-sdkNote: you can install @collboard/modules-sdk as a dev dependency beacasue it is a toolkit for modules not required in the runtime.
module.exports = {
entryPath: './src/index.ts',
};It can be either TypeScript or JavaScript. It can import other files or node modules (colldev internally uses webpack with ts-loader).
import { declareModule, UserInterfaceElementPlace, makeUserInterfaceModule } from '@collboard/modules-sdk';
import * as React from 'react';
declareModule(
makeUserInterfaceModule({
manifest: {
name: '@my-username/first-module',
},
place: UserInterfaceElementPlace.EdgeRight,
createElement({
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>
);
},
}),
);# 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
colldev develop --open none
Create file .gitignore and ignore temporary files and modules.
.colldev
node_modules
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.
To compile, pack and send the module to Collboard module store server run:
colldev publish --token YOUR_TOKENTip: You can create automated GitHub workflow to publish after new version automatically.
Some libraries are exported from @collboard/modules-sdk. We want to run one version of them in all modules and Collboard core. It saves resources (memory, network), makes it easier to maintain and avoids compatibility issues.
import { React, styled } from '@collboard/modules-sdk';
const MyDiv = styled.div`
color: red;
`;
function SomeComponent() {
return (
<MyDiv>
<h1>Hello World!</h1>
</MyDiv>
);
}It is required for React and Styled Components. And recommended for these libraries.
For all other libraries, please use isolation from global window scope. Be aware that other developers can also import same library.
import { configure } from 'mobx';
configure({ safeDescriptors: false });$.noConflict();
jQuery(document).ready(function ($) {
// ...
});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.
Core System
ApiClient provides API calls to the remote server.
AppState is not quite a system but an object representing the state of the Collboard app. @deprecated This system will be split into two CollSpace and SelectionSystem and removed
ArtSerializer serializes and deseriales Collboard arts and other objects
- Serializer is generic serializer which can work with any rules; it works synchronously
- Serializer with basic rules is Serializer which has registered basic rules; it works synchronously
- ArtSerializer serializes and deseriales Collboard arts and other objects; it works asynchronously
ArtVersionSystem synchronizes the arts with the remote server.
AttributesSystem manages shared art attributes and modules capable of selecting from them. It auto-installs / uninstalls attribute modules.
ApiClient provides API calls to the remote server.
CollSpace manages 3D objects rendered by WebGL (BABYLON JS) and provides all the tooling around the 3D scene, positioning, textures, materials, etc.
ControlSystem can register and manage keyboard shortcuts like Ctrl + C by modules (or maybe other systems).
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 creates other files from the board or the part of it. Note: This system is not just for exporting but also saves to native format.
FocusSystem can register and manage unique focuses and icons which there are.
IdentitySystem identifies the User by a pseudonym.
Import system makes support for files which are dragged onto board, imporded or pasted It auto-installs / uninstalls file support modules.
LicenseSystem is a system that manages the licenses for modules @see more on https://github.com/collboard/collboard/blob/main/documents/license-system.md
System that recieves and executes the post message API
ModuleStore unites all module store connectors into one API, so consumer have same way how to get internal or external module Note: Modules storage - is just getter / setter for modules Modules store - has full logic of modules domain
FileSupportSyncer installs / uninstalls support for files for its importing(TODO: /exporting)
RoutingSystem provides for core, other systems and modules registration of routes and hashtag routes. @see https://github.com/collboard/collboard/issues/97
StyleSystem can register and manage additional CSS styles for modules. It can scope CSS so it will do not affect others. Note: UserInterfaceSystem is for JSX (HTML) vs. StyleSystem is for CSS styles
TestSystem just for testing purposes.
ToolbarSystem can register and manage toolbars and icons which there are.
TranslationsSystem manages messages across core, systems and modules.
UsercontentSystem provides API to upload user content to the server.
UserInterfaceSystem can register and manage additional JSX Note: Using UserInterfaceSystem is not recommended to use directly because it is using very low-level API. Consider using higher-level API like ToolbarSystem, NotificationSystem, etc. Note: UserInterfaceSystem is for JSX (HTML) vs. StyleSystem is for CSS styles
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.