Aloha Editor

These guides help you to make your content editable and to develop Aloha Editor.

Aloha Editor Dependencies

1 requirejs

Aloha uses requirejs to load modules at runtime. Please see the RequireJS guide for additional information about requirejs and how paths are resolved.

It is necessary 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.

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

2.1 Custom jQuery and jQuery UI

Requirejs exports the two functions require() and define() into the global namespace. If you define a module yourself using the global define(), requirejs will use that instead of loading it from its default location:


define('jquery', [], function () { return window.jQuery; });

jQuery 1.7 actually already does the above, but only if it detects a compatible module loader like requirejs. The following is from jquery-1.7.2.js


if ( typeof define === "function" && define.amd && define.amd.jQuery ) {
    define( "jquery", [], function () { return jQuery; } );
}

That’s why if you do the following, aloha should just work:


<!-- exports require() and define() into the global namespace -->
<script src="aloha/src/lib/require.js"></script>
<!-- define('jquery'...); --> 
<script src="aloha/src/lib/vendor/jquery-1.7.2.js"></script>
<!-- Uses the jquery defined above -->
<script src="aloha/src/lib/aloha.js"></script>

Note: if you include jQuery twice (once for your own project, and once for aloha), the ‘jquery’ module will be defined twice and aloha will use one of those two – I don’t know exactly which.

In addition to the define() mechanism above, it’s also possible to explicitly tell aloha to use the jQuery that you pass to it. This way you could load two different jQuery versions in the page and make sure aloha uses the right one.


<!-- the jQuery used by your project -->
<script src="your-project/jquery-1.7.js"></script>
<!-- the jQuery used by aloha -->
<script src="aloha/src/lib/vendor/jquery-1.7.2.js"></script>
<script>
Aloha = window.Aloha || {};
Aloha.settings = Aloha.settings || {};
// Restore the global $ and jQuery variables of your project's jQuery
Aloha.settings.jQuery = window.jQuery.noConflict(true);
</script>
<script src="aloha/src/lib/require.js"></script>
<script src="aloha/src/lib/aloha.js"></script>

The above should always work for any project without causing any problems.

But, the above would cause two versions of jQuery and two versions of jQuery UI to be loaded (a second jQuery UI would be loaded asynchronously by aloha). For optimal performance your only want to load one of each.

Loading a single jQuery should be possible if the project that Aloha is part of uses a 1.7.x version of jQuery.

Loading a single jQuery UI is more problematic because aloha uses a not yet stable version of jQuery UI. The jQuery UI used by aloha is located in src/lib/vendor/jquery-ui-1.9m6.js.

If the project Aloha is part of also uses jQuery UI, then we have an additionaly problem: when loading just a single jQuery, but two different versions of jQuery UI, either aloha or your project will end up with the wrong version of jQuery UI, because both instances of jQuery UI modify a single jQuery instance.

We currently don’t have a workaround for this problem. The following example attempts to use jQuery.sub() to create a copy of jQuery so that two different jQuery UI versions can be used, but it doesn’t work – on Chrome I get the error “Uncaught TypeError: Object # has no method ‘easeOutExpo’”.


<!-- the jQuery used by your project -->
<script src="your-project/jquery-1.7.js"></script>
<script>
Aloha = window.Aloha || {};
Aloha.settings = Aloha.settings || {};
Aloha.settings.jQuery = window.jQuery.sub();
</script>
<script src="aloha/src/lib/require.js"></script>
<script src="aloha/src/lib/aloha.js"></script>

Note: you will need to access Aloha’s jQuery when you want to call aloha():


Aloha.ready(function(){
    Aloha.jQuery('#editable').aloha();
});

Note: 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.

Note: the jQuery object that is given to Aloha will be extended by Aloha.

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