timlindvall/gist:3dbac8f8a035bd6fe8d4

## gistfile1.md

      
    Raw
  

              gistfile1.md
            
          
    Hopscotch Plugins

Purpose

Tour and step callbacks work well for individual tour or step cases, but we'd like to provide a means by which developers and integrators can hook in additional functionality into Hopscotch without adding code or config bloat to the core library.
Good examples of functionality that could leverage a plugin API:

PR #76: Add a modal box that highlights what the current step points to.
PR #104: Additional event handlers for tours.

Adding Plugins

We'll provide a method for registering a new plugin with Hopscotch...
hopscotch.plugin({
  id: "my_unique_plugin_id",
  callbacks: {
    onNext: function(),
    onClose: function(),
    ...
  }
});

...and means by which to tell Hopscotch to utilize certain plugins for a given setup.
hopscotch.configure({
  defaultPlugins: ["plugin1", "plugin2", ...],
  ...
});

hopscotch.startTour({
  plugins: ["some_new_plugin"],
  disablePlugins: ["plugin2"]
});


Plugins are essentially a sane way to bundle together a collection of tour-wide callbacks. They have a unique ID and a collection of callbacks. Expected usage would be to declare plugins after Hopscotch.
Plugins are off by default. There are two ways to turn on a plugin...

Call hopscotch.configure() and pass in a defaultPlugins key as part of your object. This should be an array of plugin IDs that should always be enabled (unless a tour's config says otherwise).
As part of your tour's configuration object, include a plugins key. This should be an array of plugin IDs that should be included for this tour.
You can also add to your tour config a disablePlugins key to selectively exclude previously declared defaultPlugins on a tour-by-tour basis.


Plugins can access tour and step data using standard Hopscotch API methods (hopscotch.getCurrTour() and hopscotch.getCurrStepNum()). Thus, plugins can effectively extend the standard set of tour/step configuration options by checking the current step/tour for the existance of a given key.

Still debating whether it would be generally useful to pass in the tour data, step data, and step number to callbacks. We don't do this presently, but this would save a bit of boilerplate for plugin authors. Or, maybe we extend the Hopscotch API?


Publishing Plugins

For plugin authors that wish to share plugins with the Hopscotch community, we'll set up a separate GitHub repo for submitting plugin pull requests to. We'll need to establish guidelines for contributing plugins, including establishing a README for each plugin outlining how it works, who's responsible for maintenance, and how to contribute.