Creating Plugins

Plugin support is still in alpha. Try it out and provide feedback!

Reference Implementation

You can find the first Node plugin at https://github.com/pattern-lab/plugin-node-tab which is well-commented and covers both frontend and backend needs. It will be used as an example throughout the rest of this page.

Backend Plugin Anatomy

Installation

postinstall instructions are fed to patternlab-core to look for any plugins installed within node_modules/

  //determine if any plugins are already installed
  var plugin_manager = new pm(config, configPath);
  var foundPlugins = plugin_manager.detect_plugins();

  if (foundPlugins && foundPlugins.length > 0) {

    for (var i = 0; i < foundPlugins.length; i++) {
      console.log('Found plugin', foundPlugins[i]);
      plugin_manager.install_plugin(foundPlugins[i]);
    }
  }

"Installing" ultimately adds an entry to the patternlab-config.json file, which will look like this:

{
...
"plugin-node-tab": false
...
}

This config entry is also what let's us disable the plugin if we want to momentarily turn it off (by deleting this entry).

Initialization

Plugins are then loaded similarly to installation during patternlab.js startup:

/**
 * Finds and calls the main method of any found plugins.
 * @param patternlab - global data store
 */
function initializePlugins(patternlab) {
  var plugin_manager = new pm(patternlab.config, path.resolve(__dirname, '../../patternlab-config.json'));
  var foundPlugins = plugin_manager.detect_plugins();

  if (foundPlugins && foundPlugins.length > 0) {

    for (var i = 0; i < foundPlugins.length; i++) {
      var plugin = plugin_manager.load_plugin(foundPlugins[i]);
      plugin(patternlab);
    }
  }
}

Plugin-specific postinstall

This plugin has a postinstall script defined in its package.json file because it requires user-input. Know that not all plugins will require this.

Events

Frontend Plugin Anatomy

Plugins need to output their configuration and files to the Pattern Lab frontend in order to be found and initialized. Study plugin-loader.js to better understand how to load templates, stylesheets, and javascript from your plugin.

Plugins will be installed into the public/patternlab-components/pattern-lab/ directory.

Let's discuss both files and how they got there.

plugin-node-tab.json

{
  "name": "pattern-lab/plugin-node-tab",
  "templates": [],
  "stylesheets": [],
  "javascripts": [
    "patternlab-components/pattern-lab/plugin-node-tab/js/plugin-node-tab.js"
  ],
  "onready": "PluginTab.init()",
  "callback": ""
}

This file is heart of the configuration. It is output here and inside the plugins array for consumption alongside other plugins.

• name: The name of the plugin, (for this case) the github org and repo name
• templates: An array of template files to load. These are expected to be mustache files. Will be available to javascript as <<plugin-name>>-filename-template
• stylesheets: An array of css files to load.
• javacripts: An array of javascript files to load. Any callback or onready functions you reference need to be defined within a file here.
• onready: The function to be called when the plugin is finished loading all of its assets.
• callback: The function to be called when the plugin is finished executing. testing needed

plugin-node-tab.js

This file is copied from the plugin's dist/ folder and placed under patternlab-components/pattern-lab/<<plugin-name>>/ Any other files or structure under dist/ will be copied in similar fashion during plugin backend processing. This is done in the plugin's index.js file.