npm install --save @withkoji/custom-vcc-sdkThe @withkoji/custom-vcc-sdk package enables you to implement custom Visual Customization Controls (VCCs) for your template.
The Koji platform includes VCCs for standard elements, such as images, text, and sounds. In addition, you can build custom VCCs to provide new types of customizations that match closely with the application you are developing. For example, some Koji templates provide tile map editors, sound enhancers, or custom avatar creators to enhance the interactivity for remixers.
Install the package in your Koji project.
npm install --save @withkoji/custom-vcc-sdkInstantiates CustomVcc.
import CustomVcc from '@withkoji/custom-vcc-sdk';
const customVcc = new CustomVcc();Updates the VCC value with the user-entered value.
newValue – Any, current value of the VCC.
customVcc.change(newValue);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 VCC to match the user’s current theme on Koji (dark or light).
handler – Function, called when theme is available.
Receives the following property as input:
theme – Object, represents the theme as an object. See Theme.
customVcc.onTheme((theme) => {
// theme is a Koji editor theme
// save this value in order to style your VCC to match the user's current theme
});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.
|
handler – Function, handle changes to the custom value.
Receives the following property as input:
props – Object, contains the properties of the VCC. See Props.
customVcc.onUpdate((props) => {
// props is an object containing the VCC's current state.
});Indicates that the custom VCC has loaded and registers it to trigger the on events from the parent editor.
width – (Optional) Any, width of the custom VCC.
height – (Optional) Any, height of the custom VCC.
customVcc.register('300', '300');Saves the JSON customization file in the consumer application.
customVcc.save();Uploads a file blob to the Koji CDN.
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.
customVcc.uploadFile(myBlob, myFileName, (url) => {
// url of the uploaded file
});A props object represents the current state of a custom VCC.
It is returned to the handler listening to onUpdate.
The props object includes the following properties.
{
type: string;(1)
name: string;(2)
value: any;(3)
scope: string;(4)
variableName: string;(5)
options: object;(6)
collaborationDecoration: object;(7)
_config: object;(8)
};type – Type signature for this VCC.
name – Name of the VCC.
value – Current value of the VCC.
scope – Name of the section where this VCC appears in the consumer application.
variableName – Resolved variable name of this VCC (scope.key).
options – An object containing any options passed in typeOptions.
collaborationDecoration – An object containing any collaborators currently focused on this control.
_config – 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.
A theme object allows you to use styles that match the colors and styles of the remixer’s active theme.
It is returned to the handler listening to onTheme.
The theme object includes the following properties.
{
name: string;(1)
breakpoints: object;(2)
colors: object;(3)
mixins: object;(4)
};name – Name of the theme.
breakpoints – An object containing responsive style breakpoints of the theme.
colors – An object of key-value pairs representing the theme’s named colors.
mixins – An object containing CSS mixins to style specific elements.
Here is an example of some of the properties of the theme object.
{
"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;",
...
}
}