OpenAjax Hub Specification MarkupScanner
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.)
Markup Scanner
The OpenAjax Hub's Markup Scanner manages the process of dispatching particular elements within the document to particular Ajax runtime libraries in order to perform that library's DOM transformation on the subtree headed by that particular element.
An Ajax library or component registers callbacks that are invoked during the Markup Scanner's top-down analysis of the document's DOM. By default, the Markup Scanner begins its top-down (pre-order, depth-first) scan with the <body> element. If no scanner callback functions have been registered, the function which performs the markup scanning (e.g., OpenAjax.scanDocument() or OpenAjax.scanNode()) must return immediately and perform no processing.
Callback functions can provide return values that cause the markup scanner to stop scanning the current node or prevent scanning on the current node's child nodes. Configuration options allow the application developer to either disable markup scanning or restrict markup scanning to particular subtrees of the document.
Markup scanning begins on a particular element node, such as the <body> element. For this element, the Markup Scanner determines whether any libraries have registered:
- attribute value callbacks (via OpenAjax.registerAttrScanCB()) that match a specified attribute name and value,
- tagname callbacks (via OpenAjax.registerTagnameScanCB()) that match the elements tagname, or
- custom scanner callbacks (via OpenAjax.registerCustomScannerCB())
In each case, the Markup Scanner will invoke the registered callback function(s).
Callback functions
In all cases, the callback function must take a single parameter, the element node which is currently being processed by the Markup Scanner.
The return value from each callback can be null or an object. A null return value indicates that the Markup Scanner should continue with its scanning process. If not null, then the return value must be an object which might contain any of the following properties with boolean values:
- stopScanThisNode - true says do not pass this node to callbacks for other runtime libraries (presumably because all processing on this node has been completed)
- stopScanChildNodes - true says to cancel scanning on child nodes of this node (presumably because all processing on this subtree has been completed)
For example:
return { stopScanThisNode: true, stopScanChildNodes: true };
FIXME: Unclear what parameters are passed to the callback functions
Markup Scanner Features
The OpenAjax Hub provides the following APIs to allow libraries to register callback functions that the markup scanner will invoke as it scans the document's markup:
- OpenAjax.registerAttrScanCB()
- OpenAjax.unregisterAttrScanCB()
- OpenAjax.registerTagnameScanCB()
- OpenAjax.unregisterTagnameScanCB()
- OpenAjax.registerCustomScannerCB()
- OpenAjax.unregisterCustomScannerCB()
The following APIs are public, but usually are not invoked in typical usage patterns. Their primary value is within automated testing scenarios:
- OpenAjax.scanDocument()
- OpenAjax.scanNode()
Markup Scanner Configuration Options
Global object OpenAjaxConfig holds the configuration options that application developers can use to customize the runtime behavior of the Hub. The following sections describe the two configuration options that developers can use to control the markup scanning process.
- OpenAjaxConfig.idsToScan
- Type
- Array of strings
- Default value
- []
- Description
- Provides to the OpenAjax Hub a list of elements upon which to invoke the markup scanner. The string values hold the IDs for the element to scan. The elements will be scanned in array order. If idsToScan has any entries, it overrides OpenAjaxConfig.scanPage.
- OpenAjaxConfig.scanPage
- Type
- boolean
- Default value
- true
- Description
- Tells the OpenAjax Hub whether to auto-invoke its markup scanner on the <body> element in the document in order to trigger top/down traversal of the Web page. The markup scanner will dispatch particular elements to particular Ajax libraries based on registered pattern rules. Typically, the libraries register the pattern rules.
Conformance Requirements
OpenAjax Conformance Requirement (Libraries): Markup Scanning Through the Hub
To be OpenAjax Conformant, when the OpenAjax Hub is present within an application, a library SHOULD not perform its own top/down scan the document's markup and instead must achieve markup scanning indirectly through registering callbacks with the Hub's Markup Scanner.FIXME: Given the SHOULD, this probably isn't a Conformance Requirement any more but rather some sort of recommended best practice, but before changing, we need to look up the proper terminology.
APIs
OpenAjax.registerAttrScanCB(prefix, attrName, checkType, checkString, refOrName[, scope])
Registers a callback function that is invoked for element nodes in the document that have a particular attribute set to a particular value.
Parameters
- prefix
- The prefix that corresponds to this library. This is the same value that was previously passed to registerLibrary().
- attrName
- Parameter attrName must match the attribute's localName exactly. If parameter prefix is not null, then there must also be a match with the attribute's namespaceURI (if the browser supports XML namespaces per DOM Level 2) or with the attribute's prefix (if the browser does not support XML namespaces per DOM Level 2).
- checkType
- One of the following values:
- "match"
- The attribute's value must match parameter checkString exactly.
- "match-start"
- The attribute's value's first N characters must match parameter checkString exactly.
- "token"
- For attributes that support space-separated lists of values (i.e., tokens), one of the tokens within the attribute value must match parameter checkString exactly.
- "token-start"
- For attributes that support space-separated lists of values (i.e., tokens), the first N characters of one of the tokens must match parameter checkString exactly.
- checkString
- The string against which to test the attribute's value.
- refOrName
- A function object reference or the name of the callback function.
- scope
- Optional. An Object in which to execute refOrName at the time the callback function is invoked. If null,
windowobject is used.
Return value
None.
Module
This method is part of the "MarkupScanner" module. (Note: For a discussion of the Hub's modules, see /member/wiki/OpenAjax_Hub_Specification_Bootstrapping%2C_Modularization_and_Inclusion#Modules.)
OpenAjax.unregisterAttrScanCB(prefix)
Unregisters all attribute value scanner callback functions registered by the library associated with the given prefix.
Parameters
- prefix
- The prefix that corresponds to this library. This is the same value that was previously passed to registerLibrary().
FIXME: Must the implementation verify that the prefix corresponds to a library that has been registered? Probably not. Just extra code.
Return value
None.
Module
This method is part of the "MarkupScanner" module. (Note: For a discussion of the Hub's modules, see /member/wiki/OpenAjax_Hub_Specification_Bootstrapping%2C_Modularization_and_Inclusion#Modules.)
OpenAjax.registerTagnameScanCB(prefix, checkType, checkString, refOrName[, scope])
Registers a callback function that is invoked for element nodes in the document that have a particular tagName (with or without NS), namespace, or prefix.
Parameters
- prefix
- The prefix that corresponds to this library. This is the same value that was previously passed to registerLibrary().
- checkType
- One of the following values:
- "match"
- Must match localName exactly. If parameter prefix is not null, it must also match the element's namespaceURI (if the browser supports XML namespaces per DOM Level 2) or the prefix (if the browser does not support XML namespaces per DOM Level 2).
- "match-start"
- Must match first N chars of localName. If parameter prefix is not null, it must also match the element's namespaceURI (if the browser supports XML namespaces per DOM Level 2) or the prefix (if the browser does not support XML namespaces per DOM Level 2).
- "match-namespace"
- Must be in a given NS (requires that the browser supports XML namespaces per DOM Level 2).
- "match-prefix"
- Must have the given namespace prefix (applies to browsers that support XML namespaces per DOM Level 2 and browsers that do not)
- checkString
- The string against which to test the element's localName.
- refOrName
- A function object reference or the name of the callback function.
- scope
- Optional. An Object in which to execute refOrName at the time the callback function is invoked. If null,
windowobject is used.
Return value
None.
Module
This method is part of the "MarkupScanner" module. (Note: For a discussion of the Hub's modules, see /member/wiki/OpenAjax_Hub_Specification_Bootstrapping%2C_Modularization_and_Inclusion#Modules.)
OpenAjax.unregisterTagnameScanCB(prefix, checkType, checkString, refOrName[, scope])
Unregisters all tagname scanner callback functions registered by the library associated with the given prefix.
Parameters
- prefix
- The prefix that corresponds to this library. This is the same value that was previously passed to registerLibrary().
Return value
None.
Module
This method is part of the "MarkupScanner" module. (Note: For a discussion of the Hub's modules, see /member/wiki/OpenAjax_Hub_Specification_Bootstrapping%2C_Modularization_and_Inclusion#Modules.)
OpenAjax.registerCustomScannerCB(prefix, refOrName[, scope])
Registers a custom callback function to invoke for all element nodes in the document that the Markup Scanner encounters during the (top-to-bottom) document scanning process. This method is available for Ajax libraries whose scanning needs are not met by the tagname and attribute name scanner
Parameters
- prefix
- The prefix that corresponds to this library. This is the same value that was previously passed to registerLibrary().
- refOrName
- A function object reference or the name of the callback function.
- scope
- Optional. An Object in which to execute refOrName at the time the callback function is invoked. If null,
windowobject is used.
FIXME: The current implementation does not support late binding
Return value
None.
Module
This method is part of the "MarkupScanner" module. (Note: For a discussion of the Hub's modules, see /member/wiki/OpenAjax_Hub_Specification_Bootstrapping%2C_Modularization_and_Inclusion#Modules.)
OpenAjax.unregisterCustomScannerCB(prefix)
Unregisters all tagname scanner callback functions registered by the library associated with the given prefix.
Parameters
- prefix
- The prefix that corresponds to this library. This is the same value that was previously passed to registerLibrary().
Return value
None.
Module
This method is part of the "MarkupScanner" module. (Note: For a discussion of the Hub's modules, see /member/wiki/OpenAjax_Hub_Specification_Bootstrapping%2C_Modularization_and_Inclusion#Modules.)
OpenAjax.scanDocument()
NOTE: This function is public, but it usually is not invoked in typical usage patterns. Its primary value is within automated testing scenarios.
Determines whether any markup scanning callbacks have been registered. If not, no scanning is done. If a list of IDs has been provided via OpenAjaxConfig.idsToScan, scan all elements with the given IDs. Otherwise, if OpenAjaxConfig.scanPage is not false, start recursive scanning with the <body> element. Returns true if the document was scanned, false if not.
FIXME: Verify that the above description is accurate.
Parameters
None.
Return value
None.
Module
This method is part of the "MarkupScanner" module. (Note: For a discussion of the Hub's modules, see /member/wiki/OpenAjax_Hub_Specification_Bootstrapping%2C_Modularization_and_Inclusion#Modules.)
OpenAjax.scanNode(node[, shallowScan])
NOTE: This function is public, but it usually is not invoked in typical usage patterns. Its primary value is within automated testing scenarios.
Perform recursive scanning with the given element node. Returns true if the document was scanned, false if not.
FIXME: Verify that the above description is accurate.
Parameters
- node
- The element node at which scanning should begin.
- shallowScan
- Optional. If true, only scan this node and not any children. Defaults to false, which indicates that a deep scan should be performed.
Return value
None.
Module
This method is part of the "MarkupScanner" module. (Note: For a discussion of the Hub's modules, see /member/wiki/OpenAjax_Hub_Specification_Bootstrapping%2C_Modularization_and_Inclusion#Modules.)
