How to create a plugin

Added for version: 0.6
Updated for version: 0.7

Plugins allow you to add extensions to Conjure without having to modify the source code of Conjure and thus create a possibly incompatible version of Conjure.

Plugins consist of a directory containing at least plugin.clj. You can add any other files you wish.

Plugin.clj must contain three functions, install, uninstall and initialize. The install function is called when the user runs the plugin script and passes it the install command and the name of your plugin. Your install function can take additional arguments which the user can pass after the name of your plugin. The uninstall function is called when the user runs the plugin script and passes the uninstall command with the name of your plugin and optional arguments. The initialize function is called when the server starts, and allows you to initialize your plugin, or make modifications to the server before the app is started.

You could create the directory for your plugin and all of the files manually, but Conjure comes with a plugin generator which does most of the initial work for you. We will use the generator to create a hello world plugin which will simply print “Hello world!” when ever the plugin in is installed, uninstalled, or initialized.

First we’ll need a hello world app to create our plugin in. See Getting Started for how to create a new Conjure app.

Change directory to your hello world app directory. Then generate the hello-world plugin using the following command:

lein conjure generate plugin hello-world

In your vendor/plugins directory, you should see a new directory called hello_world. Inside that directory, generate has created the plugin.clj file and test/test_plugin.clj for you.

The generated plugin.clj file looks like:

(ns plugins.hello-world.plugin
  (:use conjure.core.plugin.base))

(defn install [arguments])

(defn uninstall [arguments])

(defn initialize [])

None of the functions have any implementations yet, but if you want to install the plugin you can do so with the command:

lein conjure plugin install hello-world

Besides some initialization output, nothing happens.

Install

Lets print “Hello world!” when the plugin is installed. To do this, update the install function to look like:

(defn install [arguments]
  (println "Hello world!"))

Now when you install hello-world, you should see the message “Hello world!” printed.

Let’s add the ability to print a message passed as an argument to the install function. Change the install function to look like:

(defn install [arguments]
  (let [message (first arguments)]
    (if message
      (println message)
      (println "Hello world!"))))

We can now pass a message to install by adding the message as an argument to the plugin install command. Showing the message “Goodbye” looks like:

lein conjure plugin install hello-world Goodbye

Running the command should display “Goodbye”.

Uninstall

We can do the same thing with the uninstall function. Replace the uninstall function with the following:

(defn uninstall [arguments]
  (let [message (first arguments)]
    (if message
      (println message)
      (println "Hello world!"))))

You can run the uninstall function with the following command:

lein conjure plugin uninstall hello-world

The above command will print “Hello world!”. You can also pass arguments to uninstall by passing them as additional arguments to the plugin uninstall command. To print out “Goodbye”, use the following:

lein conjure plugin uninstall hello-world Goodbye

Initialize

The initialize function is different from the other plugin functions. It is called when your app server starts. Since there is no plugin script command for it, initialize cannot take any arguments.

To illustrate initialize, lets make it also print out “Hello world!”. Change the initialize function to look like:

(defn initialize []
  (println "Hello world!"))

Now start your app server.

Somewhere in the initialization output, you should see “Hello World!”.

Testing

The test directory contains tests for your plugin and can be run using the plugin test command. The generate command created a test for you called test_plugin.clj.

The test_plugin.clj test script contains only one test called test-initialize which simply runs the initialize function. The full test_plugin.clj file looks like:

(ns plugins.hello-world.test-plugin
  (use clojure.contrib.test-is
      plugins.hello-world.plugin))

(deftest test-initialize
  (initialize))

We can run the test just like any other test:

lein test plugins.hello-world.test-plugin

If you’ve followed along with this tutorial, you should see “Hello World!” printed to the screen somewhere, proving the initialize function was called and worked properly.