Hitchy Plugins ​

In this topic you learn how to write plugins for Hitchy. It is also introducing common API of either plugin as assumed by Hitchy to be integrated properly.

Naming ​

A plugin's name is equivalent to the base name of folder containing it. Thus, every plugin must be available in a separate folder.

Roles ​

In addition to its name every plugin is assumed to claim a role it is taking as part of an application. This role's name is identical to the plugin's name by default. But every plugin is able to choose a different role explicitly.

Why Using Roles? ​

Roles are beneficial for creating complex applications. By supporting plugin roles it is possible to have different implementations for the same purpose resulting in same API available under same name - the role's name - at runtime.

Static vs. Dynamic vs. Approved ​

For every plugin a claimed role may be encountered in these situations:

1. In its hitchy.json beacon file (see below) a plugin may claim role explicitly or rely on role equivalent to its name by default. This role is called the plugin's static role.

2. A plugin's API may include property $meta to be merged with information read from its hitchy.json file before. This may include a role in turn which is called the plugin's dynamic role.

3. One of these roles - preferring the dynamic role over the static one - becomes the plugin's approved role which is going to be only considered one while integrating either plugin with the application.

   The approved role of a plugin will be exposed as property $role of its API.

This pattern is beneficial in plugins dynamically adopting their behaviour to an application's actual context. For example, a plugin may inspect list of available plugins and decide to replace some particular plugin unless application doesn't depend on that plugin at all.

Uniquity ​

A plugin's approved role must be unique in context of a single application. Thus, in a single application you can't have two plugins claiming same role to be approved.

Basic File Layout ​

Minimally Required Files ​

Every plugin must be implemented in its own folder.

This is achieved implicitly when distributing plugins as packages via npm. The folder's name is implicitly assumed to be the plugin's name.

Every plugin's folder must contain at least two files:

• hitchy.json is called the plugin's beacon file for indicating that a folder is actually containing a Hitchy-compatible plugin. That's why this file must exist.

• index.js must be provided for exporting the plugin's API. That API is used in two situations:

  1. It is used to integrate the plugin with an application that is based on Hitchy.

     This is the part which is described below.

  2. It may expose additional information and methods for use by the application at runtime. Therefore, it will be exposed as part of a collection in Hitchy's API using the plugin's role name.

     This part of API is optional and depends on actual plugin.

  javascript

  module.exports = function( options, pluginHandles, myHandle ) {
      const api = this;
  
      return {
          // TODO: list elements of plugin's API here
      };
  };

  module.exports = function( options, pluginHandles, myHandle ) {
      const api = this;
  
      return {
          // TODO: list elements of plugin's API here
      };
  };

  Complying with common module pattern is highly suggested to use the full potential of integrating with an application. But it's not required and thus it's okay to export the plugin's API without:

  javascript

  module.exports = {
      // TODO: list elements of plugin's API here
  };

  module.exports = {
      // TODO: list elements of plugin's API here
  };

  Note

  Using package.json it is possible to select a different name used for loading plugin's API.

As a result any plugin's folder should look similar to this layout:

+ hitchy-plugin-foo
    hitchy.json
    index.js

+ hitchy-plugin-foo
    hitchy.json
    index.js

Configuration ​

Every plugin may provide configuration to be merged into resulting application's configuration by providing a sub-folder config containing one or more Javascript files each exposing another part of desired configuration.

+ hitchy-plugin-foo
  + config
      foo.js
      bar.js  
    hitchy.json
    index.js

+ hitchy-plugin-foo
  + config
      foo.js
      bar.js  
    hitchy.json
    index.js

Names of configuration files don't matter as long as they don't start with a full stop . and end in .js.

Either plugin's configuration as merged data of all files loaded here is exposed as part of plugin's resulting API. Configuration of all plugins and resulting application is merged and gets eventually exposed via Hitchy's API.

Components ​

Just like the application itself every plugin may expose components to be discovered and exposed via Hitchy's API. Thus, a plugin may contain a folder api which in turn may contain any combination of the sub-folders controllers, policies, models and services.

+ hitchy-plugin-foo
  + api
    + controllers
        foo.js
    + policies
        bar.js
    + services
        foo.js
        bar.js
    + models
        foo.js
  + config
      foo.js
      bar.js  
    hitchy.json
    index.js

+ hitchy-plugin-foo
  + api
    + controllers
        foo.js
    + policies
        bar.js
    + services
        foo.js
        bar.js
    + models
        foo.js
  + config
      foo.js
      bar.js  
    hitchy.json
    index.js

Discovered components are exposed via Hitchy's API.

The Beacon File ​

Every folder or package meant to be discovered as a Hitchy plugin must contain a file named hitchy.json. It does not have to contain any information and thus could be as simple as this:

{}

{}

The file is used as a beacon indicating its folder to contain a plugin for Hitchy. By relying on its presence discovery of plugins is pretty fast resulting in shorter startup times.

There may be actual content in the file, though, which is used to compile the plugin's meta information.

Meta Information ​

Every plugin has meta information attached. It may be explicitly provided in one of two sources:

• The beacon file is providing a plugin's static meta information.

• The plugin's API exported from its index.js file may expose its dynamic meta information.

Both sources are merged into single set of meta information with data found in latter source replacing data found in former one.

There are elements of meta information Hitchy is using while integrating discovered plugins. These are described below. Hitchy is assuming defaults or deriving values e.g. from a plugin's name when meta information lacks either element.

In addition a plugin's meta information may contain custom data which isn't used by Hitchy for integrating the plugin. It might be used by plugins or the application at runtime using Hitchy's API.

role ​

