Introducing jQuery API Search

read 5 comments

Half-baked tutorials and plugins have been stacking up for months in my virtual kitchen, waiting for me to fire up the oven, finish the cooking, and spread them out on the table. For some reason, though, I've become less and less sure about whether I've put all the right ingredients into the mix. It's irritating, to be sure, but I'm tired of fretting about it. I'm going to consider this the first of what I hope to be many "taste tests" — experiments in various degrees of completion thrown against the wall to see what, if anything, sticks.

As some of you may know, the online jQuery documentation went through a major overhaul in January of this year, coinciding with the release of jQuery 1.4. Packt Publishing "open sourced" the jQuery 1.4 Reference Guide that Jonathan Chaffer and I had been writing, allowing us to put its entire contents (and more) on api.jquery.com. Some of you may also know that the raw XML content of the site is available as a single file, which has allowed other sites such as jqapi.com and idocs.brandonaaron.net to provide alternative views of that content. But what most of you probably do not know is that the jQuery API has been available for quite some time as a searchable API that returns the results in JSON format.

Note: The reason you probably don't know about it is that it's half-baked. So, please go easy on it until some smart people have a chance to look under the hood at what I'm doing. Crazy abuse will surely bring it to its knees.

Motivation

I wanted to let people access the jQuery documentation via JavaScript from any other site and pull out exactly what is needed. I also wanted to play around with JSONP. This fits both of those desires.

URL

To access the searchable API, use the following URL:

http://api.jquery.com/jsonp/

Examples

You can tap into the API with one of jQuery's Ajax methods. If you use $.get() or $.getJSON(), you'll need to append "?callback=?" to the URL. With $.get(), you'll also need to set the dataType argument to "jsonp".

Find entries in the API that have "class" in their name and then do something with them:

JavaScript:
  1. $.get('http://api.jquery.com/jsonp/?callback=?',
  2.   {name: 'class'},
  3.   function(data) {
  4.     // do something with data
  5.   },
  6.   'jsonp');

Find all effects-category entries and then do something with them:

JavaScript:
  1. $.getJSON('http://api.jquery.com/jsonp/?callback=?',
  2.   {category: 'effects'},
  3.   function(json) {
  4.     // do something with json
  5. });

You can, of course, also use the low-level $.ajax() method.

Find entries with a title that ends in "ajax"; append a link for each to the document body:

JavaScript:
  1.   url: 'http://api.jquery.com/jsonp/',
  2.   dataType: 'jsonp',
  3.   data: {title: 'ajax', match: 'end'},
  4.   success: function(json) {
  5.     for (var i=0, len=json.length; i<len ; i++) {
  6.       var entry = json[i];
  7.       $('<a />', {
  8.         href: entry.url,
  9.         html: entry.title
  10.       }).appendTo('body');
  11.     }
  12.   }
  13. });

Search Types

The JSONP API is searchable by name, category, and version. Searching by more than one criterion returns results that match all of the criteria. All searches are case-insensitive.

  • Search by name:
    • Key: title
    • Value: the name of any jQuery method, property, or selector
    • Searches in: post title and post slug
    • Substitutions: Before querying the database, all "$" are converted to "jQuery" and each instance of one or more spaces is converted to a hyphen ("-") for both the search values and the the post title and slug.
    • Default: all titles
  • Search by category name
    • Key: category
    • Value: category name
    • Substitutions: Before querying the database, each instance of one or more spaces is converted to a hyphen ("-")
    • Searches in: category slug
    • Default: all categories
  • Search by version number
    • Key: version
    • Value: a jQuery version number
    • Searches in: category slug for all categories that are a child of the main "version" category
    • Default: all versions

String Matching

The "match" parameter lets you be confine the results to those that match the entire search term, or just the start or end of it.

  • Key: match
  • Value: one of "start", "end", or "exact" (for search by version number, one of "end" or "exact")
  • Default: "anywhere", except for version number, which has a default of "start"

Returned Data

Data is returned as an array of objects. Each item in the array is an object representing a single method, property, or selector. For example, a result with one item would have the following structure:

JavaScript:
  1. [
  2.   {
  3.     "url": "...",
  4.     "title": "...",
  5.     "type": "...", // "method", "property", or "selector"
  6.     "signatures": [
  7.     {
  8.       "added":"...",
  9.       "params": [
  10.       {
  11.         "name": "...",
  12.         "type": "...",
  13.         "optional": "...", // either "true" or an empty string
  14.         "desc": "..." // description of the parameter
  15.       }
  16.       ]
  17.     }
  18.     ],
  19.     "desc": "...", // short description
  20.     "longdesc": "...", // long description
  21.     "return": "..." // type of return value
  22.   }
  23. ]

Note that currently the examples/demos from each entry are not returned.

A (Fairly) Basic Demo

I put together a quick demo to give an idea of the API's flexibility. Type something into the "Name" field in the form below—say, "ajax"—and watch as the results come back. Inside the "Advanced" area, choose the "Matching... End" radio button and search again to see how the results differ.

✚ Search Again

jQuery API Search A demonstration

Advanced

Matching
Include in Results

Clear Results

A Little Less Basic Demo

I replicated this search form on a test server and added back-button support with Ben Alman's crazy delicious BBQ Plugin. Try out the demo.

But wait! There's more!

I put the whole shebang (well, except for the server-side stuff) in a GitHub repo. Clone it, fork it, have your way with it.

But Wait! There's Less!

As I mentioned above, this little project is incomplete. If you peek at the scripts, you'll quickly spot some major chunks of code in need of refactoring. Also, had I but world enough and time, I'd use a nice templating system such as mustache.js or the jQuery Templates plugin to output the search results. But I'll leave all that for another day (or another developer).

comment feed

5 comments

  1. Andrey

    That is a unique idea! Good stuff!

    I could see this being used on many blogs and websites where people talk about their plugin implementation that is also part of jquery's plugin documentation. This would be perfect for reducing redundant documentation repetition and instead allow the developers to pull straight from the jquery documentation. This would also motivate people to try and get their documentation into jquery's database.

    Verrry niice, I like!

  2. awesome...ih here i'm found jQuery API versi and ...
    http://tutorialzine.com/2010/09/google-powered-site-search-ajax-jquery/
    i'm found ajax jQuery versi, so many many
    thanks ^^

  3. This is really helpful. I'm currently working on a jQuery tutorial site. I'm planning on using this to display in a tool tip when something like .hide() is hovered over..

    I'll be in touch once its up. thanks again :)

  4. Hi Karl, Glad you finally made this one ... Very helpful ... Thanks -- Kathleen :)

  5. Pretty nice, didn't know about the api support and I like japi.

4 Pings

  1. [...] This post was mentioned on Twitter by Use jQuery, Rich Tretola, mclaughj rss, Rodrigo Yoshioka, Pat Newsome and others. Pat Newsome said: RT @usejquery: Introducing jQuery API Search http://is.gd/f3Yt0 [...]

  2. [...] If you are not too satisfied with the user experience of the jQuery API documentation. You can always build your own using the jQuery API Search. learningjquery.com has a gentle introduction to it. [...]

  3. [...] This post was mentioned on Twitter by Steve Johnathan, mohamed sadik and raja, AEXT.NET Magazine. AEXT.NET Magazine said: Introducing jQuery API Search http://bit.ly/a0X91l [...]

Sorry, but comments for this entry are now closed.