[Guide] Getting started with plugin development

[ShelLuser]

Hi gang,

Editorial

Visual Paradigm, the design and management tool we all know and love, provides many different features. But there’s one in particular which really manages to excite me and that is the ability to write your own plugins. And trust me: it doesn’t even have to be all that difficult. But of course some requirements need to be met…

Requirements

• A copy of Visual Paradigm desktop, this is to get the actual openapi jarfile.
• A basic understanding of the Java programming language.
• Having a Java JDK installed, at the time of writing the use of JDK 1.8 is suggested over 1.9 but the latter works good with v15.0 and up.
• And of course an editor to write your code will also come in handy

Suggested

• Using a Java IDE will definitely help. But to make this as basic as possible (and to rule out any bias) I’m not going to use one myself just yet.
• If you’re following my lead then having Apache Ant at your disposal can help to make certain build tasks easier to automate.

Official documentation

This guide will be all you need for now as introduction, but you should also pay good attention to the official documentation, this can become really important.

• Visual Paradigm’s awesome Know How section, you’ll want to check out the OpenAPI category in specific.
• The plugin user guide, this also explains all the basic steps, and can be really useful as a reference guide.
• The Plugin API. You can view it online or download a copy, which I strongly suggest to do. You’ll need this!

What is a VP plugin and why would we use one?

Before we begin let’s start with some theory. I know this might be boring for some of you but trust me when I say that having some basic understanding on how this whole thing works can (and will!) help you out in the longer run. Trust me on this for now, but I’ll also demonstrate what I mean by all this later on.

Visual Paradigm provides a lot of features and it can do a lot of things but sometimes it might be useful if you could somehow automate certain tasks. Take for example the creation of a diagram:

• Open the diagram tab.
• Click on ‘New’
• Find the required diagram in a rather huge list.
• Select the right type, give it a name, and click ok.

Now, I’m aware that this is probably not the best example because if you need to create a certain diagram type on a regular basis then you can also assign a key combination for that. See the ‘Application options’ on the Window tab, and in that dialog pay close attention to the ‘Keys’ section.

Of course this is just one out of many examples. How about automatically creating a certain diagram type? Or maybe resetting all the formatting of the currently used model elements?

In short: you can use plugins to add customized and automated behavior to Visual Paradigm

Plugin structure

A plugin gets installed to Visual Paradigm’s data directory. On Windows this can be found in: %appdata%\VisualParadigm\plugins. On Unix environments this directory can be found in: ~/VisualParadigm\plugins/.

As you can see in the diagram above a plugin consists of 3 major components, although only 2 of them are actually mandatory:

• plugin.xml (required): This is the ‘heart’ of the plugin, it describes the whole layout and tells Visual Paradigm which classes and optional resources (think about an icon) should be used.
• VPPlugin (required): Although not used directly (it is an Interface which your class needs to implement) the structure itself obviously is. This class basically provides 2 methods: loaded() and unloaded() which get triggered by Visual Paradigm when appropriate.
• VPActionController: Once again this is an Interface but not necessarily required in order to make a plugin work, although it’s use is definitely recommended. By default a plugin is only activated when it’s being loaded (or unloaded). This class allows you to associate a specific action (such as clicking an icon in the sleek toolbar) with your plugin.

Now, the thing which is interesting to know is that plugins can be distributed as zip files, but once you install them (using the ‘Install plugin’ option found in the Help tab) then this will merely extract the zipfile and place its contents in the plugins directory (the one I mentioned above).

This can be very useful for you because it also means that if you distribute a compiled project to your plugins folder then you can basically make changes on the fly.

But more about that later…

Setting up a plugin project

This example assumes working on the command line with javac and optionally ant at your disposal. Obviously you can also use an IDE but I’ll explain that in more detail in an upcoming post.

So start by creating an empty directory and then copying the openapi.jar file. You can find this file in the ‘bundled’ or ‘lib’ sub directories within your main Visual Paradigm program directory. So, for example, in my situation I would use these commands to prepare:

• mkdir vp; cd vp
• copy d:\program files\visual paradigm 15.0\bundled\openapi.jar .

