A Comfortable jQuery API Documentation Viewer

Two weeks ago I was learning the ropes of the latest version of the jQuery framework. After learning all of it I decided to create a new application, utilizing the latest jQuery JavaScript framework.

My goal was to exploit as much as possible from the jQuery framework. So the idea I finally came up with was to create an interactive jQuery API documentation viewer, designed as a Web application that won't use standard Hyperlinks to show its content but instead create its whole content instantly and dynamically by means of jQuery, XPath, and JavaScript.

The result is a full-fledged web application, providing

If you work with jQuery yourself, you may be familiar with the situation where you find yourself searching for a jQuery function or object which you would like to use in your code. Usually you would then navigate to the jQuery website, browse to the online documentation and navigate to the jQuery item you are searching for.

I must admit that I found myself a bit unsatisfied with the jQuery online documentation. It is not very well documented itself, and for me the search algorithm is not very transparent, it never returned the result I was searching for when I was not searching in the "All" category. And I didn't feel comfortable with the online documentation's odd keyboard navigation.

Fortunately, the jQuery community has created an XML data file, containing all the necessary jQuery documentation content in a well structured way. This file virtually invites software developers to create custom jQuery documentation viewer applications, utilizing data from the file.

So I started to create my jQuery API documentation viewer application ("AjQDoc") not only as a learning project; I also tried to create a jQuery documentation viewer that better suits my needs.

Perhaps you are going to like the fast and dynamic features of my jQuery API documentation viewer, too.

Want to give it a try?

How To Start The Application

To begin using AjQDoc, click here.

(If you encounter any problems with AjQDoc, please refer to the Browser Issues section.)

A new browser window will open, automatically downloading the latest copy of the jQuery API documentation file from my web server. (You can choose to download the latest copy from the jQuery website but you need elevated privileges to do this. This is due to restrictions imposed on AJAX calls by the so-called same origin policy.)

AjQDoc Navigation panel

The jQuery API documentation viewer application window divides into three separate panels:

  1. Header panel
  2. Navigation panel
  3. Content panel

Depending on your Internet connection it takes three seconds or more for the jQuery API documentation file to download.

As soon as the documentation file is available, the application window content updates, displaying a search box and a tree showing all available jQuery API first-level categories.

Navigating The Documentation

To browse the documentation, click on any of the categories listed in the Navigation panel. This will display a list of jQuery items available for the selected category/sub-categories in the Content panel on the right.

To read the documentation for any of the jQuery items listed in the Content panel, click the corresponding item in the Content panel list to open the appropriate jQuery item documentation.

Some categories have sub-categories assigned to them. You can narrow down the list of jQuery items displayed in the Content panel list by unfolding the appropriate category node in the tree and then clicking on one of the sub-categories that appear. The Content panel will then display the jQuery items available for that sub-category. To fold or unfold a tree node, click on the bullet character left to the category name.

The tree on the left of the AjQDoc window not only holds all the jQuery API documentation categories but also contains leaf-nodes representing the jQuery items themselves. So by further unfolding branches in the tree you will finally reach the matching jQuery items at the end of each branch in the tree.

Depending on whether you select a jQuery API documentation category or a jQuery API documentation item in the tree, the Content panel will either display a list of corresponding jQuery items or the jQuery item documentation itself.

Searching The Documentation

Instead of navigating the tree you can search the documentation for jQuery items as well: Use the Search text box above the tree in the Navigation panel to search for a particular jQuery item:

  1. enter the name of the jQuery item you are searching for into the Search text box,
  2. select one of the items that appear in the list box becoming visible under the Search text box.

While you type, AjQDoc performs an incremental search. The terms you enter are auto-completed, and appertaining jQuery items are displayed in a temporary list box right under the Search text box. To display the documentation for any of the found jQuery items, select the corresponding item from the list. The Content panel will then update to display the item's documentation.

