Write An Extension

Owen Stephens edited this page Jan 22, 2018 · 5 revisions
Clone this wiki locally

This page gives a very brief overview of the structure of OpenRefine extensions. For more detailed documentation and step-by-step guides please see the following external documentation/tutorials:

OpenRefine makes use of a modified version of the Butterfly framework to provide an extension architecture. OpenRefine extensions are Butterfly modules. You don't really need to know about Butterfly itself, but you might encounter "butterfly" here and there in the code base.

Extensions that come with the code base are located under the extensions subdirectory, but when you develop your own extension, you can put its code anywhere as long as you point Butterfly to it. That is done by any one of the following methods

  • refer to your extension's directory in the butterfly.properties file through a butterfly.modules.path setting.
  • specify the butterfly.modules.path property on the command line when you run OpenRefine. This overrides the values in the property file, so you need to include the default values first e.g. -Dbutterfly.modules.path=modules,../../extensions,/path/to/your/extension

Please note that you should bundle any dependencies yourself, so you are insulated from OpenRefine packaging changes over time.

Directory Layout

A OpenRefine extension sits in a file directory that contains the following files and sub-directories:

build.xml
  src/
      com/foo/bar/... *.java source files
  module/
      *.html, *.vt files
      scripts/... *.js files
      styles/... *.css and *.less files
      images/... image files
      MOD-INF/
          lib/*.jar files
          classes/... java class files
          module.properties
          controller.js

The file named module.properties (see example) contains the extension's metadata. Of importance is the name field, which gives the extension a name that's used in many other places to refer to it. This can be different from the extension's directory name.

name = my-extension-name

Your extension's client-side resources (.html, .js, .css files) stored in the module/ subdirectory will be accessible from http://127.0.0.1:3333/extension/my-extension-name/ when OpenRefine is running.

Also of importance is the dependency

requires = core

which makes sure that the core module of OpenRefine is loaded before the extension attempts to hook into it.

The file named controller.js is responsible for registering the extension's hooks into OpenRefine. Look at the sample-extension extension's controller.js file for an example. It should have a function called init() that does the hook registrations.

The build.xml file is an Apache Ant build file. You can make a copy of the sample extension's build.xml file to get started. The important point here is that the Java classes should be built into the module/MOD-INF/classes sub-directory.

Note that your extension's Java code would need to reference some libraries used in OpenRefine and OpenRefine's Java classes themselves. The libraries are in /main/webapp/WEB-INF/lib/ and OpenRefine's classes are in main/webapp/modules/core/MOD-INF/classes/.