Next we’ll create a directory where the compiled code will be placed (called ‘build’) and we’ll also create the directory to contain the source code:

• mkdir build
• mkdir org\catslair\vp

So: ‘build’ is going to be used for the end result, and because I will be using the Java package name org.catslair.vp I created the appropriate directory structure.

The first thing we’ll need is plugin.xml. We’re going to make this really easy to begin with, and therefor we’ll only define the main class which is going to be used during loading / unloading. Create this XML file in the ‘build’ directory, because it is the first part of our plugin:

<plugin
    id="HelloWorld"
    description="This is your classic Hello World plugin."
    provider="ShelLuser"
    class="org.catslair.vp.hello" />

I think this should pretty much speak for itself, right? Assign the plugin with a specific ID (I would recommend using a combination of package/class names so that there is no risk of any accidental overlap, but to keep it easy I used something simple for now), next the plugin gets a description with a provider name and finally I’m defining the main class of my plugin.

So now it’s time to create org\catslair\vp\hello.java to program the actual backend logic:

package org.catslair.vp;

import com.vp.plugin.VPPlugin;
import com.vp.plugin.VPPluginInfo;

public class hello implements VPPlugin {

	@Override
	public void loaded(VPPluginInfo vpi) {
		System.out.println("Hello VP plugin world!");
	}
	
	@Override
	public void unloaded() {
	}
}

This should also be very straight forward I hope. Note that you can easily use ‘com.vp.plugin.*’ as import line if you want to, but I prefer keeping that a bit more strict. It’s personal preference and wouldn’t really change too much.

Now that we have all of this in place it’s time to actually build the plugin:

Easy, right?

Now comes the cool part… To test our plugin we only need to do 1 thing: copy the entire ‘build’ directory to (on Windows): %appdata%\VisualParadigm\plugins. I usually make an Ant script for this, but once again that’s a topic for an upcoming post.

Do make sure that everything is in place: ‘build’ needs to contain these files:

• plugin.xml
• org\catslair\vp\hello.class

Of course you’re free to use your own names if you want to, but this is what I’m using right now

Now, copy the build directory: copy build %appdata%\VisualParadigm\plugins, and then fire up Visual Paradigm!

Pretty exciting right? Yeah, I’m sure that this excitement will take a bit of a dive once you started VP and noticed that nothing special happened. Trust me: something happened, but you need to look in a special place to see it.

Go to the main VP data directory: %appdata%\VisualParadigm. Here you will find a file called ‘vp.log’, open it in an editor or file viewer and you’ll soon see the following:

[2018/03/15 05:26:41] [message] [Thu Mar 15 05:26:41 CET 2018]: Start Visual Paradigm Professional [VP PE]: 15.0 (20180231)
[2018/03/15 05:26:54] [message] start startup getLicenseKey on 15-mrt-2018
[2018/03/15 05:26:54] [message] getLicenseKey in local ...
[2018/03/15 05:26:54] [message] finish startup getLicenseKey
[2018/03/15 05:26:56] [message] Workspace: C:\Users\Peter\Documents\VPProjects
[2018/03/15 05:27:58] [message] Hello VP plugin world!

Congratulations! We now finished one not-so-useful plugin

Doing something a little more useful

This post is mostly meant as an introduction so we’re not going to be doing extremely special things, but why don’t we make our plugin a little bit more useful by having it create a new diagram as soon as Visual Paradigm starts?

Now, this post isn’t only about showing what to do in order to build a plugin, I’m also trying to demonstrate how to do this. Remember that URL about the plugin API documentation? We’re going to need that right now.

So start by opening this link in a new tab. Although the documentation is pretty decent it can seriously help to become more familiar with the API documentation.

The first thing we want to do is tell the Visual Paradigm application to do something for us. So if we then look closer at the com.vp.plugin package we’ll soon spot the ‘ApplicationManager’. Its description (I quote) is: “This class provides access for various service in Open API.”. Sounds exactly like something we might need.

If you then check the documentation for the ApplicationManager class you’ll eventually notice a very interesting method: instance(). “Get the application manager”, it says. That’s definitely where we’ll need to start.

