Aloha commands
After reading this guide, you will be able to:
- Understand Aloha command API
- Use selection and ranges together with commands.
1 Command API
The Aloha command API implements the HTML5 contenteditable API. The core API consists of:
Aloha.execCommand( commandId, showUI, value ) Aloha.queryCommandIndeterm( commandId ) Aloha.queryCommandState( commandId ) Aloha.queryCommandEnabled( commandId ) Aloha.queryCommandSupported( commandId ) Aloha.queryCommandValue( commandId )
1.1 execCommand
Every command defined in CommandManager specification has an action defined for it in the relevant section. For example, the bold command’s action generally makes the current selection bold, or removes bold if the selection is already bold. An editing toolbar might provide buttons that execute the action for a command if clicked, or a script might run an action without user interaction to achieve some particular effect.
Aloha.exeCommand( 'bold', false, '' );
1.2 queryIndeterm
A boolean value returned by queryCommandIndeterm(), depending on the current state of the document. Generally, a command that has a state defined will be indeterminate if the state is true for part but not all of the current selection, and a command that has a value defined will be indeterminate if different parts of the selection have different values. An editing toolbar might display a button or control in a special way if the command is indeterminate, like showing a “bold” button as partially depressed, or leaving a font size selector blank instead of showing the font size of the current selection. As a rule, a command can only be indeterminate if its state is false, supposing it has a state.
var indeterm = Aloha.queryCommandIndeterm( 'bold' );
1.3 queryCommandState
A boolean value returned by queryCommandState(), depending on the current state of the document. The state of a command is true if it is already in effect, in some sense specific to the command. Most commands that have a state defined will take opposite actions depending on whether the state is true or false, such as making the selection bold if the state is false and removing bold if the state is true. Others will just have no effect if the state is true, like the justifyCenter command. Still others will have the same effect regardless, like the styleWithCss command. An editing toolbar might display a button or control differently depending on the state and indeterminacy of the command.
var state = Aloha.queryCommandState( 'bold' );
1.4 queryCommandValue
A string returned by queryCommandValue(), depending on the current state of the document. A command usually has a value instead of a state if the property it modifies can take more than two different values, like the foreColor command. If the command is indeterminate, its value is generally based on the start of the selection. Otherwise, in most cases the value holds true for the entire selection, but see the justifyCenter command and its three companions for an exception. An editing toolbar might display the value of a command as selected in a drop-down or filled in in a text box, if the command isn’t indeterminate.
var value = Aloha.queryCommandValue( 'link' );
2 Simple examples
This simple example shows how you could implement a bold button.
<html>
<head>
<link rel="stylesheet" href="http://aloha-editor.org/builds/development/latest/src/css/aloha.css" type="text/css">
<script src="http://aloha-editor.org/builds/development/latest/src/lib/aloha.js"></script>
</head>
<body>
<button id="bold">Bold</button>
<div class="edit">This is some content</div>
<script>
// Bind to Aloha Ready Event
Aloha.ready( function() {
var $ = jQuery = Aloha.jQuery;
$('.edit').aloha();
var button = jQuery('#bold');
button.attr( 'disabled',
( Aloha.queryCommandSupported( 'bold' ) &&
Aloha.queryCommandEnabled( 'bold' ) )
);
button.click( function() {
Aloha.execCommand( 'bold', false, '' );
updateBoldColor();
});
Aloha.bind('aloha-selection-changed', function() {
updateBoldColor();
});
function updateBoldColor() {
if ( Aloha.queryCommandIndeterm( 'bold' ) ) {
button.css( 'background-color', 'yellow' );
return;
}
button.css( 'background-color',
Aloha.queryCommandState( 'bold' ) ? 'lightgreen' : 'orange'
);
}
// update the color on startup
updateBoldColor();
});
</script>
</body>
</html>
3 Selection
The Aloha selection is a standard API which gives you cross browser normalized range to use with commands. The selection implements the W3C Selection interface. Most of the interaction are done with ranges. The Aloha range object is a W3C compliant range object.
Some browsers such as webkit based browser do not support more than on range yet.
You can get the currently selected range with following method.
var range;
if ( Aloha.getSelection().rangeCount > 0 ) {
range = Aloha.getSelection().getRangeAt( 0 );
}
You may want to select the content in the curly bracets and then apply a command on the selection.
<h1>Hello there</h1>
<p>{Some content to <i>select}</i> with Aloha selection.</p>
If you want to set the selection to a specified range you should first clear all ranges and then add the range.
<html>
<head>
<link rel="stylesheet" href="http://aloha-editor.org/builds/development/latest/aloha/css/aloha.css" type="text/css">
<script src="http://aloha-editor.org/builds/development/latest/aloha/lib/aloha.js"></script>
</head>
<body>
<div class="edit">
<h1>Hello there</h1>
<p>{Some content to <i>select}</i> with Aloha selection.</p>
</div>
<script>
// Bind to Aloha Ready Event
Aloha.ready( function() {
var
range = Aloha.createRange(),
begin = jQuery( 'p' ),
end = jQuery( 'i' );
// setStart and setEnd take dom node and the offset as parameters
range.setStart( begin.get(0), 0);
range.setEnd( end.get(0), 1);
// add the range to the selection
Aloha.getSelection().removeAllRanges();
Aloha.getSelection().addRange( range );
Aloha.execCommand( 'bold', false, '' );
}
</script>
</body>
</html>
4 Changelog
- October 7, 2011: Initial version by Haymo Meran
Chapters