dmx-zettelkasten

Developers who want to develop a plugin for the DMX Knowledge Building Platform are referred to this Template. The dmx-zettelkasten is a plugin based on that template.

A plugin for the DMX platform can contain both, a server-side part, and/or a client-side part. At client-side a plugin either extends the DMX Webclient, or creates a complete custom web front-end (which possibly provides its own extension mechanism).

The template project assumes that you want to develop a DMX plugin that extends the DMX Webclient. It is not suited for developing a custom web front-end. You can also use the template to add a server-side part to the plugin later on, however this is not demonstrated here.

Build DMX Knowledge Building Platform from source

The template project assumes that you create the DMX platform from source code.

These tools are needed:

• Java 8

• Maven

• Node.js

• git

Build from source:

git clone https://github.com/dmx-systems/dmx-platform
cd dmx-platform
mvn clean install -P all -DskipTests

Only when you build DMX from source you will get Hot Module Replacement. Hot Module Replacement provides you a comfortable development experience.

Clone the template project

Clone the template project inside DMX’s modules-external directory:

cd modules-external
git clone https://github.com/dmx-systems/dmx-plugin-template

Cloning inside modules-external gives you 2 features without requiring manual configuration:

• For building the production version of the plugin the existing Webpack installation of the DMX installation will be reused (you don’t need install Webpack for every plugin project again and again).

• The production build of your plugin is automatically copied to DMX’s bundle-deploy directory in order to get hot deployed.

Configure Hot Module Replacement

In dmx-platform/modules/dmx-webclient/src/main/js/plugin-manager.js look for the comment // while development add your plugins here and add a initPlugin() call as follows:

// while development add your plugins here
initPlugin(require('modules-external/dmx-plugin-template/src/main/js/plugin.js').default)

This gives you Hot Module Replacement. That is every time you modify any of your plugin’s front-end files (e.g. .js, .vue) the browser provides you instant feedback. Hot Module Replacement is handled by Webpack Dev Server.

Start the server(s)

1. Start the DMX back-end server:

cd dmx-platform
mvn pax:run

1. In another terminal: start the Webpack Dev Server:

cd dmx-platform
npm run dev

What the Zettelkasten plugin does

The plugin mounts a "Zettel" button instead of the "Greetings!" button into the Webclient’s toolbar. When you click it, another Zettel topic is created in the database and revealed on the topicmap.

Although this is trivial functionality the plugin’s source code demonstrates a couple of crucial plugin concepts:

• Mounting Vue.js components into the DMX Webclient

• Registering a Vuex store module for managing the plugin’s state

• Injecting Webclient dependencies (e.g. dmx-api) into components and store module

• Dispatching Webclient actions (e.g. revealTopic)

Start developing

Now adapt the example plugin to your own needs. Every DMX plugin which extends the standard Webclient has a src/main/js/plugin.js file. The plugin.js file declares the various assets your plugin provides (e.g. Vue.js components, Vuex store module). Start your inspection there.

During development, the result of any change you make is immediately visible in the browser thanks to Hot Module Replacement.

Build plugin for production

cd dmx-zettelkasten
mvn clean package

This will build a .jar file for production and copy it to DMX’s bundle-deploy directory. The .jar file contains your plugin (minified Javascript, extracted CSS, both hashed for longterm caching) and is deployable in every DMX 5 installation. The production build is handled by Webpack. The DMX server serves the plugin front-end assets via http(s).

Test the production build of your plugin by opening the Webclient, but this time as served from the DMX server http://localhost:8080/systems.dmx.webclient/ (note that the trailing slash is needed). The "Zettel" button is supposed to appear and function like before. But note that this time the DMX webclient fetches the plugin’s front-end assets (Javascript, CSS) from the DMX server (no Webpack Dev Server involved). You can see this in the browser console:

Learn more

To learn more about DMX plugin development have a look at the DMX Developer Guide: https://dmx.readthedocs.io/en/latest/devel.html