But what we’re really after here is something to control diagrams. And what do you know? If we study the ApplicationManager class more thoroughly we’ll eventually find another really interesting method: getDiagramManager(), this gives us an instance of the DiagramManager class.

Now, I’m honestly merely going by names here, but if you check the API docs for the DiagramManager class then we’ll see more interesting stuff: the createDiagram() method which takes a String parameter to specify the diagram type and it returns an IDiagramUIModel class.

Looking further will show us the openDiagram() method and all it requires as parameter is an IDIagramUIModel. Where did we see that class mentioned before?

The only problem left: what string to use in order to specify the right diagram type?

When going over the fields of DiagramManager we’ll soon spot DIAGRAM_TYPE_USE_CASE_DIAGRAM but unfortunately it’s deprecated and we’re told to use IDiagramTypeConstants instead, you can find its documentation here. The interesting part here is this: static final java.lang.String DIAGRAM_TYPE_USE_CASE_DIAGRAM. So now we know that we can safely use: IDiagramTypeConstants.DIAGRAM_TYPE_USE_CASE_DIAGRAM.

Time to put this knowledge to work:

package org.catslair.vp;

import com.vp.plugin.*;
import com.vp.plugin.diagram.*;

public class hello implements VPPlugin {

	@Override
	public void loaded(VPPluginInfo vpi) {
		// Get both manager classes
		ApplicationManager vpam = ApplicationManager.instance();
		DiagramManager vpdm = vpam.getDiagramManager();
		
		// This could be joined in one command, but this is easier to follow.
		IDiagramUIModel diagram = vpdm.createDiagram(IDiagramTypeConstants.DIAGRAM_TYPE_USE_CASE_DIAGRAM);
		vpdm.openDiagram(diagram);
		
		// This is to get confirmation about what happened.
		System.out.println("New Use Case diagram created & opened.");
	}
	
	@Override
	public void unloaded() {
	}
}

Just try this out for yourself, and you’ll notice something a little peculiar

First Visual Paradigm is started and you’ll quickly notice that we’ll end up in the diagram editor, if you look quickly at the palette you’ll recognize the Use Case options.

But then Visual Paradigm is “sabotaging” us (nah, just kidding here!) by replacing the edit screen with the start page. At the time of writing I’m not sure yet if this can be skipped (I need to look into that myself first) but I figured I’d still share this piece of code because I think it’s a good example nonetheless.

Just use control-shift-b to open the project browser and you’ll soon see the newly and automatically created diagram:

Double click and you’re right back in your edit session.

And this concludes the first part

So… a quick summary… Now we know:

• What a Visual Paradigm plugin is.
• How to program one.
• Where to find some relevant information (such as the API documentation).

In my next post I’m going to demonstrate how to automate certain tasks (like deploying the newly compiled plugin using Ant), how to set up a Java IDE for more complex projects and we’re also going to take a look at a few more advanced plugin examples (as soon as I can come up with something fun).

I hope that this was useful for some of you, thanks for reading!

[ShelLuser]

Part II

Hi gang,

So in the previous part we learned about the basic plugin structure, the openapi.jar file and how to build a very simple ‘Hello world’ plugin.

Today we’re going to dive a little deeper into the OpenAPI structure. Because the OpenAPI provides us with many features, but those are useless if we don’t know how to use them. For example: the ‘Hello world’ plugin generated some output but that ended up in vp.log (the Visual Paradigm logfile). There’s nothing necessarily wrong with that, but Visual Paradigm has a message pane so why don’t we use that instead?

How? Well, for that we’ll need to take a closer look at the basic OpenAPI structure:

The OpenAPI structure

Don’t worry: it’s hardly as complex as it may seem at first glimpse.

First: The OpenAPI is realized by the Visual Paradigm program (obviously). This is seen at the top. Also: our eventual plugin depends on the OpenAPI structure to be present, that can be seen at the bottom. A regular plugin usually consists of 2 classes: the main plugin class and an “action controller” class.

So: the main important thing to know about the OpenAPI is that it fully evolves around the ApplicationManager. If you check the online API documentation yourself (see the com.vp.plugin package) you’ll soon notice that ApplicationManager is one of the very few classes. Most of the OpenAPI consists of interfaces.

