OpenAjax Hub Specification Bootstrapping, Modularization and Inclusion
From MemberWiki
(This wiki page holds a portion of the latest internal editorial draft for the OpenAjax Hub 1.0 Specification. The home wiki page for the specification is at /member/wiki/OpenAjax_Hub_Specification.)
Contents |
Bootstrapping, Modularization and Inclusion
Loading Requirements on the OpenAjax Hub
There are common Ajax application scenarios where a given Ajax application loads multiple Ajax libraries. In these scenarios, it is possible that the underlying JavaScript logic might attempt to load multiple instances of the Hub.
Only one version of the Hub must be loaded
In all cases, once one version of the OpenAjax Hub has been loaded (even if just the bootstrapping JavaScript file), all other instances of the Hub must not load themselves. Thus, the version of the Hub that is loaded by the earliest <script> element must be the one used by all Ajax libraries within the application.
Here is an example that indicates how an implementation of the Hub might prevent itself from getting loaded on top of an existing implementation:
if (typeof window.OpenAjax == "undefined") {
OpenAjax = {
implementer: "http://openajaxallianc.sourceforge.net",
implVersion: "1.0",
specVersion: "1.1",
...etc...
}
Module mixing disallowed
Modules from one implementation must not be mixed with modules from another implementation. For example, suppose an application uses 2 Ajax libaries, foolib and barlib, and each includes an implementation of the Hub. It must not be possible for Hub modules included within barlib to be dynamically loaded if the Hub from foolib were loaded first. Here is an example that show how an implementation of the Hub's LoadUnload module might prevent its modules from being used in conjunction with a different Hub implementation:
/* Only execute the code in this file if OpenAjax object exists,
this module hasn't been loaded yet, and module comes from same implementation. */
if (typeof OpenAjax!='undefined' &&
typeof OpenAjax.addOnLoad=='undefined' &&
typeof OpenAjax._oahri!='undefined' && OpenAjax._oahri == oahri_0_2) {
...implementation of the LoadUnload module...
}
What if different libraries include different versions of the Hub?
As mentioned earlier, when a given Ajax application loads multiple Ajax libraries, it is possible that the underlying JavaScript logic might attempt to load multiple instances of the Hub. Furthermore, it is possible that the first library to load the Hub might use an earlier version of the Hub than libraries that are loaded later. To illustrate this scenario, suppose the application uses two Ajax libraries, foolib and barlib, with foolib loaded first, and that foolib includes OpenAjax Hub version 1.0 and barlib includes OpenAjax Hub version 1.1. Since the first instance of the Hub that is loaded prevents other instances from loading, the result is that barlib may not work properly because it requires version 1.1, whereas version 1.0 instead will have been loaded.
One way to address this situation is for the application developer to explicitly load an implementation of the OpenAjax Hub before either foolib or barlib are loaded by including a <script> element that loads the necessary version of the Hub before foolib is loaded. As a result, the lower-version implementation of the Hub within foolib will not load itself.
Modules
Implementations of the OpenAjax Hub must support the ability to use the Hub on a modular basis where a given application loads only those portions of the Hub that are needed by that application. Some features, such as OpenAjax.registerLibrary, are part of the core and must be available in all cases, but other features are available on a modular basis.
There are 4 modules in this version of the OpenAjax Hub specification:
- LoadUnload - corresponds to the features described in the Load/Unload Management chapter
- PublishSubscribe - corresponds to the features described in the Publish/Subscribe Event Management chapter
- MarkupScanner - corresponds to the features described in the Markup Scanner chapter
- Collision - contains the method
OpenAjax.checkForCollisions()that is described in the Globals Management chapter
Single-file versus multiple-file distribution of the Hub
The Hub can be distributed as a single JavaScript file that contains all of the Hub's functionality or as a collection of separate JavaScript files, usually one JavaScript file for each of the modules listed previously.
For an implementation to support distribution as multiple files, it must be implemented such that its features can be loaded dynamically on an as-needed basis.
Dynamic loading of individual modules from a bootstrap file
Implementations of the Hub that support dynamic loading of individual modules on an as-needed basis must support OpenAjax.require() and the load= parameter on the <script> element as defined below.
APIs
OpenAjax.require(list_of_modules)
Provides a comma-separated list of OpenAjax Hub modules that are needed for subsequenet processing. If any of the modules have already been loaded, then the request is ignored and the previously loaded version of the module continues to be used. The modules must be loaded immediately (e.g., via immediate inclusion of a new <script> element) and in the order specified.
Parameters
- list_of_modules
- A comma-separate list of modules that are required. For example, "PublishSubscribe,LoadUnload". The list must not contain any whitespace.
Return value
None.
Modularization and Inclusion Configuration Options
There is one configuration option that relates to bootstrapping, modularization and configuration.
- OpenAjaxConfig.bootstrapFile
- Type
- Strings
- Default value
- "OpenAjaxBootstrap.js"
- Description
- The file name (without its path) for the bootstrap file (for implementations of the Hub that are distributed as multiple separate JavaScript files)
(Note: This parameter is necessary in some implementation scenarios for the Hub implementation performing introspection of the DOM to determine the path to the directory containing the Hub's various JavaScript files.)
