The most important change in Bespin 0.9a2 (download it now) is that it restores compatibility with Chrome. Chrome 6 included a change that broke a library used by Bespin.

Bespin Embedded now has a jslint_command plugin which adds a (you guessed it!) “jslint” command. Running this command will run jslint on the code you’re editing and tell you if it spots any problems. If you make a build with the “notifier” and “gritter_notify”, you can even get a popup message when you run jslint and your file has
errors.

Also new is a “specialmodules” setting. If you’re editing CommonJS modules and the module name entered matches a regex contained in “specialmodules”, a special syntax highlighting tag (“specialmodule”) is added. This makes it possible to differentiate to your users which modules are provided by your system and which are their own.

The Bookmarklet has been updated to include the “diff” syntax highlighter, which is useful if you are the type of person who reviews patches on the web.

As announced a few weeks ago, the Bespin project is being renamed “Skywriter”. We are working on stabilizing APIs, simplifying some code and creating new JavaScript-based build tooling. The first release branded as Mozilla Skywriter will be a 1.0 alpha release, and as we head to a 1.0 final we’ll want to be sure that the APIs
will be stable. In a few days, plenty of new opportunities to help out on the project
will arise, so head over to the skywriter-core mailing list if you’d like to help make Skywriter the best editor around.

&emdash; Kevin Dangoor on behalf of the Mozilla Developer Tools team

We’ve had many compliments and complaints about the “Bespin” codename ever since we first introduced the project. You can’t please everyone, especially when it comes to naming. The Bespin codename, derived from the awesome “cloud city” in The Empire Strikes Back, was a fun name to use for an editor that enables “coding in the cloud”.

Since the initial release in February 2009, the Bespin has come a long way. The project has changed focus and expanded its reach. The “Bespin Embedded” releases have been showing up more and more including several entries in the recent “Node Knockout” competition: Nodify, Inflatable Churn, and Wrath. Other recent development environments on the web have also chosen to use Bespin, including ShiftEdit, jGate and Mozilla’s own Add-On Builder (aka FlightDeck).

As we approach a 1.0 release, it was clear that it was time to shed Bespin’s code name and give it a real, lasting project name. We’re happy to announce that that name is Mozilla Skywriter. I think that Mozilla Skywriter fits the “coding in the cloud” theme very well indeed.

Skywriter is becoming an end-to-end JavaScript-based system. Camilo Aguilar, a new contributor to the project, has been working on porting “dryice”, our build tool, to node.js. Once that’s done, we’ll be creating a XULRunner-based desktop version of Skywriter and a new customizable server version based on node.js. It’s actually pretty amazing how many different uses for our editor we’ll be able to target with a single codebase.

Many people who have worked on Skywriter have expressed a desire to fork it on GitHub. There have been unofficial mirrors and plenty of people installing Mercurial just to use Bespin. In order to make things easier for our community, we’re moving the official repository for Skywriter over to GitHub: http://github.com/mozilla/skywriter.

A note about the repositories: that shiny new repository holds the “all JavaScript” version of Skywriter. As I write this, that repository needs a lot of work (in other words, it’s broken!). All of the “bespin” names have changed to “skywriter” and the build tooling is still in the process of being rebuilt. The existing bespinclient repository remains available for people wanting to work with something that works today. That repository is effectively a branch of the code prior to the start of the JavaScript work. For the most part, we should be able to migrate changes made to that repository over to the new Skywriter repository pretty easily. We’re just changing the tooling to JavaScript, we’re not really changing Bespin’s core plugins at all.

One final note about the Bespin to Skywriter transition: the Bespin name appears in many places and it will take some time to fully migrate over. The Mozilla Skywriter home page will always have up to date links to project resources and is the best place to look if you’re having trouble finding something.

You can follow the Skywriter project (MozSkywriter) on Twitter and ask us questions in #skywriter on irc.mozilla.org.

Finally, a big thanks to Julian Viereck who is off to university in Zürich. Julian has been a huge help to the Skywriter project since the beginning and we wish him good luck in the coming years!

– Kevin Dangoor on behalf of the Mozilla Skywriter team

The new Bespin Plugin Gallery makes it very easy to find useful plugins for Bespin and to share the plugins you’ve created.

Top lists in the Plugin Gallery

By downloading the plugins you need and adding them to the search path in your manifest file, you can easily build a custom Bespin editor with a variety of new features. Need Python syntax highlighting? Markdown conversion? Access to gists? Early testers of the Plugin Gallery have added those plugins already and there is plenty more that is possible with Bespin’s plugin system.

It’s easy to share your own plugins… just upload your .js file (for single file plugins) or zip/tar up your plugin directory (with a package.json file) and your plugin is there for the world to enjoy.

Thanks to Ryan Snyder who took the lead on building the Plugin Gallery and the rest of Mozilla’s webdev and QA teams for bringing this site to life!

Introduction

Since Bespin is a webapp, any Bespin command could conceivably pop up some bit of user interface to interact with the user. It’s just a matter of creating some DOM nodes and placing them on the screen.

But, if you want something a bit more persistent and integrated, you’ll need to learn a bit about how Bespin’s GUI is put together. That’s what this tutorial is about.

At the same time, we’re going to talk about how Bespin plugins can themselves be pluggable.

In this tutorial, we assume that you’re already familiar with using dryice and the basics of making plugins. We’re also going to assume a directory structure like the one from the commands tutorial.

