ZYLLIO Plugin Development guide

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

• Components are Visual Components set in screens like Texts, Lists, Buttons, ...
• Actions are pieces of logic executed when the app user presses a button
• Formula functions are piece of presentation to display complex data (math, substring, unit convertion, distance calculation...)
• Themes are shade of colors to customize the appearance of screens across the whole app

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

Experiment

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 repositories

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

Development environment

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

Install Zyllio SDK

To install Zyllio SDK run the folowing command

npm install @zyllio/zy-sdk --save-dev

Use Zyllio SDK

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

Reference API

This document is an overview of the reference API, please consider the comprehensive Reference API for more information Zyllio SDK Reference API

Registering Components

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 properties
• row-variable properties are assigned as element properties

To 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.detail
• update-row: updates table row data using event.detail.item and event.detail.fields

This 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

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

• Properties Panel
• Styles Panel

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 */
  }]

Registering Actions

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

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) */
  }]
}

Registering Formula functions

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)

Formula Function Metadata

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',
  }]
}

Registering Themes

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)

Use theme from Visual components

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

• --theme-primary-color : Background color used in primary components (header, footer)
• --theme-primary-text-color: Text color used in primary components (header, footer)
• --theme-secondary-color: Background color used in secondary components (button, list, carousel)
• --theme-secondary-text-color: Text color used in secondary components (button, list, carousel)
• --theme-tertiary-color: Background color used in tertiary components (input fields)
• --theme-tertiary-text-color: Text color used in tertiary components (input fields)
• --theme-background-color: Screen background color
• --theme-text-color: Text color
• --direction: Indicates whether Right To Left alignment should be activated to support Arabic and Asian languages

Support

Zyllio team is available for any support, feature requests and questions

• email: contact@zyllio.com
• linkedin: @zyllio