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 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:
Find all effects-category entries and then do something with them:
- {category: 'effects'},
- function(json) {
- // do something with json
- });
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:
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:
- [
- {
- "url": "...",
- "title": "...",
- "type": "...", // "method", "property", or "selector"
- "signatures": [
- {
- "added":"...",
- "params": [
- {
- "name": "...",
- "type": "...",
- "optional": "...", // either "true" or an empty string
- "desc": "..." // description of the parameter
- }
- ]
- }
- ],
- "desc": "...", // short description
- "longdesc": "...", // long description
- "return": "..." // type of return value
- }
- ]
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.
jQuery API Search A demonstration
✒ Advanced
Matching
Include in 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).
