h2. Using Aloha Editor

endprologue.

h3. Prerequisites

For a start, let's assume that you have a simple web page, you want to make editable with Aloha Editor and you already have placed Aloha Editor on your web server.

This is your web page:

<html>
<head>
	<meta http-equiv="content-type" content="text/html; charset=utf-8">
	<title>Getting Started with Aloha Editor</title>
	<link rel="stylesheet" href="index.css" type="text/css">
</head>
<body>
	<div id="main">
		<div id="content"><p>Getting started with Aloha Editor!</p></div>
	</div>
</body>
</html>

Aloha Editor is located in the path +/javascripts+ of your web server.

h3. Embed Aloha Editor

To embed Aloha Editor, you just need to load a single css +/javascripts/aloha/css/aloha.css+ and a javascript file +/javascripts/aloha/lib/aloha.js+ into the *head* section of your page.

NOTE: Aloha Editor currently depends on requirejs. In the future, we
      would like to give the user the option to omit this dependency for
      production deployments.

NOTE: Aloha Editor may load additional dependencies asynchronously with
      requirejs. Please see "dependencies":dependencies.html if you want
      to control dependency loading, which is particularly relevant if
      you already have a version of jQuery in your page.

<html>
<head>
	<meta http-equiv="content-type" content="text/html; charset=utf-8">
	<title>Getting Started with Aloha Editor</title>
	<link rel="stylesheet" href="index.css" type="text/css">
	<!-- Load Aloha Editor css and js -->
	<link rel="stylesheet" href="/javascripts/aloha/css/aloha.css" type="text/css">
	<script src="/javascripts/aloha/lib/require.js"></script>
	<script src="/javascripts/aloha/lib/aloha.js"
	  data-aloha-plugins="common/ui,common/format,common/highlighteditables,common/link"></script>
</head>
<body>
	<div id="main">
		<div id="content"><p>Getting started with Aloha Editor!</p></div>
	</div>
</body>
</html>

See also: https://github.com/alohaeditor/Aloha-Editor/issues/707

h3. Create editables

An editable is an HTML element that should be editable by Aloha Editor. You can specify the element with a jQuery selector, and simply call +.aloha+ for it.

When we want to make the div with ID *content* editable, we add the script

WARNING: The class 'aloha', and any other classes that begin with
         'aloha-' are used by aloha for internal purposes and you should
         therefore avoid using them in your application.

<html>
<head>
	<meta http-equiv="content-type" content="text/html; charset=utf-8">
	<title>Getting Started with Aloha Editor</title>
	<link rel="stylesheet" href="index.css" type="text/css">
	<!-- Load Aloha Editor css and js -->
	<link rel="stylesheet" href="/javascripts/aloha/css/aloha.css" type="text/css">
	<script src="/javascripts/aloha/lib/require.js"></script>
	<script src="/javascripts/aloha/lib/aloha.js"
	  data-aloha-plugins="common/ui,common/format,common/highlighteditables,common/link"></script>
</head>
<body>
	<div id="main">
		<div id="content"><p>Getting started with Aloha Editor!</p></div>
	</div>
	<script type="text/javascript">
		Aloha.ready( function() {
			Aloha.jQuery('#content').aloha();
		});
	</script>
</body>
</html>

NOTE: In this example, the HTML element is made editable in the event handler of the +Aloha.ready+ event. This ensures that aloha is fully loaded, before actually using it and is therefore the recommended way of using Aloha Editor.

The follwing reverts an editable to its non-editable form

<javascript>
    $('#editable').mahalo();
</javascript>

This should also remove the attributes added by aloha (classes, contenteditable=true, etc.).

h3. Supported elements

Aloha can be used with the following HTML text elements:

NOTE: When using calling .aloha() on a textarea, if the textarea has a HTML ID (eg. mytxtarea) the ID of the Aloha editable will be "-aloha" suffixed (eg. mytxtarea-aloha).

<javascript>
	[ 'a', 'abbr', 'address', 'article', 'aside',
	'b', 'bdo', 'blockquote',  'cite', 'code', 'command',
	'del', 'details', 'dfn', 'div', 'dl', 'em', 'footer',
	'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'header', 'i',
	'ins', 'menu', 'nav', 'p', 'pre', 'q', 'ruby',
	'section', 'small', 'span', 'strong', 'sub', 'sup',
	'textarea', 'var' ]
</javascript>

Not supported HTML elements:

<javascript>
	[ 'canvas', 'audio', 'br', 'embed', 'fieldset', 'hgroup', 'hr',
	'iframe', 'img', 'input', 'map', 'script', 'select', 'style',
	'svg', 'table', 'ul', 'video', 'ol', 'form', 'noscript' ]
</javascript>