By the end of this tutorial, we’ll have something that looks toolbar-like. We’re not trying to create a fully-functional toolbar here, because the focus is on hooking in to Bespin’s GUI.

This tutorial should work with Bespin 0.9a1 or later. However, there is a bug in Firefox 3.6.x that will cause the toolbar to not display properly. Bespin 0.9a2 has a workaround for this, and the bug itself is fixed in Firefox versions after 3.6.x.

Creating Our Plugin

As with the commands tutorial, we’re assuming that you’re working within a directory called bespintutorial that has Bespin itself in a subdirectory called bespin.

In plugins that have user interface elements, you will almost always need to create a “multi file plugin”. That just means we’ll be creating a directory rather than a single .js file.

We’ll create a directory called tutorialtoolbar. To turn it into a plugin, we need to create a file called package.json in the tutorialtoolbar directory.

We also need a dryice manifest so that we can see our plugin in action. Create a file called toolbar.json in the bespintutorial directory. Here’s what we’ll put in it to start with:

{
    "output_dir": "../build",
    "plugins": ["embedded", "tutorialtoolbar"],
    "search_path": [".."]
}

Switch to the bespin directory and run:

python dryice.py -s 8080 ../toolbar.json

You shouldn’t get any errors from dryice. That means that it was able to find our tutorialtoolbar plugin. If you open your browser to http://localhost:8080/, you’ll see a normal looking Bespin. Now we just need to put something in our plugin.

Creating A Simple View

For a first step, we’ll just toss a string up on the screen. In the tutorialtoolbar directory, create a new file called index.js. Here’s how our toolbar component will start out:

exports.ToolbarView = function() {
    var elem = document.createElement("div");
    elem.innerHTML = "<b>Toolbar!</b>";
    this.element = elem;
};

We’re creating a Toolbar class. When a new Toolbar is created, it gets a new element which just has our string in it. We set that to element on the instance. This is the key to GUI components that are integrated into Bespin’s UI: they just offer up an element that Bespin will put in place.

The next step is telling the Bespin system about our new component. We do that in the package.json file, which will now look like this:

{
    "provides": [
        {
            "ep": "factory",
            "name": "tutorialtoolbar",
            "action": "new",
            "pointer": "#ToolbarView"
        }
    ]
}

The factory extension point is used for extensions that provide components for Bespin to automatically instantiate. That may sound kind of vague, but you’ll see in a moment that it’s actually easy to use. The action tells Bespin that it’s going to be creating a new instance and the pointer is telling Bespin to look in the tutorialtoolbar plugin’s index module for something called ToolbarView.

We’ve written code that will generate our initial toolbar and we’ve told Bespin that this is available. The next step is to tell Bespin to put one into the UI. This can be done either in the dryice manifest file or even at runtime when useBespin is called. We’ll do it in the manifest file (toolbar.json). Here’s the new manifest:

{
    "output_dir": "../build",
    "plugins": ["embedded", "tutorialtoolbar"],
    "search_path": [".."],
    "config": {
        "objects": {
            "toolbar": {
                "factory": "tutorialtoolbar"
            }
        },
        "gui": {
            "north": {
                "component": "toolbar"
            }
        }
    }
}

The new section is the config section. This provides the application configuration (about which you can read more in the Embedder’s Guide).

The objects part of the config is telling Bespin to create a “global” (global within Bespin) object called toolbar. Bespin will look for a factory called tutorialtoolbar, which happens to be what we defined in the package.json file.

The gui part of the config is telling Bespin to toss the component (object) that we created with the name toolbar into the “north” part of the interface. Bespin uses a simple “border layout” with north, south, east, west and center locations. So, our toolbar should appear at the top of the page.

Refresh your browser, and you should see our Toolbar! appear at the top. If it appears at the bottom, you’ve witnessed the bug mentioned in the introduction.

CSS3 Flexible Box Model (an aside)

CSS3 includes a module called the Flexible Box Model (sometimes called flexbox), which Paul Rouget did a great job of introducing in this Mozilla Hacks article.

Traditionally, HTML+CSS have been quite nice for laying out documents but not so great for laying out user interfaces. Flexbox makes laying out UI a far easier process.

Bespin uses flexbox to create the border layout. When you declare that a GUI component belongs in the “north”, all Bespin has to do is add the “north” class to the element, and it pops into the right place.

Flexbox would also be a great way to create a toolbar, but we’re not going to go that far in this tutorial.

By using flexbox, we let the browser do all of the layout which is generally faster and smoother than JavaScript-based layouts.

Making Our Toolbar Pluggable

One of Bespin’s main features is that it is customizable and extendable. While it’s certainly possible to make a static toolbar with a certain collection of functions, it’s a lot more interesting to create a toolbar that is itself pluggable. Plus, that’s part of the point of our tutorial.

We’ll start by defining an extension point of our own in package.json. Add this as another item in the provides list in package.json:

{
    "ep": "extensionpoint",
    "name": "tutorialtoolbaritem",
    "description": "Toolbar item views",
    "params": [
        {
            "name": "name",
            "description": "name of this toolbar item",
            "type": "string"
        },
        {
            "name": "pointer",
            "description": "pointer to a component that can be instantiated with new and has an element defined on it."
        }
    ]
}