This is where your plugin programming usually begins. And it should be easy enough to remember: we’re trying to control the Visual Paradigm application, as such we need to start focusing on the ApplicationManager. Makes sense, right?

As such: ApplicationManager vpam = ApplicationManager.instance();

So, the OpenAPI consists of different parts and each is controlled by a manager class. The diagram above gives you a rough overview. Here’s what those manager classes can roughly be used for:

• ProjectManager => This class provides control over the current project (*.vpp file) which you’re working on. Some specific features are to open a project, save a project or get direct access to the IProject class which in its turn provides support to link projects, iterate over all diagrams and trivial tasks such as getting the projects name or checking if it has been modified.
• DiagramManager => Should be obvious enough: normally a project consists of several diagrams, this class gives you access to those. Notable features are the ability to create a diagram, get an overview of the currently opened diagrams and to create a specific diagram element (a shape).
• ViewManager => This class controls some GUI related aspects. So it can be used to relay information to a user, either through means of the message pane or maybe by using a simple dialog. Some specific features are to add text to the message pane and opening specific dialog windows (file dialog, message dialog, etc.).
• DatabaseManager => As you probably know Visual Paradigm can generate SQL code based on your ERD diagrams. This is the class which controls all that. Notable options are generating SQL code.
• CodeSyncManager => Generating SQL code is only but a small part of what Visual Paradigm can do with diagrams, it can also generate source code based on your diagram(s) or generate diagrams based on existing source code. This class controls all of that. Notable options are updating to code or to UML.
• ResourceManager => Visual Paradigm can use external images and use those in your project. This class provides a way to access those. It can provide access to icons or input streams.
• ModelConversionManager => If you have a diagram then you can save it as an image file. This class provides those options. Specific options are to export your diagram or in specific its elements as an image or to import specific items such as XML data.
• DocumentationManager => Apart from saving one (or more) diagram(s) as an image you could also consider adding those to a report file of some sort. Visual Paradigm can be used to generate Word, PDF or HTML files based on your current work. This class controls all of that. Specific options are to generate those external files, or to show a specific dialog which allows the user to fine tune specific options.

So in my previous ‘Hello world’ example it would have been much easier if I had used the ViewManager class. Then I could have relayed my text using the message pane; so then the user wouldn’t have to mess around with a somewhat arcane logfile.

A simple build script

If you’re building one single plugin then it might make sense to copy the OpenAPI jarfile and then using that to build against. But what if the library gets updated? Or what are you doing to do if you want to program more plugins? I suppose you could use something as: javac -cp ../helloworld/openapi.jar -d build org/catslair/vp/test.java but this isn’t very elegant.

And that’s not even mentioning the upcoming need to copy the resulting build to your plugin folder so that you can test it.

Well, to make things easier on yourself you could consider making a simple Ant build script. Ant is a program build in Java and meant to help you build your own Java programs more easily. An Ant script is set up in an XML format and can be used to make Ant do all sorts of things. From compiling your code, building jarfiles right down to deploying code to an application server.

And it’s really not as hard as it might seem…

<project name="Hello Plugin" default="build">
  <description>
    ANT build script for a Visual Paradigm plugin.
  </description>
  
  <property name="src" location="."/>
  <property name="build" location="build"/>
  <property name="openapi" location="d:/program files/visual paradigm 15.0/lib/openapi.jar"/>
  <property name="vp" location="c:/users/peter/appdata/roaming/visualparadigm/plugins"/>
  
  <target name="build">
    <javac srcdir="${src}" destdir="${build}" classpath="${openapi}" includeAntRuntime="no"/>
    <copy todir="${vp}/${ant.project.name}">
      <fileset dir="${build}"/>
    </copy>
  </target>
</project>

So here I defined an Ant project called “Hello Plugin”. I also told Ant that the default build target for this project is called ‘build’, this is where the code gets compiled and processed.

Next I defined 4 properties which should speak for themselves. The main advantage in using the openapi.jar file from the Visual Paradigm program folder is to make sure that you’re always using the latest version. So if you’ve recently updated Visual Paradigm then this build script would automatically use the updated OpenAPI.

