DOM/XPath Generator

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:

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);

Potential 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)

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

#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.  If null, use targetNode's owner document.
   *
   * @return DOMString XPath from the context node to the target node.
   */
  DOMString generateXPath(in nsIDOMNode targetNode
                          in nsIDOMNode contextNode);
}

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 generator 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.

Implementation: Bug 319768