ng-jvx-multiselect 19.0.35 → 19.0.36
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +366 -366
- package/_index.scss +1 -1
- package/fesm2022/ng-jvx-multiselect.mjs +39 -112
- package/fesm2022/ng-jvx-multiselect.mjs.map +1 -1
- package/lib/chiplist/chip/chip.component.d.ts +2 -0
- package/lib/directives/ng-jvx-disabled-option.directive.d.ts +1 -1
- package/lib/directives/ng-jvx-focus.directive.d.ts +1 -1
- package/lib/directives/ng-jvx-group-header.directive.d.ts +1 -1
- package/lib/directives/ng-jvx-options-template.directive.d.ts +1 -1
- package/lib/directives/ng-jvx-selection-template.directive.d.ts +1 -1
- package/lib/ng-jvx-multiselect.component.d.ts +8 -10
- package/lib/ng-jvx-option/ng-jvx-option.component.d.ts +1 -1
- package/lib/panel/menu-trigger/menu-trigger.directive.d.ts +1 -1
- package/package.json +1 -1
- package/public-api.d.ts +0 -1
- package/src/lib/chiplist/chip/chip.component.scss +32 -32
- package/src/lib/mixins.scss +6 -6
- package/src/lib/ng-jvx-multiselect.component.scss +172 -172
- package/src/lib/ng-jvx-option/ng-jvx-option.component.scss +32 -32
- package/src/lib/panel/panel.component.scss +11 -11
- package/lib/ng-jvx-multiselect.module.d.ts +0 -20
package/README.md
CHANGED
|
@@ -1,366 +1,366 @@
|
|
|
1
|
-
# NgJvxMultiselect
|
|
2
|
-
|
|
3
|
-
ng-jvx-multiselect is a select based on angular. It handles both single and multiple selections and allows to
|
|
4
|
-
retrieves the options via asynchronous calls.
|
|
5
|
-
|
|
6
|
-
## Install ng-jvx-multiselect
|
|
7
|
-
|
|
8
|
-
```
|
|
9
|
-
npm install ng-jvx-multiselect --save
|
|
10
|
-
```
|
|
11
|
-
|
|
12
|
-
In <b>app.module.ts</b>
|
|
13
|
-
|
|
14
|
-
```typescript
|
|
15
|
-
import {NgJvxMultiselectModule} from 'ng-jvx-multiselect';
|
|
16
|
-
|
|
17
|
-
@NgModule({
|
|
18
|
-
imports: [
|
|
19
|
-
NgJvxMultiselectModule
|
|
20
|
-
]
|
|
21
|
-
})
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
In <b>styles.scss</b>
|
|
25
|
-
|
|
26
|
-
```scss
|
|
27
|
-
@use 'index' as ng-jvx-multiselect;
|
|
28
|
-
|
|
29
|
-
:root {
|
|
30
|
-
--jvx-multiselect-primary: #008000;
|
|
31
|
-
--jvx-multiselect-accent: #0000FF;
|
|
32
|
-
--jvx-multiselect-warn: #FF0000;
|
|
33
|
-
--jvx-multiselect-on-primary: #ffffff;
|
|
34
|
-
--jvx-multiselect-on-accent: currentcolor;
|
|
35
|
-
--jvx-multiselect-on-warn: currentcolor;
|
|
36
|
-
--jvx-multiselect-panel-bg: #FFFFFF
|
|
37
|
-
}
|
|
38
|
-
```
|
|
39
|
-
In <b>example.component.html</b>
|
|
40
|
-
|
|
41
|
-
```angular2html
|
|
42
|
-
<ng-jvx-multiselect style="width: 100%" [options]="options">
|
|
43
|
-
<ng-container placeholder>
|
|
44
|
-
this is a placeholder
|
|
45
|
-
</ng-container>
|
|
46
|
-
</ng-jvx-multiselect>
|
|
47
|
-
```
|
|
48
|
-
In <b>example.component.ts</b>
|
|
49
|
-
|
|
50
|
-
```typescript
|
|
51
|
-
public options = [
|
|
52
|
-
{value: 1, text: 'text 1'},
|
|
53
|
-
{value: 2, text: 'text 2'},
|
|
54
|
-
{value: 3, text: 'text 3'},
|
|
55
|
-
{value: 4, text: 'text 4'},
|
|
56
|
-
{value: 5, text: 'text 5'},
|
|
57
|
-
{value: 6, text: 'text 6'},
|
|
58
|
-
{value: 7, text: 'text 7'},
|
|
59
|
-
{value: 8, text: 'text 8'},
|
|
60
|
-
{value: 9, text: 'text 9'},
|
|
61
|
-
{value: 10, text: 'text 10'}];
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
## API
|
|
66
|
-
|
|
67
|
-
### Slots
|
|
68
|
-
|
|
69
|
-
| Name | Description |
|
|
70
|
-
|---------------|------------------------------------------------------------------------------------------------------------|
|
|
71
|
-
| `default` | Using the default slot is one way of defining the options via the component `<ng-jvx-option>`. |
|
|
72
|
-
| `placeholder` | This slot allows the user to define a placeholder which will be displayed when no selection has been made. |
|
|
73
|
-
|
|
74
|
-
### Inputs
|
|
75
|
-
|
|
76
|
-
| Name | Type | Default | Description |
|
|
77
|
-
|------------------|----------------------------------------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
78
|
-
| `clearable` | `Boolean` | `false` | True to enable the empty selection. |
|
|
79
|
-
| `closeButton` | `Boolean` | `false` | True to show the button that closes the menu. |
|
|
80
|
-
| `disabled` | `Boolean` | `false` | True to disable the select. |
|
|
81
|
-
| `itemText` | `String` | `'text'` | The name of the property of the option object that will be displayed as description of the options. |
|
|
82
|
-
| `itemValue` | `String` | `'value'` | The name of the property of the option object that will be treated as value of the options. |
|
|
83
|
-
| `multi` | `Boolean` | `false` | True if it's a multiselect. |
|
|
84
|
-
| `options` | `Array` | `[]` | Array of option objects. |
|
|
85
|
-
| `requestHeaders` | `Object` | `{...}` | The headers of the HTTP request. |
|
|
86
|
-
| `requestType` | <code>'GET'|'POST'</code> | `'GET'` | The type of the HTTP request. |
|
|
87
|
-
| `postPayload` | `Object` | {} | Sets the payload for the post request. |
|
|
88
|
-
| `searchInput` | `Boolean` | `false` | True to enable the search input for the options list. |
|
|
89
|
-
| `searchMode` | <code>'client'|'server'</code> | `server` | `'client'` if the search is only client side, `'server'` if it's server side. |
|
|
90
|
-
| `searchLabel` | `String` | `'search'` | The label of the search input. |
|
|
91
|
-
| `searchProp` | `String` | `'search'` | The name of the search property of the HTTP request. |
|
|
92
|
-
| `listProp` | `String` | `''` | Name of the property in response.data where the list is stored. |
|
|
93
|
-
| `url` | `String` | `''` | The url to get the options. |
|
|
94
|
-
| `value` | `Array` | `[]` | The current value of the selection. |
|
|
95
|
-
| `mapper` | `NgJvxOptionMapper` | `*` | The object that will map the response of the async call. |
|
|
96
|
-
| `searchMapper` | `NgJvxSearchMapper` | `*` | The object that will map the client search result. |
|
|
97
|
-
| `pageSize` | `number` | `15` | The size of a page for pagination purposes. |
|
|
98
|
-
| `groupBy` | <code>NgJvxGroupMapper<any>|string|null</code> | `null` | If it's a `string` it defines the the property of each option by which group them in the list. If it's a `NgJvxGroupMapper` it offers a method that groups the options (useful for nested properties). |
|
|
99
|
-
|
|
100
|
-
### Methods
|
|
101
|
-
|
|
102
|
-
*None*
|
|
103
|
-
|
|
104
|
-
### Events
|
|
105
|
-
|
|
106
|
-
| Event Name | Detail | Description |
|
|
107
|
-
|---------------|---------|-----------------------------------------------------------------------------------------------------|
|
|
108
|
-
| `valueChange` | `Array` | Fired when the user changes the value of the input. The detail contains the value of the selection. |
|
|
109
|
-
| `scrollEnd` | *None* | Fired when the scrollbar in the options menu reaches the bottom. |
|
|
110
|
-
| `open` | *None* | Fired when the the menu starts opening. |
|
|
111
|
-
| `opened` | *None* | Fired when the the menu is opened. |
|
|
112
|
-
| `close` | *None* | Fired when the the menu starts closing. |
|
|
113
|
-
| `closed` | *None* | Fired when the the menu is closed. |
|
|
114
|
-
|
|
115
|
-
### Groups
|
|
116
|
-
|
|
117
|
-
It is possible to collect the options in groups. To do so the user can set the property `groupBy` with the name of the property they want to group the options by.
|
|
118
|
-
If the property is nested or the user wants to implement a more complex grouping algorithm, they set the property `groupBy` with an object that implements the interface `NgJvxGroupMapper<T>`.
|
|
119
|
-
This object offers the method
|
|
120
|
-
```typescript
|
|
121
|
-
mapGroup(option: T): Observable<NgJvxGroup<T>>
|
|
122
|
-
```
|
|
123
|
-
with
|
|
124
|
-
```typescript
|
|
125
|
-
interface NgJvxGroup<T> {
|
|
126
|
-
group: string;
|
|
127
|
-
option: T;
|
|
128
|
-
}
|
|
129
|
-
```
|
|
130
|
-
The `mapGroup` method hence takes the option and wraps it in an object that defines the name of the group it belongs to.
|
|
131
|
-
It is possible to define the look of the headers of the groups with the directive [*ngJvxGroupHeaderTemplate](#ngjvxgroupheadertemplate)
|
|
132
|
-
### HTTP Request
|
|
133
|
-
|
|
134
|
-
#### Request
|
|
135
|
-
|
|
136
|
-
The HTTP request can be either a GET or a POST request. The user can set the type using the property `requestType` which
|
|
137
|
-
is set to `'GET'` by default.
|
|
138
|
-
|
|
139
|
-
##### Headers
|
|
140
|
-
|
|
141
|
-
The headers can be set in the property `requestHeaders`. By default the ng-jvx-multiselect uses the property `trusted`
|
|
142
|
-
stored in the sessionStorage. The default headers are:
|
|
143
|
-
|
|
144
|
-
```javascript
|
|
145
|
-
var requestHeaders = {
|
|
146
|
-
'Accept': 'application/json',
|
|
147
|
-
'Access-Control-Allow-Origin': '*',
|
|
148
|
-
'Access-Control-Allow-Methods': 'GET, PUT, POST, DELETE, OPTIONS',
|
|
149
|
-
'Content-Type': 'application/json',
|
|
150
|
-
'Authorization': window.sessionStorage.getItem('trusted')
|
|
151
|
-
}
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
#### Response
|
|
155
|
-
|
|
156
|
-
The response must contain an array of elements.
|
|
157
|
-
|
|
158
|
-
The property `listProp` defines the path of the array in the response object (i.e. if `listProp` is set to `list` the
|
|
159
|
-
ng-jvx-multiselect will get the options in the array stored in the path `response.list`).
|
|
160
|
-
|
|
161
|
-
#### Mapper
|
|
162
|
-
|
|
163
|
-
The `mapper` property will be an object implementing the interface `NgJvxOptionMapper<T>`. It will expose a
|
|
164
|
-
method `mapOption` which accepts the option to be mapped in the form of an Object and returns an Observable of type `T`.
|
|
165
|
-
For example if the request returns an array of objects like this:
|
|
166
|
-
|
|
167
|
-
```javascript
|
|
168
|
-
{
|
|
169
|
-
id: number;
|
|
170
|
-
description: string;
|
|
171
|
-
}
|
|
172
|
-
```
|
|
173
|
-
|
|
174
|
-
it is possible to write a mapper like this:
|
|
175
|
-
|
|
176
|
-
```javascript
|
|
177
|
-
const mapper: NgJvxOptionMapper<{value: number, text: string}> = {
|
|
178
|
-
mapOption(source: {
|
|
179
|
-
id: number,
|
|
180
|
-
description: string
|
|
181
|
-
}): Observable<any> {
|
|
182
|
-
return of({value: source.id, text: source.description});
|
|
183
|
-
}
|
|
184
|
-
}
|
|
185
|
-
```
|
|
186
|
-
|
|
187
|
-
The `multiMapper` property works like the `mapper` property, it implements the interface `NgJvxOptionsMapper<T>`.
|
|
188
|
-
It will expose a method `mapOptions` which accepts all the options to be mapped in the form of an Object and returns an Observable of type `T[]`.
|
|
189
|
-
For example if the request returns an array of objects like this:
|
|
190
|
-
|
|
191
|
-
```javascript
|
|
192
|
-
{
|
|
193
|
-
id: number;
|
|
194
|
-
description: string;
|
|
195
|
-
}
|
|
196
|
-
```
|
|
197
|
-
|
|
198
|
-
it is possible to write a mapper like this:
|
|
199
|
-
|
|
200
|
-
```javascript
|
|
201
|
-
const mapper: NgJvxOptionMultiMapper<{value: number, text: string}> = {
|
|
202
|
-
mapOption(source: {
|
|
203
|
-
id: number,
|
|
204
|
-
description: string
|
|
205
|
-
}[]): Observable<any> {
|
|
206
|
-
return of(source.map(s=>{value: s.id, text: s.description}));
|
|
207
|
-
}
|
|
208
|
-
}
|
|
209
|
-
```
|
|
210
|
-
|
|
211
|
-
It's useful if the user wants to add any custom option to a server call
|
|
212
|
-
#### Search
|
|
213
|
-
|
|
214
|
-
If the property `searchInput` is `true`, the user will be able to search a value amongst the options.
|
|
215
|
-
`searchProp` defines the name of the property for the HTTP call.
|
|
216
|
-
|
|
217
|
-
##### searchMapper
|
|
218
|
-
|
|
219
|
-
The `searchMapper` property is an object implementing the interface `NgJvxSearchMapper<T>`. It exposes the
|
|
220
|
-
method `mapSearch` which accepts the value of the search (a string) and an array of the selectable options.
|
|
221
|
-
The method returns an Observable of type `T[]`.
|
|
222
|
-
The value of the returned Observable will then be used as the new option list.
|
|
223
|
-
This property is only useful for a client side search.
|
|
224
|
-
|
|
225
|
-
For example:
|
|
226
|
-
```typescript
|
|
227
|
-
const searchMapper: NgJvxSearchMapper<{text: string, value: number}> = {
|
|
228
|
-
mapSearch: (source: string, options: {text: string, value: number}[]): Observable<{text: string, value: number}[]> => {
|
|
229
|
-
return of(options.filter(o => o.text.toLowerCase().includes(source.toLowerCase())));
|
|
230
|
-
}
|
|
231
|
-
}
|
|
232
|
-
```
|
|
233
|
-
|
|
234
|
-
### Slots
|
|
235
|
-
|
|
236
|
-
#### default
|
|
237
|
-
|
|
238
|
-
The default slot allows to define the options directly via html. It's not compatible with the `url` parameter. The
|
|
239
|
-
options shall be wrapped in the `<ng-jvx-option>` component. The slot shall not be wrapped in the `<ng-jvx-option>`
|
|
240
|
-
component if it's decorated with one of the available directives, since it will have different purposes.
|
|
241
|
-
|
|
242
|
-
#### placeholder
|
|
243
|
-
|
|
244
|
-
The slot `placeholder` will define the placeholder. It's shown only when the selection's value is empty.
|
|
245
|
-
|
|
246
|
-
### Directives
|
|
247
|
-
|
|
248
|
-
#### ngJvxOptionsTemplate
|
|
249
|
-
|
|
250
|
-
When an element inside the `ng-jvx-multiselect` is decorated with this directive it becomes the template for the options
|
|
251
|
-
of the select. The directive provides a context. i.e.: Let's say we have the following structure:
|
|
252
|
-
|
|
253
|
-
```javascript
|
|
254
|
-
var options = [{
|
|
255
|
-
value: 1,
|
|
256
|
-
text: 'Lorem ipsum',
|
|
257
|
-
color: 'blue',
|
|
258
|
-
preview: 'path/to/first-image.jpg'
|
|
259
|
-
},
|
|
260
|
-
{
|
|
261
|
-
value: 2,
|
|
262
|
-
text: 'dolor sit amet',
|
|
263
|
-
color: 'red',
|
|
264
|
-
preview: 'path/to/second-image.jpg'
|
|
265
|
-
}];
|
|
266
|
-
```
|
|
267
|
-
|
|
268
|
-
and we want our options to have in the text field both the property color and the property text. We can write the
|
|
269
|
-
template like so:
|
|
270
|
-
|
|
271
|
-
```angular2html
|
|
272
|
-
<div *ngJvxOptionsTemplate="let option">{{option.color}} {{option.text}}</div>
|
|
273
|
-
```
|
|
274
|
-
|
|
275
|
-
It's possible to use the context inside attributes too. i.e.
|
|
276
|
-
|
|
277
|
-
```angular2html
|
|
278
|
-
<div *ngJvxOptionsTemplate="let option">
|
|
279
|
-
<span>{{option.text}}</span>
|
|
280
|
-
<span>
|
|
281
|
-
<img src="{{option.preview}}"/>
|
|
282
|
-
</span>
|
|
283
|
-
</div>
|
|
284
|
-
```
|
|
285
|
-
|
|
286
|
-
#### *ngJvxSelectionTemplate
|
|
287
|
-
|
|
288
|
-
This directive works exactly as the `ngJvxOptionsTemplate` except it defines the selection template.
|
|
289
|
-
In case of a multiple selection the context is the array of the selected options, for the non-multiple selection the
|
|
290
|
-
context is the selected option.
|
|
291
|
-
|
|
292
|
-
#### *ngJvxGroupHeaderTemplate
|
|
293
|
-
|
|
294
|
-
When an element inside the `ng-jvx-multiselect` is decorated with this directive it becomes the template for the header
|
|
295
|
-
of the groups by which the options are devided. The directive provides a context which describes the group with its
|
|
296
|
-
options in the following form:
|
|
297
|
-
|
|
298
|
-
```typescript
|
|
299
|
-
{
|
|
300
|
-
group: any;
|
|
301
|
-
options: any[];
|
|
302
|
-
}
|
|
303
|
-
```
|
|
304
|
-
|
|
305
|
-
i.e.: with the following structure:
|
|
306
|
-
|
|
307
|
-
```typescript
|
|
308
|
-
const options = [{
|
|
309
|
-
value: 'dog',
|
|
310
|
-
text: 'the dog',
|
|
311
|
-
type: 'mammal'
|
|
312
|
-
}, {
|
|
313
|
-
value: 'lizard',
|
|
314
|
-
text: 'the lizard',
|
|
315
|
-
type: 'reptile'
|
|
316
|
-
}, {
|
|
317
|
-
value: 'cat',
|
|
318
|
-
text: 'the cat',
|
|
319
|
-
type: 'mammal'
|
|
320
|
-
}];
|
|
321
|
-
```
|
|
322
|
-
|
|
323
|
-
and we want the header of each group be in the form of 'Type of animal: [mammal | reptile]'. We'll do as follows:
|
|
324
|
-
|
|
325
|
-
```angular2html
|
|
326
|
-
|
|
327
|
-
<div *ngJvxGroupHeaderTemplate="let g">Type of animal: {{g.group}}</div>
|
|
328
|
-
```
|
|
329
|
-
|
|
330
|
-
#### *ngJvxDisabledOption
|
|
331
|
-
|
|
332
|
-
This directive disables the selection of the host option. i.e.
|
|
333
|
-
|
|
334
|
-
```angular2html
|
|
335
|
-
|
|
336
|
-
<div *ngJvxOptionsTemplate="let option" [ngJvxDisabledOption]="option.text === 'text of the disabled option'">
|
|
337
|
-
<span>{{option.text}}</span>
|
|
338
|
-
<span>
|
|
339
|
-
<img src="{{option.preview}}"/>
|
|
340
|
-
</span>
|
|
341
|
-
</div>
|
|
342
|
-
```
|
|
343
|
-
|
|
344
|
-
## NgJvxMultiselectChipComponent
|
|
345
|
-
|
|
346
|
-
This component is used by `ng-jvx-multiselect` to render each selected item as a removable “chip” when `multi` is enabled. Chips provide a compact visual representation of the current selection and offer a quick way to remove individual items.
|
|
347
|
-
|
|
348
|
-
It is created and managed internally by the multiselect; typical applications do not need to instantiate it directly.
|
|
349
|
-
|
|
350
|
-
### Inputs
|
|
351
|
-
|
|
352
|
-
*None*
|
|
353
|
-
|
|
354
|
-
### Methods
|
|
355
|
-
|
|
356
|
-
*None*
|
|
357
|
-
|
|
358
|
-
### Events
|
|
359
|
-
|
|
360
|
-
| Event Name | Detail | Description |
|
|
361
|
-
|------------|--------|-----------------------------------------------------------------------------|
|
|
362
|
-
| `removed` | `any` | Fired when the user clicks the chip’s remove action. The detail is the option represented by the chip. |
|
|
363
|
-
|
|
364
|
-
Notes:
|
|
365
|
-
- When a chip emits `removed`, the multiselect removes the corresponding item from the selection.
|
|
366
|
-
- The event is handled internally by the multiselect component; consumers usually interact with selection changes via the parent’s `valueChange` event.
|
|
1
|
+
# NgJvxMultiselect
|
|
2
|
+
|
|
3
|
+
ng-jvx-multiselect is a select based on angular. It handles both single and multiple selections and allows to
|
|
4
|
+
retrieves the options via asynchronous calls.
|
|
5
|
+
|
|
6
|
+
## Install ng-jvx-multiselect
|
|
7
|
+
|
|
8
|
+
```
|
|
9
|
+
npm install ng-jvx-multiselect --save
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
In <b>app.module.ts</b>
|
|
13
|
+
|
|
14
|
+
```typescript
|
|
15
|
+
import {NgJvxMultiselectModule} from 'ng-jvx-multiselect';
|
|
16
|
+
|
|
17
|
+
@NgModule({
|
|
18
|
+
imports: [
|
|
19
|
+
NgJvxMultiselectModule
|
|
20
|
+
]
|
|
21
|
+
})
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
In <b>styles.scss</b>
|
|
25
|
+
|
|
26
|
+
```scss
|
|
27
|
+
@use 'index' as ng-jvx-multiselect;
|
|
28
|
+
|
|
29
|
+
:root {
|
|
30
|
+
--jvx-multiselect-primary: #008000;
|
|
31
|
+
--jvx-multiselect-accent: #0000FF;
|
|
32
|
+
--jvx-multiselect-warn: #FF0000;
|
|
33
|
+
--jvx-multiselect-on-primary: #ffffff;
|
|
34
|
+
--jvx-multiselect-on-accent: currentcolor;
|
|
35
|
+
--jvx-multiselect-on-warn: currentcolor;
|
|
36
|
+
--jvx-multiselect-panel-bg: #FFFFFF
|
|
37
|
+
}
|
|
38
|
+
```
|
|
39
|
+
In <b>example.component.html</b>
|
|
40
|
+
|
|
41
|
+
```angular2html
|
|
42
|
+
<ng-jvx-multiselect style="width: 100%" [options]="options">
|
|
43
|
+
<ng-container placeholder>
|
|
44
|
+
this is a placeholder
|
|
45
|
+
</ng-container>
|
|
46
|
+
</ng-jvx-multiselect>
|
|
47
|
+
```
|
|
48
|
+
In <b>example.component.ts</b>
|
|
49
|
+
|
|
50
|
+
```typescript
|
|
51
|
+
public options = [
|
|
52
|
+
{value: 1, text: 'text 1'},
|
|
53
|
+
{value: 2, text: 'text 2'},
|
|
54
|
+
{value: 3, text: 'text 3'},
|
|
55
|
+
{value: 4, text: 'text 4'},
|
|
56
|
+
{value: 5, text: 'text 5'},
|
|
57
|
+
{value: 6, text: 'text 6'},
|
|
58
|
+
{value: 7, text: 'text 7'},
|
|
59
|
+
{value: 8, text: 'text 8'},
|
|
60
|
+
{value: 9, text: 'text 9'},
|
|
61
|
+
{value: 10, text: 'text 10'}];
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
|
|
65
|
+
## API
|
|
66
|
+
|
|
67
|
+
### Slots
|
|
68
|
+
|
|
69
|
+
| Name | Description |
|
|
70
|
+
|---------------|------------------------------------------------------------------------------------------------------------|
|
|
71
|
+
| `default` | Using the default slot is one way of defining the options via the component `<ng-jvx-option>`. |
|
|
72
|
+
| `placeholder` | This slot allows the user to define a placeholder which will be displayed when no selection has been made. |
|
|
73
|
+
|
|
74
|
+
### Inputs
|
|
75
|
+
|
|
76
|
+
| Name | Type | Default | Description |
|
|
77
|
+
|------------------|----------------------------------------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
78
|
+
| `clearable` | `Boolean` | `false` | True to enable the empty selection. |
|
|
79
|
+
| `closeButton` | `Boolean` | `false` | True to show the button that closes the menu. |
|
|
80
|
+
| `disabled` | `Boolean` | `false` | True to disable the select. |
|
|
81
|
+
| `itemText` | `String` | `'text'` | The name of the property of the option object that will be displayed as description of the options. |
|
|
82
|
+
| `itemValue` | `String` | `'value'` | The name of the property of the option object that will be treated as value of the options. |
|
|
83
|
+
| `multi` | `Boolean` | `false` | True if it's a multiselect. |
|
|
84
|
+
| `options` | `Array` | `[]` | Array of option objects. |
|
|
85
|
+
| `requestHeaders` | `Object` | `{...}` | The headers of the HTTP request. |
|
|
86
|
+
| `requestType` | <code>'GET'|'POST'</code> | `'GET'` | The type of the HTTP request. |
|
|
87
|
+
| `postPayload` | `Object` | {} | Sets the payload for the post request. |
|
|
88
|
+
| `searchInput` | `Boolean` | `false` | True to enable the search input for the options list. |
|
|
89
|
+
| `searchMode` | <code>'client'|'server'</code> | `server` | `'client'` if the search is only client side, `'server'` if it's server side. |
|
|
90
|
+
| `searchLabel` | `String` | `'search'` | The label of the search input. |
|
|
91
|
+
| `searchProp` | `String` | `'search'` | The name of the search property of the HTTP request. |
|
|
92
|
+
| `listProp` | `String` | `''` | Name of the property in response.data where the list is stored. |
|
|
93
|
+
| `url` | `String` | `''` | The url to get the options. |
|
|
94
|
+
| `value` | `Array` | `[]` | The current value of the selection. |
|
|
95
|
+
| `mapper` | `NgJvxOptionMapper` | `*` | The object that will map the response of the async call. |
|
|
96
|
+
| `searchMapper` | `NgJvxSearchMapper` | `*` | The object that will map the client search result. |
|
|
97
|
+
| `pageSize` | `number` | `15` | The size of a page for pagination purposes. |
|
|
98
|
+
| `groupBy` | <code>NgJvxGroupMapper<any>|string|null</code> | `null` | If it's a `string` it defines the the property of each option by which group them in the list. If it's a `NgJvxGroupMapper` it offers a method that groups the options (useful for nested properties). |
|
|
99
|
+
|
|
100
|
+
### Methods
|
|
101
|
+
|
|
102
|
+
*None*
|
|
103
|
+
|
|
104
|
+
### Events
|
|
105
|
+
|
|
106
|
+
| Event Name | Detail | Description |
|
|
107
|
+
|---------------|---------|-----------------------------------------------------------------------------------------------------|
|
|
108
|
+
| `valueChange` | `Array` | Fired when the user changes the value of the input. The detail contains the value of the selection. |
|
|
109
|
+
| `scrollEnd` | *None* | Fired when the scrollbar in the options menu reaches the bottom. |
|
|
110
|
+
| `open` | *None* | Fired when the the menu starts opening. |
|
|
111
|
+
| `opened` | *None* | Fired when the the menu is opened. |
|
|
112
|
+
| `close` | *None* | Fired when the the menu starts closing. |
|
|
113
|
+
| `closed` | *None* | Fired when the the menu is closed. |
|
|
114
|
+
|
|
115
|
+
### Groups
|
|
116
|
+
|
|
117
|
+
It is possible to collect the options in groups. To do so the user can set the property `groupBy` with the name of the property they want to group the options by.
|
|
118
|
+
If the property is nested or the user wants to implement a more complex grouping algorithm, they set the property `groupBy` with an object that implements the interface `NgJvxGroupMapper<T>`.
|
|
119
|
+
This object offers the method
|
|
120
|
+
```typescript
|
|
121
|
+
mapGroup(option: T): Observable<NgJvxGroup<T>>
|
|
122
|
+
```
|
|
123
|
+
with
|
|
124
|
+
```typescript
|
|
125
|
+
interface NgJvxGroup<T> {
|
|
126
|
+
group: string;
|
|
127
|
+
option: T;
|
|
128
|
+
}
|
|
129
|
+
```
|
|
130
|
+
The `mapGroup` method hence takes the option and wraps it in an object that defines the name of the group it belongs to.
|
|
131
|
+
It is possible to define the look of the headers of the groups with the directive [*ngJvxGroupHeaderTemplate](#ngjvxgroupheadertemplate)
|
|
132
|
+
### HTTP Request
|
|
133
|
+
|
|
134
|
+
#### Request
|
|
135
|
+
|
|
136
|
+
The HTTP request can be either a GET or a POST request. The user can set the type using the property `requestType` which
|
|
137
|
+
is set to `'GET'` by default.
|
|
138
|
+
|
|
139
|
+
##### Headers
|
|
140
|
+
|
|
141
|
+
The headers can be set in the property `requestHeaders`. By default the ng-jvx-multiselect uses the property `trusted`
|
|
142
|
+
stored in the sessionStorage. The default headers are:
|
|
143
|
+
|
|
144
|
+
```javascript
|
|
145
|
+
var requestHeaders = {
|
|
146
|
+
'Accept': 'application/json',
|
|
147
|
+
'Access-Control-Allow-Origin': '*',
|
|
148
|
+
'Access-Control-Allow-Methods': 'GET, PUT, POST, DELETE, OPTIONS',
|
|
149
|
+
'Content-Type': 'application/json',
|
|
150
|
+
'Authorization': window.sessionStorage.getItem('trusted')
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
#### Response
|
|
155
|
+
|
|
156
|
+
The response must contain an array of elements.
|
|
157
|
+
|
|
158
|
+
The property `listProp` defines the path of the array in the response object (i.e. if `listProp` is set to `list` the
|
|
159
|
+
ng-jvx-multiselect will get the options in the array stored in the path `response.list`).
|
|
160
|
+
|
|
161
|
+
#### Mapper
|
|
162
|
+
|
|
163
|
+
The `mapper` property will be an object implementing the interface `NgJvxOptionMapper<T>`. It will expose a
|
|
164
|
+
method `mapOption` which accepts the option to be mapped in the form of an Object and returns an Observable of type `T`.
|
|
165
|
+
For example if the request returns an array of objects like this:
|
|
166
|
+
|
|
167
|
+
```javascript
|
|
168
|
+
{
|
|
169
|
+
id: number;
|
|
170
|
+
description: string;
|
|
171
|
+
}
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
it is possible to write a mapper like this:
|
|
175
|
+
|
|
176
|
+
```javascript
|
|
177
|
+
const mapper: NgJvxOptionMapper<{value: number, text: string}> = {
|
|
178
|
+
mapOption(source: {
|
|
179
|
+
id: number,
|
|
180
|
+
description: string
|
|
181
|
+
}): Observable<any> {
|
|
182
|
+
return of({value: source.id, text: source.description});
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
```
|
|
186
|
+
|
|
187
|
+
The `multiMapper` property works like the `mapper` property, it implements the interface `NgJvxOptionsMapper<T>`.
|
|
188
|
+
It will expose a method `mapOptions` which accepts all the options to be mapped in the form of an Object and returns an Observable of type `T[]`.
|
|
189
|
+
For example if the request returns an array of objects like this:
|
|
190
|
+
|
|
191
|
+
```javascript
|
|
192
|
+
{
|
|
193
|
+
id: number;
|
|
194
|
+
description: string;
|
|
195
|
+
}
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
it is possible to write a mapper like this:
|
|
199
|
+
|
|
200
|
+
```javascript
|
|
201
|
+
const mapper: NgJvxOptionMultiMapper<{value: number, text: string}> = {
|
|
202
|
+
mapOption(source: {
|
|
203
|
+
id: number,
|
|
204
|
+
description: string
|
|
205
|
+
}[]): Observable<any> {
|
|
206
|
+
return of(source.map(s=>{value: s.id, text: s.description}));
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
It's useful if the user wants to add any custom option to a server call
|
|
212
|
+
#### Search
|
|
213
|
+
|
|
214
|
+
If the property `searchInput` is `true`, the user will be able to search a value amongst the options.
|
|
215
|
+
`searchProp` defines the name of the property for the HTTP call.
|
|
216
|
+
|
|
217
|
+
##### searchMapper
|
|
218
|
+
|
|
219
|
+
The `searchMapper` property is an object implementing the interface `NgJvxSearchMapper<T>`. It exposes the
|
|
220
|
+
method `mapSearch` which accepts the value of the search (a string) and an array of the selectable options.
|
|
221
|
+
The method returns an Observable of type `T[]`.
|
|
222
|
+
The value of the returned Observable will then be used as the new option list.
|
|
223
|
+
This property is only useful for a client side search.
|
|
224
|
+
|
|
225
|
+
For example:
|
|
226
|
+
```typescript
|
|
227
|
+
const searchMapper: NgJvxSearchMapper<{text: string, value: number}> = {
|
|
228
|
+
mapSearch: (source: string, options: {text: string, value: number}[]): Observable<{text: string, value: number}[]> => {
|
|
229
|
+
return of(options.filter(o => o.text.toLowerCase().includes(source.toLowerCase())));
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
### Slots
|
|
235
|
+
|
|
236
|
+
#### default
|
|
237
|
+
|
|
238
|
+
The default slot allows to define the options directly via html. It's not compatible with the `url` parameter. The
|
|
239
|
+
options shall be wrapped in the `<ng-jvx-option>` component. The slot shall not be wrapped in the `<ng-jvx-option>`
|
|
240
|
+
component if it's decorated with one of the available directives, since it will have different purposes.
|
|
241
|
+
|
|
242
|
+
#### placeholder
|
|
243
|
+
|
|
244
|
+
The slot `placeholder` will define the placeholder. It's shown only when the selection's value is empty.
|
|
245
|
+
|
|
246
|
+
### Directives
|
|
247
|
+
|
|
248
|
+
#### ngJvxOptionsTemplate
|
|
249
|
+
|
|
250
|
+
When an element inside the `ng-jvx-multiselect` is decorated with this directive it becomes the template for the options
|
|
251
|
+
of the select. The directive provides a context. i.e.: Let's say we have the following structure:
|
|
252
|
+
|
|
253
|
+
```javascript
|
|
254
|
+
var options = [{
|
|
255
|
+
value: 1,
|
|
256
|
+
text: 'Lorem ipsum',
|
|
257
|
+
color: 'blue',
|
|
258
|
+
preview: 'path/to/first-image.jpg'
|
|
259
|
+
},
|
|
260
|
+
{
|
|
261
|
+
value: 2,
|
|
262
|
+
text: 'dolor sit amet',
|
|
263
|
+
color: 'red',
|
|
264
|
+
preview: 'path/to/second-image.jpg'
|
|
265
|
+
}];
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
and we want our options to have in the text field both the property color and the property text. We can write the
|
|
269
|
+
template like so:
|
|
270
|
+
|
|
271
|
+
```angular2html
|
|
272
|
+
<div *ngJvxOptionsTemplate="let option">{{option.color}} {{option.text}}</div>
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
It's possible to use the context inside attributes too. i.e.
|
|
276
|
+
|
|
277
|
+
```angular2html
|
|
278
|
+
<div *ngJvxOptionsTemplate="let option">
|
|
279
|
+
<span>{{option.text}}</span>
|
|
280
|
+
<span>
|
|
281
|
+
<img src="{{option.preview}}"/>
|
|
282
|
+
</span>
|
|
283
|
+
</div>
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
#### *ngJvxSelectionTemplate
|
|
287
|
+
|
|
288
|
+
This directive works exactly as the `ngJvxOptionsTemplate` except it defines the selection template.
|
|
289
|
+
In case of a multiple selection the context is the array of the selected options, for the non-multiple selection the
|
|
290
|
+
context is the selected option.
|
|
291
|
+
|
|
292
|
+
#### *ngJvxGroupHeaderTemplate
|
|
293
|
+
|
|
294
|
+
When an element inside the `ng-jvx-multiselect` is decorated with this directive it becomes the template for the header
|
|
295
|
+
of the groups by which the options are devided. The directive provides a context which describes the group with its
|
|
296
|
+
options in the following form:
|
|
297
|
+
|
|
298
|
+
```typescript
|
|
299
|
+
{
|
|
300
|
+
group: any;
|
|
301
|
+
options: any[];
|
|
302
|
+
}
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
i.e.: with the following structure:
|
|
306
|
+
|
|
307
|
+
```typescript
|
|
308
|
+
const options = [{
|
|
309
|
+
value: 'dog',
|
|
310
|
+
text: 'the dog',
|
|
311
|
+
type: 'mammal'
|
|
312
|
+
}, {
|
|
313
|
+
value: 'lizard',
|
|
314
|
+
text: 'the lizard',
|
|
315
|
+
type: 'reptile'
|
|
316
|
+
}, {
|
|
317
|
+
value: 'cat',
|
|
318
|
+
text: 'the cat',
|
|
319
|
+
type: 'mammal'
|
|
320
|
+
}];
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
and we want the header of each group be in the form of 'Type of animal: [mammal | reptile]'. We'll do as follows:
|
|
324
|
+
|
|
325
|
+
```angular2html
|
|
326
|
+
|
|
327
|
+
<div *ngJvxGroupHeaderTemplate="let g">Type of animal: {{g.group}}</div>
|
|
328
|
+
```
|
|
329
|
+
|
|
330
|
+
#### *ngJvxDisabledOption
|
|
331
|
+
|
|
332
|
+
This directive disables the selection of the host option. i.e.
|
|
333
|
+
|
|
334
|
+
```angular2html
|
|
335
|
+
|
|
336
|
+
<div *ngJvxOptionsTemplate="let option" [ngJvxDisabledOption]="option.text === 'text of the disabled option'">
|
|
337
|
+
<span>{{option.text}}</span>
|
|
338
|
+
<span>
|
|
339
|
+
<img src="{{option.preview}}"/>
|
|
340
|
+
</span>
|
|
341
|
+
</div>
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
## NgJvxMultiselectChipComponent
|
|
345
|
+
|
|
346
|
+
This component is used by `ng-jvx-multiselect` to render each selected item as a removable “chip” when `multi` is enabled. Chips provide a compact visual representation of the current selection and offer a quick way to remove individual items.
|
|
347
|
+
|
|
348
|
+
It is created and managed internally by the multiselect; typical applications do not need to instantiate it directly.
|
|
349
|
+
|
|
350
|
+
### Inputs
|
|
351
|
+
|
|
352
|
+
*None*
|
|
353
|
+
|
|
354
|
+
### Methods
|
|
355
|
+
|
|
356
|
+
*None*
|
|
357
|
+
|
|
358
|
+
### Events
|
|
359
|
+
|
|
360
|
+
| Event Name | Detail | Description |
|
|
361
|
+
|------------|--------|-----------------------------------------------------------------------------|
|
|
362
|
+
| `removed` | `any` | Fired when the user clicks the chip’s remove action. The detail is the option represented by the chip. |
|
|
363
|
+
|
|
364
|
+
Notes:
|
|
365
|
+
- When a chip emits `removed`, the multiselect removes the corresponding item from the selection.
|
|
366
|
+
- The event is handled internally by the multiselect component; consumers usually interact with selection changes via the parent’s `valueChange` event.
|