@netless/fastboard

Docs | Sandbox | 中文

A starter library for making whiteboard web app, based on white-web-sdk, @netless/window-manager and netless-app.

Table of Contents

• Install
• Usage
• Customization

Install

npm add @netless/fastboard @netless/window-manager white-web-sdk

Note: @netless/window-manager and white-web-sdk are peerDependencies.

Usage

Vanilla JavaScript

import { createFastboard, createUI } from "@netless/fastboard";

async function main() {
  const fastboard = await createFastboard({
    // [1]
    sdkConfig: {
      appIdentifier: "whiteboard-appid",
      region: "us-sv", // "cn-hz" | "us-sv" | "sg" | "in-mum" | "eu"
    },
    // [2]
    joinRoom: {
      uid: "unique_id_for_each_client",
      uuid: "room-uuid",
      roomToken: "NETLESSROOM_...",
      // (optional)
      userPayload: {
        nickName: "foo",
      },
    },
    // [3] (optional)
    managerConfig: {
      cursor: true,
    },
    // [4] (optional)
    netlessApps: [],
  });

  const container = createContainer();

  const ui = createUI(fastboard, container);

  // .....

  // destroy Fastboard UI
  ui.destroy();

  // .....

  // destroy Fastboard (disconnect from the whiteboard room)
  fastboard.destroy();
}

function createContainer() {
  const container = document.createElement("div");
  // Must give it a visible size
  Object.assign(container.style, {
    height: "400px",
    border: "1px solid",
    background: "#f1f2f3",
  });
  document.body.appendChild(container);
  return container;
}

main().catch(console.error);

[1] Read more about the SDK config at Construct WhiteWebSDK object
[2] Read more about join room config at Construct Room and Player objects
[3] Read more about WindowManager config at WindowManager.mount()

React

Install @netless/fastboard-react, use the <Fastboard /> component.

npm add @netless/fastboard-react @netless/window-manager white-web-sdk react react-dom

import { useFastboard, Fastboard } from "@netless/fastboard-react";
import React from "react";
import { createRoot } from "react-dom/client";

function App() {
  const fastboard = useFastboard(() => ({
    sdkConfig: {
      appIdentifier: "whiteboard-appid",
      region: "us-sv", // "cn-hz" | "us-sv" | "sg" | "in-mum" | "eu"
    },
    joinRoom: {
      uid: "unique_id_for_each_client",
      uuid: "room-uuid",
      roomToken: "NETLESSROOM_...",
    },
  }));

  // Container must have a visible size
  return (
    <div
      style={{
        height: "400px",
        border: "1px solid",
        background: "#f1f2f3",
      }}
    >
      <Fastboard app={fastboard} />
    </div>
  );
}

createRoot(document.getElementById("app")).render(<App />);

Whiteboard Functions

Insert Picture

await fastboard.insertImage(fileUrl);

The fileUrl is the url to load the image file, like "src" in <img src>. Fastboard itself does not contain any logic about upload/save a file.

Redo & Undo

fastboard.undo();
fastboard.redo();

Move Camera

fastboard.moveCamera({ centerX: 0, centerY: 0, scale: 1 });
fastboard.moveCameraToContain({ originX: -300, originY: -200, width: 600, height: 400 });

Set Tool

fastboard.setAppliance("pencil");
fastboard.setAppliance("shape", "triangle");
fastboard.setStrokeWidth(2);
fastboard.setStrokeColor([r, g, b]);

Netless Apps

To develop your own app, see Write you a Netless App.

Register & Insert Apps

Except for built-in apps in Fastboard, you can also insert your own apps. To do that, You have to register app at each client before entering room (createFastboard):

import { register } from "@netless/fastboard";
import MyApp from "my-app";

register({ kind: MyApp.kind, src: MyApp });

Or you can set netlessApps in createFastboard config:

createFastboard({
  ..., // other config
  netlessApps: [MyApp],
});

Then add app into the room via:

fastboard.manager.addApp({ kind: MyApp.kind });

Read more about Netless Apps.

Insert PDF, PPT and PPTX

// insert PDF/PPT/PPTX to the main whiteboard
const appId = await fastboard.insertDocs("filename.pptx", conversionResponse);

The conversionResponse is the result of this api.

Note: If you're using the new projector api, there's another way:

const appId1 = await fastboard.insertDocs({
  fileType: "pdf",
  scenePath: `/pdf/${response.uuid}`,
  scenes: [
    { name: "1", ppt: { width: 714, height: 1010, src: images[1].url } },
    { name: "2", ppt: { width: 714, height: 1010, src: images[2].url } },
  ],
  title: "filename.pdf",
});

const appId2 = await fastboard.insertDocs({
  fileType: "pptx",
  scenePath: `/pptx/${response.uuid}`,
  taskId: response.uuid,
  title: "filename.pptx",
  // "https://convertcdn.netless.link/dynamicConvert" by default
  url: response.prefix,
});

Listen PDF/PPTX Page Change Event

Note: This feature requires the following versions of dependencies:

• @netless/app-slide ≥ 0.2.50
• @netless/window-manager ≥ 0.4.66

// For static documents i.e. PDF files
const dispose = fastboard.manager.onAppEvent("DocsViewer", event => {
  if (event.type === "pageStateChange") console.log(event.value);
});
// For dynamic documents i.e. PPTX files
const dispose = fastboard.manager.onAppEvent("Slide", console.log);

onExitRoom(() => dispose());