Extension points themselves are defined via the extensionpoint extension point. Seems a bit circular, but it works. We’re creating an extension point called tutorialtoolbaritem. Bespin is designed to be introspectable, so we provide some documentation about the extension point via the description and params properties.

We’re going to make tutorialtoolbaritems look a lot like Bespin’s GUI components (an object with an element property).

Now, we need to make our toolbar go out and find the registered tutorialtoolbaritems. We’ll change index.js to look like this:

var catalog = require("bespin:plugins").catalog;

exports.ToolbarView = function() {
    var elem = document.createElement("menu");
    elem.setAttribute('class', "tutorial-toolbar");
    elem.setAttribute('type', "toolbar");
    this.element = elem;

    this._items = [];

    var extensions = catalog.getExtensions('tutorialtoolbaritem');
    var self = this;
    extensions.forEach(function(ext) {
        ext.load().then(function(item) {
            item = new item();
            self._items.push(item);
            elem.appendChild(item.element);
        });
    });
};

The first thing we’re going to do is change the element we’re creating into an HTML5 menu element. By giving it a type of toolbar, we’re letting the browser know that we’re creating a toolbar. Right now, the browsers don’t render the toolbar in any special way, but we can use CSS to render the toolbar however we wish.

Next, we’ll make a list to keep track of the items we find. Speaking of finding the items, we need to talk to the plugin catalog about that. In the first line of the file, we imported the catalog. Now, we call getExtensions which will return all of the tutorialtoolbaritems.

We use var self = this because we’ve got some nested callbacks and that’s a bit nicer to look at than binding each function individually. Then, we loop through the list of extensions and call load on each one.

The load function returns a Promise. Promises provide a convenient way to manage callbacks for asynchronous behavior. For our purposes here, the only difference between a Promise and a normal callback function is that we don’t pass the callback directly to load. Instead, we call then on the promise and pass the callback to that.

Back in our metadata for the tutorialtoolbaritem extension point, we defined the pointer property as a pointer to a component that can be instantiated with new and has an element defined on it. So, when we load the extension, that’s what we’re going to get back. With the tutorialtoolbar item in hand, we can call new on it, add that new instance to our items list and then add the instance’s element to our toolbar.

And, with that, we have created a dynamically extendable toolbar.

Adding Some Items

Of course, if we reload our Bespin, the toolbar will be rather boring. We haven’t added any toolbar items!

With the infrastructure that we put in place in the last section, we can create tutorialtoolbaritems in any plugin. For convenience, we’ll just add a couple of items in the tutorialtoolbar plugin.

We’ll make a new module (file) for them in the tutorialtoolbar directory called items.js. At this stage, we’re not going to make our toolbar items do anything, but we just want to have something to display. Here is our items.js file:

exports.Logo = function() {
    var li = document.createElement('li');
    li.innerHTML = "Logo here";
    this.element = li;
};

exports.OpenFileIndicator = function() {
    var li = document.createElement('li');
    li.innerHTML = "SampleProject — readme.txt";
    this.element = li;
};

exports.Save = function() {
    var li = document.createElement('li');
    li.innerHTML = "Save";
    this.element = li;
};

exports.PositionIndicator = function() {
    var li = document.createElement('li');
    li.innerHTML = "Row 0, Column 0";
    this.element = li;
};

As you can see, each one of these functions does nothing but create an li element (as per the HTML5 spec for menus) and add that element to the instance on the element property.

One more thing to do before we can see our toolbar. We need to register the extensions for our tutorialtoolbar extension point. Back in package.json, we’re going to add these four more items to our provides property:

{
    "ep": "tutorialtoolbaritem",
    "name": "logo",
    "pointer": "items#Logo"
},
{
    "ep": "tutorialtoolbaritem",
    "name": "openfileindicator",
    "pointer": "items#OpenFileIndicator"
},
{
    "ep": "tutorialtoolbaritem",
    "name": "save",
    "pointer": "items#Save"
},
{
    "ep": "tutorialtoolbaritem",
    "name": "positionindicator",
    "pointer": "items#PositionIndicator"
}

You can see that each one of these refers to the items module in the pointer, since that’s where we put these items.

For reference, here’s the complete package.json file at this stage:

{
    "provides": [
        {
            "ep": "factory",
            "name": "tutorialtoolbar",
            "action": "new",
            "pointer": "#ToolbarView"
        },
        {
            "ep": "extensionpoint",
            "name": "toolbaritem",
            "description": "Toolbar item views",
            "params": [
                {
                    "name": "name",
                    "description": "name of this toolbar item",
                    "type": "string"
                },
                {
                    "name": "pointer",
                    "description": "pointer to a component that can be instantiated with new and has an element defined on it."
                }
            ]
        },
        {
            "ep": "tutorialtoolbaritem",
            "name": "logo",
            "pointer": "items#Logo"
        },
        {
            "ep": "tutorialtoolbaritem",
            "name": "openfileindicator",
            "pointer": "items#OpenFileIndicator"
        },
        {
            "ep": "tutorialtoolbaritem",
            "name": "save",
            "pointer": "items#Save"
        },
        {
            "ep": "tutorialtoolbaritem",
            "name": "positionindicator",
            "pointer": "items#PositionIndicator"
        }
    ]
}

With that, we’ve done everything we need to do to see our toolbar. Let’s reload the page. You should see something that looks like this:

It worked! It has our items in it! Doesn’t look much like a toolbar, though, does it?

