Configuring Desktop

As a complex widget, Desktop consists of many stand-alone Webix views with its own API.
You can redefine inner views and also you can work with the specific Desktop settings.

Basic Configuration

You can use the following settings to provide the basic config of the widget:

systemParams (object) - contains custom parameters to be passed to the launch method;
apps (array) - an array of apps.

webix.ui({
    view: "desktop",
    systemParams: user,
    apps: myApps,
    ...
});

There are additional properties, which can be redefined if you need to make changes to a default configuration, such as tileAlign, grid, tileLayout and barPosition.

App Structure

Each object in the apps array contains settings for a particular app:

name - (string) the application name (must be unique)
icon - (string) optional, the application icon
id - (number | string) optional, app id
pin - (array) optional, defines where the application icon should be pinned. Possible options are "bar" and "desktop".
showNew - (boolean) optional, allows to open several windows of the same app
launch - (function) the method called on application launch. It loads the necessary libraries and returns a promise that is resolved with the app handlers.

Handlers

The launch() method returns an object containing the app's lifetime handlers. These handlers are used to initialize the app and respond to state changes:

"init" - handles app initialization
"destroy" - handles events before the app window is destroyed
"on" - handles various state changes

Related sample: Desktop: App Handlers

"Init"

The "init" event fires when the app window is created. The handler of this event is obligatory for correct work of the app. It takes 2 parameters:

container - {object} window HTML container, which can be used for initializing non-Webix apps;
appDataObj - {object} an app data object that each handler receives. Initially, it contains only the "$view" property for Webix views and applications, but you can add any additional properties to it.

In case of Webix view initialization, the "init" handler should return an object with view configuration:

view: "desktop",
apps: [
    { 
        name: "My App",
        icon: "imgs/myapp.png",
        launch: () => ({ init: () => ({ template: "My app" }) }),
   }
]

For Webix Jet apps (f.e. Scheduler, FileManager), "init" should return the app itself:

view: "desktop",
apps: [
    { 
        name: "filemanager",
        icon: "imgs/fm.png",
        launch: () => {
        webix.require("//cdn.webix.com/pro/edge/filemanager/skins/material.css");
        return webix.require("//cdn.webix.com/site/filemanager/filemanager.js").then(() => ({
            init: () =>
             new fileManager.App({
            url: "https://docs.webix.com/filemanager-backend/",
             })
        }));
        },
    }
]

"init" shouldn't return anything for non-Webix apps. The first argument is used to initialize the custom app inside the window container:

view: "desktop",
apps: [
    { 
        name: "TinyMCE",
        icon: "imgs/editor.png",
        launch: (sysParams) => {
        return webix.require(
            "https://cdn.tiny.cloud/1/no-api-key/tinymce/4.9.6-54/tinymce.min.js")
            .then(() => ({
                init: (container, options) =>{
                    container.innerHTML = "<textarea id='my_editor'></textarea>";
                    tinymce.init({              
                        selector: "#my_editor",
                        ...
                    });
                    ...
                }
        }));
        },
    }
]

Related sample: Desktop: External App

"Destroy"

The "destroy" event fires before the app window is destroyed. The handler of this event takes one parameter:

appDataObj - {object} an app data object that each handler receives

view: "desktop",
apps: [
    { 
        name: "MyEditor",
        icon: "imgs/editor.png",
        launch: (sysParams) => {
        return webix.require(
            "https://cdn.tiny.cloud/1/no-api-key/tinymce/4.9.6-54/tinymce.min.js")
            .then(() => ({
            ...
                destroy: appDataObj =>{
                    appDataObj.myEditor.remove();
                    appDataObj.myEditor = null;
                },
        }));
        },
    }
]

"On"

There are some more window events for which you can provide a handler:

"resize" - fires when the window resizes and takes the window body size as a parameter.
"deactivate" - fires when a window is closed to the tray;
"activate" - fires when a window is restored from the tray;
"afterinit" - fires after the "init" event.

Handlers for these events are set using the "on" method, which takes 3 parameters:

eventName - {string} an event name;
params - {object} an object with event parameters (f.e. "width" and "height" for the "resize" event);
appDataObj - {object} an app data object that each handler receives.

view: "desktop",
    apps: [{
            name: "MyApp",
            launch: (sParams) => {
                ...
                return {
                    ...
                    on: (evName, params, appDataObj) => {
                        if (evName == "resize") {
                            const {
                                width,
                                height
                            } = params;
                            ...
                        }
                    }
 
                },
            },
            ...
        ],

Compact mode

You can set the compact mode via the compact property of the constructor and provide a width value:

webix.ui({
    view: "desktop",
    systemParams: user,
    apps: myApps,
    width: 400,
    compact: true
});

Related sample: Desktop: Compact Mode