jQuery URL Toolbox *beta*

I have been working on a jQuery plugin (well actually a self-contained set of plugins) that extends the capabilites of my jQuery URL Parser. I’m calling it a ‘URL Toolbox’ as it does everything the URL parser does (i.e. retrieving various bits of any URL string) but also allows you to set parts of URL strings, link hrefs, form actions etc, amongst other things.

UPDATE (22.01.10) – I have now removed the $.observeUrl() function as I felt it was not really in line with the core idea behind the plugin. For those needing similar functionality I would highly recommend Ben Alman’s hashchange plugin. New version also includes a number of bugfixes (thanks to Pavol, Eugene et al.). Proper demos and docs coming soon I hope! :-)

It also includes a function, $.observeUrl(), that once called ‘listens’ for changes to the document URL hash fragment, and triggers a custom jquery event, ‘hash:change’ whenever the hash portion of the URL changes. The plugin includes a somewhat modified version of the jQuery History Plugin to enable full back/forwards/history support for hash changes, and will hopefully make it pretty trivial to include full bookmarking and history support in AJAX based apps/sites .

The plugin is still very beta, but I thought I would link to the current version of it here anyway for those that are feeling brave and want to have a play around.

Download the jQuery URL Toolbox beta

Some very quick pointers on how to use it are included below – once I have tested it further I will move it over to the projects area of my site and get some proper documentation together.

General usage:

1. Use  var myUrl = $(element).url() to grab an element’s  URL and return a special ‘URL’ object. (a, form, img, base, link and iframe elements are supported, and using ‘document’ (no quotes) as the selector will return a URL object based on the current page’s URL)
2. Then use myUrl.attr('theAttr') to return any part of the URL, where ‘theAttr’ can be any one of: source, protocol, host, port, query, file, hash or path.
3. If you include a second argument to the attr() method – i.e. something like myUrl.attr('path', '/myNewPath/'), then it will set the value of that part of the URL to the value of the second argument. Whatever the URL of element the initial url() function was called on will be updated accordingly. If the document URL was used (via $(document).url()) then the location will be changed accordingly, normally resulting in a page refresh.
4. Doing a .toString() on the URL object at any time will return the current string representation of the URL.
5. The .segment(i) method (where ‘i’ is the segment number, starting from zero) will return the corresponding segment from the URL. Including a second parameter will set that segment.
6. The .param('key') method (where ‘key’ is the query string key) will return the corresponding value of the suppied key in the URL query (GET) string, if there is one. Including a second parameter will set that parameter.
7. If you have a hash fragment that consists of segments, like ‘#/part1/part2/’ then you can get/set those segments using the hashSegment() method, which works exactly like the segment() one.
8. Similarly if you have a hash fragment that looks like a query string, the parts can be get/set using the hashParam() method.

Watching for hash changes in the document’s URL:

1. Calling the $.observeUrl() function in your code will result in a custom ‘hash:changed’ event being triggered on the document any time the URL hash fragment is updated.
2. It will also ensure that any changes to the URL hash fragment are correctly recorded in the browser’s history (‘fixed’ for all browsers) so that the back/forwards buttons can be used correctly.
3. You can then set up you app to respond to hash changes by listening out for the hash:change event on the document, eg. $(document).bind('hash:change', function(e, hash){ doSomething() }

A lot to take in but I will try to get together some more comprehensive and less confusing documentation in the near future!

Any bugs, suggestions or otherwise please email me at mark[at]allmarkedup.com for now.