= OpenSCD Plugin: {plugin-name} Editor
:plugin-name: Supervision
:sectnums:
:sectlinks:
:toc: macro
:imagesdir: docs/media
:icons: font
:experimental:
:uri-action-translate-ci-bundle: https://jakobvogelsang.github.io/oscd-action-translate/oscd-action-translate.js
:uri-openscd-core: https://github.com/openscd/open-scd-core#readme
:uri-openscd: https://github.com/openscd
:uri-openscd-app: https://openscd.github.io
:uri-openscd-core-app: https://openscd.github.io/open-scd/
:uri-openscd-core-plugin: pass:v[https://openscd.github.io/open-scd/?plugins=%7B%22menu%22:%5B%7B%22name%22:%22Open%20File%22,%22translations%22:%7B%22de%22:%22Datei%20%C3%B6ffnen%22%7D,%22icon%22:%22folder_open%22,%22active%22:true,%22src%22:%22https://openscd.github.io/oscd-open/oscd-open.js%22%7D,%7B%22name%22:%22Save%20File%22,%22translations%22:%7B%22de%22:%22Datei%20speichern%22%7D,%22icon%22:%22save%22,%22active%22:true,%22src%22:%22https://openscd.github.io/oscd-save/oscd-save.js%22%7D%5D,%22editor%22:%5B%7B%22name%22:%22Supervision%22,%22translations%22:%7B%22de%22:%22%C3%9Cberwachung%22,%22pt%22:%22Supervis%C3%A3o%22%7D,%22icon%22:%22ecg%22,%22active%22:true,%22src%22:%22https://danyill.github.io/oscd-supervision/oscd-supervision.js%22%7D%5D%7D]
// TIP:
// the above URI is done by taking the plugins object from demo.html (without strings) and updating to the correct {uri-ci-bundle} value and then in the browser calling:
// console.log(https://openscd.github.io/open-scd/?plugins=${encodeURI(JSON.stringify(plugins))})
// then substitute the value within the pass:v[
// badges image:https://github.com/danyill/oscd-subscriber-later-binding/actions/workflows/test.yml/badge.svg[title='Build Status'] image:https://img.shields.io/badge/built%20with-open--wc-blue.svg[link={uri-openwc},title='Built with open-wc recommendations'] image:https://img.shields.io/badge/LF%20Energy%20Slack-%20%23OpenSCD%20chat-purple?logo=slack&color=2aa198&labelColor=6c71c4[link=https://lfenergy.slack.com/archives/C03LH7EUP34,title='Slack LF Energy']
toc::[]
== What is this?
This plugin is intended to allow a user to add, remove and configure IEC 61850 GOOSE and SMV supervisions:
This is a plugin for {uri-openscd-core}[open-scd-core], the core editor engine for {uri-openscd}[OpenSCD].
This plugin is a web component and follows the {uri-openwc}[open-wc] recommendations.
This plugin uses the link:LICENSE[Apache License] and is intended for you to use, study, share and improve.
{uri-openscd-core-plugin-demo}[Try it out online]!
.Supervision Editor Plugin image::../../test/screenshots/baseline/LGOS changes supervisions can delete a used supervision-Chromium.png[width=800,link=../../test/screenshots/baseline/LGOS changes supervisions can delete a used supervision-Chromium.png]
Feel free to log issues to request fixes, improvements or new features.
=== Features
valImport=true and valKind=RO or valKind=Conf on the first LGOS/LSVS instance or the datatype)== How to use?
=== Online Using the Latest open-scd-core
==== Using a URL
Open SCD core allows plugins to be loaded from a URL.
You can click on {uri-openscd-core-plugin}[this link] to trial this plugin.
In this view it is without theming and only presents this plugin along with the open and save plugins.
==== Manually
. The latest core is available at {uri-openscd-core-app}.
. Go to menu:Menu[Add plugins...]
. Select Cancel - this is an editor plugin.
. Select OK to required a loaded document.
. Choose a plugin name of '{plugin-name}'.
. Choose a plugin icon of 'link'
. Provide a plugin source URI of: {uri-ci-bundle}
. Click OK on the summary, it should indicate the parameters previously entered.
. Open a file and enjoy!
=== Locally for testing
. Clone this project: + [subs=+attributes] .... $ git clone {uri-plugin} ....
. Install dependencies
$ npm i
. Start up a demo server
$ npm run start
. Open in your browser locally at http://localhost:8000/demo/
=== As part of the OpenSCD distribution
TIP: OpenSCD is transitioning to use of open-scd-core, these instructions will require updating at the end of this transition.
// TODO: Is this fixed yet? IMPORTANT: Currently the reactive update cycle in OpenSCD doesn't optimally support this plugin's behaviour -- it scrolls to the top of lists after a subscription is made or one of the window panes may go blank. This is a known issue and under investigation.
. Open your OpenSCD distribution or use {uri-openscd-app}.
. Create a custom extension by going to menu:menu[Extensions>Add Custom Extension].
. Enter the name '{plugin-name}', select 'Editor tab' and enter {uri-ci-bundle} as the URL. + This is the URL of the bundle built by CI and is always the latest pre-release version of this plugin. + .OpenSCD Add Custom Extension Screen image::screenshot-add-extension.png[width=300]
. Click on menu:Add[].
. Until OpenSCD is fully transitioned to open-scd-core, a conversion plugin is also required to interface between the old and new APIs.
. Create another custom extension by going to menu:menu[Extensions>Add Custom Extension].
. Enter the name 'Action Translate', select 'Menu entry' and enter {uri-action-translate-ci-bundle} as the URL. + This is the URL of the bundle built by CI and is always the latest pre-release version of this plugin.
. You should now be able to scroll across in the menu-bar and find a tab, "{plugin-name}" + TIP: If there are too many editor plugin, hold down shift and wheel-mouse up and down to scroll them easily.
=== As part of your own distribution
==== Within the current OpenSCD distribution
public/js/plugins.js folder.
Each plugin appears in the following form:
+
[source,js,subs=+attributes]<.> Name of the plugin which appears in the editor menu at top of screen
<.> URL which can be a local or remote resource.
For a local resource, begins without a forward slash, e.g. plugins/oscd-supervision/dist/oscd-supervision.js.
In this case what is shown is loading a plugin from the build process.
<.> A material icon, see others at {uri-material-icons}[Material Symbols and Icons]
<.> Whether the plugin is enabled by default or has to be enabled in the plugins menu
<.> The type of plugin, either menu or editor. This is an editor plugin.
<.> Whether a document must be loaded for this plugin to be available
<.> A string, either top, middle or bottom to give a location in the menu.
Otherwise inferred from the order in the file relative to other plugins.
. You need to copy an entry like the above, ensure the src URL resolves and the plugin should be loaded when the distribution is built.
. If you are building locally you likely need to run an npm run bundle command in each plugin to make the dist folder, containing a single JavaScript file with the plugin available to OpenSCD.
==== Within an OpenSCD core distribution
Within an OpenSCD core distribution, plugins are also loaded from a json file with a slightly different schema.
open-scd object, for instance:
+
[source,js,subs=+attributes]<.> Name of the plugin which appears in the editor menu at top of screen
<.> Translations of the plugin name as required using standard locale names.
<.> A material icon, see others at {uri-material-icons}[Material Symbols and Icons]
<.> Whether the plugin is enabled by default or has to be enabled in the plugins menu
<.> Whether a document must be loaded for this plugin to be available
<.> URL which can be a local or remote resource.
For a local resource, begins with a forward slash, e.g. plugins/oscd-supervision/dist/oscd-supervision.js.
In this case what is shown is loading a plugin from the internet using the continuous integration build process.
. You need to copy an entry like the above, ensure the src URL resolves and the plugin should be loaded when the distribution is built.
. If you are building locally you likely need to run an npm run bundle command in each plugin to make the dist folder, containing a single JavaScript file with the plugin available to OpenSCD.
== Development
=== Linting and formatting
To scan the project for linting and formatting errors, run
To automatically fix linting and formatting errors, run
=== Testing with Web Test Runner
To execute a single test run:
To run the tests in interactive watch mode run:
=== Tooling configs
For most of the tools, the configuration is in the package.json to reduce the number of files in your project.
If you customize the configuration a lot, you can consider moving them to individual files.
=== Local Demo with web-dev-server
To run a local development server that serves the basic demo located in demo/index.html
== Credit
This plugin was refactored from base code in OpenSCD and relies on the code, architecture and review effort of multiple people other than the authors of this plugin, including:
© 2023 OpenSCD Daniel Mulholland