Styling Your Plugins

To make our toolbar look like a toolbar, we need to add some styles. In order to support themes properly, Bespin uses LESS, which is an extended CSS syntax.

In the tutorialtoolbar directory, create a resources directory. In there, create a file called toolbar.less. We need to tell Bespin’s theme manager about this file, so we need to add one more thing to the provides property in package.json:

{
    "ep": "themestyles",
    "url": [ "toolbar.less" ]
}

themestyles extensions provide URLs (relative to the plugin’s resources directory) to the LESS files that this plugin needs to have loaded. The theme manager will automatically load these files as needed.

And what’s in this mysterious toolbar.less file?

.bespin {
    .tutorial-toolbar {
        display: block;
        background-color: #000;
        border-bottom: solid #424038 1px;
        -moz-box-shadow: 0px 0px 3px 3px #000;
        -webkit-box-shadow: 0px 0px 3px 3px #000;
        color: #ffffff;
        font-family: Helvetica, Arial;
        width: 100%;
        margin: 0px;
        padding: 0px;
    }

    .tutorial-toolbar li {
        display: inline;
        padding: 0px 24px 0px 0px;
    }
}

This looks like fairly normal CSS, right? Except what’s that .bespin doing surrounding those other rules? When LESS expands this out to standard CSS, the result would be something like this:

.bespin .tutorial-toolbar {
}

.bespin .tutorial-toolbar li {
}

So, the surrounding .bespin is a nice little shorthand, and it prevents CSS from leaking out onto the page. When you consider the use of Bespin Embedded on other sites, it’s a good idea to ensure that all of our styles are scoped for use only within Bespin.

With these styles in place, let’s reload the page. Much nicer, eh?

Wrapping Up

On the one hand, this tutorial didn’t give us a functioning toolbar. It’s all static text. On the other hand, look at everything we did cover:

• multi-file plugin structure
• creating a component that Bespin can display
• the awesomeness that is CSS3’s Flexible Box Model
• configuring our component for display in Bespin
• defining and using our own extension points

“Coding in the cloud” is not a new concept. There are lots of sites that allow people to edit code and other plain text formats directly in their browsers. Unfortunately, a great many of these sites use simple <textarea> elements to do the editing. If you’re like me, the first time you hit the tab key to indent some code and then end up on another field altogether is the point at which you really wish you had a better editor at that moment.

There are a handful of solutions to that problem, and today we’re giving you another: the Bespin Bookmarklet. It’s trivial to install, always up to date and easy to use.

Check out the video below for an example of the bookmarklet in use, or just follow the instructions on the Bespin Bookmarklet page.

– Kevin Dangoor, on behalf of the Bespin Team

For this tutorial, you’ll need the markdown_js plugin.

Setting Up

With this tutorial, we’re starting from the very basics. You’ll need Python (preferably 2.6) to do custom Bespin plugin development. If you don’t have Python already, you can get it prebuilt for your platform with little fuss.

You’ll also need Bespin Embedded, which you can get from the releases directory on ftp.mozilla.org. This tutorial was written for Bespin Embedded 0.9a1 (direct download link).

Important note: if your copy of Bespin Embedded has a plugins/mine directory, delete that directory before doing this tutorial. That directory was added to the release in error and includes plugins that conflict with the ones needed here.

Make a directory called bespintutorial. Uncompress the BespinEmbedded package in there and rename the directory from the tarfile bespin (so you’ll have bespintutorial/bespin/). On a Mac, you can do these things from the Terminal command line:

mkdir bespintutorial
cd bespintutorial
cp ~/Downloads/BespinEmbedded-VERSION.tar.gz .
tar xzf BespinEmbedded-VERSION.tar.gz
mv BespinEmbedded-VERSION bespin

The Manifest

Bespin’s build tool, dryice, uses a “manifest” file in JSON format to describe what it needs to build and where to find all of the parts. Open up your text editor to create a file called manifest.json in the bespintutorial directory. Here’s what will go into the file at this step:

{
    "output_dir": "../build",
    "plugins": ["embedded"],
    "search_path": [".."]
}

We’ll be running the build from the bespin directory, so those .. in the manifest are referring to the bespintutorial directory.

Now, we’ll fire up the dryice server. This command assumes at Python is on your path:

cd bespin
python dryice.py -s 8080 ../manifest.json

After running that command, you can open up your browser to http://localhost:8080/ and you should see the Bespin editor that dryice just built for us.

Next, place the markdown_js.js file which you got at the beginning of this tutorial into the bespintutorial directory.

Getting Our Plugin Going

Now, we’ll create a new file called markdown.js. This is our Bespin plugin file. Bespin plugins all have a metadata section, so let’s put that at the top of our file to get us going:

"define metadata";
({
    "dependencies": {
        "markdown_js": "0.1.2"
    }
});
"end";

So, that’s our whole plugin for now. All we’re saying is that our plugin depends on the markdown_js plugin (version 0.1.2). Now we have to tell dryice about our new plugin, so we’ll add it to the plugins line of our manifest.json file:

"plugins": ["embedded", "markdown"],

You should be able to reload http://localhost:8080/ and have things still work.

Making Our Plugin Do Something

Since we’re going to be making commands, it would be most convenient for us at this point to have a command line. So, we’ll add the command_line plugin to our manifest.json file:

"plugins": ["embedded", "markdown", "command_line"],

