h2. Aloha commands

After reading this guide, you will be able to:

* Understand Aloha command API
* Use selection and ranges together with commands.

endprologue.


h3. Command API


The Aloha command API implements the HTML5 contenteditable API. The core API consists of:

<shell>
Aloha.execCommand( commandId, showUI, value )
Aloha.queryCommandIndeterm( commandId )
Aloha.queryCommandState( commandId )
Aloha.queryCommandEnabled( commandId )
Aloha.queryCommandSupported( commandId )
Aloha.queryCommandValue( commandId )
</shell>


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

<shell>
Aloha.exeCommand( 'bold', false, '' );
</shell>

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

<shell>
var indeterm = Aloha.queryCommandIndeterm( 'bold' );
</shell>

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

<shell>
var state = Aloha.queryCommandState( 'bold' );
</shell>

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

<shell>
var value = Aloha.queryCommandValue( 'link' );
</shell>

h3. Simple examples

This simple example shows how you could implement a bold button. 

<shell> 
<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>
</shell>


h3. 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":http://dvcs.w3.org/hg/editing/raw-file/tip/editing.html#selection. Most of the interaction
are done with ranges. The Aloha range object is a "W3C compliant range object":http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#ranges.

WARNING: 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.
<shell>
var range;
if ( Aloha.getSelection().rangeCount > 0 ) {
	range = Aloha.getSelection().getRangeAt( 0 );
}
</shell>

You may want to select the content in the curly bracets and then apply a command on the selection.

<shell>
<h1>Hello there</h1>
<p>{Some content to <i>select}</i> with Aloha selection.</p>
</shell>
 
If you want to set the selection to a specified range you should first clear all ranges and
then add the range. 

<shell>
<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>
</shell>

h3. Changelog

* October 7, 2011: Initial version by "Haymo Meran":credits.html#haymo
