Examples / API

You can view the API for the XPointerLib component here. If you are unfamiliar with IDL or with any of the terms on this page, more information is available through the links page.

After installing the component, you can obtain the XPCOM service, which I've called XPointerService, in JavaScript as follows:

var xptrService = Components.classes[";1"].getService();
xptrService = xptrService.QueryInterface(Components.interfaces.nsIXPointerService);

This is the standard method for obtaining an XPCOM service and querying for the appropriate interface through Javascript. It cannot be run from code running in a web page, only in privileged code.

After this step, you may call any of the four methods that the service API defines. The API provides two functions for creating XPointers and two functions for resolving them.

The two creation functions differ only in their input format: one takes an nsISelection object and the other takes a DOM Range. Both creation functions return a string containing the newly created XPointer.

The nsISelection object is Netscape/Mozilla's representation of a selection in the document; it is quite similar in structure to a DOM Range. You can obtain the current selection through JavaScript with the function window._content.getSelection().

Here is an example of creating an XPointer representing the selection in the main window:

// assumes previous code to get xptrService object
var xptrString = xptrService.createXPointerFromSelection(window._content.getSelection(), window._content.document);

The resolution functions differ only in their return value. Of the two, the completely accurate function resolves to a DOM Range. The other function approximates to the DOM Node at the beginning of the resolved Range. The latter function exists for historical reasons--you should use the function that resolves to a DOM Range.

In actuality, an XPointer should resolve to an array of DOM Range (in XPointer terms, a location set). The next version of XPointerLib may implement that--for now, we make the simplifying assumption that an XPointer resolves only to a unified, contiguous location (the sort of thing a DOM Range will represent).

A sample resolution of the xpointer: xpointer(/html[1]/body[1]) for the current document is as follows:

// assumes previous code to get xptrService object
var range = xptrService.parseXPointerToRange("xpointer(/html[1]/body[1])", window._content.document);

In addition to creation and resolution, the XPointerLib also has a method called markElement which may be used to mark an element before inserting it into the DOM. Any element so marked, though visible in the document, will be ignored by XPointerLib processing--it will be as though it does not exist. So, if you want to insert an icon into the DOM without effecting resolution of further XPointers, be sure to call markElement on it before insertion. An example:

// assumes you already have xptrService from above
var icon = document.createElement("img");

// now you can insert the icon
// and XPointerLib will ignore it in processing

The xpointerlib project can be contacted through the mailing list or the member list.
Copyright © 2000-2017. All rights reserved. Terms of Use & Privacy Policy.