Develop a DMX plugin

Development
1

Introduction

A plugin for the DMX platform can contain both, a backend part, and/or a frontend part. The frontend part can extend the DMX Webclient or be a custom frontend (which accesses the DMX backend).

In the backend you’ll work with Java. The DMX Webclient is based on Vue components and Vuex (for state management) and uses the Element UI widget library.

What a plugin can do

Backend:

  • Provide a data model; change existing data models
  • Implement hooks to react on server-side events
  • Provide/consume services (business logic)
    • Provide an OSGi service consumable by other plugins
    • Consume OSGi services provided by other plugins
    • Provide a REST service; you can make an OSGi service method RESTful just by adding JAX-RS annotations to it.

Extending the DMX Webclient:

  • Provide a Vuex store module (for state management)
  • Mount Vue components into the Webclient; supply them with data and react to their events
  • Provide new detail renderers (for topic/association rendering)
  • Provide new topicmap renderers
  • Plug in items to the Create menu; provide Options components

Building custom frontends; independent from DMX Webclient:

  • Utilize frontend libraries/frameworks of your own choice
  • Use the dmx-api library to access the DMX backend.
  • Optionally embed particular components from the DMX Webclient, e.g. the Topicmap Panel or the topic/association detail/form renderer. See npm for available components.

Start plugin development

A starter project for developing a DMX plugin is available. It illustrates how to extend the DMX Webclient:

Note that “DeepaMehta 5” (aka “DM5”, “dm5”) and “DMX” is the same; same codebase, same features, same license (GPL 3 or later). While at GitHub and npm the projects are named “dm5”, at our own GitLab the same projects are named “dmx”. The repos at GitHub and GitLab have the same content; GitHub mirrors GitLab.

1 Like
2

Thanks to the very good DMX documentation, I was able to start modelling my own topic types (notes of a “Zettelkasten”).

In a second step, I have created a plugin dmx-zettelkasten to – as the docs said – “extend the default data model of a DMX installation by defining specific topic types and association types for your needs. If your data model is implemented in a plugin you can easily install it in new DMX installations and have your own topic types and association types ready for use.”

I think it is important to underline that the use case described in the documentation is the installation in a new DMX instance. My situation differs in that I want to install the plugin in the instance where I originally created the plugin’s data model interactively.

As I learned in a mail correspondence with Jörg (@jri), it is currently best practice to create a dedicated DMX dev instance for a plugin project. Jörg wrote: During development, you might want to change a migration which has already run. But DMX will never re-run a migration if it has already been run (according to migration number). In this case: just shut down the instance, delete the directory “dmx-db”, and relaunch the (now empty) instance. Now the internal migration counter is at zero again, i.e. all migrations will run. Of course this is only practical with a dev instance (and not if data/types have already been created).

Also check out the (incomplete) DM4 Dev-Guide, especially the section about migrations at
https://trac.deepamehta.de/wiki/PluginDevelopmentGuide.

3

HI @jri, I started to write a plugin that provides a data model. All types are automatically in the DMX workspace but the instances are not assigned to any workspace. Is there a way to control the workspace assignment in the json file / migration?

4

A type created in a migration is assigned to the DMX workspace if its URI begins with dmx.. This dedicated URI prefix is reserved for the DMX platform itself and for affiliated parties.

Non dmx. types, as well as all instances, created in a migration gets no workspace assignment by default.

This issue is addressed in these tickets:
https://trac.deepamehta.de/ticket/371
https://git.dmx.systems/dmx-intern/sprint-planning/issues/168 (login required)

At the moment you can’t create workspace assignments declaratively (in a JSON migration). You need an imperative (Java) migration instead:

import systems.dmx.core.service.Inject;
import systems.dmx.core.service.Migration;
import systems.dmx.workspaces.WorkspacesService;

public class Migration1 extends Migration {

    @Inject
    private WorkspacesService wsService;

    @Override
    public void run() {
        long workspaceId = yourWorkspaceId;
        // types
        TopicType type1 = dmx.getTopicType(yourTypeURI);
        wsService.assignTypeToWorkspace(type1, workspaceId)
        // instances
        for (Topic topic : dmx.getTopicsByType(yourTypeURI) {
            wsService.assignToWorkspace(topic, workspaceId)
        }
    }
}

For further information see the DM4 dev guide (whose “Migrations” chapter basically applies to DMX as well):
https://trac.deepamehta.de/wiki/PluginDevelopmentGuide#Migrations

Note that types and instances without a workspace assignment are fully functional. However they can’t be edited interactively. They can only be manipulated in imperative migrations.

1 Like
5

[UPDATE] DMX had a bug regarding workspace assignment: the user’s (resp. requester’s) permission was not checked in every situation.

https://git.dmx.systems/dmx-platform/dmx-platform/-/issues/352

This bug is now fixed.

As a consequence the code above does no longer work. This problem is addressed in another ticket:

https://git.dmx.systems/dmx-platform/dmx-platform/-/issues/362

See this ticket for a working code example.

6

Meanwhile a guide about DMX plugin development is available:
https://dmx.readthedocs.io/en/latest/devel.html

1 Like