Screen definitions

Sometimes plugins need to define new screens, that may be simple as a single html or comple JS applications.

Manifest YAML component definition

id: screenid
name: Label
description: Description
traits: url ssh
perms: []

The id will be used to resolve the HTML and JS files as as static/[component_id].html and static/[component_id].js from the plugin directory.

If they do not exist a warning is emitted to the console, but no further action is done. This means that both are optional.

Permissions are the required permissions to see this screen. This is only used for UI and is not secure: the API does not restrict to see that this exists, and to load the code of the screen. It MUST be used in conjunction with the command permissions to allow only allowed actors to execute plugin actions.

HTML file

The html will be embeded into the serverboards UI, and must not load external scripts; use the js file for that.

All src relative references will be changed at load time to point to the static directory of your plugin. This means that you can use normal images, scripts and css files. Remember that js files are better loaded using the static/[component_id].js file.

It should use Semantic UI for its UI and if some custom CSS is required is better to do it inline, but an external CSS may be called.

Many times this is enough for simple screens, but if comples React applications are required, check below the Using React section.

JS file

There is Serverboards global object with the following elements:

Key Description
add_screen Function to call at main JS file.
React Main React object. Used to be able to create new components using the same already present React framework.
store Global Redux store
rpc rpc object to call remote RPC methods and subscribe to events
Flash Flash object to show flash messages

The loaded JS file must call the method Serverboards.add_screen(plugin_id, fn(el, config, context)) that will be called when the user gets inside the given screen. It is guaranteed that the related HTML file will already be in place. All data MUST be local to the JS file as there may be many others JS files and this prevents JS namespace pollution and collissions.

The el HTML element is ensured to have the data-pluginid and data-screenid with the plugin id and the screen id respectively.

The config is an object with the related service data. Its good practice to do not assume any data in it, as the screen can be called from many places including other not well formed plugins.

context has data about the context of execution, that depends on where it is called. It has:

  • plugin_id – The plugin id
  • component_id – The widget component_id
  • screen_id – The full widget id (plugin_id/component_id)

It is highly recomended to encapsulate your code to use IIFE, to avoid pollution of the global namespace, as this may affect other pplugins, and other plugins may affect your code. For example if you depend on a function main, without proper encapsulation, another ill behaving plugin JS may define another main that will override yours, and your or its will be called.

Using React

[TODO]

It will be possible to use React in a recommended way, but we are still working on it. The recomended way now is transpile your individual React files into a bundle that should not include the React object. It is provided as indicated at JS file.

Actually it is possible to use your full React Single Page Application as a component, and there should not be huge performance penalties for doing it this way.

Many already developed plugins do it this way.