Labs/Bespin/DesignDocs/PluginAPI - Revision history

Kdangoor: /* A one-file plugin */

2009-08-14T16:18:45Z

A one-file plugin

← Older revision		Revision as of 16:18, 14 August 2009
Line 113:		Line 113:

	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.


			Here's an example of a single file plugin that adds commands and adds/removes a DOM element:

			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);
			}

	=== Plugin installation ===		=== Plugin installation ===

Kdangoor: /* A one-file plugin */

2009-06-14T02:54:48Z

A one-file plugin

← Older revision		Revision as of 02:54, 14 June 2009
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,

Kdangoor: /* A one-file plugin */

2009-06-14T02:53:56Z

A one-file plugin

← Older revision		Revision as of 02:53, 14 June 2009
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.
	~~entryPoints~~: {		provides: [
	"bespin.syntax.simple": {		["bespin.syntax.simple", {
	extensions: ["lua"]		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~~
	~~// you automatically. If the plugin needs to be reloaded,~~
	~~// all event handlers will automatically be unsubscribed.~~
	~~subscribe("bespin:syntax:simple:highlightBlock", function(block) {~~
	~~// do something~~
	})
	}		}

	~~// The deactivate function is optional and provides a way~~		exports.savehandler = function(event) {
	~~// for the plugin to cleanup after itself.~~		// do whatever it is we do on save
	exports.~~deactivate~~ = function() {
	// 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.

Kdangoor at 19:52, 21 May 2009

2009-05-21T19:52:56Z

← Older revision		Revision as of 19:52, 21 May 2009
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 107:		Line 107:
	// do something		// do something
	})		})
			}

			// The deactivate function is optional and provides a way
			// for the plugin to cleanup after itself.
			exports.deactivate = function() {
			// do something
	}		}

Line 130:		Line 136:
	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.		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.

	=== ~~Wordpress-like~~ ===		=== Singletons ===

	~~(TODO: ideas in this section to be shuffled around in light~~ of ~~the new direction~~ in ~~the previous section~~.)		Plugins are singletons; there is only one instance of a plugin in memory at a time.

	~~What if we have a new directory, BespinSettings/plugins which is where your plugins go.~~		=== Disabling Plugins ===

	~~They~~ can ~~either~~ be ~~one file (myplugin.js) or~~ a ~~directory (myplugin/~~plugin~~.js with other stuff too)~~.		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.

	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.		== Plugin API ==

	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\|...~~		Functions available within the plugin's loading scope:

	~~The plugin itself should have~~ a ~~set of metadata associated with it~~. ~~This can be placed into it via comments~~, a ~~la Wordpress~~.		// require() loads a module. Modules are loaded only once, so calling
			// require a second time will simply return the same object.
	~~We will have new events for items such as~~:		// var module = require("./modulename"); Example:
			var narcissus = require("narcissus");
	* plugin:activate		var ast = narcissus.parse("1+1");
	* plugin:deactivate
	* plugin:load:complete		// resourceURL() computes URLs to resources relative to code modules.
			// If only one parameter is provided, the URL is relative to the plugin.json file.
	~~and once loaded a plugin can listen for:~~		// Example:
			var url = resourceURL("bespin", "../../images/foo.png");
	* cmdline:loaded
	* settings:loaded		var url = resourceURL("images/foo.png"); // images directory at same level as plugin.json
	* toolbar:loaded
			// subscribe() is like bespin.subscribe, except the plugin handler automatically
	~~The plugin will listen in on these and will then hook itself up~~.		// keeps track of subscriptions and will unsubscribe if the plugin needs to
			// be reloaded or deactivated.
	~~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~~.		subscribe("plugin:activated", function(plugin) {
			// do something
	~~Then~~, the ~~plugin, can unsubscribe() on the type default when it adds itself~~ to the ~~subscription queue~~.		});

	~~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~~.

	=~~=== Plugin Directory ====~~

	~~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~~.

	~~==== Discovery ====~~

	~~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~~.

	~~==== Cross domain loading ====~~

	~~With a cross domain Dojo build in place, we~~ will ~~be able~~ to ~~load plugins that live remotely.~~

	~~In your config file you will~~ be ~~able to fire an event to load a plugin:~~

	~~bespin.plugin.load~~("~~http~~://~~foo.com/bespinPlugin.zip"~~);

	~~=== Server and Client Plugins ===~~

	~~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 at 20:09, 20 May 2009