Reload the page in your browser and you should see the command line at the bottom. I also like being able to press cmd-J (ctrl-J on Windows/Linux) to switch between the command line and the editor. The uicommands plugin gives us that, so let’s enable that, too:

"plugins": ["embedded", "markdown", "command_line", "uicommands"],

Now we’re ready to make our first command. We’re going to make a command that:

1. converts the Markdown text we’ve entered to HTML
2. puts that HTML in a new window so we can preview it.

Let’s write a function that does these things.

var env = require('environment').env;
var markdown = require("markdown_js");

exports.preview = function(args, request) {
    var text = env.editor.selectedText;
    if (!text) {
        text = env.editor.value;
    }
    var popup = window.open("", "_blank", "location=no,menubar=no");
    popup.document.body.innerHTML = markdown.toHTML(text);
    request.done();
};

The first two lines import other modules that we’ll be needing. The environment plugin is always available in Bespin, and the env variable inside of there is very handy, as we’ll soon see. We also import the markdown_js module that we declared in our dependencies. We’ll call it markdown when we use it in this module for convenience.

If you’re not familiar with CommonJS Modules, you’ll find that they’re simple to work with. You use the require function to import modules and you put anything you want to be available outside of the module on the exports object. We’re going to make a function called preview available from this module.

Bespin command functions all take two parameters: args and request. args contains the incoming arguments to the command and request provides methods for working with this particular request from the user. Of these, the commands we’ll be making here today only make use of request.done(), which signals that we have finished all of our processing.

Now, let’s focus on the body of the function:

var text = env.editor.selectedText;
if (!text) {
    text = env.editor.value;
}
var popup = window.open("", "_blank", "location=no,menubar=no");
popup.document.body.innerHTML = markdown.toHTML(text);
request.done();

The first line gets us the currently selected text. If the user selected only a portion of the document, we’ll preview that. The next line looks to see if there was any selected text. If there wasn’t, then we just grab all of the text from the editor.

Next, we use the standard window.open call to make a new window. A call to markdown.toHTML will give us the HTML version of our text and we drop that into our new window and we’re all set!

We need to register our new command with Bespin.

Since we’re going to create more than one Markdown related command, we’ll plan to create a top-level markdown command with subcommands. The command we’re working on now is markdown preview. We need to add a new provides section to our JSON metadata. Here’s what that looks like:

"provides": [
    {
        "ep": "command",
        "name": "markdown",
        "description": "commands for working with markdown files"
    },
    {
        "ep": "command",
        "name": "markdown preview",
        "description": "preview the HTML form of this markdown text",
        "pointer": "#preview"
    }
]

provides gives a list of extensions that are provided by this plugin. Each of those will have an ep at a minimum. That’s the “extension point” that we’re plugging into. Our first extension is a command and we give the command a name (which is what the user types) and a description that will appear in help text.

The second extension is for our preview command. It has a name and description as well. But, since this command is not just a holder for other commands, it also has a pointer. The pointer tells Bespin where to find the object (in this case, a function) for the extension. #preview is equivalent to markdown:index#preview which means the preview function in the index module in the markdown plugin.

Your complete file should now look like this:

"define metadata";
({
    "dependencies": {
        "markdown_js": "0.1.2"
    },
    "provides": [
        {
            "ep": "command",
            "name": "markdown",
            "description": "commands for working with markdown files"
        },
        {
            "ep": "command",
            "name": "markdown preview",
            "description": "preview the HTML form of this markdown text",
            "pointer": "#preview"
        }
    ]
});
"end";

var env = require('environment').env;
var markdown = require("markdown_js");

exports.preview = function(args, request) {
    var text = env.editor.selectedText;
    if (!text) {
        text = env.editor.value;
    }
    var popup = window.open("", "_blank", "location=no,menubar=no");
    popup.document.body.innerHTML = markdown.toHTML(text);
    request.done();
};

Let’s come up with some sample Markdown to use. How about this:

# Markdown Test #

This is a *simple* test of Markdown.

* one
* two
* three

Reload your browser, select all of the text and paste in that text. Then, jump down to the command line and run the markdown preview command. You should see a new window popup with the HTML version of the text there.

Congratulations! You’ve extended Bespin with a new command.

Keyboard Shortcut

Previewing the HTML seems like a very useful feature. Why don’t we add a keyboard shortcut so that we don’t need to go to the command line each time. To do this, we just need to add a key to the markdown preview metadata, like so:

{
    "ep": "command",
    "name": "markdown preview",
    "description": "preview the HTML form of this markdown text",
    "key": "ctrl_shift_p",
    "pointer": "#preview"
}

Now, cmd-shift-P on the Mac or ctrl-shift-P on Windows/Linux will run the markdown preview command. This also means that we can run the markdown preview command even if we don’t have the command line plugin in our build.

An aside about keyboard shortcuts: the key defined in command metadata like this is the lowest priority keyboard binding. A keymapping plugin can redefine the keys as can user preferences.

Replacing Text

One more common requirement of commands is that they need to be able to manipulate the text in some fashion and then put the manipulated version back into the editor.

We’ll make a markdown convert command that converts the text to HTML and then puts the text back into the editor. As before, we’ll start by writing a function that does this conversion and we’ll place it at the bottom of our file:

