MozillaWiki

Labs/Bespin/DesignDocs/PluginAPI: Difference between revisions

Page Discussion

Labs/Bespin/DesignDocs/PluginAPI (view source)

Revision as of 16:18, 14 August 2009

1,346 bytes added ,  14 August 2009
→‎A one-file plugin
No edit summary
 
(4 intermediate revisions by the same user not shown)
Line 61: Line 61:
* Plugins should be loaded lazily to improve startup time. For example, a plugin that provides a syntax highlighter shouldn't be loaded until that highlighter is needed.
* Plugins should be loaded lazily to improve startup time. For example, a plugin that provides a syntax highlighter shouldn't be loaded until that highlighter is needed.


== Core Plugin API ==
== Plugin Definition and Loading ==


Here we will talk about the first goal, the core plugin API itself
Here we will talk about the first goal, the ability for plugins to load and be activated.


=== A one-file plugin ===
=== A one-file plugin ===
Line 76: Line 76:
         // referred to by name
         // referred to by name
         name: "luaHighlighter",
         name: "luaHighlighter",
   
       
         // up to the first "." would be used as the short description. Everything
         // up to the first "." would be used as the short description. Everything
         // else is viewed in a long description context.
         // else is viewed in a long description context.
         description: "Syntax highlighter for the Lua programming language.",
         description: "Syntax highlighter for the Lua programming language.",
   
       
         // version numbers will be good for automatic updates.
         // version numbers will be good for automatic updates.
         version: "1.0",
         version: "1.0",
   
       
         // core parts of Bespin (and even plugins) can query for metadata
         // core parts of Bespin (and even plugins) can query for metadata
         // and request that a plugin is loaded. In this case,
         // and request that a plugin is loaded. In this case,
Line 90: Line 90:
         // If it's a lua file, it will see that this plugin can handle
         // If it's a lua file, it will see that this plugin can handle
         // lua.
         // lua.
         "bespin.syntax.simple": {
         provides: [
            extensions: ["lua"]
            ["bespin.syntax.simple", {
         }
                extensions: ["lua"],
                // in the single file version of a plugin, you just refer to the
                // functions in the plugin itself
                load: "luaHighlighter"
            ]
         ],
        subscribes: [
            ["file:savefile", "savehandler"]
        ]
     }
     }
      
      
    // The activate function is called when this plugin is loaded.
     exports.luaHighlighter = function() {
    // It is responsible for setting up even listeners.
         // return a lua highlighter instance
     exports.activate = function() {
    }
         // note the use of "subscribe" instead of "bespin.subscribe".
   
        // in a plugin context, all subscriptions are handled for
    exports.savehandler = function(event) {
        // you automatically. If the plugin needs to be reloaded,
        // do whatever it is we do on save
        // all event handlers will automatically be unsubscribed.
        subscribe("bespin:syntax:simple:highlightBlock", function(block) {
            // do something
        })
     }
     }
   


