jQuery API Update: offline and anywhere

I’ve been beavering away at the API behind the scenes for a little while, and if you follow me on Twitter you’ve probably already seen the API browser has already been upgraded.

The key change I’ve made is to de-couple the API search engine from the front end. What this has resulted in, is a fairly simple API to create any number of bespoke front ends to the jQuery API browser.

Since the engine now runs separately, it’s been easy to create different front ends.

So now the following front ends are available with the latest API:

There’s no reason this can’t be utilised within a Dashboard app (or update the existing one), implemented as an iGoogle widget and so on.

Feedback for AIR app

Currently there’s no icon for the app – any designers out there want to contribute? Please get in touch.

Originally the app had a quick silver “smoke” look to it, but I’ve since changed it a straight window so it can be minimised, maximised, etc.

I’m also aware the window settings don’t save and the auto updater might ask each time you open the app – there will be updates to fix this very soon!

Build Your Own

Grab an SVN Copy

I’ve got all the code in Google’s SVN repo (though I’m also mirroring across in git – but it’s pretty new to me).

If you’re app is online, I strongly recommend pulling the code, or at the least the API database, directly out of the SVN repo to ensure you’re running from the latest API.

If you’re working offline, I encourage you to build in an auto update feature, if only to refresh the database.

API Loader

Before loading the database, you must import the api-loader.js library which holds the callback to mount the functions on the API database (since it’s all contained within one object)

<script src="api-docs.js" type="text/javascript"></script>

API Database

The API database is loaded in one of two ways:

  • Import the pre-packaged JSON database
  • Converted from XML

The pro of the JSON version is that the browser doesn’t have to do any processing before the data is available. The con is that it’s almost twice the size of the raw XML version. I’m looking at what I can do to optimising the JSON version.

Loading the Database

JSON

<script src="api-docs.js" type="text/javascript"></script>

XML

Call the loadDocs function when the DOM is ready.

There is an option to point the XML database to a different location via the xmldoc variable. If you’ve exported XML from the wiki (via createjQueryXMLDocs.pl) then the XML is compatible. For example, the API browser currently works with all the jQuery Ui documentation (I’ll be adding this soon).

$(loadDocs);

Using the Database

The API database is a global variable called jquerydocs.

When the database is loaded it triggers a api-load-complete event on the document.

$(document).bind('api-load-complete', function () {
  alert(jquerydocs.version);
});

jquerydocs

The jquerydocs is an array with properties and a single find function. Running a query on the database returns the same structure back filtered by the given string.

>>> console.dir(jquerydocs);

'categories' : [Object name=Core subcategories=[5], 8 more...],
'data' : [Object jquery1=Object, 226 more...],
'letters' : ["a", "b", "c", 20 more...],
'searchNames' : ["jquery1", "jquery2", "jquery3", 224 more...]
'startdoc' : "API",
'timestamp' : "2008-06-03T15:40:58Z"
'version' : "1.2.6"
'find': function()

Querying

The best way to get familiar with the API database is to drop jquerydocs in to Firebug and look at the properties.

Generally everything is queried through the find function.

The find function takes two parameters, the second being optional:

  1. Query
  2. Field filter

If the field filter isn’t passed in, the query will search for functions, selectors and properties that ‘start with’ the query string.

A few examples:

// all API functions starting with 'trigg'
jquerydocs.find('trig');

// all functions in the category start with 'ajax'
jquerydocs.find('ajax', 'category');

Running Live Examples

// this would be the ID of the result
var id = 'trigger141',
  item = jquerydocs.data[id],
  i = 0,
  blank_iframe = '/index_blank.html',
  examples = $('exampleHolder'), // arbitrary placeholder
  html = [];

for (i = 0; i < item.examples.length; i++) {
  if (item.examples[i].html) {
      html.push('<iframe id="' 
        + item.examples[i].id 
        + '" src="' 
        + blank_iframe 
        + '"></iframe>');
  }
}

examples.append(html.join(''));

// runExample is a helper in api-loader.js
runExample(item);

Online/Offline Differences

If you’re running offline, you’ll need to ensure the following:

  1. In api-loader.js, change where example_jquery is pointing to – currently it points to the Google jQuery copy 1.2.6. If you’re running online, this will update when the loader script is updated.
  2. Again in api-loader.js, change where blank_iframe points to. This is required for the live examples. If you don’t run the examples in your code, then you shouldn’t need to change this.

