: Using Aloha Editor

Using Aloha Editor

1 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:


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

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

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


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

3 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


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

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.

4 requirejs

Aloha uses requirejs to load modules at runtime.

It is necessary, for development and when using aloha-bare.js, to include requirejs before Aloha. It is not necessary to include requirejs when using aloha-full.js, as that already includes requirejs (as well as jQuery).

It is possible to build a custom version of Aloha that does not need requirejs, although that has not been tested at the time of this writing and requires a customized build profile. See Customized builds for more information.

5 Custom jQuery, jQueryUI and other modules

Aloha requires many third party modules. If these modules are not combined during building, they will be loaded at runtime by requirejs. Two of the most prominent modules are jQuery and jQueryUI.

5.1 Custom jQuery

The simplest way to make Aloha use a jQuery that you give it, and to prevent Aloha from loading its own jQuery, is by doing either of the following


<script src="aloha/lib/require.js"></script>
<script>Aloha = {}; Aloha.settings = {}; Aloha.settings.jQuery = window.jQuery;</script>
<script src="aloha/lib/aloha.js" data-aloha-plugins="..."></script>

In the above example Aloha will prefer Aloha.settings.jQuery over loading its own jquery via requirejs.


<script src="aloha/lib/require.js"></script>
<script src="aloha/lib/vendor/jquery-1.7.2.js"></script>
<script src="aloha/lib/aloha.js" data-aloha-plugins="..."></script>

In the above example, first jQuery is included, which will call the global define() function exposed by requirejs to define the ‘jquery’ module, and afterwards Aloha is included, which will pick up the ‘jquery’ module that was previously defined.

The jQuery that is given to Aloha should be the same version as the one Aloha would load itself, which should be the most recent version of jQuery. Older versions may work, but since older versions are not tested against, please expect for things to break.

Please also note that the given jQuery will be extended by jQuery plugins.

5.2 Customizing other modules

There are other ways to customize the module loading for modules beside jQuery.

Use requirejs directly (preferred)


define('jquery', function(){ return window.jQuery; })
define('jqueryui', function(){ return window.jQuery.ui; })

Use Aloha.settings.predefinedModules – does a define() call as above, except it also works if requirejs is bundled as part of Aloha (aloha-full.js). Using requirejs defines like above is preferred.

  
Aloha.settings.predefinedModules = {'jquery': window.jQuery, 'jqueryui': window.jQuery.ui};

Customize the requirejs path configuration – this will only work if jQuery was not already defined via a call to define() as above. Using requirejs defines like above is preferred.


  Aloha.settings.requireConfig.paths = {'jquery': 'path/to/jquery.js', 'jqueryui': 'path/to/jqueryui.js'};

Customize the r.js path configuration – the r.js build profiles also contain path configuration, like Aloha.settings.requireConfig.paths above, that can be adapted. This is different from the other methods in that this controls how Aloha will be combined, whereas the other methods control runtime module loading. See Customized builds for more information.

Please note that if a ‘jqueryui’ module is given this way, a ‘jquery’ module must also be given this way, and the given ‘jqueryui’ module must extend the given ‘jquery’ module. The same rule holds for any other jQuery plugins.

Also note that if a jQuery instance is given with Aloha.setings.predefinedModules or Aloha.settings.jQuery, it will be extended (jquery plugins will be registered on it).

Care must be taken with both settings. Passing in a version of a module that differs from what Aloha expects may result in unpredictable behaviour.

Also, the third part libraries that come with Aloha may have been patched to fix bugs or address Aloha specific issues. See the git log for each third party library for further information before redefining it.

For this reason, if you experiencing problems when using custom versions of some modules, please go back to using the modules packaged with Aloha before making a bugreport.