Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Write An Extension
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:
- Giuliano Tortoreto has written documentation detailling how to build extension for OpenRefine
- Owen Stephens has written a guide to developing an extension which adds new GREL functions to OpenRefine.
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
- 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.
Please note that you should bundle any dependencies yourself, so you are insulated from OpenRefine packaging changes over time.
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.
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
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/.