Aloha Editor

Aloha Editor Guides

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

Guides Index ▸

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

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.

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

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>
<!-- defines the 'jquery' module -->
<script src="aloha/src/lib/vendor/jquery-1.7.2.js"></script>
<!-- uses the 'jquery' module defined above -->
<script src="aloha/src/lib/aloha.js"></script>

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 versions of jQuery 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>

When using multiple jQuery instances in the host page, you must use Aloha’s jQuery when you want to call aloha():

// Aloha.ready() is only necessary if jQuery was loaded asynchronously
// instead of being passed directly to Aloha as explained above.
Aloha.ready(function(){
    Aloha.jQuery('#editable').aloha();
});

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

If the host page already includes a version of jQuery, you can try to pass that to aloha instead of including an extra jQuery just for aloha. This may or may not work depending on the particular version of jQuery used by Aloha and the host page.

at the time of this writing, aloha doesn’t yet support jquery-1.8.×.

2.2 Custom jQuery UI

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 host page 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’”. Any help with getting this working would be appreciated.

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

Aloha may work with older or newer versions of jQuery and jQuery UI, but since they are not tested against, please expect for things to break.

the jQuery object that is given to aloha will be extended (mutated) by multiple jQuery plugins that are part of aloha. If the host page also contains jQuery plugins, they may overlap potentially causing errors.

2.3 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 party 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.