- Overview
- Documents
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.
How it works
HTML:
<select class="image-picker show-html"> <option data-img-src="img/01.png" value="1"> Page 1 </option> <option data-img-src="img/02.png" value="2"> Page 2 </option> <option data-img-src="img/03.png" value="3"> Page 3 </option> <option data-img-src="img/04.png" value="4"> Page 4 </option> <option data-img-src="img/05.png" value="5"> Page 5 </option> <option data-img-src="img/06.png" value="6"> Page 6 </option> <option data-img-src="img/07.png" value="7"> Page 7 </option> <option data-img-src="img/08.png" value="8"> Page 8 </option> <option data-img-src="img/09.png" value="9"> Page 9 </option> <option data-img-src="img/10.png" value="10"> Page 10 </option> <option data-img-src="img/11.png" value="11"> Page 11 </option> <option data-img-src="img/12.png" value="12"> Page 12 </option> </select>
JAVASCRIPT
$("select").imagepicker()
Document
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, all the callbacks have the scope (value of the this variable) set to the jQuery object where the plugin was initialized.
- 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. Receives the old values as the first option and the new values as the second.
- clicked
- Default: undefined. Specify a function to be called when an option has been clicked. Receives the image picker options as the first arguments.
- selected
- Default: undefined. Specify a function to be called when an option has been selected. Receives the image picker options as the first arguments.
- 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'>
Interacting via Javascript
You can also interact directly with the ImagePicker object via JS. To retrieve the object just call .data('picker') on the jQuery element. Example:
// Initialize the object $("select").imagepicker(); // Retrieve the picker $("select").data('picker');
Probably the two more common interactions are to either destroy the ImagePicker or to sync it after modifying the selected options on the select element.
// Syncs the picker with the current selected values on the 'select' element $("select").data('picker').sync_picker_with_select(); // Destroyes the picker and shows the original 'select' element again $("select").data('picker').destroy();
However if you do some heavy changes to the 'select' element like adding or removing options you will need to reinitialize the picker. This will destroy the old version and create a new one.
// Initialize the picker once $("select").imagepicker(); ... // We modify the select element, we need to reinitilize the picker $("select").imagepicker();