## Introduction ##

jquery_collections_browser is a jquery plugin which provides a graphical interface to the Victoria and Albert Museum's collections data and images opendata [API](http://www.vam.ac.uk/api).

This data can also be browsed at the [V&A's search the collections site](http://collections.vam.ac.uk)

This plugin is designed to be simple to implement, whilst offering plenty of customizability and functionality.

It is built on jquery, and makes extensive use of jquery-ui for user interface control elements.

Supported browsers:
 
* Firefox 3.6 +
* Internet Explore 8
* Chrome 13
* Opera 11.5

_If a browser appears in the list, it means we've tested it, and it seems to work fine; it's not an absolute guarantee._ If you spot a problem, let us know.

## Installation  ##

First, make sure you're using jQuery and jQuery-UI (1.7+ works). 
An easy way to load them is to use the minified versions hosted on google cdn:

    <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script>
    <script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8/jquery-ui.min.js"></script>

You also need to load jQuery-UI CSS. You can either load one of the pre-rolled themes yourself from google:

    <link rel="stylesheet" type="text/css" href="http://ajax.googleapis.com/ajax/libs/jqueryui/1.8/themes/smoothness/jquery-ui.css" media="all" />
    
or roll your own and host it yourself.

Next, install the plugin's javascript and css files into your site in a directory named, for example, "wall".

Then add the following code to your page:

    <link rel="stylesheet" type="text/css" href="wall/wall.css" media="all" />
    <script type="text/javascript" src="wall/wall.js"></script>

Next, add an element to your document to bind the plugin to:

    <div id="#wall"></div>

Finally, call the function like this:

    <script type="text/javascript">
            
        $(document).ready(function() {
            $("#wall").wall({
                'search_term': 'rainbow',
            });
        });
    
    </script>

This gives you a basic interface, loading images for the search term 'rainbow' (you can pass whatever you like in here of course).

## What's this "wall" all about then? ##

So the plugin queries the [V&A's collections API](http://www.vam.ac.uk/api), and builds a grid of images of museum objects from the response. This grid is draggable, and as you drag it, more images are downloaded to fill in the bits of the grid as they come into view. What you have is, if you will, a draggable "wall" of images.

## Customizing your wall ##

The plugin as initialized above runs off the default settings, which will give you a basic functioning wall, showing images of objects which match the search term 'rainbow'. However, there are many settings you can set yourself by passing them to the function like this:

    <script type="text/javascript">
            
        $(document).ready(function() {
            $("#wall").wall({
                'start_size': 1,
                'width': 1000,
                'height': 600,
                'search_term': 'rainbow',
                'fill_direction': 'forwards'
            });
        });
    
    </script>

The available settings and how to use them will be documented in due course, but for now please refer to the source code and comments in [jquery-wall.js](https://github.com/vanda/jquery_collections_browser/blob/master/jquery-wall.js#L7)

## Notes ##

You may use this plugin under the terms of either the MIT License or the GNU General Public License (GPL) Version 2.

Please note that there are terms and conditions attached to the use of V&A data and images, which you can read [here](http://collections.vam.ac.uk/information/information_apiterms).

If you have a question, or would like to report a bug or tell us about something we could do better, we'd love to hear from you. Please send all queries to [[email protected]]([email protected])