And finally the build target itself. It consists of 2 instructions. ‘javac’ makes sure that the code gets build against the openapi.jar file and that the class files will be placed in the build folder. The ‘copy’ instruction makes sure that the contents of that build folder get copied to the Visual Paradigm plugin folder. In a separate folder of course, it uses the same name as that of the Ant project.

So instead of having to run javac and copy manually now all you have to do is run Ant and it will take care of the rest:

The fun part is that Ant can be used for tons of different things. For example a new target called “dist” which would archive the build folder contents to a ZIP file which can then be used to sent the plugin to someone else.

After that a mere ant dist would be enough to build the plugin and archive it.

And that concludes part 2

So now we’ve taken a look at some of the key components of the OpenAPI (the manager classes) and we have an easier way to build our plugins using Apache Ant.

In the next part we’re going to look at making our plugin work “on demand”; so that it will only do something after the user clicks on an option.

[ShelLuser]

Part III (now ready ;))

Hi gang,

I know it’s an old thread but one which is still relevant today and I simply don’t like loose ends like this. So I figured we’d pick up where we left off. In case this is the first time you read this thread then I strongly suggest you scroll up and read the previous two posts as well.

Where were we?

We made a simple ‘Hello world’ plugin which placed its message in the VP logfile. Then we changed the plugin so that it automatically creates (and opens) a Use Case diagram for us every time we start Visual Paradigm.

Now, this is obviously not an ideal situation so in this part we’re going to remove the automation and instead make our plugin interactive. So: it will only create and open the Use Case diagram whenever we tell it to.

Let’s Git going

In the previous posts I already introduced you to Ant; a Java developers tool which can make building (‘compiling’) and distributing a Java program much easier. In my setup the only thing we have to do to build and install our plugin is simply run ant after which Ant will follow the instructions defined in the build.xml script.

But there’s another invaluable tool I’d like to introduce: Git. Git is a freely available (open source) version control system which is available for all platforms (Windows, MacOS, Linux, FreeBSD, etc.). A version control system (‘VCS’) can keep track of your source code and the changes you make to it. This allows you to make changes to your code but to also roll those changes back at a later time if you have to. In a way you could compare Git’s functionality with that of VPository (as provided by Visual Paradigm online).

Git is an immensely flexible and powerful tool and therefor I won’t be explaining all its details, I’ll just introduce you to its basic options. If you want to learn more then I definitely recommend that you read through it’s excellent documentation.

Setting up our repository

Right now we have a working plugin which creates (and opens) a new use case diagram. So before we’re going to change our code (and our plugin definition XML file) we’re going to save it in a new repository:

(note that Git also provides a GUI, but I prefer using the command line)

So I used git init and now Git tells me that it has detected several so called untracked files. Before Git can keep your code safe you first need to tell it that it should actually keep track of those files. Right now I could simply tell Git to add everything but I don’t like doing that because the build directory contains the binary class files which I don’t want to store. However, the build directory also contains the plugin.xml file which I do want to keep safe. Fortunately this is very easy to set up with Git:

> git add org build.xml
> git add build\plugin.xml

So now I told Git to track the org directory and everything in it, which means that it will add my current hello.java file but will also check if any new files are added. Then I told it to explicitly add the plugin.xml file, so without tracking the rest of the directory structure.

This is a good starting point so now we’re going to save our changes by using: git commit -sm "Initial commit". This will store the current situation with a brief description. The -s parameter ensures that we ‘signed’ our commit, it’s common practice to sign off on something when it’s a little more important change than usual. I also ‘tagged’ this commit with the name “start”. Tagging assigns a name to a specific commit. Without the name you’d need to use the hex fingerprint if you needed to specify it:

However, as you can see Git still notices that the build\org directory exists and isn’t being tracked. So I’m going to tell Git to ignore that directory entirely, we can do that by adding its name to a file called .gitignore:

> echo build/org > .gitignore

If we check the status again you’ll see that Git no longer complaints about build/org but now mentions the existence of .gitignore. So we’ll add & commit this change as well:

> git add .
> git commit -sm "Set up directories to ignore"

Now we’re ready to continue. All our project files which we wanted to keep save have been added to our repository, so any changes which we make from here on can be easily reverted if we want to.

