Confirm
146
edits
Changes
no edit summary
This page is to propose a XPathGenerator global constructor function for
returning a XPath string leading from the context node to the target node. Each
instance would be a XPCOM component, providing features for modifying the desired
XPath value, and a namespace resolver which corresponds to the XPath.
A consumer might use the code in the following manner:
<pre>
var generator = new XPathGenerator();
generator.searchFlags |= generator.GO_TO_DOCUMENT_ROOT;
generator.includeAttributeNS("http://www.w3.org/1999/xlink", "href", true);
var xpath = generator.generateXPath(targetNode, contextNode);
</pre>
== Use Cases ==
Currently, mozilla.org code uses similar functionality in at least two places:
http://lxr.mozilla.org/seamonkey/source/content/base/src/nsContentUtils.cpp#1567
GenerateStateKey
http://lxr.mozilla.org/seamonkey/source/xpfe/browser/resources/content/viewPartialSource.js#215
View Selection Source
Other sources:
https://bugzilla.mozilla.org/show_bug.cgi?id=208500
Copy XPath of node in DOM Inspector (not implemented yet)
[http://verbosio.mozdev.org Verbosio] would be able to translate a XPath for a document it's editing into a XPath for a XUL tree (a la DOM Inspector) representing the document's structure. This would be through simple text replaces. Thus, a node found in the master document would easily translate to a XUL tree item.
Developers would no longer have to guess a working XPath to a node for future reference. This would reduce development time.
== Proposed IDL ==
<pre>
#include "domstubs.idl"
[scriptable, uuid(ab50beb3-4049-4299-92ea-4dea4609a1e1)]
interface nsIXPathGenerator : nsISupports {
/* A collection of bitwise flags which modify behavior.
* 0x01000000 and flags greater are reserved for custom implementations.
*/
/**
* Ignore ID-type attribute nodes on elements and continue to the document node.
*/
const unsigned long GO_TO_DOCUMENT_ROOT = 0x00000001;
/**
* Flags which modify the parameters used to generate the xpath string.
*/
unsigned long attribute searchFlags;
/**
* If an attribute is present at a particular element's step, include it.
*
* @param namespaceURI The namespace URI of the attribute.
* @param localName The local name of the attribute.
* @param includeAttrValue Include the attribute value as well.
*/
void includeAttributeNS(in DOMString namespaceURI,
in DOMString localName,
in boolean includeAttrValue);
/**
* Stop including any attributes with this namespace URI and local name.
*
* @param namespaceURI The namespace URI of the attribute.
* @param localName The local name of the attribute.
*/
void excludeAttributeNS(in DOMString namespaceURI,
in DOMString localName);
/**
* Clear list of attributes included in returned xpath.
*/
void clearAttributes();
/**
* Namespace resolver corresponding to all generated xpaths.
*/
readonly nsIDOMXPathNSResolver resolver;
/**
* Generate the xpath as a string.
*
* @param targetNode The node our xpath ends at.
* @param contextNode The node our xpath starts from. May be null.
*
* @return DOMString XPath from the context node to the target node.
*/
DOMString generateXPath(in nsIDOMNode targetNode
in nsIDOMNode contextNode);
}
</pre>
The resolver of each XPathGenerator object would not be a standard document.createNSResolver(node) object. Instead, the XPathGenerator object will create and maintain the resolver independently. This will allow the resolver to add additional namespaces transparently and harmlessly as needed.
Certain consumers may wish to have attributes included in the xpath (for example, /a[href='foo.html'] or /a[href][2] instead of /a[5]). The includeAttributeNS() method exists for this purpose. Also, as consumers are generally expected to reuse the same generator, excludeAttributeNS allows consumers to exclude an attribute previously included, and clearAttributes() excludes all attributes currently in the search queue.
The bitwise flags are currently largely undefined, with the intent being for developers to add flags as needed. For instance, if a developer wants to ignore anonymous-to-non-anonymous content boundaries, they can add a flag for it, implement it, and offer a patch. While a patch awaits review or if it has been rejected, the upper 8 bits of the searchFlags number may be used privately for the same feature. The official XPathGenerator implementation must not use any of these eight flags for any purpose.
returning a XPath string leading from the context node to the target node. Each
instance would be a XPCOM component, providing features for modifying the desired
XPath value, and a namespace resolver which corresponds to the XPath.
A consumer might use the code in the following manner:
<pre>
var generator = new XPathGenerator();
generator.searchFlags |= generator.GO_TO_DOCUMENT_ROOT;
generator.includeAttributeNS("http://www.w3.org/1999/xlink", "href", true);
var xpath = generator.generateXPath(targetNode, contextNode);
</pre>
== Use Cases ==
Currently, mozilla.org code uses similar functionality in at least two places:
http://lxr.mozilla.org/seamonkey/source/content/base/src/nsContentUtils.cpp#1567
GenerateStateKey
http://lxr.mozilla.org/seamonkey/source/xpfe/browser/resources/content/viewPartialSource.js#215
View Selection Source
Other sources:
https://bugzilla.mozilla.org/show_bug.cgi?id=208500
Copy XPath of node in DOM Inspector (not implemented yet)
[http://verbosio.mozdev.org Verbosio] would be able to translate a XPath for a document it's editing into a XPath for a XUL tree (a la DOM Inspector) representing the document's structure. This would be through simple text replaces. Thus, a node found in the master document would easily translate to a XUL tree item.
Developers would no longer have to guess a working XPath to a node for future reference. This would reduce development time.
== Proposed IDL ==
<pre>
#include "domstubs.idl"
[scriptable, uuid(ab50beb3-4049-4299-92ea-4dea4609a1e1)]
interface nsIXPathGenerator : nsISupports {
/* A collection of bitwise flags which modify behavior.
* 0x01000000 and flags greater are reserved for custom implementations.
*/
/**
* Ignore ID-type attribute nodes on elements and continue to the document node.
*/
const unsigned long GO_TO_DOCUMENT_ROOT = 0x00000001;
/**
* Flags which modify the parameters used to generate the xpath string.
*/
unsigned long attribute searchFlags;
/**
* If an attribute is present at a particular element's step, include it.
*
* @param namespaceURI The namespace URI of the attribute.
* @param localName The local name of the attribute.
* @param includeAttrValue Include the attribute value as well.
*/
void includeAttributeNS(in DOMString namespaceURI,
in DOMString localName,
in boolean includeAttrValue);
/**
* Stop including any attributes with this namespace URI and local name.
*
* @param namespaceURI The namespace URI of the attribute.
* @param localName The local name of the attribute.
*/
void excludeAttributeNS(in DOMString namespaceURI,
in DOMString localName);
/**
* Clear list of attributes included in returned xpath.
*/
void clearAttributes();
/**
* Namespace resolver corresponding to all generated xpaths.
*/
readonly nsIDOMXPathNSResolver resolver;
/**
* Generate the xpath as a string.
*
* @param targetNode The node our xpath ends at.
* @param contextNode The node our xpath starts from. May be null.
*
* @return DOMString XPath from the context node to the target node.
*/
DOMString generateXPath(in nsIDOMNode targetNode
in nsIDOMNode contextNode);
}
</pre>
The resolver of each XPathGenerator object would not be a standard document.createNSResolver(node) object. Instead, the XPathGenerator object will create and maintain the resolver independently. This will allow the resolver to add additional namespaces transparently and harmlessly as needed.
Certain consumers may wish to have attributes included in the xpath (for example, /a[href='foo.html'] or /a[href][2] instead of /a[5]). The includeAttributeNS() method exists for this purpose. Also, as consumers are generally expected to reuse the same generator, excludeAttributeNS allows consumers to exclude an attribute previously included, and clearAttributes() excludes all attributes currently in the search queue.
The bitwise flags are currently largely undefined, with the intent being for developers to add flags as needed. For instance, if a developer wants to ignore anonymous-to-non-anonymous content boundaries, they can add a flag for it, implement it, and offer a patch. While a patch awaits review or if it has been rejected, the upper 8 bits of the searchFlags number may be used privately for the same feature. The official XPathGenerator implementation must not use any of these eight flags for any purpose.
