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:

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

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

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

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

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

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.

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

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

<javascript>
// 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();
});
</javascript>

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 #<Object> has no
method 'easeOutExpo'". Any help with getting this working would be
appreciated.

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

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

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

h4. Customizing other modules

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

* Use requirejs directly (preferred)
<javascript>
define('jquery'  , function(){ return window.jQuery; })
define('jqueryui', function(){ return window.jQuery.ui; })
</javascript>

* 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.
<javascript>  
Aloha.settings.predefinedModules = {
	'jquery': window.jQuery,
	'jqueryui': window.jQuery.ui
};
</javascript>

* 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.
<javascript>
Aloha.settings.requireConfig.paths = {
	'jquery': 'path/to/jquery.js',
	'jqueryui': 'path/to/jqueryui.js'
};
</javascript>

* Customize the "r.js":https://github.com/jrburke/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":develop_aloha.html 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.
