L'Math Plugin API

Hello, and welcome to the "beautiful" (horrible) documentation of L'Math's WIP plugin API. The purpose of this API is to allow users (...nerds) extend and enhance the software.

Basics

Just like L'Math itself, user-created plugins are written in JavaScript. Feel free to use any languages that transpile to ES6 compliant vanilla JS. Basic node.js features can be used, but the developer will not provide any support whatsoever outside the provided API.

Plugins are stored and loaded from the data folder

• %APPDATA%\LMath\plugins on Windows
• ~/Library/Application Support/LMath/plugins on macOS
• ~/.local/share/LMath/plugins on GNU/Linux

The plugin api was introduced in version r1.7, so, you won't find the plugins folder if you haven't updated.

Plugins have to be installed in the following fashion:

• plugins/
  • plugin-id
    • plugin.json - the metadata file
    • ... - any other files
  • another-plugin-id
    • plugin.json
    • ...

Every plugin is its own folder, named with the plugin's id defined in the plugin.json file.

Backend and frontend

L'Math consists of two parts: the node.js backend and the Electron frontend. Even though L'Math isn't sandboxed and node.js integration is allowed on the frontend, it is highly recommended to use the messaging channel provided by the plugin API. The plugin api uses the ipc messaging channel, and its sole purpose is to enable communicate between the two processes.

plugin.json

The plugin.json file is the metadata file. The main purpose of the file is to act as an information source. This file contains information about the plugin, including the id, version, author and modules to be loaded. The plugin.json file has similarities with a typical package.json file, but it's not to be confused with one. L'Math reads and interprets plugin.json files in its own way.

Example plugin.json

{
    "id": "test-plugin",
    "name": "Test plugin 123",
    "description": "Just a test plugin.",
    "author": "Roni Lehto",
    "modules": [
        {
            "type": "backend",
            "file": "plugin.js"
        },
        {
            "type": "frontend",
            "file": "front.js"
        }
    ],
    "pluginVersion": "1.0",
    "requiredVersion": "r1.7"
}

The id field has to equal to the folder name, otherwise the plugin will not be loaded. If the plugin.json file doesn't exist, the folder will be ignored.

There is an array named modules in the metadata file. It basically lists all JS files that should be loaded and where to load them. If a module should be loaded on the backend side, its type field should equal to backend, and similarly frontend for every frontend module.

Plugin modules

As stated at the metadata file section, in order to actually get anything done, a plugin should have loadable modules. These modules will be loaded using a standard require call, and have to have an init method. Some useful arguments are passed to the init methods. To learn more, see the plugin page.

Plugins can interact with the program using a set of revealed objects. The frontend side gets the window object and an API object. Similarly the backend side gets a logger object and an API object. More about the API object down below.

The plugin API objects

Horribly bad documentation is available here. Feel free to take a look at the example plugin.