= OpenSCD Plugin: {plugin-name}
:plugin-name: Network Config
:sectnums:
:sectlinks:
:toc:
: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,%7B%22name%22:%22Network%20Data%22,%22icon%22:%22hub%22,%22active%22:true,%22requireDoc%22:true,%22src%22:%22/dist/oscd-network-config.js%22%7D%5D,%22editor%22:%5B%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[
== What is this?
This plugin uses the information provide by the Network Data to create an initial configuration for Cisco IE-9320 devices including:
Technically:
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]!
Feel free to log issues to request fixes, improvements or new features.
== Using the Plugin
Follow the steps in <
. The plugin provides a menu option. Go to the menu in the top left and click on the plugin name.
. This will add the information required and remove any prior information this plugin has written (within the Private
elements).
== Loading the Plugin
=== 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.
. 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 'Menu entry' 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[].
. This plugin is now available in the menu entry.
=== 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-network-config/dist/oscd-network-config.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-network-config/dist/oscd-network-config.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
© 2023 Daniel Mulholland