Sample Extension

Owen Stephens edited this page Dec 22, 2017 · 2 revisions

The sample extension is included in the code base so that you can copy it and get started on writing your own extension. After you copy it, make sure you change its name inside its module/MOD-INF/controller.js file.

Basic Structure

The sample extension's code is in refine/extensions/sample/. In that directory, Java source code is contained under the src sub-directory, and webapp code is under the module sub-directory. Here is the full directory layout:

refine/extensions/sample/
      build.xml (ant build script)
      src/
          com/google/refine/sampleExtension/
              ... Java source code ...
      module/
          MOD-INF/
              module.properties (module settings)
              controller.js (module init and routing logic in Javascript)
          classes/
              ... compiled Java classes ...
          lib/
              ... Java jars ...
          ... velocity templates (.vt) ...
          ... LESS css files ...
          ... client-side files (.html, .css, .js, image files) ...

The sub-directory MOD-INF contains the Butterfly module's metadata and is what Butterfly looks for when it scans directories for modules. MOD-INF serves similar functions as WEB-INF in other web frameworks.

Java code is built into the sub-directory classes inside MOD-INF, and supporting external Java jars are in the lib sub-directory. Those will be automatically loaded by Butterfly. (The build.xml script is wired to compile into the classes sub-directory.)

Client-side code is in the inner module sub-directory. They can be plain old .html, .css, .js, and image files, or they can be LESS files that get processed into CSS. There are also Velocity .vt files, but they need to be routed inside MOD-INF/controller.js.

MOD-INF/controller.js lets you configure the extension's initialization and URL routing in Javascript rather than in Java. For example, when the requested URL path is either / or an empty string, we process and return MOD-INF/index.vt ( see http://127.0.0.1:3333/extension/sample/ if OpenRefine is running).

The init() function in controller.js allows the extension to register various client-side handlers for augmenting pages served by Refine's core. These handlers are feature-specific. For example, this is where the jython extension adds its parser. As for the sample extension, it adds its script project-injection.js and style project-injection.less into the /project page. If you view the source of the /project page, you will see references to those two files.

Wiring Up the Extension

The Extensions are loaded by the Butterfly framework. Butterfly refers to these as 'modules'. The location of modules is set in the main/webapp/butterfly.properties file. Butterfly simply descends into each of those paths and looks for any MOD-INF directories.

For more information, see Extension Points.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.