GM_xpath

Description

GM_xpath is a simple API for selecting DOM nodes with XPath, eliminating much of the work typically required when using XPath in JavaScript.

Arguments

Object options

A single object with properties defining the behavior of GM_xpath.

• String path: A single XPath expression.
• [String] paths: Optional. An array of XPath expressions to be evaluated sequentially.
• DOMNode node: Optional. A DOM context node against which the XPath expression(s) will run. Defaults to the commonly used document element.
• Boolean all: Optional. If true, all nodes matching the XPath expression(s) will be returned. If false, only the first matched node will be returned. Defaults to false.
• String/Function/Object resolver: Optional. A namespace resolver. Defaults to the namespace of the context node.
  • Provide a string to always resolve namespaces to that fixed string.
  • Provide a function or an object implementing lookupNamespaceURI to dynamically resolve namespaces.
  • For more information see the DOM XPath reference and Implementing a User Defined Namespace Resolver.

Note: If both obj.path and obj.paths are set (which they should not be), Scriptish will use obj.paths.

Note: If obj.node is "falsy" (null, undefined, etc.), Scriptish will use document as the context node.

Alternate Usage

If you pass a string as the argument for GM_xpath then it will be used as the option.path with all of the defaults mentioned above.

Returns

DOMNode node

A single DOM node matching the XPath any expression, or null if no match was found.

or (if all is true):

[DOMNode] nodes

An array of DOM nodes matching the XPath expression(s), or an empty array [] if no match was found.

Examples

// Gets the first anchor found in the page, and logs its `href` attribute.
var anchor = GM_xpath("//a");

if (anchor) {
  GM_log("The first anchor's `href` attribute is: " + anchor.getAttribute("href"));
} else {
  GM_log("No anchors were found!");
}

// Gets the first anchor found in the page, and logs its `href` attribute.
var anchor = GM_xpath({
  path: "//a"
});

if (anchor) {
  GM_log("The first anchor's `href` attribute is: " + anchor.getAttribute("href"));
} else {
  GM_log("No anchors were found!");
}

// Gets all "required" text input fields and gives them a red border.
var reqTextInputs = GM_xpath({
  path: "//input[@type='text' and contains(@class, 'required')]",
  all: true
});

for (var i = 0, e = reqTextInputs.length; i < e; ++i) {
  reqTextInputs[i].style.border = "1px solid red";
}

// Gets all list item <li> elements in any "active" list (under "#foo") and gives them a nice color.
// Assumes there is some element with an ID of "foo".  If there is not, GM_xpath will throw an error.
// Note: this could be accomplished with a single, better XPath expression... this is just an example!
var activeListItems = GM_xpath({
  paths: ["ul[contains(@class, 'active')]/li", "ol[contains(@class, 'active')]/li"],
  node: document.getElementById("foo"),
  all: true
});

for (var i = 0, e = activeListItems.length; i < e; ++i) {
  activeListItems[i].style.color = "#bada55";
}

Related Pages

Manual: API