25 Responses to “jQuery API Update: offline and anywhere”

  1. Hey man – looks great! An excellent excuse to write an AIR app :)

    I’d be interested in seeing the code and how you handled the auto-update check.

  2. @Tane – as mentioned on Twitter, I’m going to post a follow up article on the issues I had and how I resolved them.

    As a starting point though, take a look at the AIR update framework

  3. Tane, and others, for installed HTML/JS AIR apps, the source code is completely public. AIR simply installs plain text files of your source in the install directory. You could actually take the source files and create a completely functional Aptana AIR project should you desire.

    Remy…fantastic idea. I have a few questions for you.

    1) Might this app be able to handle multiple versions? Would be cool to drop a new jQuery file in the directory and get a dropdown for “which version would you like?”.

    2) I see that the app handles updates (probably for the app itself), but will it handle updating to new versions of jQuery or would that require a new version of the app?

  4. @Andy – to answer your questions:

    1) Yep – it should just be a case of loading the selected JSON db – and if only one is required, the quick and dirty way (though I’m not sure if it’s that dirty) is to just attach a script tag with the selected api-docs.xxx.js – it’ll run the callback itself and load in to the jquerydocs namespace.

    2) The plan is to handle it just upgrading the api docs itself. In fact the first version I wrote did go off and parse the XML then loaded it in the app-store. In the medium term though the app will upgrade itself in it’s entirety to get a new copy of the database. The priority for me was to release a version that self maintained so that when I fixed bugs or created optimisations it could be distributed without you chaps having to come to my blog and downloading another app.

  5. Awesome stuff, Remy!

  6. wow great Remy ! I love it! i think it just needs an “options” panel, allowing to set “autoupdate” (silent mode), save the window position, keep always on top. And the kewl jQuery devo hat icon, which i happen to have in a nice resolution. Drop me a mail if you want to include it !

  7. [...] você deve o AIR instalado no micro, após vá até o site de Remy sharp’s e faça o download do [...]

  8. Finally.. the offline jquery API. Thanks…

  9. No offline jquery API with .html ??

  10. What about use jquery.com/favicon.ico for AIR app?

    and offline API miss some API from dimensions(into core from 1.2.6)

    check docs.jquery.com/CSS

  11. @remy, great job with the offline Air app.
    One remark though, on the windows (XP SP2 – Air 1.5) version, at least, the jquery-api-browser.exe process says running even after I close the Air app.
    This small issue fixed and I’m fullfilled :)

  12. Hi Remy,

    Great App and it is really helpful. I second what Marin said. However, it keeps on running on Vista Ultimate SP1 also. I read on funkatron.com that HTML AIR apps are leaky. I don’t know when this issue in AIR will be fixed.

  13. awesome, what about the 1.3?

  14. Nice, work Remy. Excellent tool and I am glad to see it stay up to date.

  15. I am really fond of Visual jQuery and the jquery-api-browser. They’re both everyday used tools. I use Visual jQuery a lot in a quick-hiding tab in Aptana Studio and the jquery-api-browser as desktop app to experiment with the code samples and JSBin (which is awesome too btw).

    Anyway, I took the time and did an update to Visual jQuery so that it supports 1.3.2. You can download it here:

    http://support.aptana.com/asap/browse/STU-3495

  16. Hey Remy, another issue with the offline doc:
    I just fired up Charles Http Proxy and I found out that the Air app was making automatic requests to the jquery.com website every 30sec or so… I guess it would hammer the site a bit.

    Apparently it’s the check for upgraded version

    Request:
    GET /update.xml HTTP/1.1
    Referer: app:/application.html
    Accept: text/xml, application/xml, application/xhtml+xml, text/html;q=0.9, text/plain;q=0.8, text/css, image/png, image/jpeg, image/gif;q=0.8, application/x-shockwave-flash, video/mp4;q=0.9, flv-application/octet-stream;q=0.8, video/x-flv;q=0.7, audio/mp4, application/futuresplash, */*;q=0.5
    x-flash-version: 10,0,22,87
    User-Agent: Mozilla/5.0 (Windows; U; en-US) AppleWebKit/526.9+ (KHTML, like Gecko) AdobeAIR/1.5.1
    Host: api.jquery.com
    X-ProcessAndThread: jquery-api-browser.exe [5628; 5816]
    Pragma: no-cache
    Cache-Control: no-cache

    Response Xml:
    <?xml version=”1.0″ encoding=”utf-8″?>
    <update xmlns=”http://ns.adobe.com/air/framework/update/description/1.0″>
    <version>2.0</version>
    <url>http://api.jquery.com/update/jquery-api-browser-2.0.air</url&gt;
    <description><![CDATA[
    Minor upgrade - doesn't show the 'do you want to update' popup upon start up.]]></description>
    </update>

    That needs to be slowed down (once we fire up the very-usefull app?)

  17. @Marin – that’s useful to know. Tane Piper gave me the framework, so there were changes I needed to make – and it looks like auto update after it’s loaded should be disabled.

    That said, this might also be the poll to check whether it’s online or not – which it does check regularly (but should only be a HEAD request) to switch the “online features”.

    I’m trying to finish the upgrades to the api.jquery.com (permalinks and back button and changes to accordion are done) – but I’ve not found time to finish it off, annoyingly it’s about 90% there :-(

    Thanks for pointing that out though!

  18. Thanks so much Remy! This rocks!

  19. Hi,

    I found a bug in VisualJquery.
    The category ‘selectors’ contains the subcategory ‘basics’.
    The category ‘effects’ also includes the subcategory ‘basics’.
    This poses a problem because the two sub-categories display same functions.

    thanks

  20. Remy. One thing I’ve noticed about the API browser. After you’ve closed the application, it stays running in the background. While it doesn’t take up much memory, it’s still there when unexpected. Not sure if that’s intentional or not, but I wanted to point it out.

  21. Can you update jquery-api-browser to jQuery 1.4 ?

    Great stuf

  22. – Can you update jquery-api-browser to jQuery 1.4 ? –

    This would be my question, too. Will there be an update of your great “API AIR explorer”?

  23. +1 for jquery api browser update

  24. +1 for upgrading the air application it’s really useful but less so if its behind the latest version.

  25. Awesome – Thank you – Looking forward to future versions with updated jQuery, and am trying to find you an icon design.

    Friendly note: I had to get this off of your website, because the small swf on the jquery site that offers the download as an air app seems to be broken.

Leave a Reply
Not required

CODE: Please escape code and wrap in <pre><code>, doing so will automatically syntax highlight