CustomVcc

Implements a custom control for capturing user input in Koji apps.

Constructor

Instantiates CustomVcc.

Example

import CustomVcc from '@withkoji/custom-vcc-sdk';
const customVcc = new CustomVcc();

Methods

.change(newValue)

Updates the value with the user-entered value.

Parameters

newValue – Any, Current value of the custom control.

Example

customVcc.change(newValue);

.onTheme(handler)

Listens to changes to the theme value, to retrieve values relating to the Koji display theme. The theme returned in the listener allows you to style the control to match the user’s current theme on Koji (dark or light).

Parameters

handler – Function, Called when theme is available. Receives the following property as input:
- theme – Theme, Represents the theme as an object.

Example

customVcc.onTheme((theme) => {
	// theme is a Koji editor theme
 	// save this value in order to style your control to match the user's current theme
});

.onUpdate(handler)

Listens to changes in the custom value from the consumer application to enable updates to rendered values.

Tip	It is prefereable to update the rendered value only in response to `onUpdate` events. Calling `change` immediately fires an `onUpdate`.

Parameters

handler – Function, Handles changes to the custom value. Receives the following property as input:
- props – Props, Properties of the custom control.

Example

customVcc.onUpdate((props) => {
	// props is an object containing the control's current state.
});

.register(width, height)

Indicates that the custom control has loaded and registers it to trigger the on events from the parent editor.

Parameters

width – (Optional) Any, Width of the custom control.
height – (Optional) Any, Height of the custom control.

Example

customVcc.register('300', '300');

.save()

Saves the JSON customization file in the consumer application.

Example

customVcc.save();

.uploadFile(file, fileName, onComplete)

Uploads a file blob to the Koji CDN.

Parameters

file – Blob, File blob data to be uploaded.
fileName – String, Name of the file to be uploaded.
onComplete – Function, Called when upload has completed. Receives the following property as input:
- url – String, URL of the uploaded file.

Example

customVcc.uploadFile(myBlob, myFileName, (url) => {
  // url of the uploaded file
});

Interfaces

Props

Represents the current state of a custom control. It is returned to the handler listening to onUpdate.

Properties

type – String, Type signature for this VCC.
name – String, Name of the control.
value – Any, Current value of the control.
scope – String, Name of the section where this VCC appears in the consumer application.
variableName – String, Resolved variable name of this VCC (scope.key).
options – Object, Any options passed in typeOptions.
collaborationDecoration – Object, Any collaborators currently focused on this control.
_config – Object, The full VCC configuration file. Most controls are isolated to a single value. However, this object can be useful when creating more complex custom controls, like map builders.

Theme

Allows you to use styles that match the colors and styles of the calling app’s active theme. It is returned to the handler listening to onTheme.

Properties

name – String, Name of the theme.
breakpoints – Object, Responsive style breakpoints of the theme.
colors – Object, Key-value pairs representing the theme’s named colors.
mixins – Object, CSS mixins to style specific elements.

Example

{
	"name": "aspergillus",
	"breakpoints": {
		"default": "(min-width: 1025px)",
		"phone": "(max-width: 767px)",
		"tablet": "(max-width: 1024px)"
	},
	"colors": {
		"background.default": "#ffffff",
		"foreground.default": "#111111",
		"input.background": "#ffffff",
		"input.foreground": "#111111"
		...
	},
	"mixins": {
		"card.default": "box-shadow: 0 6px 24px 0 rgba(0,0,0,0.05); background-color: #fff;",
		"clickable": "cursor: pointer; user-select: none;",
		...
	}
}