<jvx-multiselect>

A web component that offers a multipurpose material multiselect which handles both synchronous and asynchronous selections.

Install jvx-multiselect

npm install jvx-multiselect

API

Slots

| Name | Description | -------------- | ----------- | option-item | Use this slot to pass a custom template for the options. Use [[option.propertyname]] to access the property of the item. The template should be styled inline. | options | It's one of the way to pass the options to the select: the elements inside the slot shall be divs with a value attribute and a text attribute that are used to define the option.

Properties/Attributes

| Name | Type | Default | Description | ----------------------- | ------------------------------- | ----------| --------------------------------------------------------------------------- | advancedSearch | Boolean | false | True to enable the advanced search (searchInput must be true). | clearable | Boolean | false | True to enable the empty selection. | closeOnClick | Boolean | false | True if the options list must be closed on each click outside the component. | disabled | Boolean | false | True to disable the select. | filter | Object | null | The custom filter for the post call. | flatRound | Boolean | false | When true gives the jvx-multiselect a nice flat-rounded appearance. | hasErros | Boolean | false | True to display the component in the "error" mode. | httpParameters | Object | null | The custom search value and pagination for the asynchronous selection. | itemText | String | 'text' | The name of the property of the option object that will be displayed as description of the options. | itemValue | String | 'value' | The name of the property of the option object that will be treated as value of the options. | placeholder | String | '' | The placeholder. | label | String | '' | The label. | labels | Object | null | The dictionary to map the response. | multi | Boolean | false | True if it's a multiselect. | options | Array | [] | Array of the options in the form of Objects. | requestHeaders | Object | {...} | The headers of the HTTP request. | requestType | 'GET'|'POST' | 'GET' | The type of the HTTP request. | searchInput | Boolean | false | True to enable the search input for the options list. | searchLabel | String | 'search'| The label of the search input. | useOnlyHttpParameters | Boolean | false | True to ignore the default pagination. | paginated | Boolean | false | True if the the response is never paginated. | listProp | String | false | Name of the property in response.data where the list is stored. | totalRowsProp | String | false | Name of the property in response.data where the number of total rows is stored. | url | String | '' | The url to get the options. | value | Array | [] | The current value of the selection.

Methods

None

Events

| Event Name | Target | Detail | Description | --------------------- | ------------- | ------- | ----------- | input | | Array | Fired when the user changes the value of the input. The detail contains the value of the selection. | showAdvancedSearch | | None | Fired when the user clicks on the advanced search icon. | response | | Object| Fired when the backend call returns successfully. The detail contains the response. | invalid-jwt | | Object| Fired when the backend call returns with an invalit jwt error. The detail contains the response. | error | | String| Fired when the backend call throws an exception. The detail contains the exception. | scrollEnd | | None | Fired when the scrollbar in the options menu reaches the bottom. | jvx-menu-openeed | | None | Fired when the the menu is opened. | jvx-menu-closed | | None | Fired when the the menu is closed.

CSS Custom Properties

None

Global Custom Properties

| Name | Default | Description | ------------------------------------------------- | --------------------------------- |------------ | --jvx-multiselect-primary | blue | Color of the select bottom line when idle. | --jvx-multiselect-accent | green | Color of the underline ripple, the outline, and the caret when active. | --jvx-multiselect-error | red | Color of the underline ripple, the outline, and the caret when has errors. | --jvx-multiselect-color | #000 | Color of the text. | --jvx-multiselect-background-color | #fff | Color of the background of the menu. | --jvx-material-input-height | `` | Height of the select. | --jvx-multiselect-selection-color | currentColor | Color of the selected value. | --jvx-multiselect-selection-font-size | 14px | Font size of the selected value. | --jvx-multiselect-selection-font-weight | 400 | Font weight of the selected value. | --jvx-multiselect-label-color | currentColor | Color of the label. | --jvx-multiselect-label-font-size | 14px | Font size of the label. | --jvx-multiselect-label-font-weight | 400 | Font weight of the label. | --jvx-multiselect-placeholder-color | var(--jvx-multiselect-color) | Color of the placeholder. | --jvx-multiselect-placeholder-font-size | 14px | Font size of the placeholder. | --jvx-multiselect-placeholder-font-weight | 400 | Font weight of the placeholder.

