Plugins

Since 0.4, Scripted now has a plugin architecture. This page provides an introduction to the Scripted plugin model and APIs. The information is intended to convey the general architectural ideas and help you get started but won't document the API in detail.

A Simple Plugin

A Scripted plugin is an AMD module that is autoloaded by the Scripted-client when it starts up.

The easiest way to explain what a Scripted plugin looks like is with an example. Simple plugins just consists of single JavaScript file. The entire source-code of a very simple plugin is shown below:

	define(function(require) {
		var editorExt = require('scripted/api/editor-extensions');

		//Defines an editor action.
		editorExt.setAction('allCaps', {
			name: 'All Caps', // readable description
			handler: function (editor) {
				var sel = editor.getSelection();
				var text = editor.getText(sel.start, sel.end);
				text = text.toUpperCase();
				editor.setText(text, sel.start, sel.end);
			}
		});
	});

This plugin contributes an action to the editor. When the action executes, it converts the currently selected text into upercase letters. To execute actions a trigger is needed.

Let's disect the code a little as it's structure is pretty typical.

AMD Wrapper code

  define(function (require) {
  	  ... your actual code goes here ...
  });

If you have used requirejs/AMD before you will already know what this is. Essentially you need this little-bit of boilerplate so an AMD module loader like requirejs can load your module and keep track of its dependencies.

Accessing Plugin APIs

The next bit of code at the start of your plugin usually makes one or more calls to the require function to import various APIs/libraries the plugin wants to use. A typical plugin will want to contribute some kind of extension to the Scripted editor. This is done by calling function in the editor-extensions apis. Our plugin has this line:

 var editorExt = require('scripted/api/editor-extensions');

Anywhere below this line we can call functions in the api with editorExt.<functon-name>(...).

Contributing an 'extension' to the editor

The editor-extensions API contains several functions plugins can call to add different kinds of functionality to the Scripted editor(s).

Our example plugin calls setAction to associate an actionID allCaps, with a handler function that converts the current editor selection into upper case.

Installing a Plugin

To install a plugin you simply need to drop it in the right place.

The Scripted plugin loader will look in these two places:

• USER_HOME/scriptedrc/plugins/
• SCRIPTED_HOME/plugins

SCRIPTED_HOME is whichever directory you installed Scripted in. Normally you would find any plugins that come pre-installed with Scripted in SCRIPTED_HOME/plugins and you would install your own custom plugins under USER_HOME.

Packaging

The simplest plugins consist of only a single JavaScript file. More complex plugins may consist of multiple files. Some of the files may contain JavaScript, but others may be resources such as CSS or text snippets used by your plugin.

To support this, we allow a plugin to be packaged as a directory. You can browse an example here.

A "directorified" plugin needs at least a plugin.json file and a main .js. The main .js file can be anywhere in your directory and have any name as long as you point to it from the plugin.json file like. If you don't point to it explicitly, the main file should be called index.js.

Unlike a single-file plugin, a directorified plugin is not activated by default but needs to be explicitly turned on by adding some code like this to the plugin.json:

{
	"scripted" : {
		"plugin" : true
	}
}

A 'main' property can be added to point to your plugin's main JavaScript file. Effectively, the 'main' file will be the one that Scripted loads. The other files in the directory are entirely yours to manage and load in whatever way you need them to support your plugin's functionality.

Note that some of the more complex plugins in the SCRIPTED_HOME/plugins folder are shipped as example code, but are disabled by default. To see them in action you will have switch them on by changing the "plugin" property to "true".

What APIs are available to plugins?

A Scripted plugin is just an ordinary AMD module. The Scripted-client itself is entirely built out of AMD modules. Thus your plugin can, in theory, do anything any other Scripted client code can do through internal APIs. These internal APIs are neither stable, well-documented nor easy to use. We don't want to stop you from reading our code and using those APIs... However, we want to make things easier for you. Therefore, we are developing a growing set of plublic APIs scripted/api/<some-name>. These are the APIs we intend plugin authors to use and the are being designed to make doing the things typical plugins may want to do easy.

Learning about the Public APIs

To find out what plublic APIs are available you can browse their source code.

Also, when you have already imported an API like editor-extensions in your plugin module. You can ge content assist from Scripted about the functions defined in that API. For example:

![content assist](img/editor-extensions-proposals.png)

Or you can see the attached JSDoc when hovering over an API call with the mouse:

![JSDoc hover](img/setAction-jsdoc-hover.png)

Hovers and content assist works quite well for APIs imported via an explicit require call. Unfortunately, due to current limitations it doesn't yet work so well for APIs that are implicitly passed as arguments to callback functions. Many of these callbacks receive an editor instance. To find out about the edtiro instance API you will currently need to refer to the source code here. Evidently, we intend to solve this problem in a future version of Scripted.

More Examples

Another good way to learn about the plugin-apis is looking at our example plugins. They are part of the Scripted distribution in the SCRIPTED_HOME/plugins folder. You can browse them by their code with Scripted. Or you can browse them on github.