Skip to content

Plugins

Jump to bottom
Mark Friedrich edited this page Feb 1, 2020 · 2 revisions

Important: Custom plugins require Pathfinder ≥ v.2.0!

What are "plugins"?

Plugins are extensions in form of UI modules (users can interact with) that provide some custom features which are currently not implemented in Pathfinder.

As of ≥ v.2.0 Pathfinder provides a simple API for plugins where self hosted installations of Pathfinder can be configured with custom plugins.

Just as the default modules (e.g. "Signatures", "Routes", "Killboard",…), custom plugins render their own module/panel UI. Plugins get auto updated by PF whenever the underlaying map data was changed.

Limitations for plugins:

  • The "plugin system" is still [BETA], the API interface for loading/updating custom plugins might change at any time! - Make sure to test your plugins after Pathfinder was upgraded.
  • At this point custom plugins should not make any backend/ajax calls to Pathfinder! All data, a plugin has access to, can be accessed by the plugin API.

Demo:

There are two custom plugins/modules available for developers by default, that can be activated through the "layout settings" popover. They should be used as boilerplate and demonstrate how plugins/modules interact with the the plugin API.

layout settings

  • "(sys) Empty" - Blank module with minimal/base configuration

    Empty module

  • "(sys) Demo" - Demo of the plugin API

    • shows the "life-cycle" of a module in form of plugin handler/methods
    • visualization of render/update/destroy handlers for current plugin/module instance
    • visualization of other event handlers e.g. "drag&drop", "sort", "lock"

    Demo module

Load/Install plugins:

All custom plugins/modules are defined in plugin.ini.

Like all other *.ini files, you can add a new plugin.ini to a custom dir (see CONF.CUSTOM = conf/ in config.ini) to overwrite settings from the default plugin.ini. This prevents GIT conflicts inside an *.ini file, when Pathfinder gets updated (e.g. git pull).

plugin.ini:

MODULES_ENABLED = 1 is a global trigger that enables the plugin loader.

Each custom plugin must be added to the [PLUGIN.MODULES] section. Successfully loaded plugins can be activated by users from the "layout settings" popover (see prev images).

Guidelines for development:

  • Good skills in Javascript development. → Plugins are written as JS Class()-es [ECMAScript 6 (ES6)].
  • Honor the scope. - Each plugin has its own *.js file. Stick close to the methods/interface, provided by the plugin API to update the UI of your plugin/module. Do not change any JS code outside the scope/file of your plugin!
  • Minimal dependencies. → Plugins should be written in vanilla JS. Even though you can requireany other JS file/lib from Pathfinder´s core (e.g. jQuery,...), it is highly recommended to keep your plugins independent from other scripts.
  • Plugin "life-cycle". → Each instance of a plugin/module has its own life-cycle. (e.g. Clients with access to 3 maps and one active system per map handles 3 instances of a plugin).
  • Objects are a reference type. → All map data send to a plugin/module instance is a reference. Changes(or delete) will affect other plugins and might break Pathfinder! You should always (deep) clone data objects before manipulation.
  • Graceful unload/destroy instances. → Since Pathfinder is a SPA, it is important to clean up variables if they are no longer needed! Use the beforeDestroy() handler to unload/destroy open dialogs, active tooltips,…
  • Error handling. → You are responsible for catching JS errors thrown inside a plugin/module instance. You can send UI notifications to users and/or provide alternate code to run in case of unexpected errors…. Uncaught exceptions/errors are handled by Pathfinder´s default error handler → console.error().

If you like Pathfinder , why not make a donation?

PayPal Patreon
PayPal Patreon
Clone this wiki locally