Skip to content

Latest commit

 

History

History
43 lines (30 loc) · 3.29 KB

Sample-Extension.md

File metadata and controls

43 lines (30 loc) · 3.29 KB
Raw

Explains the sample extension.

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 http:lesscss.org/ 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 ( http:localhost: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, https:github.com/OpenRefine/OpenRefine/blob/master/extensions/jython/module/MOD-INF/controller.js#L46 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-source:http:localhost:3333/project view source the /project page], you'd see references to those two files.

Wiring Up the Extension

Butterfly is able to locate the sample extension because of https:github.com/OpenRefine/OpenRefine/blob/master/main/webapp/WEB-INF/butterfly.properties#L27. Butterfly simply descends into each of those paths and look for MOD-INF directories.

For more information, see Extension Points.