Skip to content

jQuery-based custom select control, represents options as paginated grid, features search and filter by first letter.

License

Notifications You must be signed in to change notification settings

ukrbublik/grisel

Repository files navigation

grisel

grisel (GRId_SELect) is a custom multi- or single-select control (over standard <select>).
Represents options as paginated grid.
Features search and filter by first letter.
Customizable. Has cool animations. Useful for big list of options.
Built on top of jQuery.

How it looks:


Getting started:

1) Include this JS/CSS:
<script src="vendor/jquery-1.11.3.js"></script>
<script src="vendor/jquery.easing.1.3.2.js"></script>
<script src="src/js/grisel.js"></script>

2) Add class "grisel" to <select>'s you want to convert.
3) Customize options. Example:
<script>
grisel.defaultOptions = jQuery.extend(grisel.defaultOptions, {
	//options to override, see list below
});
grisel.optionsBySelId = {
	's_street': {
		//options to override for select '#s_street' 
	}
};
grisel.optionsBySelClass = {
	//...
};
grisel.defaultLang = 'en';
grisel.defaultStrings = jQuery.extend(grisel.defaultStrings, {
	'en': {
		//default strings in english
	}
});
grisel.stringsBySelId = {
	's_street': {
		'en': {
			//strings for '#s_street' in english
		}
	},
};
grisel.stringsBySelClass = {
	//...
};
</script>
Also you can override options for particular <select> by using "data-*". Example: <select class="grisel" data-div-popup-width="500">...</selec>

Notes:

Popup can be in extended view (with search and filter by first char) or compact - see options isExt, minPagesForExt.
Options list can contain special "any"-option, to be able to select all/any values by one click (and send to server), see options anyVal, hideAny.

Options:

KeyDescriptionDefault value
General
gridRowsNumber of options rows in grid5
gridColumnsNumber of options columns in grid3
minPagesForExtIf list of options has pages >= this value, popup will be in extended view mode (with search and filter by first char)3
isExtShow popup in extended view mode?
-1 for auto applying extended mode (by option minPagesForExt), 1/0 to force extended mode on/off
-1
anyValValue attribute of special <oprion> "All values" (or "Any value") (if there is one in options)'a-n-y'
hideAnyHide special "any"-option?false
gridDirectionHorizontalHow options should be filled in grid?
1 - fill items in left-to-right direction (horizontal) (in html group by rows), 0 - up-to-down direction (vertical) (in html group by cols)
false
useRowsStyleForVerticalDirection1 - force group by rows (not cols) in html for vertical direction (to make all elements in one row having equal height)
1 is highly recommended (also because of animation problems with cols)
true
openOnHover1 - open popup by hover on selector, 0 - open by clickfalse
areInnerCtrlsFocuableAdd tabindex attribute for all controls (options, inputs, buttons) in popup?false
maxCntToShowListAsValStrFor example. When set to 4: for 5+ selected values selector text will be "X values", for 1-4 - "valA, valB, valC, valD", for 0 - one of allStr/anyStr/allStrDefault.
When set to -1: always "X values"
3
Show/hide elements
showPagesListtrue
showSearchtrue
showIndextrue
showControlstrue
hidePageControlsWhenThereIsPageListtrue
showCtrlSaveSelectiontrue
showCtrlShowSelectiontrue
showCtrlGotoSelectiontrue
showCtrlClearAlltrue
showCloseCrosstrue
Sizes
divSelWidth-2 - equal to <select>'s width, -1 - equal to wrapper's width, 0 - auto, > 0 - concrete width0
divSelHeight-2 - equal to <select>'s height, -1 - equal to wrapper's height, 0 - auto, > 0 - concrete height0
divSelPaddingLeftLeft padding of selector's text, in px8
divSelIsMultilineShow selector's text as multiline?false
divSelClassesOptional list of classes for selector divided by ' '''
divPopupWidth-2 - equal to wrapper's width, -1 - equal to sel's width, 0 - auto, > 0 - concrete width0
divPopupHeight0 - use css, > 0 - concrete height0
divPopupLabelsMinWidthFor auto popup width - set min checkbox/radio's labels width0
divPopupClassesOptional list of classes for popup win divided by ' '''
divWrapperClassesOptional list of classes for selector's wrapper divided by ' '''
tryToKeepConstPopupHeightWhen page with long labels appeared, keep new bigger popup height for all other pagestrue
reserveForPopupHeightReserve (once) more height for popup (for case of appearing long labels at next pages), in px0
Animation
animatePopupDurationDuration in ms for open & close animations[600, 400]
isElasticPopupAnimationIs animation elastic for open & close? If yes, some tricks will be applied for smoother animation[1, 0]
animatePopupEasingEasing function names for open & close animations['easeOutElastic', 'easeInOutBack']
animatePageDurationDuration of animation of switching pages150
animatePageEasingEasing function name of animation of switching pages'swing'
"Legacy" options (made for dom-plus.ua)
flushSearchStringAfterSelectionWhen using search, clear search string after every selectionfalse
showSelectedItemsWhenNoFoundWhen using search and no options found, show selected items anywayfalse
showSelectedItemsFirstIn options list show selected items first, but after "any"-optionfalse
maxSelectionLimitOnly for showSelectedItemsFirst==1. If count of selected items > this value, warning (see string "maxSelectionMsg") will be shown0

Strings:

KeyDescriptionDefault value for english
indexAllFirst button in index by first char, which clears filter by first char'All'
ctrlSaveSelectionButton that closes popup, like 'X' at bottom-right'Save'
ctrlGotoSelectionButton to goto page with selected option (for single-select)'Go to selected'
ctrlShowSelectionButton to show only selected options'Show selected'
ctrlClearAllButton to clear selection. First for multi-select, second for single-select['Clear all', 'Clear selection']
allStrSelector text when all options are selected, for overriding in 'stringsBySelId', 'stringsBySelClass'''
allStrDefaultDefault selector text when all options are selected. First for multi-select, second for single-select['All', 'Any']
noSelectionMsgText when no option is selected. Only for option hideAny == 1'No selected'
noResultsMsgText when filter gaven't any results'Nothing found'
inputPlaceholderPlaceholder text for search input'Enter a name'
cntFmtTemplate to format selector text'{cnt} {cnt_name}'
cntNamesDeclensions of word 'value': for english - [singular, plural, plural], for russian - [ед.им., ед.род., мн.род.]['value', 'values', 'values']
maxSelectionMsgOnly for option maxSelectionLimit > 0 ("legacy").
Warning text when count of selected items > maxSelectionLimit
'You reached max number of selected elements.<br>Please save your selection'

Examples:

See demo.html

Browsers support:

Requires browser with CSS3 support (for flex).