HTTP Request

Request

The HTTP request can be either a GET or a POST request. The user can set the type using the property requestType which is set to 'GET' by default.

The HTTP request will be executed via axios.

httpParameters

The parameters for the HTTP request are stored in the property httpParameters. If the property useOnlyHttpParamters is false, a new object will be created which will integrate a copy of httpParameters will be completed as follows:

  Object.assign(httpParametersCopy, {
        search: this.searchValue,
        page: this.pagination.page,
        pageSize: this.pagination.pageSize,
        filter: !!this.filter && (typeof this.filter === 'object' || this.filter.length > 0) ? JSON.stringify(this.filter) : null
      });

This object will be passed in the property data or in the property params of the axios request depending on the HTTP request type.

Headers

The headers can be set in the property requestHeaders. By default the jvx-multiselect uses the property trusted stored in the sessionStorage. The default headers are:

var requestHeaders = {
  'Accept': 'application/json',
  'Access-Control-Allow-Origin': '*',
  'Access-Control-Allow-Methods': 'GET, PUT, POST, DELETE, OPTIONS',
  'Content-Type': 'application/json',
  'Authorization': window.sessionStorage.getItem('trusted')
}

Response

By now the response must contain an array of objects, stored in the property message in the response.data object.

The object template should be

var obj: {
  value: Number|String,
  text: String
}

If the object comes in different form, via the property labels it is possible to set an object that maps the properties in order to make it readable for the jvx-multiselect. For example if the response object template is

var response = {
  id: 1,
  title: 'This is the title',
  description: 'This is the description',
  start: 2020/01/01,
  end: 2020/03/01
}

and the property labels is

var labels = {
  id: 'value',
  title: 'text'
}

the response object will be mapped like this

var response = {
  value: 1,
  text: 'This is the title',
  id: 1,
  title: 'This is the title',
  description: 'This is the description',
  start: 2020/01/01,
  end: 2020/03/01,
  selected: Boolean
}

The user can use the properties itemText and itemValue to prevent the need for the mapping (being in the example above itemText = 'title' and itemValue = 'id').

Search

When the user searches for a term, the property searchInput is updated with the searched value. Its value is then copied in the property search of the object of the search parameters.

Pagination

The property pagination is structured by default as follows:

var pagination = {
  page: 1,
  pageSize: 15
}

Whenever the scrollbar in the menu reaches the bottom, the property page is incremented by one and a further http request is called. When the user searches or closes the menu the property page is set again at 1. The jvx-multiselect copies these values individually in the object of the search parameters.

Slots

option-item

The slot option-item allows to define a template for the options that will be shown in the dropdown menu. It is possible to access the context wrapping it between square brackets. i.e.: Let's say we have the following structure:

var options = [{
  value: 1, 
  text: 'Lorem ipsum',
  color: 'blue',
  preview: 'path/to/first-image.jpg'
},
  {
    value: 2,
    text: 'dolor sit amet',
    color: 'red',
    preview: 'path/to/second-image.jpg'
  }];

and we want our options to have in the text field both the property color and the property text. We can write the template like so:

<div slot="option-item">[[option.text]] [[option.color]]</div>

It's possible to use the context inside attributes too. In that case it's suggested to preppend the string data-jvx- to all the attributes' names that will access the context. i.e.

<div slot="option-item">
    <span>[[option.text]]</span>
    <span>
        <img data-jvx-src="[[option.preview]]"/>
    </span>
</div>

selected-item

This slot works exactly as option-item, but it is used to style the selected value when multi is false.

options

The slot options is there to provide an easy way to describe all the available options of the select. This is necessary because some frameworks may have problems in passing the array to the options prop. Each option will be a div and all the properties of the corresponding object can be written inside an attribute preceded by data-jvx-, like so:

<div slot="options">
    <div value="1" text="Lorem ipsum" data-jvx-color="blue" data-jvx-preview="path/to/first-image.jpg"></div>
    <div value="2" text="dolor sit amet" data-jvx-color="red" data-jvx-preview="path/to/second-image.jpg"></div>
</div>