plugin-api.md

OpenSCD API for plugins

Overview

OpenSCD is a plugin-based editor for editing XML files in the IEC 61850-6 "SCL" dialect directly in the browser.

OpenSCD core is the central supervisory component which coordinates the work of all the plugins, allowing them to work together in editing the same SCL document.

An OpenSCD plugin is a custom element that has been registered in the global customElements registry under some tag name. OpenSCD core renders an element with that tag name into the app. The component may optionally provide a run() method for OpenSCD core to call in order to trigger an action.

The OpenSCD core API describes the ways in which:

• OpenSCD core communicates relevant data to the plugins,
• plugins communicate user intent to OpenSCD core, and
• OpenSCD sets CSS fonts and colors for plugins.

Communicating data to plugins

OpenSCD core communicates the data necessary for editing SCL documents by setting the following properties on the plugin's DOM Element:

export default class MyPlugin extends HTMLElement {
  editor: Transactor<EditV2>;
  docs: Record<string, XMLDocument> = {}; // all loaded documents
  doc?: XMLDocument; // the document currently being edited
  docName?: string; // the current doc's name
  docVersion: unknown; // changes value when the document is modified.
  locale: string = 'en'; // the end user's chosen locale
}

editor

editor provides a reference to the central editor class used for modifying SCL documents. For more details on the Transactor (Defaults to XMLEditor). For more on the XMLEditor checkout the documentation

docs

docs is set to an object mapping string keys (document names) to XMLDocument values.

docName

The name of the XMLDocument currently being edited.

doc

The XMLDocument currently being edited.

docVersion

A value which changes with edits to the current document.

locale

Selected language (IETF language tag).

Communicating user intent to OpenSCD core

Plugins communicate user intent to OpenSCD core by dispatching the following custom events:

EditEventV2

The edit event allows a plugin to describe the changes it wants to make to the current doc.

export type EditDetailV2<E extends EditV2 = EditV2> = {
  edit: E;
  title?: string;
  squash?: boolean;
};

export type EditEventV2<E extends EditV2 = EditV2> = CustomEvent<
  EditDetailV2<E>
>;

export type EditEventOptions = {
  title?: string;
  squash?: boolean;
};

export function newEditEventV2<E extends EditV2>(
  edit: E,
  options: EditEventOptions,
): EditEventV2<E> {
  return new CustomEvent<E>('oscd-edit-v2', {
    composed: true,
    bubbles: true,
    detail: { ...options, edit },
  });
}

declare global {
  interface ElementEventMap {
    ['oscd-edit-v2']: EditEventV2;
  }
}

Its title property is a human-readable description of the edit.

The squash flag indicates whether the edit should be merged with the previous edit in the history.

EditV2 type

The EditDetailV2 defined above contains an edit of this type:

export type EditV2 =
  | Insert
  | SetAttributes
  | SetTextContent
  | Remove
  | EditV2[];

This means that a single edit can either consist in a sequence of other edits or in one of the following atomic edit types:

Intent to set or remove (if null) attributes on element.

/** Record from attribute names to attribute values */
export type AttributesV2 = Partial<Record<string, string | null>>;

/** Record from namespace URIs to `Attributes` records */
export type AttributesNS = Partial<Record<string, AttributesV2>>;

/** Intent to set or remove (if `null`) `attributes`(-`NS`) on `element` */
export type SetAttributes = {
  element: Element;
  attributes?: AttributesV2;
  attributesNS?: AttributesNS;
};

Intent to set the textContent of element.

export type SetTextContent = {
  element: Element;
  textContent: string;
};

Intent to parent.insertBefore(node, reference)

export type Insert = {
  parent: Node;
  node: Node;
  reference: Node | null;
};

Intent to remove a node from its ownerDocument.

export type Remove = {
  node: Node;
};

OpenEvent

The open event allows a plugin to add a document doc to the docs collection under the name docName.

export type OpenDetail = {
  doc: XMLDocument;
  docName: string;
};

export type OpenEvent = CustomEvent<OpenDetail>;

export function newOpenEvent(doc: XMLDocument, docName: string): OpenEvent {
  return new CustomEvent<OpenDetail>('oscd-open', {
    bubbles: true,
    composed: true,
    detail: { doc, docName },
  });
}

declare global {
  interface ElementEventMap {
    ['oscd-open']: OpenEvent;
  }
}

Theming

OpenSCD core sets the following CSS variables on the plugin:

* {
  --oscd-primary: var(--oscd-theme-primary, #2aa198);
  --oscd-secondary: var(--oscd-theme-secondary, #6c71c4);
  --oscd-error: var(--oscd-theme-error, #dc322f);

  --oscd-base03: var(--oscd-theme-base03, #002b36);
  --oscd-base02: var(--oscd-theme-base02, #073642);
  --oscd-base01: var(--oscd-theme-base01, #586e75);
  --oscd-base00: var(--oscd-theme-base00, #657b83);
  --oscd-base0: var(--oscd-theme-base0, #839496);
  --oscd-base1: var(--oscd-theme-base1, #93a1a1);
  --oscd-base2: var(--oscd-theme-base2, #eee8d5);
  --oscd-base3: var(--oscd-theme-base3, #fdf6e3);

  --oscd-shape: var(--oscd-theme-shape, 8px);

  --oscd-text-font: var(--oscd-theme-text-font, 'Roboto');
  --oscd-text-font-mono: var(--oscd-theme-text-font-mono, 'Roboto Mono');
  --oscd-icon-font: var(--oscd-theme-icon-font, 'Material Icons');
}