Skip to content

Plug in Architecture

Jump to bottom
Jonathan Eiten edited this page Oct 11, 2016 · 9 revisions

Definition

Plug-ins (or "add-ons") are basically mix-ins; there is no real plug-in "architecture" at this time other than the installation methodology described here.

Where found

Plug-ins currently live in the add-ons folder and are not part of Hypergrid "core," i.e., not part of the browserfied build on the CDN (http://openfin.github.io/fin-hypergrid/build/hypergrid.js).

Single .js file vs. npm module

Plug-ins, like Hypergrid itself, are reduced by a build process (using Browserify) to a single .js file and output to the http://openfin.github.io/fin-hypergrid/build as both "dev" and "min" (uglified; no source map) versions. From there they can be referenced in a <script> tag.

However, also like Hypergrid, they are also npm modules which you, as the application developer, can "require" into your own browserified build. (None of them have been published yet, however, and we have not decided which ones we will publish and which we will simply leave as sample code.)

The npm module approach has several advantages, starting with the fact that your code will be reduced to a single file, requiring a single <script> tag (as opposed to separate <script> tags for all your files and plug-ins).

Types of plug-ins

There are two basic types of plug-ins, consisting of:

  • A simple API - a plain object
  • An object API - an object constructor

Either API may have a name (or $$CLASS_NAME) property.

The simple API type of plug-in may be:

  • A shared plug-in which has a preinstall method and whose logic is intended to be available to all grids on the page.
  • An instance plug-in which has an install method and whose logic is intended to be available only to the specified grid.

Installation methodology

Plug-ins are installed implicitly upon Hypergrid instantiation when a plugins option is supplied to the constructor; or explicitly by calling installPlugins yourself.

There are two kinds of plugin installation:

  • Shared plug-ins are installed on the prototype. These are simple API plug-ins with a preinstall method, called from the top of the Hypergrid constructor. The constructor itself (Hypergrid) is passed as the first argument.
  • Instance plug-ins are installed on the instance. These are either simple API plug-ins with an install method to call or object API plug-ins. The install method or the object instantiation (as the case may be) is called from the bottom of the Hypergrid constructor. The new Hypergrid object (this) is passed as first argument.

Plugins may have both preinstall and install methods, in which case both will be called as explained above. However, note that in any case, if an object API plug-in has an install method, it will be ignored.

In all cases, additional args are passed when included in the pluginSpec (see below for details).

The resulting plain or instantiated objects are named as follows (in priority order):

  1. As named in the pluginSpec
  2. The simple API object has a name property
  3. The instantiated object API object has a name or $$CLASS_NAME property
  4. Unnamed if none of the above

If named, a reference to each shared plugin is saved in Hypergrid.plugins and a reference to each instance plug-in is saved in this.plugins. If the plug-in is unnamed, no reference is kept.

Plug-in specs

The pluginSpec (jsdoc typedef name) takes any of the following forms:

  • undefined (or any other falsy value) - This is a no-op.
  • A reference to a plug-in API - Installs the plug-in as explained above.
  • An array:
    • Plug-in name (a string). (optional)
    • Reference to plug-in API.
    • Additional installation parameter(s). (optional)
Clone this wiki locally