You don't know the exact writing of a jQuery item? Do you want to search using wildcards and Regular Expressions? Just enter a Regular Expression term or use asterisks ("*") in your search phrase where you feel appropriate.

Search is done case insensitive.

Keyboard Support

Some people, like me, prefer to use the keyboard when working with programs. Thus I have put reasonable effort into adding keyboard support to AjQDoc.

If you prefer to use AjQDoc with your keyboard, you can do the following:

* The keyboard combination to give focus to the Search text box is browser dependant. You need to try out the "S" key with different modifier keys to find the keyboard combination appropriate for your browser.

Setting Your Preferences

Do you perhaps want to browse through a different jQuery API documentation file? Or do you dislike the graphical design of AjQDoc and want to use your own one? Sure, go ahead! You can change a number of settings by giving your preferences in the URL query string when starting AjQDoc.

AjQDoc accepts the following query string parameters:

URL to CSS file containing rules on how to display documentation content.
A template with default rules for all classes used in the jQuery API documentation viewer application can be found here.
URL to jQuery API documentation XML file.
Please note: Using this parameter requires elevated privileges because it will download the XML file from a different host than the application. AJAX imposes a so-called same origin policy, which usually inhibits a successful download from a different domain.
If set, disables the AjQDoc Bookmark feature.
Debug setting: AjQDoc uses fragment identifiers so you can bookmark any of the jQuery items in the documentation.
At the time of writing, some browsers reload the web page when the window location's fragment identifier changes. These browsers' behaviour does not comply to HTML specification.
To disable the Bookmark feature, and to prevent these browsers from permanently reloading the whole application, add this parameter with any arbitrary value to the query string. This will leave the window's address location fragment identifier unchanged.
If set to "debug", loads local jQuery API documentation file and uncompressed jQuery code.
Debug setting: This setting is mainly of use only to me.
If this parameter is provided and set to "debug", the jQuery API documentation viewer application doesn't use AJAX to load the jQuery API documentation file but instead loads the XML file "jQuery API.xml" from the application files' current directory using XML object's load functionality. Moreover, it links the application to the uncompressed version of the jQuery code.
This setting allows local use of AjQDoc.

Using URL query strings is a bit tricky and requires knowledge of how to compose valid URLs. You might want to read about URL query strings first before using them.

All parameters are case-insensitive and accept an abbreviated syntax: You can provide just the first letter of a parameter name instead of the full name.

For example, to load the jQuery API documentation file from a different location, you would write:


To disable the Bookmark feature and load the local jQuery API documentation file you may write:


You can check which files are currently in use by AjQDoc: Click on the AjQDoc headline in the Header panel. The Header panel will temporarily change to display the path to the CSS and jQuery documentation files for about 10 seconds.

Browser Issues

At the time of writing, AjQDoc seems to run flawlessly only in Internet Explorer, but not in other browsers. I have tested AjQDoc on Windows 7 (64 bit) against:

All browsers except Internet Explorer seem to share the same problem: Updating the hash portion of a window's location object causes a reload of the current document, which is not correct behaviour according to current HTML specification.

AjQDoc's Bookmark feature updates the hash portion of the document address location so you can store bookmark Hyperlinks for often used jQuery items. This works well in Internet Explorer but all other browsers I tested unnecessarily reload the page.

To disable the Bookmark functionality in order to avoid permanent reloading of the page, add the query string "bookmark=false" to the address of AjQDoc. Or just use this amended link to AjQDoc.

In the course of testing my application against various browsers I recorded the following other browser bugs:

Addendum on February 2014:

XPath is no longer available in Internet Explorer as of Internet Explorer 10.

Your Feedback Is Appreciated

I am very much interested in how AjQDoc did help you work with jQuery. Your improvement suggestions and complaints on AjQDoc are also very welcome!

Currently, my website is static, not allowing any comments online. If you want to comment on AjQDoc, please fill-in the contact form.

Axel Dahmen Soft- and Hardware-Engineering
04/09/2010 02:41