2009-05-20T20:09:44Z

@@ Line 90: / Line 90: @@
          // If it's a lua file, it will see that this plugin can handle
          // lua.
-         "bespin.syntax.simple": {
+         entryPoints: {
-            extensions: ["lua"]
+            "bespin.syntax.simple": {
+         }
+     }
@@ Line 108: / Line 110: @@
 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 ===

Kdangoor at 01:50, 19 May 2009

2009-05-19T01:50:24Z

@@ Line 54: / Line 54: @@
 Create new settings
 == Core Plugin API ==
 Here we will talk about the first goal, the core plugin API itself
 === Wordpress-like ===
 What if we have a new directory, BespinSettings/plugins which is where your plugins go.

Dalmaer at 21:45, 24 April 2009

2009-04-24T21:45:03Z

@@ Line 12: / Line 12: @@
 * First, we need an API that allows you to register and activate new plugin code
 * Second, we need public APIs to let plugins easily get done what they need too, without having to go deep into the code, and accessing APIs that are a known public contract. This is vital to the goal of rapid innovation without constantly breaking plugins.
 == Core Plugin API ==

Dalmaer at 16:26, 15 April 2009

2009-04-15T16:26:15Z

← Older revision		Revision as of 16:26, 15 April 2009
Line 34:		Line 34:
	* plugin:deactivate		* plugin:deactivate
	* plugin:load:complete		* plugin:load:complete

			and once loaded a plugin can listen for:

			* cmdline:loaded
			* settings:loaded
			* toolbar:loaded

	The plugin will listen in on these and will then hook itself up.		The plugin will listen in on these and will then hook itself up.
Line 42:		Line 48:

	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.		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.

			==== Plugin Directory ====

			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.

	==== Discovery ====		==== Discovery ====
Line 53:		Line 63:
	In your config file you will be able to fire an event to load a plugin:		In your config file you will be able to fire an event to load a plugin:

	bespin.~~publish("~~plugin:load~~", {~~		bespin.plugin.load("http://foo.com/bespinPlugin.zip");
	~~url:~~ "http://foo.com/bespinPlugin.zip"
	});

	=== Server and Client Plugins ===		=== Server and Client Plugins ===

Dalmaer at 22:33, 3 April 2009

2009-04-03T22:33:14Z

← Older revision		Revision as of 22:33, 3 April 2009
Line 8:		Line 8:
	For this we want a plugin API. The goal is for this API to be as simple as possible.		For this we want a plugin API. The goal is for this API to be as simple as possible.

	As well as commands and the config work, we also have the low level construct of the publish/subscribe event system that you can tie into.		As well as commands and the config work, we also have the low level construct of the publish/subscribe event system that you can tie into. This shows that there are actually a couple of pieces to a plugin API:

	~~Here is a short term~~ go at a ~~simple~~ plugin ~~system:~~		* First, we need an API that allows you to register and activate new plugin code
			* Second, we need public APIs to let plugins easily get done what they need too, without having to go deep into the code, and accessing APIs that are a known public contract. This is vital to the goal of rapid innovation without constantly breaking plugins.

			== Core Plugin API ==

			Here we will talk about the first goal, the core plugin API itself

	=== Wordpress-like ===		=== Wordpress-like ===
Line 51:		Line 56:
	url: "http://foo.com/bespinPlugin.zip"		url: "http://foo.com/bespinPlugin.zip"
	});		});

			=== Server and Client Plugins ===

			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.

			This would be pretty unique, and would enable feature rich changes across the stack.

Dalmaer: /* Wordpress-like */

2009-03-25T00:07:31Z

Wordpress-like

← Older revision		Revision as of 00:07, 25 March 2009
Line 26:		Line 26:
	We will have new events for items such as:		We will have new events for items such as:

	* ~~bespin:~~plugin:activate		* plugin:activate
	* ~~bespin:~~plugin:deactivate		* plugin:deactivate
	* ~~bespin:~~plugin:load:complete		* plugin:load:complete

	The plugin will listen in on these and will then hook itself up.		The plugin will listen in on these and will then hook itself up.
Line 48:		Line 48:
	In your config file you will be able to fire an event to load a plugin:		In your config file you will be able to fire an event to load a plugin:

	bespin.publish("~~bespin:~~plugin:load", {		bespin.publish("plugin:load", {
	url: "http://foo.com/bespinPlugin.zip"		url: "http://foo.com/bespinPlugin.zip"
	});		});