Namespace atropa.xpath

Version 20130313.
An Xpath toolkit for manipulating the DOM.
Defined in: <node_modules/atropa-xpath/src/atropa-xpath.js>.

Namespace Summary
Constructor Attributes	Constructor Name and Description
	atropa.xpath An Xpath toolkit for manipulating the DOM.

Method Summary
Method Attributes	Method Name and Description
<static>	atropa.xpath.escapeQuotesXpath(string) Escapes single quotes (apostrope) in Xpath queries.
<static>	atropa.xpath.getNodesByXpath(xpathExpression, contextNode, docref) Selects nodes from the DOM using an Xpath expression.
<static>	atropa.xpath.processNodesByXpath(xpathExpression, contextNode, docref, callback) Processes nodes from the DOM using an Xpath expression.
<static>	atropa.xpath.removeNodesByXpath(xpathExpression, contextNode, docref) Removes nodes from the DOM using an Xpath expression.

Namespace Detail

atropa.xpath

An Xpath toolkit for manipulating the DOM.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

Method Detail

<static> {String} atropa.xpath.escapeQuotesXpath(string)

Escapes single quotes (apostrope) in Xpath queries.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

 // this is useful for using arbitrary strings in your queries.
 var arbStr, escapedStr, xpathExpression, foundNodes;
 arbStr = "Jimmy ain't never said \"Shur\" Why? I don't know!";
 escapedStr = atropa.xpath.escapeQuotesXpath(arbStr);
 // produces: concat('Jimmy ain', "'", 't never said "Shur" Why? I don', "'",
 // 't know!')
 // it is much easier to deal with the variable name than it is to deal with
 // all those quotes and commas!
 xpathExpression = './/p[contains(text(),' + escapedStr + ')]';
 foundNodes = atropa.xpath.getNodesByXpath(xpathExpression);
 // found nodes will contain the p elements where the text was matched.

Parameters:
{String} string: An Xpath query

Returns:: {String} Returns a string representing a concat function in Xpath which will effectively work in escaping quotes in your xpath query.

<static> {Array} atropa.xpath.getNodesByXpath(xpathExpression, contextNode, docref)

Selects nodes from the DOM using an Xpath expression.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

  // To get all the elements in the document with a src attribute:
  var srcElements = atropa.xpath.getNodesByXpath('[@src]');

Parameters:
{String} xpathExpression: An Xpath expression as a string
{DOM Node} contextNode: Optional. The node which is to serve as the root for the supplied Xpath expression. Defaults to the document's root node.
{DOM Document} docref: Optional. A reference to the document you are searching, defaults to document.

Returns:: {Array} Returns an array whose elements are DOM Nodes

See:: atropa.xpath.processNodesByXpath for more information.

<static> {Number} atropa.xpath.processNodesByXpath(xpathExpression, contextNode, docref, callback)

Processes nodes from the DOM using an Xpath expression.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

  // Say you wanted to touch all the anchors and links in window.document
  var xpathExpression, callback;
  xpathExpression = './/a';
  callback = function(oneNode) {
      oneNode.touched = true;
  }
  atropa.xpath.processNodesByXpath(
      xpathExpression, document, document, callback);
  
  // Or say you have an iframe, with the id 'myFrame'. In the iframe there
  // is a div with the id myDiv.
  // Here is how you would remove all the anchors in that div.
  var myFrame, xpathExpression, contextNode, docref, callback;
  myFrame = document.getElementById('myFrame');
  docref = myFrame.contentWindow.document;
  contextNode = docref.getElementById('myDiv');
  xpathExpression = './/a';
  callback = function(oneNode) {
      atropa.removeNodeByReference(oneNode);
  }
  atropa.xpath.processNodesByXpath(
      xpathExpression, contextNode, docref, callback);

Parameters:
{String} xpathExpression: An Xpath expression as a string
{DOM Node} contextNode: Optional. The node which is to serve as the root for the supplied Xpath expression. Defaults to whatever docref is. If you are using a relative path such as .//a and, you only want the anchors that are descendants of another element, you would supply a reference to that element for this argument. When using a context node, the docref argument must refer to the context node's containing document.
{DOM Document} docref: Optional. A reference to the document you are searching, defaults to document. If you have created a separate DOMDocument with the atropa.HTMLParser, an iframe, or by some other means, you would put a reference to that document here to indicate that you intend to use that document's root.
{Function} callback: A function applied to every element found using the supplied xpath expression. The callback receives a single element as it's only argument.

Returns:: {Number} Returns the quantity of nodes processed.

<static> {Number} atropa.xpath.removeNodesByXpath(xpathExpression, contextNode, docref)

Removes nodes from the DOM using an Xpath expression.
Author: Matthew Christopher Kastor-Inare III
☭ Hial Atropa!! ☭.

  // to remove all anchors with the class "oops" inside of any div in
  // document
  var xpathExpression = ".//div//a[@class='oops']";
  atropa.xpath.removeNodesByXpath(xpathExpression);

Parameters:
{String} xpathExpression: An Xpath expression as a string
{DOM Node} contextNode: Optional. The node which is to serve as the root for the supplied Xpath expression. Defaults to whatever docref is.
{DOM Document} docref: Optional. A reference to the document you are searching, defaults to document.

Returns:: {Number} Returns the quantity of nodes removed.

See:: atropa.xpath.processNodesByXpath for more information.

Classes

Namespace atropa.xpath