jarradraumati/oscd-import-ieds

OpenSCD Plugin: Import IEDs

Table of Contents

• 1. What is this?
• 2. How to use?
  • 2.1. Online Using the Latest open-scd-core
  • 2.2. Locally for testing
  • 2.3. As part of the OpenSCD distribution
  • 2.4. As part of your own distribution
• 3. Development
  • 3.1. Prerequisites
  • 3.2. Cloning and Demo Server
  • 3.3. Linting and formatting
  • 3.4. Testing with Web Test Runner
  • 3.5. Tooling configs

1. What is this?

This plugin is intended to allow a user to import multiple IEDs from an SCL file.

• This is a plugin for open-scd-core, the core editor engine for OpenSCD.

• This plugin is a web component and follows the open-wc recommendations.

• This plugin uses the Apache License and is intended for you to use, study, share and improve.

Try it out online!

Feel free to log issues to request fixes, improvements or new features.

2. How to use?

2.1. Online Using the Latest open-scd-core

2.1.1. Using a URL

Open SCD core allows plugins to be loaded from a URL.

You can click on 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.

2.1.2. Manually

1. The latest core is available at https://openscd.github.io/open-scd/.

2. Go to Menu › Add plugins…​

3. Select Cancel - this is an editor plugin.

4. Select OK to required a loaded document.

5. Choose a plugin name of 'Subscriber Later Binding'.

6. Choose a plugin icon of 'link'

7. Provide a plugin source URI of: https://danyill.github.io/oscd-import-ieds/oscd-import-ieds.js

8. Click OK on the summary, it should like similar to that shown below:

   

9. Open a file and enjoy!

2.2. Locally for testing

See Development

2.3. As part of the OpenSCD distribution

Note	OpenSCD is transitioning to use of open-scd-core, these instructions will require updating at the end of this transition.

1. Open your OpenSCD distribution or use https://openscd.github.io.

2. Create a custom extension by going to menu › Extensions › Add Custom Extension.

3. Enter the name 'Subscriber Later Binding', select 'Editor tab' and enter https://danyill.github.io/oscd-import-ieds/oscd-import-ieds.js as the URL.

   This is the URL of the bundle built by CI and is always the latest alpha version of this plugin.

   

   Figure 1. OpenSCD Add Custom Extension Screen

4. Click on Add.

5. Until OpenSCD is fully transitioned to open-scd-core, a conversion plugin is also required to interface between the old and new APIs.

6. Create another custom extension by going to menu › Extensions › Add Custom Extension.

7. Enter the name 'Action Translate', select 'Menu entry' and enter https://jakobvogelsang.github.io/oscd-action-translate/oscd-action-translate.js as the URL.

   This is the URL of the bundle built by CI and is always the latest alpha version of this plugin.

8. You should now be able to scroll across in the menu-bar and find a tab, "Subscriber Later Binding"

   Tip	If there are too many editor plugin, hold down shift and wheel-mouse up and down to scroll them easily.

2.4. As part of your own distribution

2.4.1. Within the current OpenSCD distribution

1. Within the current OpenSCD distribution, plugins are stored in the public/js/plugins.js folder. Each plugin appears in the following form:

   {
       name: 'Subscriber Later Binding', // (1)
       src: 'https://danyill.github.io/oscd-import-ieds/oscd-import-ieds.js', //  (2)
       icon: 'link', // (3)
       default: true, // (4)
       kind: 'editor', // (5)
       requireDoc: true, // (6)
       position: 'middle' // (7)
     }

   1. Name of the plugin which appears in the editor menu at top of screen

   2. URL which can be a local or remote resource. For a local resource, begins without a forward slash, e.g. plugins/oscd-import-ieds/dist/oscd-import-ieds.js. In this case what is shown is loading a plugin from the build process.

   3. A material icon, see others at Material Symbols and Icons

   4. Whether the plugin is enabled by default or has to be enabled in the plugins menu

   5. The type of plugin, either menu or editor. This is an editor plugin.

   6. Whether a document must be loaded for this plugin to be available

   7. 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.

2. 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.

3. 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.

2.4.2. Within an OpenSCD core distribution

Within an OpenSCD core distribution, plugins are also loaded from a json file with a slightly different schema.

1. Typically the distribution will be served from a static web page and within the web page there will be a plugins property declared on an open-scd object, for instance:

   <open-scd
     plugins='{
     "menu":
     [
       {"name": "Open File", "translations": {"de": "Datei öffnen"}, "icon": "folder_open", "active": true, "src": "https://openscd.github.io/oscd-open/oscd-open.js"},
       {"name": "Save File", "translations": {"de": "Datei speichern"}, "icon": "save", "active": true, "src": "https://openscd.github.io/oscd-save/oscd-save.js"}
     ],
     "editor":
     [
       {"name": "Subscriber Later Binding", "translations": {"de": "Späte Bindung des Abonnenten", "pt": "Associação Tardia de Assinante"}, "icon": "link", "active": true, "requireDoc": true, "src": "/plugins/oscd-import-ieds/dist/oscd-import-ieds.js"}
     ]
   }'
   ></open-scd>

2. This plugin is an editor plugin, editor plugins are an array of JSON of the following form:

   {
     "name": "Subscriber Later Binding", // (1)
     "translations": { // (2)
       "de": "Späte Bindung des Abonnenten",
       "pt": "Associação Tardia de Assinante"
     },
     "icon": "link", // (3)
     "active": true, // (4)
     "requireDoc": true, // (5)
     "src": "https://danyill.github.io/oscd-import-ieds/oscd-import-ieds.js" // (6)
   }

   1. Name of the plugin which appears in the editor menu at top of screen

   2. Translations of the plugin name as required using standard locale names.

   3. A material icon, see others at Material Symbols and Icons

   4. Whether the plugin is enabled by default or has to be enabled in the plugins menu

   5. Whether a document must be loaded for this plugin to be available

   6. URL which can be a local or remote resource. For a local resource, begins without a forward slash, e.g. plugins/oscd-import-ieds/dist/oscd-import-ieds.js. In this case what is shown is loading a plugin from the internet using the continuous integration build process.

3. 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.

4. 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.

3. Development

3.1. Prerequisites

This plugin uses Node.js and the npm package ecosystem and is verified to work on Linux.

For development, you’ll need Node.js (including npm, which is bundled with Node.js) on your system.

To check whether you have Node.js installed, and which version, open a terminal and type:

$ node -v

A good way to install Node.js is to use nvm (Node Version Manager), however system-wide installations may also work.

If you’re using Linux or macOS, follow the nvm installation instructions to set up nvm on your machine.

Once you’ve installed nvm, open a new terminal and install the active Node.js LTS release using:

$ nvm install --lts

Now that you have Node.js installed, you can install this plugin.

3.2. Cloning and Demo Server

Tip	This repository uses Git LFS so ensure this is is installed on your system prior (on Debian based systems sudo apt install git-lfs). Then clone this repository using:

$ git clone https://github.com/danyill/oscd-import-ieds

Now, install dependencies

$ npm i

Start up a demo server

$ npm run start

Now open in your browser locally to http://localhost:8000/demo/ to use the plugin.

3.3. Linting and formatting

To scan the project for linting and formatting errors, run

$ npm run lint

To automatically fix linting and formatting errors, run

$ npm run format

3.4. Testing with Web Test Runner

To execute a single test run:

$ npm run test

To run the tests in interactive watch mode run:

$ npm run test:watch

3.5. 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.

© 2023 OpenSCD Daniel Mulholland