istvan-ujjmeszaros / bootstrap-duallistbox
A responsive dual listbox widget optimized for Twitter Bootstrap. It works on all modern browsers and on touch devices.
Installs: 159 335
Dependents: 4
Suggesters: 0
Security: 0
Stars: 624
Watchers: 41
Forks: 262
Open Issues: 124
Language:JavaScript
Suggests
- components/jquery: 2.0.*
- twbs/bootstrap: 3.*
This package is not auto-updated.
Last update: 2024-12-18 09:44:23 UTC
README
Bootstrap Dual Listbox is a responsive dual listbox widget optimized for Twitter Bootstrap. Works on all modern browsers and on touch devices.
Check the official website for a demo.
Usage
- Download the latest tag from the releases page or get it via bower:
$ bower install bootstrap-duallistbox
- Include jQuery and Bootstrap:
<link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/css/bootstrap.min.css" integrity="sha384-Gn5384xqQ1aoWXA+058RXPxPg6fy4IWvTNh0E263XmFcJlSAwiGgFAW/dAiS6JXm" crossorigin="anonymous"> <script src="https://code.jquery.com/jquery-3.2.1.slim.min.js" integrity="sha384-KJ3o2DKtIkvYIK3UENzmM7KCkRr/rE9/Qpg6aAZGJwFDMVNA/GpGFF93hXpG5KkN" crossorigin="anonymous"></script> <script src="https://cdnjs.cloudflare.com/ajax/libs/popper.js/1.12.9/umd/popper.min.js" integrity="sha384-ApNbgh9B+Y1QKtv3Rn7W3mgPxhU9K/ScQsAP7hUibX39j7fakFPskvXusvfa0b4Q" crossorigin="anonymous"></script> <script src="https://maxcdn.bootstrapcdn.com/bootstrap/4.0.0/js/bootstrap.min.js" integrity="sha384-JZR6Spejh4U02d8jOt6vLEHfe/JQGiRRSQQxSfFWpi1MquVdAyjUar5+76PVCmYl" crossorigin="anonymous"></script>
- Include plugin's code:
<script src="dist/jquery.bootstrap-duallistbox.min.js"></script> <link rel="stylesheet" type="text/css" href="../src/bootstrap-duallistbox.css">
- Call the plugin:
$("#element").bootstrapDualListbox({ // see next for specifications });
Specifications
Initialization parameters object
When calling $("#element").bootstrapDualListbox()
you can pass a parameters object with zero or more of the following:
bootstrap2Compatible
, defaults tofalse
, set this totrue
if you want graphic compatibility with Bootstrap 2.bootstrap3Compatible
, defaults tofalse
, set this totrue
if you want graphic compatibility with Bootstrap 3.filterTextClear
, defaults to'show all'
, is the text for the "Show All" button.filterPlaceHolder
, defaults to'Filter'
, is the placeholder for theinput
element for filtering elements.moveSelectedLabel
, defaults to'Move selected'
, is the label for the "Move Selected" button.moveAllLabel
, defaults to'Move all'
, is the label for the "Move All" button.removeSelectedLabel
, defaults to'Remove selected'
, is the label for the "Remove Selected" button.removeAllLabel
, defaults to'Remove all'
, is the label for the "Remove All" button.moveOnSelect
, defaults totrue
, determines whether to moveoption
s upon selection. This option is forced totrue
on the Android browser.moveOnDoubleClick
, defaults totrue
, determines whether to moveoption
s upon double click. This option is not used on the Android browser.preserveSelectionOnMove
, can be'all'
(for selecting both moved elements and the already selected ones in the target list) or'moved'
(for selecting moved elements only); defaults tofalse
.selectedListLabel
, defaults tofalse
, can be astring
specifying the name of the selected list.nonSelectedListLabel
, defaults tofalse
, can be astring
specifying the name of the non selected list.helperSelectNamePostfix
, defaults to'_helper'
. The addedselect
s will have the same name as the original one, concatenated with thisstring
and1
(for the non selected list, e.g.element_helper1
) or2
(for the selected list, e.g.element_helper2
).selectorMinimalHeight
, defaults to100
, represents the minimal height of the generated dual listbox.showFilterInputs
, defaults totrue
, whether to show filter inputs.nonSelectedFilter
, defaults to the empty string''
, initializes the dual listbox with a filter for the non selected elements. This is applied only ifshowFilterInputs
is set totrue
.selectedFilter
, defaults to the empty string''
, initializes the dual listbox with a filter for the selected elements. This is applied only ifshowFilterInputs
is set totrue
.infoText
, defaults to'Showing all {0}'
, determines whichstring
format to use when all options are visible. Set this tofalse
to hide this information. Remember to insert the{0}
placeholder.infoTextFiltered
, defaults to'<span class="label label-warning">Filtered</span> {0} from {1}'
, determines which element format to use when some element is filtered. Remember to insert the{0}
and{1}
placeholders.infoTextEmpty
, defaults to'Empty list'
, determines thestring
to use when there are no options in the list.filterOnValues
, defaults tofalse
, set this totrue
to filter theoption
s according to theirvalue
s and not their HTML contents.iconsPrefix
, defaults tooi
, set it to whichever prefix your icon family uses.iconMove
, defaults tooi-arrow-thick-right
, sets the class for the move icon.iconRemove
, defaults tooi-arrow-thick-left
, sets the class for the remove icon.
Methods
You can modify the behavior and aspect of the dual listbox by calling its methods, all of which accept a value
and a refresh
option. The value
determines the new parameter value, while refresh
(optional, defaults to false
) tells whether to update the plugin UI or not.
To call methods on the dual listbox instance, use the following syntax:
$(selector).bootstrapDualListbox(methodName, parameter);
Note: when making multiple chained calls to the plugin, set refresh
to true
to the last call only, in order to make a unique UI change; alternatively, you can also call the refresh
method as your last one.
Here are the available methods:
setBootstrap2Compatible(value, refresh)
to change thebootstrap2Compatible
parameter.setBootstrap3Compatible(value, refresh)
to change thebootstrap3Compatible
parameter.setFilterTextClear(value, refresh)
to change thefilterTextClear
parameter.setFilterPlaceHolder(value, refresh)
to change thefilterPlaceHolder
parameter.setMoveSelectedLabel(value, refresh)
to change themoveSelectedLabel
parameter.setMoveAllLabel(value, refresh)
to change themoveAllLabel
parameter.setRemoveSelectedLabel(value, refresh)
to change theremoveSelectedLabel
parameter.setRemoveAllLabel(value, refresh)
to change theremoveAllLabel
parameter.setMoveOnSelect(value, refresh)
to change themoveOnSelect
parameter.setMoveOnDoubleClick(value, refresh)
to change themoveOnDoubleClick
parameter.setPreserveSelectionOnMove(value, refresh)
to change thepreserveSelectionOnMove
parameter.setSelectedListLabel(value, refresh)
to change theselectedListLabel
parameter.setNonSelectedListLabel(value, refresh)
to change thenonSelectedListLabel
parameter.setHelperSelectNamePostfix(value, refresh)
to change thehelperSelectNamePostfix
parameter.setSelectOrMinimalHeight(value, refresh)
to change theselectorMinimalHeight
parameter.setShowFilterInputs(value, refresh)
to change theshowFilterInputs
parameter.setNonSelectedFilter(value, refresh)
to change thenonSelectedFilter
parameter.setSelectedFilter(value, refresh)
to change theselectedFilter
parameter.setInfoText(value, refresh)
to change theinfoText
parameter.setInfoTextFiltered(value, refresh)
to change theinfoTextFiltered
parameter.setInfoTextEmpty(value, refresh)
to change theinfoTextEmpty
parameter.setFilterOnValues(value, refresh)
to change thefilterOnValues
parameter.
Furthermore, you can call:
refresh()
ortrigger
thebootstrapDualListbox.refresh
event to update the plugin element UI.destroy()
to restore the originalselect
element and delete the plugin element.getContainer()
to get the container element.
Structure
The basic structure of the project is given in the following way:
├── demo/
│ └── index.html
├── dist/
│ ├── bootstrap-duallistbox.css
│ ├── bootstrap-duallistbox.min.css
│ ├── jquery.bootstrap-duallistbox.js
│ └── jquery.bootstrap-duallistbox.min.js
├── src/
│ ├── bootstrap-duallistbox.css
│ └── jquery.bootstrap-duallistbox.js
├── .editorconfig
├── .gitignore
├── .jshintrc
├── .travis.yml
├── bootstrap-duallistbox.jquery.json
├── bower.json
├── Gruntfile.js
└── package.json
demo/
Contains a simple HTML file to demonstrate your plugin.
dist/
This is where the generated files are stored once Grunt runs.
src/
Contains the source files, both js
and css
.
.editorconfig
This file is for unifying the coding style for different editors and IDEs.
Check editorconfig.org if you haven't heard about this project yet.
.gitignore
List of files that we don't want Git to track.
Check this Git Ignoring Files Guide for more details.
.jshintrc
List of rules used by JSHint to detect errors and potential problems in JavaScript.
Check jshint.com if you haven't heard about this project yet.
.travis.yml
Definitions for continous integration using Travis.
Check travis-ci.org if you haven't heard about this project yet.
bootstrap-duallistbox.jquery.json
Package manifest file used to publish plugins in jQuery Plugin Registry.
Check this Package Manifest Guide for more details.
Gruntfile.js
Contains all automated tasks using Grunt.
Check gruntjs.com if you haven't heard about this project yet.
package.json
Specify all dependencies loaded via Node.JS.
Check NPM for more details.
Building
To build and test the plugin, you need:
- NodeJS with npm
- bower (install it with
npm install bower --g
) - grunt-cli (install it with
npm install grunt-cli --g
)
Then, cd
to the project directory and install the required dependencies:
$ npm install $ bower install
To run jshint on the plugin code, call:
$ grunt jshint
To build the output js and css files, with the related minified ones, run:
$ grunt
Issues and Contributions
You can report any issue you may encounter on the GitHub Issue Tracker.
To contribute, please follow the contribution guidelines.
History
Check Release list.
License
Copyright 2013-2014 István Ujj-Mészáros
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.