exports.convert = function(args, request) {
    var allOrSelection = 'selectedText';
    var text = env.editor.selectedText;
    if (!text) {
        allOrSelection = 'value';
        text = env.editor.value;
    }
    var html = markdown.toHTML(text);
    env.editor[allOrSelection] = html;
    request.done();
};

In this function, we’re going to do the same kind of thing we did in the preview function. We’ll work with the user’s selection, if there is one, and the complete text otherwise. In this case, we need to keep track of which it was so that, when we do the replacement, we’re only replacing the text that the user had selected.

Once we’ve gotten our text, we can use markdown.toHTML to do the conversion. Then, we put the text back into the editor (going into either selectedText or value, depending on where the text came from originally).

We need to tell Bespin about our new command, so we’ll add another object to the provides part of our metadata.

{
    "ep": "command",
    "name": "markdown convert",
    "description": "convert the selected text to HTML",
    "pointer": "#convert"
}

Looks just like the markdown preview command, doesn’t it?

Reload the page in your browser, paste in the sample markdown text and then run the markdown convert command. You should see the text converted to HTML. Try converting just a section of the text, and you’ll see that just that portion of the file is modified.

That was easy, wasn’t it?

Undo

Try converting the Markdown to HTML and then pressing cmd/ctrl-Z.

Submitting to the Bespin Plugin Gallery

Once you’ve completed creating a plugin that you want to share with the rest of the world, you should add a little more to the metadata before uploading your plugin to the Bespin Plugin Gallery. (As of this writing, the Bespin Plugin Gallery has not yet been released… but it’s coming soon, so you can follow this section to be ready when it’s here.)

We’ll add version, license and maintainer information:

"version": "1.0.0",
"maintainers": [
    {
        "name": "Kevin Dangoor",
        "email": "kid@blazingthings.com",
        "web": "http://blueskyonmars.com/"
    }
],
"licenses": [
    {
        "type": "MPL",
        "url": "http://www.mozilla.org/MPL/MPL-1.1.html"
    },
    {
        "type": "GPL",
        "url": "http://creativecommons.org/licenses/GPL/2.0/"
    },
    {
        "type": "LGPL",
        "url": "http://creativecommons.org/licenses/LGPL/2.1/"
    }
]

Bespin Plugin metadata is actually a superset of the CommonJS package metadata. As specified there, the version numbers should follow the Semantic Versioning numbering so that useful information about compatibility can be picked up from the version number alone.

I added myself as a maintainer and made this plugin available under the tri-license that Bespin itself is available under.

With all of this metadata in place, the final plugin file looks like this:

"define metadata";
({
    "dependencies": {
        "markdown_js": "0.1.2"
    },
    "provides": [
        {
            "ep": "command",
            "name": "markdown",
            "description": "commands for working with markdown files"
        },
        {
            "ep": "command",
            "name": "markdown preview",
            "description": "preview the HTML form of this markdown text",
            "key": "ctrl_shift_p",
            "pointer": "#preview"
        },
        {
            "ep": "command",
            "name": "markdown convert",
            "description": "convert the selected text to HTML",
            "pointer": "#convert"
        }
    ],
    "version": "1.0.0",
    "maintainers": [
        {
            "name": "Kevin Dangoor",
            "email": "kid@blazingthings.com",
            "web": "http://blueskyonmars.com/"
        }
    ],
    "licenses": [
        {
            "type": "MPL",
            "url": "http://www.mozilla.org/MPL/MPL-1.1.html"
        },
        {
            "type": "GPL",
            "url": "http://creativecommons.org/licenses/GPL/2.0/"
        },
        {
            "type": "LGPL",
            "url": "http://creativecommons.org/licenses/LGPL/2.1/"
        }
    ]
});
"end";

var env = require('environment').env;
var markdown = require("markdown_js");

exports.preview = function(args, request) {
    var text = env.editor.selectedText;
    if (!text) {
        text = env.editor.value;
    }
    var popup = window.open("", "_blank", "location=no,menubar=no");
    popup.document.body.innerHTML = markdown.toHTML(text);
    request.done();
};

exports.convert = function(args, request) {
    var allOrSelection = 'selectedText';
    var text = env.editor.selectedText;
    if (!text) {
        allOrSelection = 'value';
        text = env.editor.value;
    }
    var html = markdown.toHTML(text);
    env.editor[allOrSelection] = html;
    request.done();
};

We can upload this single .js file to the plugin gallery to share it with others. Once we do, we’ll have a change to add images and further description of the plugin if we wish. You can actually add a description to the plugin metadata itself, if you wish.

The End

In this tutorial, we created a brand new plugin that leveraged an existing JavaScript library to do useful text transformation in Bespin. Key concepts covered:

• using dryice server mode to test new plugins
• plugin structure and metadata
• the mechanics of creating an extension
• how to write command extensions
• how to manipulate the text in the editor

Multiple Bespins

Ever since we released the first Bespin Embedded, we’ve had requests on and off for the ability to have multiple Bespin editors on the page. When you factor in complexities around the plugin system, allowing multiple Bespins on a page is non-trivial. But, now multiple editors on the page works fine:

Multiple Bespins with command lines in white

The screenshot above shows off multiple Bespins with two of the new features from Bespin 0.8 (the white theme and the ability to include the command line). A couple of interesting implementation notes: Bespin uses Charles Jolley’s Tiki CommonJS module loader, which supports separate “sandboxes” of modules. The modules are downloaded from the server once, but each Bespin instance gets its own sandbox. That way, modules that store data in module-global variables will not get confused about which Bespin they’re working with. Settings and themes are shared between Bespin instances.

