Getting Started

To replace ContentEditable with Aloha Editor is as simple as 1 line of markup and 1 line of JavaScript:

aloha() transforms the element given to it into a rich-text editing canvas.

Deactivate editing by invoking aloha.mahalo() on the same element that was given to aloha().

You can initialize multiple editables at once with this line of code:

Once an editable is initialized you will see that Aloha Editor uses a blinking DIV element as the caret. This caret is the minimal visual user interface (which you can style and animate with CSS, by the way).

Sooner or later you'll need more for UI than just a caret, so the next section shows you how to add a simple bold button to your UI.

These instructions will show you how to add a button that, when clicked, will format the selected content in an editable to bold.

Begin by putting the following markup somewhere in the body your document:

The next step is to bind the bold command to this element.

NB: We will use the jQuery API for these code snippets because it's terse and familiar to most. This is not a requirement for Aloha Editor, however; you are free to pick your own poison.

The two notable components of the code above are aloha.ui.command() and aloha.ui.commands.bold.

aloha.ui.command is a function that generates an event handler, and uses a map of properties—defined through aloha.ui.commands.bold—to determine what that event handler should do when the button is clicked. In this case, any content that is selected inside of an editable when this button is clicked will be formatted bold.

There are a number of other formatting commands that come as defaults with Aloha Editor. You've just seen the aloha.ui.commands.bold command in action, but there are a few more. The next section explains a convenient way to bind multiple buttons.

aloha.ui.commands contains a set of editing commands that can be bound to elements in order to be executed from event handlers, which aloha.ui.commands.bold is one of.

These commands are just objects with properties that help to define a formatting operation. For example, this is what the the bold command looks like:

Now let's bind 4 of these commands to buttons at once. First the HTML...

... then some JavaScript...

... and done.

But what if we want the underline button to be able to effect one editable and not the other? We can do this with a little more code. We will need to pass 2 arguments into aloha.ui.command instead of 1.

First let's add some suffixes to our button classnames. We add 1 to demark buttons that should effect editable 1 and 2 to demark buttons that should effect editable editable 2.

Bare in mind that aloha.ui.command can also take an array of editables as its first argument to bind a single button to more than just one editables.

As well as formatting the selection inside of an editable, you will want your buttons to also reflect the formatting at the selection inside of an editable.

You can achieve this by adding a function (called "middleware") at the end of aloha.editor.stack array of functions.

All such middleware functions receive an event object that is threaded through aloha.editor.stack everytime there is an editing interaction.

You are not restricted to the default commands found in aloha.ui.commands. You can also use your own custom commands.

You do this by specifying your own command object that contains an action function, and any other properties you want. When the event to which this command is bound is fired, this command's action function will be called, and will receive an array of boundaries that represent the current boundary selection, the selection context object, and the the command itself. The last parameter is the event which trigger the command to be executed.