# Image Picker

Image Picker is a simple jQuery plugin that transforms a select element into a more user friendly graphical interface.

## Features

- Works great on both single and multiple select elements.
- Falls back nicely for clients without JavaScript enabled.
- Integrates nicely with Twitter's Bootstrap markup.

## What it does?

It turns a select element into a more user friendly interface, e.g.:

Note: Select items are hidden by default when using Image Picker. They are left visible in the examples for pedagogical purposes.

## How it works?

Simply add the attribute `data-img-src` with the url of the image you want to use as a preview, e.g:

    <option
      data-img-src='http://www.example.com/image.jpg'
      value='42'
    >

Then just call imagepicker on the target elements.

    $("select").imagepicker()

## More examples

### Include blanks

If you want to allow blanks, just include an extra option with an empty value and no image data associated. Clicking a selected image will deselect it.

### Selects Multiple

Image Picker works great on select multiple elements too.

### Limit multiple selects Original submit and idea by Jason M. Batchelor.

You can also limit the amount of images to be selected by either passing an argument to the initialization when calling `imagepicker()`, ej: `$("select").imagepicker({limit: 2})` or adding it as data to the select element (click view html for example).

You can also trigger a callback when the limit has been reached by specifying a function in either the initialization under the attribute `$("select").imagepicker({limit_reached: function(){alert('We are full')}})`.

### Labels

You can also use the options text as labels by passing the option `show_label: true` when calling `imagepicker()`.

You can specify more complex labels by passing them as part of the option data in the attribute `data-img-label`. You can even specify HTML code.

### Uneven images

By default, Image Picker does not resize or order your images in any way, there are better tools for it if you need it. It can look great if your images are properly designed and ordered.

Or awful if they are just some random images. Thankfully, it works great with third party grid aligning scripts like Masonry.

## Documentation

### Image Picker Options

You can specify the following options when calling image picker:

hide_select
  Default: true. Wheter the original select item should be hidden or not.
show_label
  Default: false. If set to true, the text of each option will be added as a paragraph below each image.
limit
  Default: undefined. If it's a select multiple and set to any value, it'll cap the selectable elements at that value.

Additionally you can specify the following callbacks:

initialized
  Default: undefined. Specify a function to be called when the picker has been initialized.
changed
  Default: undefined. Specify a function to be called when the picker has changed.
clicked
  Default: undefined. Specify a function to be called when an option has been clicked.
selected
  Default: undefined. Specify a function to be called when an option has been selected.
limit_reached
  Default: undefined. Specify a function to be called when the limit cap has been reached.

Example:

            $("select").imagepicker({
              hide_select : true,
              show_label  : false
            })

### Select data

You can also pass some data directly to the select tag:

data-limit
  Optional. If it's a select multiple and set to any value, it'll cap the selectable elements at that value.

Example:

            <select multiple="multiple"
              data-limit='2'
            >

### Options data

You can also pass some data on each option element of the select tag:

data-img-src
  Required. The url of the image to use as a preview
data-img-label
  Optional. If `show_label` is set to true when calling `imagepicker()`. Then this content will be used as a label for the displayed image. This will not be escaped so you can actually put HTML here (although I wouldn't recommend it).

Example:

            <option
              data-img-src='http://www.example.com/image.jpg'
              data-img-label='Just an image!'
              value='42'
            >