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
- full keyboard support
- search capabilities supporting wildcards and Regular Expressions
- fast search query response times
- entirely based on client-side JavaScript code, so it can be run without a web server
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.)
The jQuery API documentation viewer application window divides into three separate panels:
- Header panel
- Navigation panel
- 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.
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:
- enter the name of the jQuery item you are searching for into the Search text box,
- 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:
- Tree
UP/DOWN/LEFT/RIGHT ARROWkeys: navigate through the treeENTERkey: select an item from the tree and update the Content panelTABkey: give focus to the Content panel
- Search box
ALT+S*orSHIFT+ALT+S*key combination: give focus to the Search text fieldUP/DOWN ARROWkeys: navigate through the list of search resultsENTERkey: select an item from the list of search resultsTABorESCkey: set focus back to the tree
- Content panel
CTRL+LEFT ARROWkey combination: give focus to the tree
* 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:
- c(ss)
- 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.
- a(pi)
- 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.
- b(ookmark)
- 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.
- v(ersion)
- 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:
http://www.dashop.de/scripts/blog/jQuery/AjQDoc/AjQDoc.html?api=http%3A%2F%2Fapi.jquery.com%2Fapi%2FTo disable the Bookmark feature and load the local jQuery API documentation file you may write:
http://www.dashop.de/scripts/blog/jQuery/AjQDoc/AjQDoc.html?bookmark=false&v=debugYou 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:
- Mozilla Firefox 3.6 to 12.0
- Microsoft Internet Explorer 8 to 9
- Google Chrome 4.1
- Apple Safari 4.0
- Opera Webbrowser 10.51
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:
- Firefox has a bug in its XPath implementation. This bug prevents it from processing the jQuery API documentation file at all.
- Opera Webbrowser 10.51 can't correctly address <frame> targets. Nor does it provide common JavaScript keyboard handling support. Preventing default event behaviour to occur doesn't seem to be supported either. These bugs prevent it from correctly displaying/interacting with AjQDoc.
- Safari 4.0 has problems displaying transparent animated GIFs. Hence, the Loading image appears scrambled sometimes.
- Safari 4.0 and Chrome 4.1 do not fire a DOMfocusin() event immediately after the DOMfocusout() event has been fired. This hides the dropdown list box beneath the Search text box when clicking a found jQuery item before the Hyperlink is actually followed. As a workaround I have added a delay of a 10th of a second for the dropdown list box to stay visible when clicked. You must release the mouse button within this 1/10 second for the Hyperlink to be followed and the Content panel to be updated when using these browsers.
- Safari 4.0 and Google Chrome 4.1 do not provide an XML load() method. So they can not be used to run AjQDoc locally.
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.