Code Completion

The other big new feature is one that is available today, but will become easier and smoother to use over time. Bespin can now do code completion, take a look at this screenshot for an example:

Code Completion Example

As soon as you hit “.”, Bespin will try to figure out what is available on the object you’re accessing. That information is gathered up beforehand in the well-known ctags format. We’re using the jsctags project (from Bespin team member Patrick Walton) to generate the tags. Using jsctags, we’ll eventually be generating the tags right in your browser (that’s the “easier and smoother” part that’s coming in the future).

Simplification

Bespin 0.9a1 simplifies two things over 0.8. First, there is now just one downloadable “Bespin Embedded” package that combines the features of both the “Drop In” and “Customizable” packages that we offered in previous releases. You can download this one package and deploy the contents of the “prebuilt” directory to your server, and you’re all ready to go! If you need to go beyond that, you can make sure you have Python installed and customize away.

The second thing we’ve simplified was the signature of “command” functions. A “command” in Bespin is basically any action you take in the editor or the command line. In versions prior to 0.9, commands took an “env” argument as the first parameter. With 0.9 onward, you should no longer include that parameter and instead just grab the “env” variable from the “environment” module.  There are more details of this change in the Bespin 0.9 Release Notes. A new tutorial on making commands is coming today or tomorrow.

Version Numbering

To date, every release of Bespin has been an alpha release. With 0.9 (codenamed “Edison”), we’re switching to the kind of release cycles used by stable and mature projects. We’ll start with a series of alpha releases that are not yet feature complete. Then we’ll move to beta test releases to work out any kinks before having a final release. 0.9a1 is no more or less “alpha” than 0.8 was, but the version number reflects that we’re heading toward a stable state.

Download Bespin Now

Download Bespin Embedded 0.9a1. Take a look at the full 0.9 Release Notes for more information about what’s new.

Stay tuned for more interesting developments in Bespin this week.

– Kevin Dangoor, on behalf of the Bespin team

A Quick Demo

There’s a bit more information in the blog post below, but there’s more action in the video. Check it out:

Less

There are three features that make Bespin 0.8 “less” than 0.7.

First, Bespin Embedded 0.8 minified is now less than half the size of the 0.7.3 release. The “Drop In” release is now just under 300K minified. If you are already using jQuery on your page, you can build a custom Bespin that is about 225K minified and only 65K after gzipping. Without a doubt, there is more we can do to shrink Bespin further, but we’re quite happy with its new, slimmer size. One more bonus with respect to Bespin’s size: Bespin 0.8 makes it possible to dynamically load plugins in Embedded builds. That way, the initially loaded Bespin script can contain just the parts needed to get Bespin going, and extra features can be loaded in as the user wants them.

Second, Bespin 0.8 includes a new theme capability that allows you to radically change the appearance through a simple plugin. Bespin’s themes go beyond just CSS, because we wanted theme creators to be able to change the appearance of plugins they had never even heard of before. Bespin 0.8 uses the new LESS.js package to allow UI components to use global theme variables so that they can change appearance as the theme dictates. You can see this by switching your Bespin to use the new “white” theme. LESS also provides a very convenient syntax that ensures that Bespin plugins won’t leak the CSS rules onto the page.

Speaking of leaking onto the page, Bespin 0.8 exposes only the variable “bespin” to your page. And there is no more manipulation of built-in object prototypes.

More

In addition to being less than Bespin 0.7.3, Bespin 0.8 also does more. One of our most requested features has been fulfilled: you can now embed Bespin’s spiffy command line in custom Embedded builds. And it’s easier to do than you’d expect. Just add the “command_line” plugin to your manifest file, rebuild and you’ll see the command line there.

Bespin 0.8 with command line in white

We’re able to do this now because of a new “application configuration” mechanism that determines how certain objects that are global within a given Bespin editor are created and how components are added to the GUI. With this new mechanism, we have reached the point where the difference between Bespin Embedded and Bespin+Server is just a difference of configuration (and, of course, the server itself!)

Speaking of servers, our dryice build tool, which is responsible for creating embeddable Bespins, now includes a little server. Fire it up, and on each page load it will rebuild your Bespin. It’s the easiest way to try out different plugins and configurations.

One more oft-requested feature that has now landed in 0.8 is the ability to replace a <textarea> with Bespin. Earlier embedded releases could only put themselves in a container. Bespin is now able to replace a textarea and update the textarea when the form is submitted, making Bespin much more of a drop-in replacement for a textarea.

We’ve added CSS syntax highlighting, and all of our highlighters now run in Web Workers. By running the highlighters in workers, we get better performance and open the door to add interesting new features in future releases.

Among the minor tweaks and improvements made: you can indent/unindent blocks of text by selecting the block and hitting tab/shift-tab and a new CSS syntax highlighter, initially contributed by Cody Marquart.

For Plugin Authors

We’ve got a new, client-side template engine that makes it easy to generate your user interfaces.

If you’re writing editor commands, you now have access to the same convenient APIs that Embedded users had before. It’s simple to get the selected text, manipulate it and replace it.

We’ve added a Growl-like notification system to Bespin, making it easy for plugin authors to get the user’s attention and easy for the user to choose which kind of notifications they want to see.

