Allow for adding plugins

[ariutta]

The core of the library is now nearly feature complete, so to keep the size reasonable, we'll think twice before adding new features to the core.

But sometimes additional features will be useful to a subset of users. To allow for sharing the code for these kinds of features, we need to refactor to make it easy to add plugins. Then we can freely add unlimited new features as plugins while keeping the core of the library as small as possible.

Work in progress

• Namespace methods calls
• Events
  • Add events hooks
  • Make events modifiable
  • Update library to trigger all events
  • Documentation with events listing
  • Documentation on how to use them
  • Tests (Add tests #17)
• Plugins
  • Add plugins system
  • Plugins load order
  • Pass options into plugins
  • Tests
  • Documentation (how to use, listing, building your own plugin)
  • Separate tests for each plugin

  ---

  • Move click/touch/pointer events into a plugin
  • Move center, containand fit into a plugin
  • Move controls into a plugin
  • Move pan limit into a plugin (Keep SVG content visible when zooming #37)
  • Move min/max zoom into a plugin
  • Move enable/disable pan into a plugin
  • Move enable/disable zoom into a plugin
  • Move double click into a plugin
  • Move mouse wheel scroll into a plugin
  • Allow building momentum/inertia plugins (as in Inertia effect to end pan #117 and Add momentum scrolling support #174)
  • Add right click plugin (as in Add right-click to reset zoom and pan #87)
  • Move thumbnail viewer/navigator into a plugin (Thumbnail viewer / navigator? #110)
  • Add Change mouse cursor when panning into a plugin (Change mouse cursor when panning #154)
  • Move rotation into a plugin (Add rotate options in javascript #169)
• Separate zoom for X and Y axis (Separate Zoom for X-Y axis #176)
• Join beforePan/beforeZoom and onPan/onZoom into one event beforeChange/onChange that will contain both zoom and pan data
• Remove customEventsHandler
• Update demos
• On actual CTM update fire render event (onZoom, onPan events to early #121)

@bumbu and @dlg-yahoo, are there other things needed to make it easy to add plugins? It might be awhile before I have time to do this myself, so don't let me be the bottleneck if either of you want to tackle this sooner. I'm fine with whatever you prefer, @bumbu.

[bumbu]

It seems that a plugin system will slightly break current API. That way I would go with a new milestone (v4).

If so it would be great to have following features/changes:

• Plugins should replace customEventsHandler option
• It should be possible to attach/detach plugins at runtime
• Move current builtin controls into plugin
• A plugin for mobile/touch events (wrap and improve current example)
• A plugin for limit pan (wrap and improve current example)
• Refactor inner hooked events
• It should be possible for 2 different plugins to manipulate with the same event (eg. mouseclick)

And there are few questions:

• How plugin attaching/detaching should work? jQuery model with attaching methods to jQuery prototype (fn) will not work here as library core should know about its plugins (in order to pass events).
• Should we allow attaching the same plugin 2 times to the same library instance? It may sound ridiculous, but if a each version of plugin has different options it may be a desired use-case.
• How should we pass events? We can use modified versions of PubSub/Observer and Chain of Responsibility. But here are some vital questions:
  • Is a plugin allowed to cancel an event? For example there are 2 plugins. Both are listening for click. First one is meant to filter all the clicks outside a circle. So second plugin will receive click event for processing only when first plugin will not block it.
  • If a plugin is allowed to cancel an event, how should it do it (what should it return)?
  • Should plugins work with raw browser events, with processed events (eg. clickevent may contain position and target) or with wrapped events (what jQuery)
  • These questions are also related to library inner events.

Other changes to consider for v4 would be:

• Joining beforePan/beforeZoom and onPan/onZoom into one event beforeChange/onChange that will contain both zoom and pan data
• Replacing callbacks (beforePan, onPan) with events thus allowing to have multiple subscribers to the same event (necessary for plugins)
• A demo page with in-browser play with options.

[ariutta]

Agreed that this would be a new major version and also on the list of features/changes.

Lots of good questions, and I don't have answers to them all at this point.

How plugin attaching/detaching should work? jQuery model with attaching methods to jQuery prototype (fn) will not work here as library core should know about its plugins (in order to pass events).

Not sure about this one, although my comment at the bottom about Highland might be related.

Should we allow attaching the same plugin 2 times to the same library instance? It may sound ridiculous, but if a each version of plugin has different options it may be a desired use-case.

This sounds analogous to window.onload vs. window.addEventListener("load", function load(event){ },false);, and the latter is definitely better than the former. So if we can, let's do it.

How should we pass events? We can use modified versions of PubSub/Observer and Chain of Responsibility. But here are some vital questions:

Thinking this through - so a click could trigger new zoom event, and then we would then only use zoom events in the core to initiate zooming...

Is a plugin allowed to cancel an event? For example there are 2 plugins. Both are listening for click. First one is meant to filter all the clicks outside a circle. So second plugin will receive click event for processing only when first plugin will not block it.

Following on from the above click example, we could cancel the zoom event, but I'd be hesitant to cancel the click event.

If a plugin is allowed to cancel an event, how should it do it (what should it return)?

Not sure. jQuery does something where when event.preventDefault() is called, you can then use event.isDefaultPrevented() to know that it was called.

Should plugins work with raw browser events, with processed events (eg. clickevent may contain position and target) or with wrapped events (what jQuery)

If possible, it would be nice to allow for a combination, such as we allow the plugins to listen to raw browser events (but not cancel them) and also subscribe to processed (or wrapped) events.

The event handling ideas from Highland.js are pretty interesting. For example:

var clicks = _('click', btn).map(1);
var counter = clicks.scan(0, _.add);

counter.each(function (n) {
    $('#count').text(n);
});

Then if you want to have multiple listeners, you can fork that event stream.

[bumbu]

The event handling ideas from Highland.js are pretty interesting.
I don't think that we need streams. A simple PubSub/Observer should be enough. And it's really easy to be implemented. Or we can use many existing solutions like Radio.

Here is a library that has some plugins functionality. Not what we need but can be useful for inspiration.
https://github.com/brianreavis/microplugin.js

How should we pass events? We can use modified versions of PubSub/Observer and Chain of Responsibility. But here are some vital questions:

Thinking this through - so a click could trigger new zoom event, and then we would then only use zoom events in the core to initiate zooming...

After some thought a solution that I see is:

• Plugins are initialized and declare their event listeners (eg. 2 plugins subscribed to mouseclick event)

• A browser event is triggered (eg. mouseclick)

• Library (svg-pan-zoom) catches this event

• Library processes the event, wraps it in a new object that is passed to plugins. A wrapped object would look like:

  originalEvent: event
  oldPan: {x: 0, y: 0} // read only
  newPan: {x: 1, y: 1}
  oldZoom: 1 // read only
  newZoom: 2
  preventDefault: function(){} // Prevents library inner processing (not browser event)
  isDefaultPrevented: function(){} 
  

• Wrapped event is passed forward to listening plugins using Chain of Responsibility (object is passed to first plugin, the result is awaited, when the result is received the object is passed to second plugin and so on until there are no more listening plugins). Plugins are allowed to modify newPan and newZoom. Also by calling preventDefault the event will not be passed forward to other plugins and will not be processed.

• When all plugins finished processing the event, if event is not prevented - it is executed.

We may also have subscription to mouseclick and before:mouseclick events. before:mouseclick is the event that is wrapped by library, but newPan and newZoom are still not computed. Preventing from before:mouseclick would halt further event propagation and its computation.

Also I'm not sure about wrapped events attributes. They may look different. But the idea is that you should have access to original event, and you should be able to alter library default computation results.

[ariutta]

Right, I mentioned Highland for inspiration but don't want to make it a dependency. That microplugin library has some good ideas.

Let's go with your proposed solution. Nice work!

For the wrapped events attributes, we can mimic jQuery attributes, whenever appropriate, to make it easier for other developers to understand.

[ariutta]

@dlg-yahoo, if you have any preferences here, feel free to chime in!

[bumbu]

I feel like all these ideas are still raw and need some more thought. Also some implementation prototypes would be helpful. Unfortunately right now I don't have time to work on these things actively as I'll be in India this whole month (it really takes time to travel).
But if anyone else has time and wants to play with it - it would be a great contribution. At least prototyping this plugin system would help us a lot.

[bumbu]

One more thing to think about: How to allow plugins to update SVG manually. For example if you want to animate zoom/pan then you may want inner state of library to have final values, manipulation with SVG done by the plugin. Or maybe such a thing is not necessary and there are other solution that would allow to achieve the same result.

Related to #101

[ariutta]

Yeah, this is an ambitious refactoring, and I won't be able to get to it for awhile either. Let's keep thinking about it and then try some prototypes as time allows.

I hadn't thought of the use case from #101, but I can see how that might be useful. If we can accommodate something like that, it would be great, as long as we don't start over-engineering this library to point where it's painful to work with.

[ariutta]

Also, for any changes that we are more sure about, let's not let this issue become a roadblock. We can come back to this at any time.

[bumbu]

I agree on fact that this issue shouldn't be a stopper, we can still add minor versions to v3.