578 lines
25 KiB
HTML
578 lines
25 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<title>Select Picker | jQuery plugin</title>
|
|
<meta name="description" content="Multi-select tags-like picker as plugin for jQuery">
|
|
<meta name="author" content="Adam Uhlir">
|
|
<link rel="stylesheet" href="css/main.css">
|
|
<link href="css/prism.css" rel="stylesheet"/>
|
|
|
|
<script type="text/javascript" src="js/libs.js"></script>
|
|
<script type="text/javascript" src="js/picker.js"></script>
|
|
<script type="text/javascript" src="js/prism.js"></script>
|
|
</head>
|
|
<body data-spy="scroll" data-target="#picker-nav">
|
|
<div class="content-container">
|
|
<a href="https://github.com/AuHau/select-picker"><img style="position: fixed; top: 0; right: 0; border: 0;"
|
|
src="https://camo.githubusercontent.com/a6677b08c955af8400f44c6298f40e7d19cc5b2d/68747470733a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f677261795f3664366436642e706e67"
|
|
alt="Fork me on GitHub"
|
|
data-canonical-src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png"></a>
|
|
|
|
<div class="masthead clearfix">
|
|
<h3 class="masthead-brand">Select Picker</h3>
|
|
<nav id="picker-nav">
|
|
<ul class="nav masthead-nav">
|
|
<li class="active"><a href="#about">About</a></li>
|
|
<li><a href="#examples">Examples</a></li>
|
|
<li><a href="#installation">Installation</a></li>
|
|
<li><a href="#documentation">Documentation</a></li>
|
|
</ul>
|
|
</nav>
|
|
</div>
|
|
|
|
<div id="about">
|
|
<h1>About</h1>
|
|
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.<br><br>
|
|
|
|
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 <a href="http://www.designeo.cz" target="_blank">Designeo
|
|
Creative s.r.o</a>
|
|
</div>
|
|
|
|
<div id="examples">
|
|
<h1>Examples</h1>
|
|
|
|
<h2>Basic Picker</h2>
|
|
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 <code>hidden</code> attribute, therefore if you don't want to have
|
|
placeholder in list of options, use it with your placeholder option.
|
|
<div class="well">
|
|
Categorize your personality:
|
|
<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>
|
|
<script type="text/javascript">
|
|
$('#ex-basic').picker();
|
|
</script>
|
|
|
|
</div>
|
|
|
|
<strong>HTML</strong>
|
|
<pre><code class="language-markup"><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>
|
|
</code></pre>
|
|
|
|
<strong>Javascript</strong>
|
|
<pre><code class="language-javascript">$('#ex-basic').picker();</code></pre>
|
|
|
|
<h2>Multi-selection Picker</h2>
|
|
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 <code>multiple</code>
|
|
attribute with select tag and then enable multiple selection.
|
|
<div class="well">
|
|
Choose what type of people you like:
|
|
<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>
|
|
<script type="text/javascript">
|
|
$('#ex-multiselect').picker({containerWidth: 410});
|
|
</script>
|
|
</div>
|
|
|
|
<strong>HTML</strong>
|
|
<pre><code class="language-markup"><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>
|
|
</code></pre>
|
|
|
|
<strong>Javascript</strong>
|
|
<pre><code class="language-javascript">$('#ex-multiselect').picker();</code></pre>
|
|
|
|
<h2>Multi-selection Picker with limit</h2>
|
|
There is possibility to limit how much options can user choose with the multi-selection picker.
|
|
<div class="well">
|
|
Choose what type of people you like:
|
|
<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>
|
|
<script type="text/javascript">
|
|
$('#ex-multiselect-limit').picker({containerWidth: 410, limit: 2});
|
|
</script>
|
|
</div>
|
|
|
|
<strong>HTML</strong>
|
|
<pre><code class="language-markup"><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>
|
|
</code></pre>
|
|
|
|
<strong>Javascript</strong>
|
|
<pre><code class="language-javascript">$('#ex-multiselect-limit').picker({limit: 2});</code></pre>
|
|
|
|
<h2>Picker with search</h2>
|
|
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!
|
|
|
|
<div class="well">
|
|
Choose the main city you love:
|
|
<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>
|
|
<script type="text/javascript">
|
|
$('#ex-search').picker({containerWidth: 465, search: true});
|
|
</script>
|
|
</div>
|
|
|
|
<strong>HTML</strong>
|
|
<pre><code class="language-markup"><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>
|
|
</code></pre>
|
|
|
|
<strong>Javascript</strong>
|
|
<pre><code class="language-javascript">$('#ex-search').picker({search : true});</code></pre>
|
|
|
|
<h2>Data loading</h2>
|
|
With Picker there are two ways how to handle data loading - automatic and manual.<br>
|
|
Picker will automatically load and "select" options with <code>select</code>
|
|
attribute. This will work for either basic or multiple modes. <br>
|
|
Or you can set your selected options manually through Picker's API via <code>set</code>
|
|
method. More about Picker's API in <a href="#documentation">Documentation section</a>.
|
|
|
|
<div class="well">
|
|
Choose the main city you love:
|
|
<select name="basic" id="ex-data-multiple" 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" class="btn btn-default">Select Cairo city</button>
|
|
<script type="text/javascript">
|
|
$('#ex-data-multiple').picker({containerWidth: 465});
|
|
$('#ex-data-trigger').click(function () {
|
|
$('#ex-data-multiple').picker('set', 12);
|
|
})
|
|
</script>
|
|
</div>
|
|
|
|
<strong>HTML</strong>
|
|
<pre><code class="language-markup"><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>
|
|
</code></pre>
|
|
|
|
<strong id="coloring">Javascript</strong>
|
|
<pre><code class="language-javascript">$('#ex-data-multiple').picker();
|
|
$('#ex-data-trigger').click(function () {
|
|
$('#ex-data-multiple').picker('set', 12);
|
|
})</code></pre>
|
|
|
|
<h2>Coloring</h2>
|
|
|
|
Select Picker has small feature which will let you assign specific classes to
|
|
specific elements based on their option's <code>value</code>. 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.<br>
|
|
Note that this feature applies only to selected options while multiple selection
|
|
mode is selected. Also the classes are applied only to selected options.
|
|
|
|
<div class="well">
|
|
Choose the main city you love:
|
|
<style type="text/css">
|
|
.orange {
|
|
background-color: orange !important;
|
|
}
|
|
|
|
.blue {
|
|
background-color: lightblue !important;
|
|
}
|
|
</style>
|
|
<select name="basic" id="ex-coloring" 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>
|
|
<script type="text/javascript">
|
|
var classes = {
|
|
2: 'orange',
|
|
4: 'blue',
|
|
5: 'orange'
|
|
};
|
|
|
|
$('#ex-coloring').picker({containerWidth: 465, coloring: classes});
|
|
</script>
|
|
</div>
|
|
<pre><code class="language-markup"><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>
|
|
</code></pre>
|
|
|
|
<strong>Javascript</strong>
|
|
<pre><code class="language-javascript">var classes = {
|
|
2 : 'orange',
|
|
4 : 'blue',
|
|
5 : 'orange'
|
|
};
|
|
|
|
$('#ex-coloring').picker({coloring: classes});</code></pre>
|
|
|
|
|
|
<h2>Events</h2>
|
|
|
|
Select Picker has basic support for events. Attach your event listeners to the original
|
|
<code>select</code> element.
|
|
|
|
<div class="well">
|
|
Choose what type of people you like:
|
|
<select name="basic" id="ex-events" multiple>
|
|
<option value="1">Kind</option>
|
|
<option value="2">Easy-going</option>
|
|
<option value="3">Extroverted</option>
|
|
<option value="4">Introvertted</option>
|
|
<option value="5">Ambitious</option>
|
|
<option value="6">Loud</option>
|
|
</select>
|
|
<script type="text/javascript">
|
|
var $elem = $('#ex-events');
|
|
$elem.picker({containerWidth: 410});
|
|
$elem.on('sp-change', function(){
|
|
alert('Great! Thanks for letting me know!');
|
|
});
|
|
</script>
|
|
</div>
|
|
|
|
<strong>HTML</strong>
|
|
<pre><code class="language-markup"><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>
|
|
</code></pre>
|
|
|
|
<strong>JavaScript</strong>
|
|
<pre><code class="language-javascript">var $elem = $('#ex-events');
|
|
$elem.picker();
|
|
$elem.on('sp-change', function(){
|
|
alert('Great! Thanks for letting me know!');
|
|
});</code></pre>
|
|
|
|
</div>
|
|
|
|
<div id="installation">
|
|
<h1>Installation</h1>
|
|
You can install Select Picker in three ways - directly, through Bower and through npm.
|
|
|
|
<h2>Directly</h2>
|
|
To install Select Picker directly download ZIP archive from <a
|
|
href="https://github.com/AuHau/select-picker/archive/master.zip">here</a>, unzip it and
|
|
copy files <code>css/picker.min.css</code> and <code>js/picker.min.js</code> in to your project
|
|
structure.
|
|
|
|
<pre><code class="language-markup"><link rel="stylesheet" href="path/to/file/picker.min.css">
|
|
<script type="text/javascript" src="path/to/file/picker.min.js"></script>
|
|
</code></pre>
|
|
|
|
<h2>Bower</h2>
|
|
To install Select Picker through Bower run following command:
|
|
<div class="well">
|
|
bower install select-picker --save
|
|
</div>
|
|
|
|
<h2>npm</h2>
|
|
To install Select Picker through npm run following command:
|
|
<div class="well">
|
|
npm install select-picker --save
|
|
</div>
|
|
</div>
|
|
|
|
<div id="documentation">
|
|
<h1>Documentation</h1>
|
|
To start using Select Picker, first you have to include required files in your
|
|
HTML page. Basic way is to include in your <code>head</code> tag following part,
|
|
of course with modifying the path to the files
|
|
<pre><code class="language-markup"><link rel="stylesheet" href="css/picker.css">
|
|
<script type="text/javascript" src="js/picker.js"></script></code></pre>
|
|
|
|
Then only thing you need to do is initialize Picker!
|
|
<pre><code class="language-javascript"><script type="text/javascript">
|
|
$(document).ready(function(){
|
|
$('#your-selector').picker();
|
|
});
|
|
</script></code></pre>
|
|
|
|
<h2>Parameters</h2>
|
|
|
|
Picker bring you several parameters with which you can customize your Picker.
|
|
|
|
<h3>autofocusScrollOffset</h3>
|
|
|
|
<div class="well">
|
|
<strong>Type:</strong> Integer<br>
|
|
<strong>Default:</strong> 0 <br>
|
|
<strong>Dependency:</strong> enabled search feature and search auto-focus.
|
|
</div>
|
|
If you need to modify the position to which the window is scrolled to, you can
|
|
set a offset from the Picker, by specifying <code>autofocusScrollOffset</code>.
|
|
|
|
<h3>coloring</h3>
|
|
|
|
<div class="well">
|
|
<strong>Type:</strong> Object<br>
|
|
<strong>Default:</strong> {} <br>
|
|
<strong>Dependency:</strong> multi-selection mode
|
|
</div>
|
|
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 <code>coloring</code>
|
|
parameter.<br>
|
|
Check the <a href="#coloring">example</a> to understand it better.
|
|
|
|
<h3>containerClass</h3>
|
|
|
|
<div class="well">
|
|
<strong>Type:</strong> String<br>
|
|
<strong>Default:</strong> ''
|
|
</div>
|
|
Through <code>containerClass</code> parameter you can specify what class should be
|
|
added to whole Picker wrapping element. It is mostly to be used for specific styling purposes.
|
|
|
|
|
|
<h3>containerWidth</h3>
|
|
|
|
<div class="well">
|
|
<strong>Type:</strong> Integer<br>
|
|
<strong>Default:</strong> none
|
|
</div>
|
|
With <code>containerWidth</code> 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.
|
|
|
|
<h3>limit</h3>
|
|
|
|
<div class="well">
|
|
<strong>Type:</strong> Integer<br>
|
|
<strong>Default:</strong> none <br>
|
|
<strong>Dependency:</strong> multi-selection mode
|
|
</div>
|
|
If you want to limit, how much options can user select in the multi-selection mode,
|
|
can use <code>limit</code> parameter. After reaching the limit, the dropdown will be
|
|
hidden and will be shown again only when user will remove some of the options.
|
|
|
|
<h3>search</h3>
|
|
|
|
<div class="well">
|
|
<strong>Type:</strong> Boolean<br>
|
|
<strong>Default:</strong> false
|
|
</div>
|
|
With this option you can control the search feature. It can be used both with
|
|
single-selection and multi-selection mode.
|
|
|
|
<h3>searchAutofocus</h3>
|
|
|
|
<div class="well">
|
|
<strong>Type:</strong> Boolean<br>
|
|
<strong>Default:</strong> false<br>
|
|
<strong>Dependency:</strong> enabled search feature
|
|
</div>
|
|
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.
|
|
|
|
<h3>texts</h3>
|
|
|
|
<div class="well">
|
|
<strong>Type:</strong> Object<br>
|
|
<strong>Default:</strong> { trigger : "Select value", noResult : "No results", search : "Search" }
|
|
</div>
|
|
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.
|
|
|
|
<h3>width</h3>
|
|
|
|
<div class="well">
|
|
<strong>Type:</strong> Integer<br>
|
|
<strong>Default:</strong> 165 (set via CSS)
|
|
</div>
|
|
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.
|
|
|
|
<h2>API</h2>
|
|
|
|
Select Picker has also basic API to modify already initialized Picker.<br>
|
|
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.
|
|
|
|
<pre><code class="language-javascript">$('.multiple-used-class').picker(); // Will work
|
|
$('.multiple-used-class').picker('set', 2); // Will work
|
|
$('.multiple-used-class').picker('get'); // Won't work</code></pre>
|
|
|
|
<h3>$('...').picker('destroy');</h3>
|
|
|
|
<div class="well">
|
|
<strong>Parameters:</strong> none<br>
|
|
<strong>Return:</strong> original jQuery selector
|
|
</div>
|
|
This method will remove all Pickers elements and display original select box.
|
|
|
|
|
|
<h3>$('...').picker('get');</h3>
|
|
|
|
<div class="well">
|
|
<strong>Parameters:</strong> none<br>
|
|
<strong>Return:</strong> string/array - actually selected value(s)
|
|
</div>
|
|
This method will return actually selected values of single Picker.<br>
|
|
<strong>This method has to be called from single-element selector!</strong>
|
|
|
|
<h3>$('...').picker('set', id);</h3>
|
|
|
|
<div class="well">
|
|
<strong>Parameters:</strong> id - string<br>
|
|
<strong>Return:</strong> original jQuery selector
|
|
</div>
|
|
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.
|
|
|
|
<h3>$('...').picker('remove', id);</h3>
|
|
|
|
<div class="well">
|
|
<strong>Parameters:</strong> id - string<br>
|
|
<strong>Return:</strong> original jQuery selector
|
|
</div>
|
|
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.
|
|
|
|
<div class="mastfoot">
|
|
<p>Created by <a href="http://www.adam-uhlir.me">Adam Uhlíř</a> © 2016</p>
|
|
</div>
|
|
|
|
<h2>Events</h2>
|
|
|
|
Select Picker has currently basic support for events. Any suggestions for extending currently supported events
|
|
will be very much welcomed.
|
|
|
|
<table class="table">
|
|
<tr>
|
|
<th>Name of event</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>sp-change</strong></td>
|
|
<td>Triggered when some element is chosen (in single mode)<br> or add/removed (in multiple mode).</td>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>sp-open</strong></td>
|
|
<td>Triggered when is the dropdown menu opened.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><strong>sp-close</strong></td>
|
|
<td>Triggered when is the dropdown menu closed.</td>
|
|
</tr>
|
|
</table>
|
|
|
|
</div>
|
|
</div>
|
|
<script>
|
|
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
|
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
|
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
|
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
|
|
|
|
ga('create', 'UA-69554274-1', 'auto');
|
|
ga('send', 'pageview');
|
|
|
|
</script>
|
|
</body>
|
|
</html>
|