Keep an eye on this blog in the coming days for new tutorials. If you create any plugins that you want to share with the Bespin community within the next few days, please email me so that you can be added to the initial Bespin Plugin Gallery.

Bespin Server News

During the past few weeks, we’ve figured out where we’re going with the Bespin Server. Given that I’ve written at length about this in other places, I’ll just give the short form here. If you’re interested in the full story, you can read about it here.

The short form is this: software developers work on all kinds of different projects. For Bespin to support “coding in the cloud” for that variety of projects, we need a server that’s as customizable as our editor is. So, we’re going to rewrite the server in JavaScript and leverage the same plugin system we use on the client. We’re going to couple that with ways to get that server running easily, so that everyone can run their own Bespin server.

bespin.mozillalabs.com has never been a “production-level” service. In the future, it will be used to demonstrate Bespin features, but will be even less production-level than it is today. We’ve added the “export” command so that you can get your projects off of the bespin.mozillalabs.com server, if you have any data there that you care about.

As a stepping stone to the new server, we’re planning to package up Bespin for use as a desktop editor. We think that Bespin is a fun and productive editor to use, and it makes a great environment for editing Bespin plugins. The desktop version of Bespin will also be our proving grounds for the JavaScript port of our dryice build tool.

Bespin 0.8 does add a much-requested server-related feature: working directories. The combination of using “cd” to get to a specific spot in the filesystem and “open” with its awesome file searching abilities is a really productive way to navigate between files.

Getting Involved

Our version numbers have been creeping upwards and 0.8 is not a lot of distance from 1.0. Quite a bit has stabilized on the client side now. The easiest way to get involved with Bespin right now is to create plugins. Syntax highlighters, themes, commands and keymappings are all straightforward to create.

Bespin is now ready to add more user interface components. Things like a file browser and a toolbar would be great. A notification configuration GUI (like the Growl preferences pane) or a settings UI would be cool. A menu system for commands would be neat as well, and help new users.

And, of course, there’s more to be done in the core editor. Things like TextMate-style snippets (which are fantastic!) and rectangular selection are good bets if you’re looking for a bit of a challenge. And we’re always looking to improve the performance, so profiling and optimization help is ever welcome.

The desktop and server tooling is just about to get started. We’d love your help on those projects! This will certainly be the area with the most churn, so you only want to dive in here if you’re feeling adventurous.

Release Notes and Download

You can download Bespin Embedded releases from http://ftp.mozilla.org/pub/mozilla.org/labs/bespin/Embedded/

The complete Bespin 0.8 release notes are available as part of the official documentation.

Enjoy the new release!

– Kevin Dangoor, on behalf of the Bespin project team

From a day-to-day usability perspective, my favorite new feature in Bespin 0.7.3 is the new file completion for the “open” command (which, incidentally, is now available via cmd-O/ctrl-O). Take a look at the screen shot below:

After typing “open pldev/com”, you can see that Bespin found two files that match: commands.js in the “plugindev” directory and commands.js in the “bespin_server” directory. Those two match because those letters that I typed can be found in that order in both names. The one in plugindev (which is the one I was looking for) was a better match, so it appears at the top. You can see that in faint letters Bespin is showing the full path for the top hit. This is what I get if I hit <tab>. Also convenient is that I can press <alt-2> to select the second match in the list from the keyboard. I could also click on one of the choices with the mouse. Joe put in a good deal of work to make this slick and usable, and I expect we’ll be adding a lot more useful completions to the command line over time.

With this release, we’ve knocked off 3 of the items requested via our feedback forum (thanks for submitting and voting on the items there!). The preview command is back, you can now log in using your email address (assuming you only have 1 account associated with that address). The “I forgot my password” feature also returns in this release. Thanks to Julian and Patrick for a bunch of fixes in 0.7.3.

Plugins

Plugin development has also gotten easier, with the addition of the “ep” and “plugin info” commands. These commands provide you with a bunch of information about what’s available in Bespin.

On the topic of plugins, the first plugin has landed in the plugin gallery! It’s an experimental PHP syntax highlighter by Scott Teglasi. You can install it by running “plugin install php”. You can also download it from https://bespin.mozillalabs.com/plugin/download/php/current/. Thanks, Scott!

Add to this a bunch of bug fixes, and I think we’ve got a nice, but minor, update for you.  We’re planning for a meatier release for our next one (codenamed “Cheviot”).

Docs

The Bespin wiki was very out of date. I salvaged what I could, and moved more docs into our Mercurial repository. Those docs are visible at https://bespin.mozillalabs.com/docs/. A generic wiki is really a bad tool for software documentation, so we’ll be sticking with having the main docs in Mercurial for the time being.

Embedded

Bespin 0.7.3 has goodies for Bespin Embedded users as well. In addition to the general fixes made, there are now a bunch of new methods available on the bespin object for working with the text that the user is editing. These are documented in the Embedders’ Guide.

Pick up the latest Bespin Embedded release in its usual home: http://ftp.mozilla.org/pub/mozilla.org/labs/bespin/Embedded/

Thanks for all of the feedback and activity! Between now and the “Cheviot” release of Bespin, keep an eye on this space for some new tutorials.

(This article has been changed to reflect the codename of “Cheviot” for the next release of Bespin.)

– Kevin Dangoor, on behalf of the Bespin team