Skip to content

docs(API): remove plugin management #35

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ca-d wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(API): remove plugin management #35

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 12 additions & 81 deletions API.md → docs/API.plugins.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,16 +1,12 @@
# OpenSCD core API
# OpenSCD core 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 [JavaScript module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) which exports a particular [custom element class](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#implementing_a_custom_element) as its [default export](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules#default_exports_versus_named_exports). OpenSCD core imports the module, registers its custom element under a uniquely generated tag name, and finally renders a new element with that tag name into the app.

An **OpenSCD menu plugin** is an OpenSCD plugin with an additional `run()` instance method which is called when the plugin's entry is clicked in OpenSCD's menu. It is continuously rendered into the app and is expected to normally not display any content of its own. It is meant for one-shot editing tasks or tasks that always run in the background (like validation).

An **OpenSCD editor plugin** is a OpenSCD plugin that is only rendered as long as the user has its tab selected in OpenSCD's tab bar. It is meant for rendering the main part of OpenSCD's user interface.
An **OpenSCD plugin** is a [custom element](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_custom_elements#implementing_a_custom_element) that has been registered in the global [`customElements`](https://developer.mozilla.org/en-US/docs/Web/API/Window/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,
Expand All @@ -24,42 +20,15 @@ OpenSCD core communicates the data necessary for editing SCL documents by settin

```typescript
export default class MyPlugin extends HTMLElement {
docs: Record<string, XMLDocument> = {};
doc?: XMLDocument;
docName?: string;
editable: string[] = [
'cid',
'icd',
'iid',
'scd',
'sed',
'ssd',
];
history: LogEntry[];
editCount: number = 0;
plugins: { menu: Plugin[], editor: Plugin[] }[];
locale: string = 'en';
}

/** Helper types exported by OpenSCD core **/

type LogEntry = {
redo: Edit; // `Edit` defined below
undo: Edit;
title?: string
}

type Plugin = {
name: string;
translations?: Record<string, string>;
src: string;
icon: string; // Material icon name or image URL
requireDoc?: boolean; // disable plugin if no doc is opened
docs: Record<string, XMLDocument> = {}; // all loaded documents
doc?: XMLDocument; // the document currently being edited
docName?: string; // the current doc's name
docVersion: unknown; // current doc's state indicator
locale: string = 'en'; // the end user's chosen locale
}
```

### `docs`

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

### `docName`
Expand All @@ -68,22 +37,10 @@ The name of the `XMLDocument` currently being edited.
### `doc`
The `XMLDocument` currently being edited.

### `editable`
Filename extensions of user-editable documents.

### `history`
History of edits done to `doc`.

### `docVersion`

A change in the property indicates a change to the `doc` as a result of edits (including undo and redo).

### `plugins`

Arrays of `Plugin` objects describing the currently loaded `menu` and `editor` plugins, respectively.
A change in this property's value indicates a change to the `doc`.

### `locale`

Selected language (IETF language tag).

## Communicating user intent to OpenSCD core
Expand Down Expand Up @@ -123,16 +80,15 @@ declare global {
}
```

Its `title` property is a human-readable description of the edit for displaying in the editing history dialog.
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.

#### `Edit` type

The `EditDetailV2` defined above contains an `edit` of this type:

```typescript
export type EditV2 = Insert | SetAttributes | SetTextContent | Remove | Edit[];
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:
Expand Down Expand Up @@ -204,7 +160,7 @@ The **wizard event** allows the plugin to request opening a modal dialog enablin
```typescript
/* eslint-disable no-undef */
interface WizardRequestBase {
subWizard?: boolean;
subWizard?: boolean; // TODO: describe what this currently means
}

export interface EditWizardRequest extends WizardRequestBase {
Expand Down Expand Up @@ -277,30 +233,6 @@ declare global {
}
```

### `ConfigurePluginEvent`

The **configure plugin event** allows the plugin to request that OpenSCD core add, remove, or reconfigure a plugin.

```typescript
export type ConfigurePluginDetail = {
name: string;
kind: 'menu' | 'editor';
config: Plugin | null;
};

export type ConfigurePluginEvent = CustomEvent<ConfigurePluginDetail>;

export function newConfigurePluginEvent(name: string, kind: 'menu' | 'editor', config: Plugin | null): ConfigurePluginEvent {
return new CustomEvent<ConfigurePluginDetail>('oscd-configure-plugin', {
bubbles: true,
composed: true,
detail: { name, kind, config },
});
}
```

The combination of `name` and `kind` uniquely identifies the plugin to be configured. If `config` is `null`, the plugin is removed. Otherwise, the plugin is added or reconfigured.

## Theming

OpenSCD core sets the following CSS variables on the plugin:
Expand All @@ -321,8 +253,7 @@ OpenSCD core sets the following CSS variables on the plugin:
--oscd-base3: var(--oscd-theme-base3, #fdf6e3);

--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');
}
```

It is expected that the fonts `--oscd-theme-text-font` and `--oscd-theme-icon-font` will be loaded in OpenSCD's `index.html` file. OpenSCD core does not load any fonts by itself.
Loading