h2. Aloha Editor Dependencies
endprologue.
h3. requirejs
Aloha uses "requirejs":http://requirejs.org/ to load modules at runtime.
Please see the "RequireJS":require.html 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":develop_aloha.html
for more information.
h3. Custom jQuery, jQueryUI and other modules
NOTE: 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.
h4. 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:
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 versions of jQuery in the page and make sure
aloha uses the right one.
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.
NOTE: at the time of this writing, aloha doesn't yet support jquery-1.8.x.
h4. 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 #