propertyhive / assets / js / multiselect / README.md

README.md in Property Hive 2.3.1, at assets/js/multiselect/README.md

209 lines 7.4 KB

Raw Download Zip

1	jQuery MultiSelect
2	==================
3
4	Turn a multiselect list into a nice and easy to use list with checkboxes. This plugin is simply an alternative interface for the native select list element. When you check an option in the plugin the value is selected on the native list. This allows the value to be submitted in a form as well as retreived through normal POST/GET and javascript methods.
5
6	## Support
7	I only provide limited support through the Github Issues area. DO NOT ask for support via email, socialmedia, or other means. Also check the closed issues before opening a new issue.
8
9	## Design Methodology
10	This plugin is not meant to be a full featured multiselect plugin. I envision this as a multiselect plugin that contains a base set of features that can be enhanced using callbacks by the developer. Because of this I am hesitant on adding functionality but am open to adding callbacks where it makes sense. But feel free to open an [](https://github.com/nobleclem/jQuery-MultiSelect/issuesissue](https://github.com/nobleclem/jQuery-MultiSelect/issues](https://github.com/nobleclem/jQuery-MultiSelect/issues) and suggest a feature request if you feel that most people will benefit from it.
11
12	## Demo
13	http://springstubbe.us/projects/jquery-multiselect/
14
15	## Usage
16	```
17	// BASIC
18	$('select[multiple]').multiselect();
19
20	// 4 COLUMNS with custom placeholder text
21	$('select[multiple]').multiselect({
22	columns: 4,
23	texts: {
24	placeholder: 'Select options'
25	}
26	});
27
28	// RELOAD multiselect (in case you modify options or selected options in the native select list since loading the plugin)
29	$('select[multiple]').multiselect('reload');
30
31	// DYNAMICALLY LOAD OPTIONS
32	$('select[multiple]').multiselect( 'loadOptions', [{
33	name : 'Option Name 1',
34	value : 'option-value-1',
35	checked: false,
36	attributes : {
37	custom1: 'value1',
38	custom2: 'value2'
39	}
40	},{
41	name : 'Option Name 2',
42	value : 'option-value-2',
43	checked: false,
44	attributes : {
45	custom1: 'value1',
46	custom2: 'value2'
47	}
48	}]);
49	```
50
51
52	### Options
53	\| Option \| Values \| Default \| Description \|
54	\| ------------------- \| -------- \| -------------- \| ------------------------------ \|
55	\| columns \| int \| 1 \| # of columns to show options \|
56	\| search \| bool \| false \| enable option search/filering \|
57	\| searchOptions \| object \| \| \|
58	\| - delay \| int \| 250 \| time (in ms) between keystrokes until search happens \|
59	\| - showOptGroups \| bool \| false \| show option group titles if no options remaining \|
60	\| - searchText \| bool \| true \| search within option text \|
61	\| - searchValue \| bool \| false \| search within option value \|
62	\| - onSearch \| function \| \| fires before search on options happens \|
63	\| texts \| object \| \| \|
64	\| - placeholder \| string \| Select options \| default text for dropdown \|
65	\| - search \| string \| Search \| search input placeholder text \|
66	\| - selectedOptions \| string \| selected \| selected suffix text \|
67	\| - selectAll \| string \| Select all \| select all text \|
68	\| - unselectAll \| string \| Unselect all \| unselect all text \|
69	\| - noneSelected \| string \| None Selected \| None selected text \|
70	\| selectAll \| bool \| false \| add select all option \|
71	\| selectGroup \| bool \| false \| add select all optgroup option \|
72	\| minHeight \| number \| 200 \| min height of option overlay \|
73	\| maxHeight \| number \| null \| max height of option overlay \|
74	\| maxWidth \| number \| null \| maximum width of option overlay (or selector) \|
75	\| maxPlaceholderWidth \| number \| null \| maximum width of placeholder button \|
76	\| maxPlaceholderOpts \| number \| 10 \| maximum number of placeholder options to show until "# selected" shown instead \|
77	\| showCheckbox \| bool \| true \| display the option checkbox \|
78	\| checkboxAutoFit \| bool \| false \| auto calc space requirements for checkbox instead of css padding on label \|
79	\| onLoad \| function \| \| fires at end of initial loading, hides native select list \|
80	\| onOptionClick \| function \| \| fires after on option is clicked \|
81	\| onControlClose \| function \| \| fires when the options list is closed \|
82	\| onSelectAll \| function \| \| fires when (un)select all is clicked \|
83	\| onPlaceholder \| function \| \| fires when the placeholder txt is updated \|
84	\| optionAttributes \| array \| \| array of attribute keys to copy to the checkbox input \|
85
86
87	### Methods
88	loadOptions( options, overwrite, updateSelect )
89
90	Update options of select list. Default state will replace existing list with this one.
91	- Set the second parameter to `false` to append to the list. (default = true)
92	- Set the third parameter to `false` to leave the native select list as is. (default = true)
93
94	This will NOT modify the original select list element.
95	```
96	$('select[multiple]').multiselect( 'loadOptions', [{
97	name : 'Option Name 1',
98	value : 'option-value-1',
99	checked: false
100	},{
101	name : 'Option Name 2',
102	value : 'option-value-2',
103	checked: false
104	}]);
105	```
106
107
108	settings
109
110	Update Multiselect list settings after it has been rendered. It accepts the same [](https://github.com/nobleclem/jQuery-MultiSelect#optionsoptions](https://github.com/nobleclem/jQuery-MultiSelect#options](https://github.com/nobleclem/jQuery-MultiSelect#options) listed above.
111
112	This will reload the plugin for the select list it references
113
114	`$('select[multiple]').multiselect( 'settings', {
115	columns: 2
116	});`
117
118	unload
119
120	Disable the jquery multiselect list and show the native select list.
121
122	This is distructive. You will have to reinitialize with all options to enable the plugin for the list.
123
124	`$('select[multiple]').multiselect( 'unload' );`
125
126
127	reload
128
129	This is a quick unload/load while maintaining options during plugin initialization.
130
131	`$('select[multiple]').multiselect( 'reload' );`
132
133
134	reset
135
136	Reset the element back to its default selected values.
137
138	`$('select[multiple]').multiselect( 'reset' );`
139
140
141	disable
142
143	Disable or enable the select list. If no second parameter is passed then true is assumed.
144
145	`$('select[multiple]').multiselect( 'disable', true );`
146	`$('select[multiple]').multiselect( 'disable', false );`
147
148
149	### Callbacks
150	onLoad
151
152	Fires after initial loading and hides native select list
153
154	`onLoad( element )`
155
156	element: select list element object
157
158
159	onOptionClick
160
161	Fires after an option is clicked
162
163	`onOptionClick( element, option )`
164
165	element: select list element object
166
167	option: option element object
168
169
170	onControlClose
171
172	Fires when the options list is closed
173
174	`onControlClose( element )`
175
176	element: select list element object
177
178
179	onSelectAll
180
181	Fires when (un)select all is clicked
182
183	`onSelectAll( element, selected )`
184
185	element: select list element object
186
187	selected: the total number of options selected
188
189	onPlaceholder
190
191	Fires when the placeholder txt is updated (only fires if there are selected options)
192
193	`onPlaceholder( element, placeholder, selectedOpts )`
194
195	element: select list element object
196
197	placeholder: placeholder element object
198
199	selectedOpts: selected options
200
201
202	onSearch
203
204	Fires before search on options happens
205
206	`searchOptions.onSearch( element )`
207
208	element: select list element object
209