Every plugin has to claim a certain role by name. It defaults to the plugin's name which in turn is equivalent to the filename of folder containing the plugin's hitchy.json file.

{
    "role": "odm"
}

{
    "role": "odm"
}

module.exports = {
    $meta: {
        role: "odm",
    },
};

module.exports = {
    $meta: {
        role: "odm",
    },
};

dependencies ​

Either plugin may declare roles of plugins it depends on. This affects bootstrap in several ways:

• When sorting plugins for sequential processing any plugin listing roles as its dependencies here is processed after those plugins claiming either role.

• If any of the declared dependencies is missing the bootstrap fails cancelling whole application startup.

{
	"role": "odm-provider",
	"dependencies": [
		"odm"
	]
}

{
	"role": "odm-provider",
	"dependencies": [
		"odm"
	]
}

dependants ​

A plugin is capable of listing roles depending on it without requiring plugins claiming those roles as dependency on their own.

This feature is important for controlling order of plugins to assure some plugin is processed between two other ones.

{
    "role": "auth",
    "dependencies": ["odm"]
}

{
    "role": "auth",
    "dependencies": ["odm"]
}

{
    "role": "fast-user",
    "dependencies": ["odm"],
    "dependants": ["auth"]
}

{
    "role": "fast-user",
    "dependencies": ["odm"],
    "dependants": ["auth"]
}

deepComponents 0.4.0 ​

When loading components of a plugin this boolean property controls whether Hitchy is deeply searching for components in either type of component's sub-folder or not. Deep search is enabled by default.

appendFolders 0.4.0 ​

When deeply searching for components Hitchy is using the relative path name of every component's module for deriving the resulting component's name. This option is controlling whether names of containing sub-folders are prepended to files' base names in given order or appended to them in reverse order.

The latter case is used by default so you need to explicitly set this property false to establish the former case.

+ api/services
  + management
    + user
        system-admin.js
        guest.js
      room.js

+ api/services
  + management
    + user
        system-admin.js
        guest.js
      room.js

Common Plugin API ​

This is a summary of properties and methods in a plugin's API supported by Hitchy for integrating the plugin with an application. See the description of process integrating plugins for additional information.

plugin.$name ​

This property names the plugin which is exposing this API.

plugin.$role ​

This property names the role claimed by plugin exposing this API. Since accessing the plugin involves knowing the role this information may be considered redundant but is included for sake of integrity.

plugin.$meta ​

When exported by a plugin's index.js file this property is meant to provide information extending and/or replacing related information found in plugin's beacon file.

After loading plugin in discovery stage exported information is merged with any information found in beacon file. Thus, this object is eventually providing final state of a plugin's meta information.

plugin.$index ​

Due to sorting plugins for sequential processing either plugin has an index into that list which is exposed in this property mostly for testing purposes.

plugin.$config 0.3.3 ​

When loading configuration files of a plugin a single object merged from information exported by either found file is exposed as part of plugin's API. The information is also merged with related configuration objects of all other plugins and the application itself into one global configuration object.

plugin.onDiscovered() ​

Signature: onDiscovered( options, pluginHandles, myHandle ) (CMFP)

This optional method is invoked on all eventually integrated plugin's APIs have been loaded. At this point every plugin's API has been loaded and is available as part of provided handles which is a dictionary mapping either plugin's name into its handle. This dictionary includes discovered plugins that are dropped in favour of others.

plugin.onExposing() ​

Signature: onExposing( options, myHandle ) (CMFP)

This optional method is invoked at start of exposure stage right before detecting either plugin's components and exposing them in Hitchy's API.

plugin.onExposed() ​

Signature: onExposed( options, myHandle ) (CMFP)

This optional method is invoked at end of exposure stage after having detecting and exposed either plugin's components.

plugin.configure() ​

Signature: configure( options, myHandle ) (CMFP)

This optional method is invoked at end of configuration stage to request either plugin for fixing any configuration read from its files.

plugin.initialize() ​

Signature: initialize( options, myHandle ) (CMFP)

This optional method is invoked so the plugin is able to initialise its resources e.g. by connecting to some database.

plugin.policies ​

Signatures: policies or policies( options, myHandle ) (CMFP)

This optional property or method is used to fetch a plugin's routing declarations for policies during routing stage of bootstrap. It is either an object with structure equivalent to the one supported in configuration or some method invoked in compliance with common module function pattern to get that set of declarations.

plugin.routes ​

Signatures: routes or routes( options, myHandle ) (CMFP)

Similar to plugin.policies this optional property or method is used to fetch plugin's routing declarations for (terminal) routes during routing stage of bootstrap. See its configuration counterpart for information on supported syntax.

plugin.blueprints ​

Signatures: routes or routes( options, myHandle ) (CMFP)

Similar to plugin.routes this optional property or method is used to fetch plugin's routing declarations for blueprint routes during routing stage of bootstrap. The supported syntax is basically identical to the one supported by plugin.routes, though blueprints are limited in multiple ways:

plugin.shutdown() ​

Signature: shutdown( options, myHandle ) (CMFP)

This optional method is invoked on gracefully shutting down Hitchy-based application. It is meant to enable a plugin to release its resources e.g. by disconnecting from some database.

A Plugin's Particular API ​

In addition to complying with Hitchy's Plugin API every plugin may expose its own API to be made available via Hitchy's API available at runtime of a Hitchy-based application.

A plugin's API is specific to either plugin and thus you should consult the plugin's documentation.

class Widget {
}

module.exports = {
    createWidget( name ) { ... },
    Widget,
};

class Widget {
}

module.exports = {
    createWidget( name ) { ... },
    Widget,
};