This is a classic example why Git is so immensely versatile: all I had to do was to set up a new repository and start using it. With some of the classic tools like SVN or CVS you had to set up a server first before you could commit any changes. With Git we set it up locally and could get to work straight away.

Sorry for a small de-tour but I honestly think that Git can severely enhance your workflow. As such I felt this was needed

Making our plugin interactive: actionSets & Controllers

So in the previous posts we defined plugin.xml and made it point to our main class (hello.java). In the class we overruled loaded() and unloaded() and we put our code to create the diagram in the first method. This resulted in the plugin to run as soon as we started Visual Paradigm.

So how do we tell Visual Paradigm that it should only run our plugin when we want it to? Well, we do that by setting up a so called action:

<plugin
    id="HelloWorld"
    description="This is your classic Hello World plugin."
    provider="ShelLuser"
    class="org.catslair.vp.hello">
    <actionSets>
        <actionSet id="HelloActionSet">
            <action
                id="HelloAction"
                actionType="generalAction"
                label="New Use Case"
                tooltip="Create a new Use Case diagram."
                menuPath="Plugins/#"
                toolbarPath="Plugins/#">
                <actionController class="org.catslair.vp.helloControl" />
            </action>
        </actionSet>
    </actionSets>
</plugin>

Here I added an actionSet section to our previous plugin.xml. It has its id’s (which have rather poor names, but this works), we specified a label and tooltip which use will become more obvious later and finally the most important part: we defined an action controller class, namely org.catslair.vp.helloControl.

As such: we’ll now need to create org\catslair\vp\helloControl.java.

The actionController class

So what is an action controller? Basically it’s a class which implements the VPActionController interface to override performAction() and update(). These two methods are triggered by VP as soon as a user clicks on our defined action:

package org.catslair.vp;

import com.vp.plugin.*;
import com.vp.plugin.action.*;
import com.vp.plugin.diagram.*;


public class helloControl implements VPActionController {

   @Override
   public void performAction(VPAction action) {
		// Get both manager classes
		ApplicationManager vpam = ApplicationManager.instance();
		DiagramManager vpdm = vpam.getDiagramManager();
		
		// Create & Open the new diagram.
		vpdm.openDiagram(vpdm.createDiagram(IDiagramTypeConstants.DIAGRAM_TYPE_USE_CASE_DIAGRAM));
   }
   
   @Override
   public void update(VPAction action) {
   }
}

I moved this code from hello.java which I limited to this:

package org.catslair.vp;

import com.vp.plugin.*;

public class hello implements VPPlugin {

	@Override
	public void loaded(VPPluginInfo vpi) {
		// Logging our plugin
		System.out.println("Plugin loaded.");
	}
	
	@Override
	public void unloaded() {
	}
}

Thanks to the way we previously set up our build.xml file we don’t need to change anything and can simply run ant which will compile (and copy) both classes. And if we then start Visual Paradigm we get to see this:

(please ignore the other plugins, I made quite a few over the years )

And as soon as we click the option VP will create and open a new Use Case diagram for us (using a default name).

Saving our work

As you can see Git tracked everything we did. It noted the changes we made to plugin.xml and hello.java and also picked up the addition of helloController.java.

Time to save our changes so that we’re ready for the next part:

> git add .
> git commit -m "Made the plugin interactive"

Next time

Our plugin is getting a little more complex so next time we’ll be taking a look at how we can use a Java IDE for our VP plugin development. Which, in my opinion, is going to be seriously exciting because we’ll be able to use VP within our IDE to help us develop stuff FOR VP.

We’re also going to clean a few things up and check how we can use proper VP options. For example: why dump stuff in the logfile while VP has a log pane?

[gemisigo]

I see you’ve got Reload plugins on your Plugin menu. Does that reload plugins without restarting VP? If so, how did you achieve that? I had to alter a plugin I got from Antony and it was quite a burden having to quit and restart VP to test after each modification.

[claudenirmf]

@gemisigo, have a look at this post. However, in my experience, it doesn’t work when developing listerners (e.g., model listeners, diagram listeners, and project listeners).