Write your first Add-on

First, we will focus on the frontend UI part of your Add-on.

Specific app functionality can be defined using the Admin API (for access to the backend services, such as shop/product data) and the Add-on API (for access to the SCAYLE Panel session data, such as user information).

The Add-on UI is written as a micro frontend, utilizing the single-spa framework. It can be written in the JavaScript framework of your choice. However, we recommend using Vue 3. This will also allow you to utilize the Panel style component library, assuring the look and feel of your Add-on matches the rest of the SCAYLE Panel. You can find out more about the concept of micro frontends at single-spa.js.org.

Every new Add-on application is set up and configuration similar to our demo Add-on. It requires a manifest file where application data and routes are set.

SPA Overview

Add-on Apps are:

Written as JavaScript applications
Mounted through single-spa (single-spa.js.org)
Packaged in the systemjs format

Applications should be wrapped as a single-spa application. In other words, it is an object containing three methods:

bootstrap
mount
unmount

bootstrap is called the first time the application is mounted while mount and unmount contain the logic for mounting and un-mounting the application.

How frontend Add-on Apps are loaded into the SCAYLE Panel

On the initial page load, the SCAYLE Panel will request the manifest file of each active Add-on. Inside the manifest, the Add-on app will be registered with single-spa.

Single-spa then automatically loads or unloads applications on URL changes. When the URL matches /add-ons/{addOnName}/* or /shops/:id/{addOnName}/* the Add-on with that name is loaded.

Each Add-on should have a unique identifier, used as part of the URL. In case the app URL of multiple Add-ons is the same, opening one of the Add-ons results in loading all of them. This can cause undesirable behavior such as the sidebar loading multiple times.

Manifest file

Each Add-on app must have a manifest file. This is the file that the SCAYLE Panel fetches in order to load the application. The manifest should export a single function manifestRegistration.

The manifest should be formatted in the System.register module format. With Webpack, this can be configured by setting output.library.type to be system (or set rollup's format to "system").

See Webpack documentation for more information.

When using Webpack

Make sure you are using Webpack 5 or greater. Since Webpack 4 does not support outputting in the System.js format, it will not work properly.
It’s also important to configure the Webpack public path so that additional chunks will be loaded from your Add-on server instead of the cloud-panel.

Here’s an example of an app manifest (from the demo Add-on), it contains the configuration for registering your Add-on into the single-spa framework and registers your Add-on routes:

Routes

For routes, the routes.ts file is the single source of truth. Import and map routes in the manifest.ts file as shown in the example below. Properties required for the manifest routes should be defined in the route meta of routes.ts.

To define the path of route children, use one of the following formats: :id OR /table-listing/:id.

Here’s an example router.ts file:

import { createRouter, createWebHistory, RouteRecordRaw } from 'vue-router';
import { GroupRouteDefinition } from './types';
import { ADD_ON_ID, BASE_URL, generateGroupName } from './utils';

// Use dynamic imports to enable code-splitting
const DashboardPage = () => import('./pages/DashboardPage.vue');
const AlertsPage = () => import('./pages/AlertsPage.vue');
const FormPage = () => import('./pages/FormPage.vue');
const TableListing = () => import('./pages/TableListing.vue');
const ComponentsPage = () => import('./pages/ComponentsPage.vue');

export type AddOnRoute = Omit<RouteRecordRaw, "meta"> & { meta: GroupRouteDefinition };

export const routes: AddOnRoute[] = [
    {
        name: 'dashboard',
        path: '/',
        component: DashboardPage,
        meta: {
            id: 'dashboard',
            name: {
                'en': 'Dashboard',
                'de': 'Dashboard'
            },
            icon: 'dashboard',
            path: BASE_URL + '/',
            sidebar: ADD_ON_ID,
            group: generateGroupName('general'),
        }
    },
    {
        path: '/table-listing',
        component: TableListing,
        children: [
            {
                name: "table-detail",
                path: ":id",
                component: TableListing
            }
        ],
        meta: {
            id: 'table-listing',
            name: {
                'en': 'Table Listing',
                'de': 'Tabellenauflistung'
            },
            icon: 'data-table',
            path: BASE_URL + '/table-listing',
            sidebar: ADD_ON_ID,
            group: generateGroupName('general'),
        }
    },
    {
        path: '/form',
        component: FormPage,
        meta: {
            id: 'form',
            name: {
                'en': 'Form',
                'de': 'Form'
            },
            icon: 'search',
            path: BASE_URL + '/form',
            group: generateGroupName('general'),
        }
    },
    {
        path: '/alerts',
        component: AlertsPage,
        meta: {
            id: 'alerts',
            name: {
                'en': 'Alerts',
                'de': 'Meldungen'
            },
            icon: 'warning',
            path: BASE_URL + '/alerts',
            group: generateGroupName('general'),
        }
    },
    {
        path: '/components',
        component: ComponentsPage,
        meta: {
            id: 'components',
            name: {
                'en': 'Components',
                'de': 'Komponenten'
            },
            icon: 'ufo',
            path: BASE_URL + '/components',
            group: generateGroupName('general'),
        }
    },
];

export default createRouter({
    routes: routes as RouteRecordRaw[],
    // Make sure to set the base because all Add-on pages will be under add-ons/demo
    history: createWebHistory(BASE_URL),
});

Permissions

Each Add-on defines its own permissions. They are published to the SCAYLE Panel via the Add-on API. Permissions can then be assigned to roles, which are attached to users, using the SCAYLE Panel.

Follow our Add-on API Guide to see how you can publish permissions, from your backend application.

*Permissions are defined for each Add-on and published to the SCAYLE Panel via the Add-on API.*

Permission Naming Rules

A permission name follows a simple structure to be displayed correctly inside the role creation.

{{add-on-name}}__{{section}}__{{permission}}

For example, you may want to have your own section within the permissions that is called “Posts”, and within this is the permission “Update”. The full permission name could look as follows: your-add-on-identifier__posts__update.

Read more about the translation of permissions below.

SCAYLE Panel User Authentication

Once the user is logged into the SCAYLE Panel, all registered Add-ons will have access to the current user’s Authorization Token (available under window.Scayle.Panel.Config.auth.token
e.g.: 3|yUt2******************RyQ9)

That Authorization Token can then be used by your Add-on backend application, to authorize the user against the Add-on API.

Read more about the Add-on API Get User endpoint.

Why your Add-on backend application needs to authorize users against the Add-on API?

The goal is, to initiate your own auth token for all communication between your Add-on frontend and backend. To achieve that, your Add-on frontend sends the SCAYLE Panel Authorization Token to your Add-on backend. To confirm the authenticity of that provided SCAYLE Panel Authorization Token, your Add-on backend validates the Token against the SCAYLE Add-on API, and receives confirmation whether the Token is valid or not. The SCAYLE Add-on API response also includes up-to-date information about the users' permissions.

We recommend a dedicated backend route for this initial authentication process (e.g., /api/v1/external/add-ons/user).

*Token-based authentication between the* SCAYLE *Panel and Add-on.*

The Add-on API response only returns the information that belongs to the requesting Add-on. For example, User Custom Data only returns the permissions and custom data that was added through the Add-on. All other information is based on the SCAYLE Panel user.

Example response

Translations

The Add-on API translations endpoint allows developers to easily create and modify translations for Add-ons. Translations can be applied to the Add-on permissions, title, and descriptions. You cannot, for example, apply a button's translation.

Translations are divided into two types:

System Translations
- permission translations (e.g., add-on-dev-guide__dashboard__view). Those translations can be seen in the Settings/Roles section where the permissions are configured
Add-on Translations (title, description) title or description
- Those translations can be seen inAdd-on Edit page next to the title and description.

System Translations
permission translations (e.g., add-on-dev-guide__dashboard__view). Those translations can be seen in the Settings/Roles section where the permissions are configured
Add-on Translations (title, description) title or description
Those translations can be seen in Add-on Edit page next to the title and description.

System Translations

For System translations, we first need to set up some permissions.

Create a set of permissions with the Add-on API

Add translations for the Add-on, permission groups and the permissions

Follow our Add-on API Guide to see how you can create translations, from your backend application.

These translations are then visible under Settings ➜ Users management ➜ Roles for the corresponding Add-on.

*Add-on permissions with Add-on title, permission group, and permissions.*

Panel-Event Webhooks

It is possible for Add-ons to receive messages when certain events happen in the panel (i.e, user updates, role updates).

To receive these messages, two conditions need to be met:

A callback URL is configured for the Add-on (that can be defined in the SCAYLE Panel Add-on config page)
The Add-on is active in the SCAYLE Panel

That callback URL should accept a POST request with content type: application/json.

To increase security of incoming webhooks calls, the best option is to whitelist the domains that the calls can come from (e.g., *.scayle.cloud), or to use Basic Auth.

Message Structure

Every message sent to the callback URL will have the same structure:

Property	Type	Notes
event	string	Contains the event key, which will be used by the Add-on to determine which flow should be used in any case. Dot-separated string with the following structure: `{model}.{action}` (e.g., `user.created`)
context	object	Contains any exposed model attribute. Its content varies from model to model, but all events related to the same entity will have the same fields.
id	int	ID of the entity that has been affected (i.e., the user ID for User)

Model Definition

Every model that will post messages is defined below.

Deleted events will not contain any field in their context attribute of the message.

Model	User
Possible events	`UserCreated`, `UserUpdated`, `UserDeleted`, `UserLoggedOut`, `UserUpdatedPassword`
Context fields	none
Structure example	`{"id": 4, "event": "UserCreated", "context": {},}`

Model	Role
Possible events	`RoleCreated`, `RoleUpdated`, `RoleDeleted`
Context fields	none
Structure example	`{ "id": 6, "event": "RoleUpdated", "context": {"userIds": [3,5,6]},}`

Create your first Add-on

Add-on
Tech

Mikheil Kupatadze

Senior Frontend Developer

Add-ons

Your first SCAYLE Add-on

Intermediate
4 lessons
26m

Play tutorial