### Select Picker

# About

Select Picker is a jQuery plugin supporting work with select boxes. It extends the default possibilities of select boxes with a new range of features. In the basic setup, it will simply mimic a basic select box, but at the same time provide you with extensive ways of styling the appearance of your select box and several more neat features.
The main area where Select Picker truly rocks is when you want to use multiple-selection select boxes. It will give you an easy way how to facilitate user's selections with a tag-like appearance solution, providing features like custom styling and search. Basic Select Picker was developed while working on project for Designeo Creative s.r.o

# Examples

## Basic Picker

Basic Picker mimic a standard select box. It will load first option as selected one, therefore if you want to have placeholder use first option as placeholder. Also Picker support `hidden` attribute, therefore if you don't want to have placeholder in list of options, use it with your placeholder option.
Categorize your personality:
HTML

    <select name="basic" id="ex-basic">
        <option value="" disabled hidden>Select value</option>
        <option value="1">Nice</option>
        <option value="2">Very nice</option>
        <option value="3">Awesome</option>
        <option value="4">Godlike</option>
    </select>

Javascript

    $('#ex-basic').picker();

## Multi-selection Picker

Main purpose why Picker was developed was for tag selection. You can enable this feature really easily. Picker is smart enough to detect presence of `multiple` attribute with select tag and then enable multiple selection.
Choose what type of people you like:
HTML

    <select name="basic" id="ex-multiselect" multiple>
        <option value="1">Kind</option>
        <option value="2">Easy-going</option>
        <option value="3">Extroverts</option>
        <option value="4">Introverts</option>
        <option value="5">Ambitious</option>
        <option value="6">Loud</option>
    </select>

Javascript

    $('#ex-multiselect').picker();

## Multi-selection Picker with limit

There is possibility to limit how much options can user choose with the multi-selection picker.
Choose what type of people you like:
HTML

    <select name="basic" id="ex-multiselect-limit" multiple>
        <option value="1">Kind</option>
        <option value="2">Easy-going</option>
        <option value="3">Extroverts</option>
        <option value="4">Introverts</option>
        <option value="5">Ambitious</option>
        <option value="6">Loud</option>
    </select>

Javascript

    $('#ex-multiselect-limit').picker({limit: 2});

## Picker with search

Since sometime you have a lot of possibilities to choose from and it might be hard to find the choice you are looking for. But don't fall in despair my friend! Exactly for this case, there is search function implemented!
Choose the main city you love:
HTML

    <select name="basic" id="ex-search" multiple>
        <option value="1">Shanghai</option>
        <option value="2">Karachi</option>
        <option value="3">Beijing</option>
        <option value="4">Tianjin</option>
        <option value="5">Istanbul</option>
        <option value="6">Lagos</option>
        <option value="7">Tokyo</option>
        <option value="8">Guangzhou</option>
        <option value="9">Mumbai</option>
        <option value="10">Moscow</option>
        <option value="11">Dhaka</option>
        <option value="12">Cairo</option>
    </select>

Javascript

    $('#ex-search').picker({search : true});

## Data loading

With Picker there are two ways how to handle data loading - automatic and manual.
Picker will automatically load and "select" options with `select` attribute. This will work for either basic or multiple modes.
Or you can set your selected options manually through Picker's API via `set` method. More about Picker's API in Documentation section.
Choose the main city you love:
HTML

    <select name="basic" id="ex-search" multiple>
        <option value="1">Shanghai</option>
        <option value="2" selected>Karachi</option>
        <option value="3">Beijing</option>
        <option value="4" selected="selected">Tianjin</option>
        <option value="5">Istanbul</option>
        <option value="6">Lagos</option>
        <option value="7">Tokyo</option>
        <option value="8">Guangzhou</option>
        <option value="9">Mumbai</option>
        <option value="10">Moscow</option>
        <option value="11">Dhaka</option>
        <option value="12">Cairo</option>
    </select><br>
    <button id="ex-data-trigger">Select Cairo city</button>

Javascript

    $('#ex-data-multiple').picker();
    $('#ex-data-trigger').click(function () {
        $('#ex-data-multiple').picker('set', 12);
    })

## Coloring

Select Picker has small feature which will let you assign specific classes to specific elements based on their option's `value`. To enable this feature you just have to pass object where key is the desired option's and the class you want to assign to desired element.
Note that this feature applies only to selected options while multiple selection mode is selected. Also the classes are applied only to selected options.
Choose the main city you love:

    <select name="basic" id="ex-search" multiple>
        <option value="1">Shanghai</option>
        <option value="2" selected>Karachi</option>
        <option value="3">Beijing</option>
        <option value="4" selected="selected">Tianjin</option>
        <option value="5">Istanbul</option>
    </select><br>

Javascript

    var classes = {
        2 : 'orange',
        4 : 'blue',
        5 : 'orange'
    };

    $('#ex-coloring').picker({coloring: classes});