The event above will be like:

{
  "kind": "Slide",
  "appId": "Slide-aa1840ba",
  "type": "pageStateChange",
  "value": {
    "index": 0,
    "length": 12
  }
}

The dispose above is a function to stop listening.

Control the PDF/PPTX Apps

import { dispatchDocsEvent } from "@netless/fastboard";

dispatchDocsEvent(fastboard, "nextPage"); // prevPage, nextStep, prevStep
dispatchDocsEvent(fastboard, "jumpToPage", { page: 2 });

By default it will dispatch event to the focused PDF/PPTX app, you can also specify the appId:

dispatchDocsEvent(fastboard, "nextPage", { appId });

Set PPTX Render Options

import { register, SlideApp, addSlideHooks } from "@netless/fastboard";

register({
  kind: SlideApp.kind,
  src: SlideApp,
  appOptions: {
    // ... your slide options here
    // Note: import type {SlideOptions} to get type hints
  },
  addHooks: addSlideHooks,
});

Read more about these options.

Insert Video & Audio

const appId = await fastboard.insertMedia("filename.mp3", fileUrl);

The fileUrl is the url to load the media file, like "src" in <video src>. Fastboard itself does not contain any logic about upload/save a file.

Insert @netless/app-monaco

const appId = await fastboard.manager.addApp({
  kind: "Monaco",
  options: { title: "Code Editor" },
});

Insert @netless/app-countdown

const appId = await fastboard.manager.addApp({
  kind: "Countdown",
  options: { title: "Countdown" },
});

Insert @netless/app-geogebra

[!NOTE] GeoGebra is licensed under GPLv3 and is free only in non-commercial use. If you want to use it in commercially, please refer to their license first: https://www.geogebra.org/license

const appId = await fastboard.manager.addApp({
  kind: "GeoGebra",
  options: { title: "GeoGebra" },
});

Insert @netless/app-plyr

const appId = await fastboard.manager.addApp({
  kind: "Plyr",
  options: { title: "YouTube" },
  attributes: {
    src: "https://www.youtube.com/embed/bTqVqk7FSmY",
    provider: "youtube",
  },
});

Insert @netless/app-embedded-page

const appId = await fastboard.manager.addApp({
  kind: "EmbeddedPage",
  options: { title: "Google Docs" },
  attributes: {
    src: "https://docs.google.com/document/d/1bd4SRb5BmTUjPGrFxU2V7KI2g_mQ-HQUBxKTxsEn5e4/edit?usp=sharing",
  },
});

Note: EmbeddedPage uses <iframe> to display external web resources, you'd better not embedding 2 more nested iframes (i.e. webpage>iframe1>iframe2) in the same page.

More apps goto netless-app.

To develop your own app, see Write you a Netless App.

Customization

Fastboard isn't that customizable due to its fast design goal. But we do have some lightweight configuration for easy changes.

// vanilla js
const ui = createUI(fastboard, container);
ui.update({ config: { ...ui_config } });

// react
<Fastboard app={fastboard} config={{ ...ui_config }} />;

The ui_config looks like:

{
  toolbar: {
    enable: true,
    placement: 'left',
    items: ['pencil', 'eraser'],
    apps: { enable: true },
  },
  redo_undo: { enable: true },
  zoom_control: { enable: true },
  page_control: { enable: true },
}

For example, you can hide the zoom control component with:

// vanilla js
ui.update({ config: { zoom_control: { enable: false } } });
// react
<Fastboard app={fastboard} config={{ zoom_control: { enable: false } }} />;

Or change the items on toolbar with:

Available items:
clicker, selector, pencil, text, shapes, eraser, clear, hand, laserPointer.

const toolbar_items = ["pencil", "eraser"];
// vanilla js
ui.update({ config: { toolbar: { items: toolbar_items } } });
// react
<Fastboard app={fastboard} config={{ toolbar: { items: toolbar_items } }} />;

You can also write your own component with the same source of truth as Fastboard UI. Just disable those components and refer to Write Your Own UI (for Fastboard).

Replay Mode

Fastboard has a similar usage to replay a whiteboard.

const player = await replayFastboard(...)
const ui = createReplayUI(player, container);

const player = useReplayFastboard(() => ({...}))
return <ReplayFastboard player={player} />

The player instance is similar to a native video player that has methods like play() stop() seek() pause() etc. To sync the progress of the whiteboard player with other players (like a video player), see @netless/sync-player.

Error Handling

You will get callbacks when:

• Cannot connect to server at the very beginning
• Connecting status changed (to reconnecting or disconnected)
• Kicked from room (when the room is banned from the backend)

Note that Fastboard will reconnect automatically internally, you only have to do things below to ensure the user experience.

To properly handle these cases, please refer to this piece of code:

try {
  fastboard = await createFastboard({
    sdkConfig: {
      onWhiteSetupFailed(error) {
        console.error("Failed to find the whiteboard server", error);
      },
    },
    joinRoom: {
      callbacks: {
        onPhaseChanged(phase) {
          if (phase === "reconnecting") console.log("Whiteboard connection lost, reconnecting...");
        },
        onDisconnectWithError(error) {
          console.error("Failed to connect to whiteboard server");
        },
        onKickedWithReason(reason) {
          console.log("You're kicked by", reason);
          // Properly close this room
          leaveRoom();
        },
      },
    },
  });
} catch (error) {
  console.error("Failed to join whiteboard room", error);
}

The React way should be similar.

License

MIT @ netless