We consider where plugins come from and how they travel. We start with issues of software development, distribution, installation, configuration and then operation.
Programming
Plugins are javascript modules written in coffeescript that conform to and use a specific module interface now tending towards those used by node.js.
Plugins occupy individual subdirectories of the server's plugins directory. Code, metadata and documentation files are served directly from the directory.
Plugin subdirectory names correspond to the item type they interpret. There is no universal registry of type names. However, a federated wiki server is expected to serve pages with items of types consistent with the available plugins.
Plugins are generally debugged with console.log or other programmer oriented browser features such as single stepping.
Development can start by hand editing the json for an item of the new type, seeing errors when that type is not correctly rendered, and then revising the plugin until satisfied. This has been captured into a plugin generator script. See Make Plugin Script
Plugins can contribute tests which will be rolled up to build a single page of mocha tests called runtests.html. Privileged access to plugin resources may be provided to aid testing.
Configuration
Plugins persist configuration information by storing fields in the items they interpret.
The plugin's documentation can include pre-configured examples that can be copied and used as if they were many distinct plugins. The 'changes' plugin offers two versions this way. See About Changes Plugin
The plugin's documentation can describe user configuration options made available through special markup interpreted by the plugin when it starts on behalf of each item. The text editor can revise this markup and will reinstall the plugin when it is finished. The 'radar' visualization plugin accepts axis selections and limits this way. See About Radar Plugin
The plugin's configuration can involve interpreting a domain specific language (DSL) that behaves one way on the page and cooperatively but distinctly differently on the sever. The 'report' email scheduling plugin works this way. See About Report Plugin
Operation
A Plugin is dynamically loaded when an item of its type is rendered on the screen. The loading will always be from the origin server even if the item came with a page from a remote site.
The plugin offers two entry points, emit and bind. For some plugins, notably 'paragraph' and 'image' the dom objects may have been constructed by the server and need not be emitted. Beyond this case, emit and bind are called right after one another and can be used interchangeably.
A plugin can dynamically load additional resources including code and data. It becomes the plugin's responsibility to schedule callbacks to complete rendering when the loads are complete.
A plugin can dynamically locate resources in the dom. Our current approach is to find these resources by looking for pages or items with jQuery. Page rendering is intentionally serialized so that items above and pages to the left will have emitted their dom elements before subsequent plugins attempt to bind.
A plugin that sources data will emit dom elements of a class that is easily recognized by plugins that consume data. The 'data' plugin sources data and the 'radar' plugin consumes it. The 'method' plugin consumes data it finds before itself in the dom and offers results it calculates to plugins that come after it. See About Method Plugin
A plugin can register for events and make updates to its dom elements in response to those events. See Well Known Events
A plugin can schedule timers and make updates to its dom elements in response to timer events.
A plugin can open websocket connections with a server-side component and source or sink data through it.
A plugin is not (yet) explicitly stopped when a page is discarded. Browsers may stop clock ticks when a page is not visible. More real time will have elapsed than expected when tick events resume.
A plugin may retrieve objects from other pages and ask those objects to perform computations based on how they might be configured. The 'reduce' plugin finds pages with 'methods', creates inputs for them, and retrieves outputs from them, possibly without the pages being visible on the screen. See About Reduce Plugin
We've adopted a step-by-step method for merging pull requests where the order of steps depends on the complexity of the change. In the simplest form, we merge in GitHub and then double check on localhost. See Step by Step Merge