1 | # ng2-completer
|
2 |
|
3 | Auto complete component for Angular 2.
|
4 |
|
5 | This component is based on [angucomplete-alt](https://github.com/ghiden/angucomplete-alt)
|
6 |
|
7 | Click for [demo](http://oferh.github.io/ng2-completer/) or [plunk](https://plnkr.co/edit/sVnfpBiEb5jBdtul4ls9?p=preview)
|
8 |
|
9 | ## help needed
|
10 | I don't use this library much anymore and don't have time to properly maintain it.
|
11 | If you are currently using ng2-completer and interested to maintain it please let me know!
|
12 |
|
13 | ## Installation
|
14 |
|
15 | ```sh
|
16 | npm install ng2-completer --save
|
17 | ```
|
18 |
|
19 | ## Usage
|
20 |
|
21 | The module you want to use ng2-completer in must import `Ng2CompleterModule` and `FormsModule` (to use the ngModel
|
22 | directive on ng2-completer). `Ng2CompleterModule` provides the `CompleterService`, and declares the `ng2-completer`
|
23 | directive.
|
24 | ```ts
|
25 | import { NgModule } from '@angular/core';
|
26 | import { BrowserModule } from '@angular/platform-browser';
|
27 | import { FormsModule } from "@angular/forms";
|
28 | import { HttpClientModule } from "@angular/common/http";
|
29 | import { AppComponent } from './app.component';
|
30 | import { Ng2CompleterModule } from "ng2-completer";
|
31 |
|
32 |
|
33 | @NgModule({
|
34 | imports: [
|
35 | BrowserModule,
|
36 | FormsModule,
|
37 | HttpClientModule,
|
38 | Ng2CompleterModule,
|
39 | ],
|
40 | declarations: [ AppComponent ],
|
41 | bootstrap: [ AppComponent ]
|
42 | })
|
43 | export class AppModule { }
|
44 | ```
|
45 |
|
46 | Add ng2-completer to your component and create a data source:
|
47 |
|
48 | ```ts
|
49 | import { Component } from '@angular/core';
|
50 | import { CompleterService, CompleterData } from 'ng2-completer';
|
51 |
|
52 | @Component({
|
53 | selector: 'my-component',
|
54 | template: `<h1>Search color</h1>
|
55 | <ng2-completer [(ngModel)]="searchStr" [datasource]="dataService" [minSearchLength]="0"></ng2-completer>
|
56 | <h1>Search captain</h1>
|
57 | <ng2-completer [(ngModel)]="captain" [datasource]="captains" [minSearchLength]="0"></ng2-completer>`
|
58 | })
|
59 | export class MyComponent {
|
60 |
|
61 | protected searchStr: string;
|
62 | protected captain: string;
|
63 | protected dataService: CompleterData;
|
64 | protected searchData = [
|
65 | { color: 'red', value: '#f00' },
|
66 | { color: 'green', value: '#0f0' },
|
67 | { color: 'blue', value: '#00f' },
|
68 | { color: 'cyan', value: '#0ff' },
|
69 | { color: 'magenta', value: '#f0f' },
|
70 | { color: 'yellow', value: '#ff0' },
|
71 | { color: 'black', value: '#000' }
|
72 | ];
|
73 | protected captains = ['James T. Kirk', 'Benjamin Sisko', 'Jean-Luc Picard', 'Spock', 'Jonathan Archer', 'Hikaru Sulu', 'Christopher Pike', 'Rachel Garrett' ];
|
74 |
|
75 | constructor(private completerService: CompleterService) {
|
76 | this.dataService = completerService.local(this.searchData, 'color', 'color');
|
77 | }
|
78 | }
|
79 | ```
|
80 |
|
81 | ng2-completer uses [rxjs](https://github.com/Reactive-Extensions/RxJS) stream as data sources.
|
82 | There are 2 ready made data sources that can be used to fetch local and remote data but it's also possible to provide
|
83 | a custom source that generates a stream of items.
|
84 |
|
85 | ### System.js configuration
|
86 |
|
87 | Add the following to `System.js` map configuration:
|
88 | ```ts
|
89 | var map = {
|
90 | ...
|
91 | 'ng2-completer': 'node_modules/ng2-completer/ng2-completer.umd.js'
|
92 | }
|
93 | ```
|
94 |
|
95 |
|
96 |
|
97 | ## API
|
98 |
|
99 | ### ng2-completer component
|
100 |
|
101 | |Attribute|Description|Type|Required|Default|
|
102 | |:--- |:--- |:--- |:--- |:--- |
|
103 | |datasource|Autocomplete list data source can be an array of strings or a URL that results in an array of strings or a CompleterData object|Array\<string\>\|string\|CompleterData|Yes||
|
104 | |dataService|**Deprecated** use `datasource` instead. Autocomplete list data source.|CompleterData|Yes||
|
105 | |ngModel| see the angular [forms API](https://angular.io/docs/js/latest/guide/forms.html).|string|Yes||
|
106 | |autoMatch|Auto select an item if it is the only result and it is an exact match of the search text.|boolean|No|false
|
107 | |autofocus|Set input focus when the page loads|boolean|No|false
|
108 | |clearUnselected|Clear the input on blur if not selected.|boolean|No|false|
|
109 | |clearSelected|Clear the input when a result is selected.|boolean|No|false|
|
110 | |disableInput|If true disable the input field.|boolean|No|false|
|
111 | |fieldTabindex|Set the `tabIndex` of the input.|number|No||
|
112 | |initialValue|Initial value for the component. Value is parsed using: titleField, descriptionField and imageField and used as selected value|any|No||
|
113 | |inputId|`id` attribute of the input element.|string|No||
|
114 | |inputName|`name` attribute of the input element.|string|No||
|
115 | |inputClass| `class` attribute of the input element.|string|No||
|
116 | |matchClass|CSS class to apply for matching part of the title and description.|string|No||
|
117 | |maxChars|Maximal number of characters that the user can type in the component.|number|No|524288|
|
118 | |minSearchLength|Minimal number of characters required for searching.|number|No|3|
|
119 | |overrideSuggested|If true will override suggested and set the model with the value in the input field.|boolean|No|false|
|
120 | |openOnFocus|If true will open the dropdown and perform search when the input gets the focus.|boolean|No|false|
|
121 | |openOnClick|If true will open and close the dropdown by click.|boolean|No|false|
|
122 | |selectOnFocus|If true will select the input text upon focus.|boolean|No|false|
|
123 | |selectOnClick|If true will select the input text by click.|boolean|No|false|
|
124 | |fillHighlighted|If true will set the model with the value in the input field when item is highlighted.|boolean|No|true|
|
125 | |pause|Number of msec. to wait before searching.|number|No|250|
|
126 | |placeholder|Placeholder text for the search field.|string|No||
|
127 | |textNoResults|Text displayed when the search returned no results. if the string is falsy it won't be displayed|string|No|
|
128 | |textSearching|Text displayed while search is active. if the string is falsy it won't be displayed|string|No|Searching...|
|
129 | |autoHighlight|Automatically highlight the best matching search result when the input changes. the "best match" is selected by: exact match, starts with and finally includes|boolean|No|false|
|
130 |
|
131 | ### ng2-completer events
|
132 |
|
133 | |Name|Description|Type|
|
134 | |:--- |:--- |:--- |
|
135 | |selected|emitted when an item is selected.|(selected: CompleterItem): void|
|
136 | |highlighted|emitted when an item is highlighted.|(highlighted: CompleterItem): void|
|
137 | |focus|emitted when the input gets focus|(): void|
|
138 | |blur|emitted when the input looses focus|(): void|
|
139 | |opened|emitted when the dropdown is opened or closed|(isOpen: boolean): void|
|
140 | |keyup|emitted when the input emits keyup|(event: any): void|
|
141 | |keydown|emitted when the input emits keydown|(event: any): void|
|
142 |
|
143 | ### ng2-completer methods
|
144 |
|
145 | |Method|Description|Parameters|
|
146 | |:--- |:--- |:--- |
|
147 | |open()|Open the dropdown| |
|
148 | |close()|Close the dropdown| |
|
149 | |focus()|Set the focus to the completer input| |
|
150 | |blur()|Remove the focus from the completer input| |
|
151 | |isOpen()|Returns the state of the dropdown| |
|
152 |
|
153 | ### Local data
|
154 |
|
155 | Create local data provider by calling `CompleterService.local`.
|
156 |
|
157 | #### Parameters
|
158 |
|
159 | |Name|Type|Description|Required|
|
160 | |:---|:---|:--- |:--- |
|
161 | |data|any[] \| Observable<any[]>|A JSON array with the data to use or an Observable that emits one|Yes|
|
162 | |searchFields|string|Comma separated list of fields to search on. Fields may contain dots for nested attributes; if empty or null all data will be returned.|Yes|
|
163 | |titleField|string|Name of the field to use as title for the list item.|Yes|
|
164 |
|
165 | #### Attributes
|
166 | |Name|Type|Description|
|
167 | |:---|:---|:--- |
|
168 | |descriptionField|string|Name of the field to use as description for the list item.|
|
169 | |imageField|string|Name of the field to use as image url for the list item.|
|
170 |
|
171 | ### Remote data
|
172 |
|
173 | Create remote data provider by calling `CompleterService.remote`.
|
174 |
|
175 | #### Parameters
|
176 |
|
177 | |Name|Type|Description|Required|
|
178 | |:---|:---|:--- |:--- |
|
179 | |url|string|Base url for the search|Yes|
|
180 | |searchFields|string|Comma separated list of fields to search on. Fields may contain dots for nested attributes; if empty or null all data will be returned.|Yes|
|
181 | |titleField|string|Name of the field to use as title for the list item.|Yes|
|
182 |
|
183 | #### Attributes
|
184 |
|
185 | |Name|Type|Description|
|
186 | |:---|:---|:--- |
|
187 | |descriptionField|string|Name of the field to use as description for the list item.|
|
188 | |imageField|string|Name of the field to use as image url for the list item.|
|
189 | |urlFormater|(term: string) => string|Function that get's the searchterm and returns the search url before each search.|
|
190 | |dataField|string|The field in the response that includes the data.|
|
191 | |requestOptions|RequestOptions (@angular/common/http)|HTTP request options that should be sent with the search request.|
|
192 |
|
193 | ### CSS classes
|
194 |
|
195 | * `.completer-holder`
|
196 | * `.completer-input`
|
197 | * `.completer-dropdown-holder`
|
198 | * `.completer-dropdown`
|
199 | * `.completer-searching`
|
200 | * `.completer-no-results`
|
201 | * `.completer-row`
|
202 | * `.completer-image-holder`
|
203 | * `.completer-image`
|
204 | * `.completer-image-default`
|
205 | * `.completer-title`
|
206 | * `.completer-description`
|
207 | * `.completer-list-item-holder`
|
208 | * `.completer-list-item`
|
209 | * `.completer-selected-row`
|
210 |
|
211 | ## Credits
|
212 |
|
213 | * This product uses the TMDb API but is not endorsed or certified by TMDb
|