Plugin modules are implemented not as Dojo modules, but rather as [https://wiki.mozilla.org/ServerJS/Modules/SecurableModules ServerJS Securable Modules]. This would allow seamless interop for plugins that have both client and server side JS components.
Plugin modules are implemented not as Dojo modules, but rather as [https://wiki.mozilla.org/ServerJS/Modules/SecurableModules ServerJS Securable Modules]. This would allow seamless interop for plugins that have both client and server side JS components.


=== Wordpress-like ===


(TODO: ideas in this section to be shuffled around in light of the new direction in the previous section.)
Here's an example of a single file plugin that adds commands and adds/removes a DOM element:


What if we have a new directory, BespinSettings/plugins which is where your plugins go.
    exports.info = {
        name: "Something Fun",
        provides: [
            ["bespin.command", {
                name: "woot",
                pointer: ":woot"
            }],
            ["bespin.command", {
                name: "hello",
                takes: ["name"],
                pointer: ":hello"
            }]
        ]
    }
   
    exports.woot = function(instruction) {
        instruction.addOutput("woot!");
    }
   
    exports.activate = function() {
        dojo.create("div", {
            id: "fun",
            style: "opacity: 0; position: absolute; top: 0; left: 0; padding: 2em; background: white"
        }, document.body);
    }
   
    exports.deactivate = function() {
        dojo.query("#fun").orphan();
    }
   
    exports.hello = function(instruction, name) {
        instruction.addOutput("Hi there, " + name);
    }


They can either be one file (myplugin.js) or a directory (myplugin/plugin.js with other stuff too).
=== Plugin installation ===


To activate a plugin, you add a line to your config file (loadplugin pluginname say). We don't automatically load all plugins JUST in case there is an issue, or you want to easily activate and deactivate plugins without having to delete files. In theory we could create a "loadplugin all" semantic for those that really want it.
New commands will allow you to work with plugins:


To get a plugin into the system, we need to piggy back on the ability to import code into a project. Right now we have an explicit import command that ends up with a new project. We need to also allow you to import a piece into an existing project. In this case, into the "plugin" directory under the magic "BespinSettings" directory. This is a dependency. We also want to let you do this not just by grabbing a URL, but also via file upload of a .zip|tgz|...
;plugin install URL|Bespin file path:Install a plugin. You can point it at a single file plugin, or at a zip file or tarball. If it's a zip or tgz, it needs to have a single .js file in it or contain a directory that includes a plugin.json. plugin.json provides the equivalent of the info object above. You can also give it a Bespin file path pointing to a directory or file where there is a plugin.
;plugin uninstall PluginName:If installed from a remote location, the plugin files will be deleted. If it was a Bespin path, the plugin is just removed from the installed plugin data.
;plugin reload:generally used in development of a plugin.
;plugin list:list the installed plugins.


The plugin itself should have a set of metadata associated with it. This can be placed into it via comments, a la Wordpress.
Bespin keeps track of installed plugins in a file called BespinSettings/plugins.metadata. The plugins themselves are installed into BespinSettings/plugins/. The metadata file includes all of the info objects from all of the plugins. Additionally, it stores where the plugin came form and where it is located within Bespin.


We will have new events for items such as:
When a plugin is installed, the module is loaded and the info object is extracted. For this reason, plugin modules should not actually *do* anything when they are loaded. The call to activate() is the time when the plugin should actually do something.


* plugin:activate
=== Plugin loading ===
* plugin:deactivate
* plugin:load:complete


and once loaded a plugin can listen for:
The idea behind this plugin system is to load as little as possible. Bespin will always load the plugins.metadata file. Based on the metadata, Bespin will decide when to load a plugin. The exact timing of loading the code will depend on what the plugin does. For example, syntax highlighters are loaded when a file of the appropriate type is opened.


* cmdline:loaded
It will be possible to have a plugin load immediately, but the goal is to seek out ways to allow plugins to load more lazily.
* settings:loaded
* toolbar:loaded


The plugin will listen in on these and will then hook itself up.
=== Singletons ===


How does a plugin change the default behaviour? What if we change bespin.publish/subscribe to have an id, or a type associated with the event. All default behaviour will pass in a "default" or whatever makes sense.
Plugins are singletons; there is only one instance of a plugin in memory at a time.


Then, the plugin, can unsubscribe() on the type default when it adds itself to the subscription queue.
=== Disabling Plugins ===


We also need to think about how data, or images, or JSON can be used from within a plugin (using its own resources). Furthermore, having a simple include() from within the config and plugin work would be nice. This could piggy back on dojo.require/provide.
Adding ?disable=ALL to the editor URL will turn off all plugins. Adding ?disable=PluginName will disable a single plugin. This can be used as an escape hatch if a plugin is ill-behaved and renders Bespin inoperable.


==== Plugin Directory ====
== Plugin API ==


Plugins will be placed in either BespinSettings/plugins/yourplugin.js or BespinSettings/plugins/yourplugin/*.  You will use the directory version if your plugin packages up multiple files and resources such as CSS, images, etc.
Functions available within the plugin's loading scope:


==== Discovery ====
    // require() loads a module. Modules are loaded only once, so calling
 
    // require a second time will simply return the same object.
Another part of plugins, is having people find them! A natural fit would be to use the Mozilla Add-ons infrastructure (AMO) to host plugins.
    // var module = require("./modulename");  Example:
 
    var narcissus = require("narcissus");
==== Cross domain loading ====
    var ast = narcissus.parse("1+1");
 
   
With a cross domain Dojo build in place, we will be able to load plugins that live remotely.
    // resourceURL() computes URLs to resources relative to code modules.
 
    // If only one parameter is provided, the URL is relative to the plugin.json file.
In your config file you will be able to fire an event to load a plugin:
    // Example:
 
    var url = resourceURL("bespin", "../../images/foo.png");
  bespin.plugin.load("http://foo.com/bespinPlugin.zip");
   
 
    var url = resourceURL("images/foo.png"); // images directory at same level as plugin.json
=== Server and Client Plugins ===
   
    // subscribe() is like bespin.subscribe, except the plugin handler automatically
    // keeps track of subscriptions and will unsubscribe if the plugin needs to
    // be reloaded or deactivated.
    subscribe("plugin:activated", function(plugin) {
        // do something
    });
   


One *future* item that we are excited to explore is the notion of a plugin that can not only contain client code to change the editor or dashboard, but also deploy server changes.
=== Bespin Extension API ===


This would be pretty unique, and would enable feature rich changes across the stack.
The sections above describe the basic framework for handling plugins. The API for extending Bespin will be developed over time, based entirely upon the development of real-world plugins. Documentation in this spot will grow along with that API.
Kdangoor
canmove, Confirmed users, Bureaucrats and Sysops emeriti
1,093

edits

Retrieved from "https://wiki.mozilla.org/Special:MobileDiff/144597...162112"