[ADR] Make use of Addons

Owned by pascal wilbrink
Last updated: Jul 03, 2023 by Steffen van den Driest
2 min read

Context

Current problems:

No easy way to extend OpenSCD-Core e.g.

  • No options to run code in the background if a solution requires this
  • No way to introduce new functionality without making a stable API for all plug-in authors / no easy way to experiment
  • Minimize the risk of forking (since OpenSCD-core is apparently missing functionality)


CoMPAS needs a extension in order to allow:

  • Connecting it to a monitoring system agent (e.g. Elastic APM)
  • Single sign-on (user authorization)


Decision


The use of OpenSCD addons

OpenSCD addons are an extension of OpenSCD-Core to split functionality. This functionality can be pure technical and requires no custom UI. Examples for some OpenSCD addons are Wizarding, Validating, Waiting, etc.

OpenSCD addons will be a replacement for current mixins, so there is no/less need to fork  OpenSCD-Core and to build mixins on top of the fork. Addons allow experiments with (potential) new core functionality. Succesful addons can be merged into OpenSCD-Core.


Example

Example: Wizarding API is hard to make pefect in the first run. If started with an addon for wizarding, we can experiment/use it. If it turns out that the addon is missing crucial functionality. We can introduce a new addon next to the old addon (with its limitations).


If we want OpenSCD to be extendable, we should allow OpenSCD to support `addons`.  An addon is like a plug-in, but without the requirement of needing to extend from `HTMLElement`. An `add-on` is a default exported function from a file.
an `addon` function gets the `OpenSCD` class as a parameter. From here, it can fetch the document if needed. It can also subscribe to events dispatched to `open-scd`.
By implementing addons, we can minimize the risk of people forking OpenSCD and adding new functionality. If people want extra functionality on OpenSCD, they can create an addon for it.


export default function xsdValidate(openSCD: OpenSCD) {
    openSCD.addEventListener('validate', (evt: ValidationEvent) => {
        const { doc } = openSCD;
        // Do actual validation to the doc.
    });
}

When `addons` or `background plug-ins` are supported, it will be possible to migrate current mixins from OpenSCD into `addons` or `background plug-ins`.

An `addon` is a function that's not depending on anything. The `addon` function gets the `OpenSCD` instance class as a parameter.

Once a addon is used a lot and considered stable, it could become a part of OpenSCD-Core itself.



Alternatives

Background plug-in

Another option is to support a new kind of plug-in, `background` plug-ins. These plug-ins are rendered upon document load, like the `menu` plug-ins. Except these plug-ins are not shown in the UI. These plug-ins use the dom for dependency injection.

Pros
- It can use the current `plug-in` mechanism to load.
Cons
- A background plug-in is extending from `HTMLElement` but it's not rendering anything. This goes against the `CustomElement` principles.
- The dom can get polluted quickly by creating background plug-ins


Other alternatives: OpenSCD-core addons alternatives


Consequences

  • `Addons` need to be loaded apart from `plug-ins` 
  • Risk of having addons with similar functionality