Plugins

Plugins add panels and 3D views to a CAD app, for the features of a model or for a whole drawing: for those who make plugins.

Functions

getPlugin()

function getPlugin(drawingId, pluginId): PluginState;

Returns a plugin's state: its description, its own state, and set to change that.

Plugins of features are created when their feature is opened, global plugins when the drawing is made (see PluginState). Read once; usePlugin of @buerli.io/react follows it in a component.

Parameters

Parameter	Type	Description
drawingId	DrawingID	The drawing the plugin belongs to.
pluginId	PluginID	The plugin: for a feature's plugin, the feature's object id.

Returns

PluginState

The plugin's state, or undefined when the drawing or the plugin does not exist.

Example

import { getDrawing, getPlugin } from '@buerli.io/core'

// Open the Measure plugin of a drawing, and have it show three digits
const drawing = getDrawing(drawingId)
const measureId = drawing.plugin.global.find(id => drawing.plugin.refs[id]?.name === 'Measure')
if (measureId) {
  drawing.api.plugin.setActiveGlobal(measureId, true)
  getPlugin(drawingId, measureId)?.set({ digits: 3 })
}

Types

Plugin

type Plugin = {
  description: PluginDescription;
  Root?: ((options?) => any) | null;
  View?: ((options?) => any) | null;
};

A plugin: what it is (description), its panel (Root) and its 3D view (View).

Plugins of features are registered with the plugins option of init of @buerli.io/classcad, by feature class; global plugins with globalPlugins. @buerli.io/react renders Root and View with the props drawingId and pluginId; a feature's View is placed in the feature's coordinate system. A module that exports Root, View and description is a plugin.

Example

import { init, WASMClient } from '@buerli.io/classcad'
import { elements } from '@buerli.io/react'
import { Measure } from '@buerli.io/react-cad'

// Every drawing gets the Measure plugin; plugins need the form controls they are made of
init(drawingId => new WASMClient(drawingId, { token: 'ccpk_…' }), { globalPlugins: [Measure], elements })

Properties

Property	Type	Description
description	PluginDescription	What the plugin is.
Root?	((options?) => any) | null	The plugin's panel, a React component.
View?	((options?) => any) | null	What the plugin shows in the 3D view, a React component inside the canvas.

---

PluginDescription

type PluginDescription<InternalState> = {
[key: string]: any;
  author: string;
  global?: boolean;
  initialState?: ((drawingId, objectId) => InternalState) | InternalState;
  name: string;
  persistent?: boolean;
  version: string;
};

What a plugin is: its name, whether it is global, and the state it starts with.

It is the description of a Plugin. A plugin is either a feature's, made for one feature object when the feature is opened, or global, one for the whole drawing (like Measure of @buerli.io/react-cad).

Example

import { DrawingID, Plugin, PluginDescription, PluginID } from '@buerli.io/core'
import { usePlugin } from '@buerli.io/react'

type State = { count: number }
const description: PluginDescription<State> = {
  name: 'Counter',
  version: '1.0.0',
  author: 'me',
  global: true,
  initialState: { count: 0 },
}

// Its panel counts clicks, in the plugin's own state
function Root({ drawingId, pluginId }: { drawingId: DrawingID; pluginId: PluginID }) {
  const count = usePlugin(drawingId, pluginId, plugin => (plugin.state as State).count) ?? 0
  const set = usePlugin(drawingId, pluginId, plugin => plugin.set)
  return <button onClick={() => set?.({ count: count + 1 })}>{count}</button>
}

// For `globalPlugins` of init
export const Counter: Plugin = { description, Root }

Type Parameters

Type Parameter	Default type	Description
InternalState	any	The plugin's own state.

Indexable

[key: string]: any

Anything else the plugin keeps in its description.

Properties

Property	Type	Description
author	string	Who made it.
global?	boolean	Whether it is a global plugin, one for the whole drawing, rather than a feature's.
initialState?	((drawingId, objectId) => InternalState) | InternalState	The state the plugin starts with (state of PluginState), or a function of the drawing and the feature object that returns it. A global plugin that a drawing gets when it is made is called with neither.
name	string	The plugin's name.
persistent?	boolean	For a feature's plugin: whether it keeps its state when another feature is opened. Without it, the state goes back to initialState then.
version	string	The plugin's version.

---

PluginID

type PluginID = ObjectID | string;

A plugin's id: for a feature's plugin the feature's object id, for a global plugin a uuid.

---

PluginState

A plugin in a drawing: its description, its components, and its own state with set to change it.

drawing.plugin.refs holds them by id; getPlugin reads one, usePlugin of @buerli.io/react follows one in a component. Its own state starts as initialState of the PluginDescription.

Example

import { DrawingID, PluginID } from '@buerli.io/core'
import { usePlugin } from '@buerli.io/react'

// A plugin's panel: reads its own state, and changes it with `set`
function Digits({ drawingId, pluginId }: { drawingId: DrawingID; pluginId: PluginID }) {
  const digits = usePlugin(drawingId, pluginId, plugin => plugin.state.digits as number) ?? 2
  const set = usePlugin(drawingId, pluginId, plugin => plugin.set)
  return <input type="number" value={digits} onChange={event => set?.({ digits: Number(event.target.value) })} />
}

Type Parameters

Type Parameter	Default type	Description
InternalState extends Record<any, any>	any	The plugin's own state.

Indexable

[key: string]: any

Properties

Property	Modifier	Type	Description
author	readonly	string	Who made it.
drawingId?	readonly	DrawingID	The drawing it belongs to, when it was created with one.
global?	readonly	boolean	Whether it is a global plugin, one for the whole drawing, rather than a feature's.
id	readonly	PluginID	The plugin's id.
initialState?	readonly	InternalState | ((drawingId, objectId) => InternalState)	The state the plugin starts with (state of PluginState), or a function of the drawing and the feature object that returns it. A global plugin that a drawing gets when it is made is called with neither.
name	readonly	string	The plugin's name.
objectId?	readonly	number	For a feature's plugin, the feature object.
persistent?	readonly	boolean	For a feature's plugin: whether it keeps its state when another feature is opened. Without it, the state goes back to initialState then.
Root	readonly	((options?) => any) | null	Its panel, from the Plugin; rendered with drawingId and pluginId.
set	readonly	(sel) => void	Changes the plugin's own state: merges the given values (or what the function returns for the state) into it. Does nothing once the drawing is gone.
state	readonly	InternalState	The plugin's own state.
version	readonly	string	The plugin's version.
View	readonly	((options?) => any) | null	Its 3D view, from the Plugin; rendered with drawingId and pluginId.