Zyllio SDK is a development kit that allows developers to extend Zyllio Studio by creating Plugins. These plugins contain Components, Actions, Formula functions and Themes
It is the decision of developer to define the granularity of a plugin, it may contain any number of Components, Actions, Functions and Themes altogether
Use these pre-built plugins to experiment Zyllio Plugins within Zyllio Studio
| Plugin | Plugin URL |
|---|---|
| Progress Bar Component | https://zyllio.github.io/zyllio-plugin-progressbar/dist/plugin.js |
| Ionic Slider Component | https://zyllio.github.io/zyllio-plugin-ionic-slider/dist/plugin.js |
| Rating Component | https://zyllio.github.io/zyllio-plugin-rating/src/rating.js |
| Angular Timeline Component | https://zyllio.github.io/zyllio-plugin-angular/dist/plugin.js |
| ReactJS Chart Component | https://zyllio.github.io/zyllio-plugin-reactjs/dist/plugin.js |
| VueJS Counter Component | https://zyllio.github.io/zyllio-plugin-vuejs/public/plugin.js |
| Meme Generator Action | https://zyllio.github.io/zyllio-plugin-meme-generator/src/meme.js |
| Custom Theme | https://zyllio.github.io/zyllio-plugin-theme/src/theme.js |
| Area number formula | https://zyllio.github.io/zyllio-plugin-formula/plugin.js |
| Plugin | GitHub Repository |
|---|---|
| Progress Bar Component | https://github.com/zyllio/zyllio-plugin-progressbar |
| Ionic Slider Component | https://github.com/zyllio/zyllio-plugin-ionic-slider |
| Rating Component | https://github.com/zyllio/zyllio-plugin-rating |
| Angular Timeline Component | https://github.com/zyllio/zyllio-plugin-angular |
| ReactJS Chart Component | https://github.com/zyllio/zyllio-plugin-reactjs |
| VueJS Counter Component | https://github.com/zyllio/zyllio-plugin-rating |
| Meme Generator Action | https://github.com/zyllio/zyllio-plugin-meme-generator |
| Custom Theme | https://github.com/zyllio/zyllio-plugin-theme |
| Week number formula | https://github.com/zyllio/zyllio-plugin-week-number |
| Area number formula | https://github.com/zyllio/zyllio-plugin-formula |
Zyllio SDK requires Node.js 20+ installed on any operating system it runs
Zyllio team recommends development tools that support Javascript, Typescript technical stack
These following tools are recommended: VS Code and WebStorm
To install Zyllio SDK run the folowing command
npm install @zyllio/zy-sdk --save-dev
Zyllio SDK is a Typescript Library meant to be consumed from a Typescript project. Using Typescript is the recommended approach even though it is not mandatory and could be used from pure Javascript projects
To use Zyllio SDK, add this statement at the top of your index file
/// <reference types="@zyllio/zy-sdk" />
This statement allows the development tool to discover the services exposed by Zyllio SDK and thus provide completion and inline documentation
This document is an overview of the reference API, please consider the comprehensive Reference API for more information Zyllio SDK Reference API
Zyllio Components have to implement a CustomElement from Web Components standard. Any Javascript frameworks could be used to develop this custom element: Pure JS, Angular, Vue.Js, StencilJS, ReactJS (using react-to-webcomponent)...
Please refer to GitHub examples to review components made with different technologies
Component properties are injected by the SDK wrapper using the property id defined in metadata.
For primitive property types such as text, number, boolean, date, options or screen, the wrapper writes the value as an HTML attribute on the inner custom element. In practice, a component can usually read its input with this.getAttribute('<property-id>').
For richer types, the wrapper assigns values directly on the element instance instead of using HTML attributes:
table properties are assigned as element propertiesrow-variable properties are assigned as element propertiesTo send a value back to Zyllio, the component must dispatch a CustomEvent from the inner element. The wrapper listens in particular to these events:
changed: updates a writable property in the data dictionary from event.detail, for example this.dispatchEvent(new CustomEvent('changed', { detail: { value: newValue } }))selected: updates a row-variable or row-column-variable selection from event.detailupdate-row: updates table row data using event.detail.item and event.detail.fieldsThis means a simple input component usually reads with getAttribute('<property-id>') and writes back with a changed custom event.
Here is fairly simple example based on Pure Javascript
class MyComponent extends HTMLElement {
constructor() {
this.shadow = this.attachShadow({ mode: 'open' });
}
connectedCallback() {
this.shadow.innerHTML = HtmlContent;
this.render()
}
render() {
const element = this.shadowRoot.querySelector('div')
const value = this.getAttribute('value')
element.innerText = '⭐'.repeat(parseInt(value))
}
}
In addition, a Metadata is required to describe the component to Zyllio platform, see below for more details. To register a component and its metadata use the following API assuming MyComponentMetadata is a JSON object and MyComponent a custom element Class
registry.registerComponent(MyComponentMetadata, MyComponent)
Component Metadata is a static Javascript object that describes the component, it is required by Zyllio Studio to display its properties and styles from Design Editor.
Click here to see component configuration panels
This metadata is compliant to these specifications
const Icon = `
<svg xmlns="http://www.w3.org/2000/svg" version="1.1" width="24" height="24" viewBox="0 0 24 24">
<path fill="#cccccc" d="M12,2A10,10 0 0,0 2,12A10,10 0 0,0 12,22A10,10 0 0,0 22,12A10,10 0 0,0 12,2Z" />
</svg>
`
const MyComponentMetadata = {
metadataVersion: 2, /* Must be version 2 */
id: 'zyllio-list', /* Unique identifier, must be lower case and contain a dash character */
icon: Icon, /* SVG icon displayed in Zyllio Studio */
label: 'List', /* Label displayed in Zyllio Studio */
category: 'Basics', /* Category in which the component is displayed in Zyllio Studio */
subCategory: 'Lists', /* Sub category in which the component is displayed in Zyllio Studio */
hidden: false, /* Should be false */
properties: [{ /* Properties to configure the component */
id: 'name', /* Unique id of the property, should be lower case */
name: 'Name', /* Name of the property displayed in Zyllio Studio */
type: 'row-variable', /* Type of the property (see Reference API) */
options: [], /* Array of possible options, used only when type is PropertyTypes.Options */
default: '', /* Default value if any, it is assigned at component creation by Zyllio Studio user */
write: true, /* Indicates whether this property is used to save data at runtime (likely when a component allows selections or inputs) */
main: true /* Indicates whether this property is the main one, Zyllio Studio needs it to populate the component panel. One main property must be defined */
}],
styles: [{ /* Styles to configure the component (width and height styles are mandatory) */
id: 'width', /* Unique id of the style, should be lower case */
name: 'Width', /* Name of the style displayed in Zyllio Studio */
type: 'width', /* Any of the folowing: width, height, background-image, background-color, icon, size, font-size, color, font-weight, font-style, border-width, border-color, border-radius, box-shadow */
default: '360px' /* Default value if any, it is assigned at component creation by Zyllio Studio user */
}]
An action is a piece of logic executed by the app, most of the time when a component is pressed
An Action is a Typescript class that implements ActionInterface.
Its property values are resolved by Zyllio SDK and injected into the action instance as class members before execute() is called.
class MyAction implements ActionInterface {
message: string
async execute(): Promise<string | null> {
console.log(this.message)
return 'complete'
}
}
When an action needs to update a variable or a row value, mark the target property with write: true in metadata and assign the new value to the matching class member inside execute().
Studio lets the user choose where to write, and the runtime persists the value when the action updates the property.
class MyAction implements ActionInterface {
text: string
async execute(): Promise<string | null> {
const generatedValue = 'A new value'
this.text = generatedValue
return 'complete'
}
}
const MyActionMetadata = {
metadataVersion: 2,
id: 'my-action',
label: 'My action',
category: 'Utilities',
properties: [{
id: 'text',
name: 'Write in',
type: 'text',
default: '',
write: true
}]
}
To register an action to Zyllio platform, use registry service.
Actions must be registered with their constructor, not with an instance.
registry.registerAction(MyActionMetadata, MyAction)
Action Metadata is a static Javascript object that describes the action, it is required by Zyllio Studio to display its properties from the Action Editor. This metadata is compliant to these specifications
const Icon = `
<svg xmlns="http://www.w3.org/2000/svg" version="1.1" width="24" height="24" viewBox="0 0 24 24">
<path fill="#cccccc" d="M12,2A10,10 0 0,0 2,12A10,10 0 0,0 12,22A10,10 0 0,0 22,12A10,10 0 0,0 12,2Z" />
</svg>
`
const MyActionMetadata = {
metadataVersion: 2,
id: 'get-random-meme', /* Unique identifier, must be lower case */
icon: Icon, /* SVG icon displayed in Zyllio Studio */
label: 'Get random meme', /* Label displayed in Zyllio Studio */
category: 'Memes', /* Category in which the action is displayed in Zyllio Studio */
properties: [{ /* Properties to configure the action */
id: 'value', /* Unique id of the property, should be lower case */
name: 'Meme URL', /* Label displayed in Zyllio Studio */
type: 'row-variable', /* Type of the property from PropertyTypes enum (see Reference API) */
options: [], /* Array of possible options, used only when type is PropertyTypes.Options */
default: '', /* Default value if any, it is assigned at component creation by Zyllio Studio user */
main: true, /* Indicates whether this property is the main one */
write: true /* Indicates whether this property is used to save data at runtime (likely when an action needs to set data) */
}]
}
Formula functions are piece of presentation to display complex data (math, substring, unit convertion, distance calculation)
A generation 2 Function is a Typescript class that implements FunctionInterface.
Its property values are resolved by Zyllio SDK and injected into the function instance as class members before execute() is called.
class AreaFunction implements FunctionInterface {
width: number
height: number
async execute(): Promise<string> {
return (this.width * this.height).toString()
}
}
To register a Formula function to Zyllio platform, use registry service.
Generation 2 formula functions must be registered with their constructor, not with an instance.
registry.registerFunction(AreaMetadata, AreaFunction)
Function Metadata is a static Javascript object that describes the function, it is required by Zyllio Studio to display its properties from the Formula Editor. This metadata is compliant to these specifications
const IconData =
'<svg xmlns="http://www.w3.org/2000/svg" version="1.1" width="24" height="24" viewBox="0 0 24 24" fill="currentColor">' +
'<path d="M4 6H20V18H4V6M6 8V16H18V8H6Z" />' +
'</svg>';
const AreaMetadata = {
metadataVersion: 2,
id: 'area',
icon: IconData,
label: 'Area',
category: 'Number',
properties: [{
id: 'width',
name: 'Width',
type: 'number',
default: '0',
}, {
id: 'height',
name: 'Height',
type: 'number',
default: '0',
}]
}
Themes are shade of colors to customize the appearance of screens across the whole app
A theme is defined as per these specifications
const theme = {
name: 'MyTheme', /* Name displayed in Zyllio Studio */
theme: {
primaryColor: '#4f7d96', /* Background color used in primary components (header, footer) */
primaryTextColor: '#ffffff', /* Text color used in primary components (header, footer) */
secondaryColor: '#fe844b', /* Background color used in secondary components (button, list, carousel) */
secondaryTextColor: '#ffffff', /* Text color used in secondary components (button, list, carousel) */
tertiaryColor: '#0000000a', /* Background color used in tertiary components (input fields) */
tertiaryTextColor: '#000000', /* Text color used in tertiary components (input fields) */
backgroundColor: '#f0f6f9', /* Screen background color */
textColor: '#474f5b', /* Text color */
rtl: false /* Indicates whether Right To Left alignment should be activated mainly to support Arabic and Asian languages */
}
}
To register a new Theme, use registry service
registry.registerTheme(theme)
Visual components could make use of theme style properties using the following CSS variables
These variables are set at body level automatically by Zyllio SDK at startup
Zyllio team is available for any support, feature requests and questions