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).
TODO: at the time of this writing it is not clear what aloha.js is going to be in the distributable package – is it aloha-bare.js or aloha-full.js?
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.
There are severaly ways to customize the module loading in Aloha.
- Use requirejs (preferred) define(‘jquery’, function(){ return window.jQuery; }) define(‘jqueryui’, function(){ return window.jQuery.ui; })
- Use Aloha settings Aloha.settings.predefinedModules = {’jquery’: window.jQuery, ‘jqueryui’: window.jQuery.ui}; which just does a define() call as above, except it also works if requirejs is bundled as part of Aloha (aloha-full.js). Calling define yourself is always preferred if possible.
- Customize the requirejs path configuration Aloha.settings.requireConfig.paths = {’jquery’: ‘path/to/jquery.js’, ‘jqueryui’: ‘path/to/jqueryui.js’}; This will only work if jQuery was not already defined via a call to define() as above. Loading the modules and calling define yourself is always preferred if possible.
- Customize the r.js path configuration during building r.js build profiles also contain path configuration, like above, that can be adapted. See Customized builds. This is different from the other methods in that this controls how Aloha will be combined, whereas the other methods control module loading during runtime.
Please note that if jqueryui 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 this way, 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.
6 Further reading
- Learn about Plugins