|
| 1 | +# PFElements Autocomplete Element |
| 2 | + |
| 3 | +<pfe-autocomplete> is a Web Component that provides options in a dropdown list as user types in an input box by showing result from an api call. |
| 4 | + |
| 5 | +## Install |
| 6 | +``` |
| 7 | +npm install @patternfly/cp-theme |
| 8 | +npm install @patternfly/pfe-autocomplete |
| 9 | +``` |
| 10 | + |
| 11 | +cp-theme is a package that contains css variables setting that is used for theming patternfly elements. |
| 12 | + |
| 13 | +Once installed, import it to your application: |
| 14 | +``` |
| 15 | +import '@patternfly/cp-theme.umd.js'; |
| 16 | +import '@patternfly/pfe-autocomplete.umd.js'; |
| 17 | +``` |
| 18 | + |
| 19 | +## Usage |
| 20 | +``` |
| 21 | +<pfe-autocomplete debounce="500" init-value="uni"> |
| 22 | + <input placeholder="Enter Your Search Term"/> |
| 23 | +</pfe-autocomplete> |
| 24 | +``` |
| 25 | + |
| 26 | +## Setup |
| 27 | + |
| 28 | +**`autocompleteRequest`** |
| 29 | +`autocompleteRequest` is a property that is assigned a function. When user types, component calls this function. |
| 30 | + |
| 31 | +It is called inside component but we define it outside component. First param is the typed phrase by user and second param is a callback function to send api response back to the component. |
| 32 | + |
| 33 | +In the function, we add loading attribute then send api call. When result is ready, we remove loading attribute and pass the result to web component by calling callback function. Here is an example: |
| 34 | + |
| 35 | +``` |
| 36 | +// autocomplete call |
| 37 | +searchAutocomplete.autocompleteRequest = function(params, callback) { |
| 38 | + var xhr = new XMLHttpRequest(); |
| 39 | +
|
| 40 | + searchAutocomplete.setAttribute('loading', ''); |
| 41 | + xhr.onload = function() { |
| 42 | + searchAutocomplete.removeAttribute('loading'); |
| 43 | +
|
| 44 | + if(xhr.status === 404) { |
| 45 | + callback([]); |
| 46 | + } else { |
| 47 | + const response = JSON.parse(xhr.responseText); |
| 48 | + const regx = new RegExp("\^" + params.query, "i"); |
| 49 | +
|
| 50 | + var responseReady = response.reduce(function(acc, item) { |
| 51 | + if (regx.test(item.name)) acc.push(item.name); |
| 52 | + return acc; |
| 53 | + }, []); |
| 54 | + callback(responseReady); |
| 55 | + } |
| 56 | + }; |
| 57 | +
|
| 58 | + const url = 'https://restcountries.eu/rest/v2/name/' + params.query; |
| 59 | +
|
| 60 | + xhr.open('GET', url, true); |
| 61 | + xhr.send(); |
| 62 | +}; |
| 63 | +``` |
| 64 | + |
| 65 | +**`debounce`** |
| 66 | +This attribute is optional. By default, It has been set tp 300ms. User may type very fast. We allow to input box value changes trigger autocomplete api call each 300ms. |
| 67 | + |
| 68 | +**`loading`** |
| 69 | +loading is a boolean attribute. If you add this attribute on element a loading icon is added in input box. Add this attribute before autocomplete api call and remove this attribute form element when api call response is ready. |
| 70 | + |
| 71 | +**`init-value`** |
| 72 | +Set this attribute when you want to set a value in input box when web component is added to page. |
| 73 | + |
| 74 | +**`is-disabled`** |
| 75 | +is-disabled is a boolean attribute. Add this attribute to element when you want to make the element disabled. By adding this attribute input box and buttons become disabled. |
| 76 | + |
| 77 | +## Get selected item |
| 78 | +User can select an item by clicking on search button, type press enter or select an item by using keyboard and press enter. The selected item can be captured by listening to an event(`pfe-search-event`) or observing attribute(`selected-value`) change. |
| 79 | + |
| 80 | +### pfe-search-event |
| 81 | +When user performs search, `pfe-search-event` event is fired. By listening to this event you can get selected phrase by getting `e.detail.searchValue`. |
| 82 | + |
| 83 | +``` |
| 84 | +searchAutocomplete.addEventListener('pfe-search-event', function(e) { |
| 85 | + console.log('do search= ' + e.detail.searchValue); |
| 86 | +}); |
| 87 | +``` |
| 88 | + |
| 89 | +### selected-value attribute |
| 90 | +By observing `selected-value` attribute you can detect autocomplete selected value. |
| 91 | + |
| 92 | +## Dependencies |
| 93 | + |
| 94 | +Make sure you have [Polyserve][polyserve] and [Web Component Tester][web-component-tester] installed. |
| 95 | + |
| 96 | + npm install -g polyserve web-component-tester |
| 97 | + |
| 98 | +## Dev |
| 99 | + |
| 100 | + npm start |
| 101 | + |
| 102 | +## Test |
| 103 | + |
| 104 | + npm run test |
| 105 | + |
| 106 | +## Build |
| 107 | + |
| 108 | + npm run build |
| 109 | + |
| 110 | +## Demo |
| 111 | + |
| 112 | +Run `npm start` and Polyserve will start a server and open your default browser to the demo page of the element. |
| 113 | + |
| 114 | +## Code style |
| 115 | + |
| 116 | +Autocomplete (and all PFElements) use [Prettier][prettier] to auto-format JS and JSON. The style rules get applied when you commit a change. If you choose to, you can [integrate your editor][prettier-ed] with Prettier to have the style rules applied on every save. |
| 117 | + |
| 118 | +[prettier]: https://github.com/prettier/prettier/ |
| 119 | +[prettier-ed]: https://github.com/prettier/prettier/#editor-integration |
| 120 | +[polyserve]: https://github.com/Polymer/polyserve |
| 121 | +[web-component-tester]: https://github.com/Polymer/web-component-tester |
0 commit comments