How to create a Clickframes Plugin

From Clickframes

This tutorial shows you step by step how to create your own Clickframes Plugin.

Contents

What exactly is a clickframes plugin?

A clickframes plugin is something which taken an appspec.xml and does something with it. Most Clickframes plugins generate file, like java code, flow diagrams, excel spreadsheets, reports, etc.

What does a plugin look like?

Each plugin has a universal name, for example, "com.mycompany.myplugin". Here is a sample folder structure for this plugin: 

CLASSPATH/clickframes/
CLASSPATH/clickframes/com.mycompany.myplugin/techspec.xml
CLASSPATH/clickframes/com.mycompany.myplugin/autoscan/
CLASSPATH/clickframes/com.mycompany.myplugin/autoscan/hello.txt
CLASSPATH/com/mycompany/myplugin/Plugin.class

To use the above plugin, make sure that the root folder "clickframes" in the above folder is in classpath. You can then call it from your techspec.xml using the following directive. 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<techspec xmlns="http://www.clickframes.org/techspec" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <plugin class="com.mycompany.myplugin" />
</techspec>


Plugin phases/lifecycle

There are 3 phases in the plugin lifecycle

Phase 1: Run dependencies

If the file 'techspec.xml' exists in the following location, run it! This is a mechanism for including other plugins from your plugin. 

CLASSPATH/clickframes/com.mycompany.myplugin/techspec.xml

This file is optional. If the file is not found, nothing happens and no error is thrown.

Phase 2: Run templates in the autoscan directory

Look for templates in the autoscan directory at the following location. 

CLASSPATH/clickframes/com.mycompany.myplugin/autoscan/
CLASSPATH/clickframes/com.mycompany.myplugin/autoscan/hello.txt

In the above example, one template was found called 'hello.txt'. It will be run. See more detailed reference on Plugin Templates.

This directory is optional. If not found, nothing will happen in this phase.

Phase 3: Run custom java code, if found

Look for a class called 'Plugin' in the plugin package. If found execute it. 

CLASSPATH/com/mycompany/myplugin/Plugin.class

This file is optional. Nothing will be done if not found.

Some plugins generate a graph or an excel spreadsheet. Such plugin can't be implemented using a template. Instead you need to write custom Java code to implement such plugins.

Create a java package with that name: 

com.mycompany.mycustomplugin

Then create a java file with the following name: 

com.mycompany.mycustomplugin.Plugin

This Java must implement the Java interface org.clickframes.plugins.ClickframesPlugin 

package com.mycompany.mycustomplugin;

import org.clickframes.plugins.ClickframesPlugin;
import org.clickframes.plugins.PluginContext;

public class Plugin implements ClickframesPlugin {
  @Override
  public void execute(PluginContext pluginContext) {
    // write your code here
  }
}

Create a new Plugin using the Clickframes Plugin Archetype

To create and publish Clickframes Plugins, there is a maven archetype which makes it easy to do that. Start a new plugin project using the following command 

mvn archetype:generate -DinteractiveMode=n -DarchetypeRepository=http://nexus.clickframes.org/nexus/content/repositories/snapshots/ -DarchetypeArtifactId=clickframes-plugin-archetype -DarchetypeGroupId=org.clickframes -DarchetypeVersion=0.9.2-SNAPSHOT -Dversion=1.0-SNAPSHOT -DgroupId=com.mycompany -DartifactId=my-clickframes-plugin

Go to your newly created plugin project 

cd my-clickframes-plugin

Choose a plugin name space

Create your unique plugin namespace under which you would like to publish your plugin. For example, if you would like to publish under com.mycompany.myplugin, then create the following folder in your base directory. 

# the following command works on linux
mkdir -p src/main/resources/clickframes/com.mycompany.myplugin/autoscan

Start creating your templates

Create as many files as you want in your plugin's autoscan folder. 

# first template, hello.txt
mkdir -p src/main/resources/clickframes/com.mycompany.myplugin/autoscan/hello.txt

Publish your templates 

mvn install

Using your published templates

You can use this template in other projects by adding the following autoscan directive to your techspec.xml. 

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<techspec xmlns="http://www.clickframes.org/techspec"  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <plugin class="com.mycompany.myplugin" />
</techspec>

Just remember, the published jar needs to be in the classpath.

Using your published templates in other maven projects

If you are using yours, or other third party templates in your maven project, make sure that the jar containing the templates is in your classpath. More specifically it needs to be in the <plugin> classpath, which means that it must be a plugin dependency. Remember, the techspec is pre-compile code generation, so any jars you need don't need to go into your runtime classpath.

Here's a sample usage scenario: 

<plugin>
 <groupId>org.clickframes</groupId>
 <artifactId>clickframes-maven-plugin</artifactId>
 <version>0.9.2-SNAPSHOT</version>
 <dependencies>
   <dependency>
    <version>0.1-SNAPSHOT</version>
    <groupId>com.mycompany</groupId>
    <artifactId>myplugin</artifactId>
   </dependency>
 </dependencies>
</plugin>
Retrieved from "http://wiki.clickframes.org/How_to_create_a_Clickframes_Plugin"