OpenAjax Hub Specification v04 Globals
From MemberWiki
(The most current version of the OpenAjax Hub Specification is at http://www.openajax.org/member/wiki/OpenAjax_Hub_Specification.
(This wiki page holds a portion of the version 0.4 internal editorial draft for the OpenAjax Hub 1.0 Specification. The home wiki page for the version 0.4 draft specification is at http://www.openajax.org/member/wiki/OpenAjax_Hub_Specification_04. Version 0.4 is preserved for historical reasons and is very much out of date. A key point about version 0.4 is that it was the most recent version of the Hub spec before the March 2007 InteropFest.))
Contents |
Globals Management
Globals Management Features
The OpenAjax Hub provides the following APIs for managing the global objects that are added to the JavaScript runtime environment by Ajax libraries.
- OpenAjax.registerGlobals()
- OpenAjax.checkForCollisions()
Conformance Requirements
OpenAjax Conformance Requirement (Libraries): OpenAjax Registry
To be OpenAjax Conformant, libraries MUST register a reserved unique prefix for the given library and all objects and properties the library adds to the JavaScript runtime environment with the OpenAjax Registry (documented at the OpenAjax Alliance Web site: http://www.openajax.org).
OpenAjax Conformance Requirement (Libraries): Globals Uniqueness
To be OpenAjax Conformant, libraries MUST not use any global objects or properties that have been reserved for use by the Web browser or which the OpenAjax Registry reserves for other libraries.
OpenAjax Conformance Requirement (Libraries): Globals Registration
To be OpenAjax Conformant, libraries MUST register all objects and properties they add to the JavaScript runtime environment via OpenAjax.registerGlobals() at the time when the <script> tag(s) that includes the given library is processed (i.e., when the JavaScript files are fetched and then parsed by the browser's JavaScript's engine).
OpenAjax Conformance Requirement (Libraries): Read-only OpenAjax.globals
To be OpenAjax Conformant, libraries MUST treat OpenAjax.globals as a read-only public variable.
APIs
OpenAjax.registerGlobals(prefix, globals)
Identifies the global objects that the given Ajax library is adding to the JavaScript runtime environment.
This function must be called exactly once. The function raises an error if invoked a subsequent time for a given library. FIXME: Does it really make sense to only allow registerGlobals() to be called only once? Is this consistent with the rest of the APIs?
Parameters
- prefix
- The prefix that corresponds to this library. This is the same value that was previously passed to registerLibrary().
- globals
- An array of strings that identify the globals added to the JavaScript runtime environment by this library. Each global object is expressed in JavaScript dot notation relative to the 'window' object. Thus, the OpenAjax Hub registers the "OpenAjax" object. If the OpenAjax Hub also added a "squeak()" method to the Object prototype, then it would register the following globals:
["OpenAjax", "Object.prototype.squeak"]
Return value
None.
Module
This method is part of the core. (Note: For a discussion of the Hub's modules, see http://www.openajax.org/member/wiki/OpenAjax_Hub_Specification_v04_Bootstrapping_Modularization_Inclusion.)
OpenAjax.checkForCollisions(candidate_globals[, prefix)
Determines whether the list of global objects in array 'candidate_globals' collides with any of the global objects that have been listed by currently registered Ajax libraries.
Parameters
- candidate_globals
- An array of strings that identify the globals that we want to check against the globals registered by previously registered Ajax libraries.
- prefix
- Optional parameter. If provided, then this routine will not compare 'globals' against the list of globals registered by library 'prefix'. In other words, compare against all libraries except for library 'prefix'.
Return value
Returns an array that lists all collisions that were found. Each item in the array is an object that has two properties:
- global: a string that indicates the global variable with which there was a collision
- registeredByPrefix: a string that indicates the prefix of the library that has previously registered the given global variable
If there are no collisions, an empty array will be return ed(i.e., an array of length zero). Note that a given global variable will appear in the return array multiple times if the given global has been registered multiple times.
Module
This method is part of the "Collision" module. (Note: For a discussion of the Hub's modules, see http://www.openajax.org/member/wiki/OpenAjax_Hub_Specification_v04_Bootstrapping_Modularization_Inclusion.)
Public variables
OpenAjax.globals
This variable holds the list of global variables that have registered themselves with the OpenAjax Hub. OpenAjax-conformant libraries must treat this as a read-only variable.
OpenAjax.globals is a JavaScript associative array, where OpenAjax.globals contains a <prefix> property for each library that has registered itself via OpenAjax.registerGlobals(). For example, if the FooLib library has prefix foo and has registered its globals itself via OpenAjax.registerGlobals(), then there will be a OpenAjax.globals.foo property. The value of the OpenAjax.globals.foo property must be the same array of strings value that was passed as a parameter to OpenAjax.registerGlobals().
Module
This method is part of the core. (Note: For a discussion of the Hub's modules, see http://www.openajax.org/member/wiki/OpenAjax_Hub_Specification_v04_Bootstrapping_Modularization_Inclusion.)