## Events

Select Picker has basic support for events. Attach your event listeners to the original `select` element.
Choose what type of people you like:
HTML

    <select name="basic" id="ex-events" multiple>
        <option value="1">Kind</option>
        <option value="2">Easy-going</option>
        <option value="3">Extroverts</option>
        <option value="4">Introverts</option>
        <option value="5">Ambitious</option>
        <option value="6">Loud</option>
    </select>

JavaScript

    var $elem = $('#ex-events');
    $elem.picker();
    $elem.on('sp-change', function(){
        alert('Great! Thanks for letting me know!');
    });

# Installation

You can install Select Picker in three ways - directly, through Bower and through npm.

## Directly

To install Select Picker directly download ZIP archive from here, unzip it and copy files `css/picker.min.css` and `js/picker.min.js` in to your project structure.

    <link rel="stylesheet" href="path/to/file/picker.min.css">
    <script type="text/javascript" src="path/to/file/picker.min.js"></script>

## Bower

To install Select Picker through Bower run following command:
bower install select-picker --save

## npm

To install Select Picker through npm run following command:
npm install select-picker --save

# Documentation

To start using Select Picker, first you have to include required files in your HTML page. Basic way is to include in your `head` tag following part, of course with modifying the path to the files

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

Then only thing you need to do is initialize Picker!

    <script type="text/javascript">
        $(document).ready(function(){
            $('#your-selector').picker();
        });
    </script>

## Parameters

Picker bring you several parameters with which you can customize your Picker.

### autofocusScrollOffset

Type: Integer
Default: 0
Dependency: enabled search feature and search auto-focus.
If you need to modify the position to which the window is scrolled to, you can set a offset from the Picker, by specifying `autofocusScrollOffset`.

### coloring

Type: Object
Default: {}
Dependency: multi-selection mode
If you want to customize each selected option, during multi-selection mode, you can do it by creating object, where key value is option's value and the value of pair is the class you want to assign and pass this object through `coloring` parameter.
Check the example to understand it better.

### containerClass

Type: String
Default: ''
Through `containerClass` parameter you can specify what class should be added to whole Picker wrapping element. It is mostly to be used for specific styling purposes.

### containerWidth

Type: Integer
Default: none
With `containerWidth` parameter you can set the width of whole container. This comes handy especially in multiple-selection mode, when the selected options could be outstretching the container and cause some layout problems.

### limit

Type: Integer
Default: none
Dependency: multi-selection mode
If you want to limit, how much options can user select in the multi-selection mode, can use `limit` parameter. After reaching the limit, the dropdown will be hidden and will be shown again only when user will remove some of the options.

### search

Type: Boolean
Default: false
With this option you can control the search feature. It can be used both with single-selection and multi-selection mode.

### searchAutofocus

Type: Boolean
Default: false
Dependency: enabled search feature
When you enable the search feature, you can also enhance the user's experience, with automatic focus to search field. At the same time when the focus is put to search field, window is scrolled to the Picker.

### texts

Type: Object
Default: { trigger : "Select value", noResult : "No results", search : "Search" }
If you want to modify the Picker's messages you can modify it by passing object with modified texts. Just please remember that you have to use same key values as default object.

### width

Type: Integer
Default: 165 (set via CSS)
When you have a long option's text, Picker's drop-down list will break the text when it will reached default width. With this option you can override the default width.

## API

Select Picker has also basic API to modify already initialized Picker.
Methods which do not return any value can be called with jQuery selector which contains more than one elements. Methods which returns some values have to be called through single element selector.

    $('.multiple-used-class').picker(); // Will work
    $('.multiple-used-class').picker('set', 2); // Will work
    $('.multiple-used-class').picker('get'); // Won't work

### $('...').picker('destroy');

Parameters: none
Return: original jQuery selector
This method will remove all Pickers elements and display original select box.

### $('...').picker('get');

Parameters: none
Return: string/array - actually selected value(s)
This method will return actually selected values of single Picker.
This method has to be called from single-element selector!

### $('...').picker('set', id);

Parameters: id - string
Return: original jQuery selector
This method will allow you to manually set value as selected. Parameter id is value of option element. In case of multi-selection mode, it will add option as another selected one.

### $('...').picker('remove', id);

Parameters: id - string
Return: original jQuery selector
This method will allow you to manually remove value as selected. Parameter id is value of option element. This method works only while multi-selection mode.

Created by Adam Uhlíř © 2016

## Events

Select Picker has currently basic support for events. Any suggestions for extending currently supported events will be very much welcomed.

Name of event | Description
--- | ---
sp-change | Triggered when some element is chosen (in single mode) or add/removed (in multiple mode).
sp-open | Triggered when is the dropdown menu opened.
sp-close | Triggered when is the dropdown menu closed.