From 3d236a64986bad7ff346bee613b3b2737f6f5567 Mon Sep 17 00:00:00 2001 From: Kara Date: Fri, 27 Jan 2017 18:39:36 -0800 Subject: [PATCH] docs(autocomplete): add autocomplete docs (#2840) --- src/lib/autocomplete/OVERVIEW.md | 150 +++++++++++++++++++++++++++++++ src/lib/autocomplete/README.md | 6 +- 2 files changed, 151 insertions(+), 5 deletions(-) create mode 100644 src/lib/autocomplete/OVERVIEW.md diff --git a/src/lib/autocomplete/OVERVIEW.md b/src/lib/autocomplete/OVERVIEW.md new file mode 100644 index 000000000000..19f4acbededa --- /dev/null +++ b/src/lib/autocomplete/OVERVIEW.md @@ -0,0 +1,150 @@ + +The autocomplete is a normal text input enhanced by a panel of suggested options. You can read more about +autocompletes in the [Material Design spec](https://material.io/guidelines/components/text-fields.html#text-fields-auto-complete-text-field). + +### Simple autocomplete + +Start by adding a regular `mdInput` to the page. Let's assume you're using the `formControl` directive from the +`@angular/forms` module to track the value of the input. + +*my-comp.html* +```html + + + +``` + +Next, create the autocomplete panel and the options displayed inside it. Each option should be defined by an +`md-option` tag. Set each option's value property to whatever you'd like the value of the text input to be +upon that option's selection. + +*my-comp.html* +```html + + + {{ option }} + + +``` + +Now we'll need to link the text input to its panel. We can do this by exporting the autocomplete panel instance into a +local template variable (here we called it "auto"), and binding that variable to the input's `mdAutocomplete` property. + +*my-comp.html* +```html + + + + + + + {{ option }} + + +``` + +### Adding a custom filter + +At this point, the autocomplete panel should be toggleable on focus and options should be selectable. But if we want +our options to filter when we type, we need to add a custom filter. + +You can filter the options in any way you want based on the text input. Here we will do a simple string test on the +input value to see if it matches the option value. We already have access to the built-in `valueChanges` observable on +the `FormControl`, so we can simply map the text input's values to the suggested options by passing them through this +filter. The resulting observable (`filteredOptions`) can be added to the template in place of the `options` property +using the `async` pipe. + +Below we are also priming our value change stream with `null` so that the options are filtered by that value on init +(before there are any value changes). + +*my-comp.ts* +```ts +class MyComp { + myControl = new FormControl(); + options = [ + 'One', + 'Two', + 'Three' + ]; + filteredOptions: Observable; + + ngOnInit() { + this.filteredOptions = this.myControl.valueChanges + .startWith(null) + .map(val => val ? this.filter(val) : this.options.slice()); + } + + filter(val: string): string[] { + return this.options.filter(option => new RegExp(val, 'gi').test(option)); + } +} +``` + +*my-comp.html* +```html + + + + + + + {{ option }} + + +``` + +### Setting separate control and display values + +If you want the option's control value (what is saved in the form) to be different than the option's display value +(what is displayed in the actual text field), you'll need to set the `displayWith` property on your autocomplete +element. A common use case for this might be if you want to save your data as an object, but display just one of +the option's string properties. + +To make this work, create a function on your component class that maps the control value to the desired display value. +Then bind it to the autocomplete's `displayWith` property. + +```html + + + + + + + {{ option }} + + +``` + +*my-comp.ts* +```ts +class MyComp { + myControl = new FormControl(); + options = [ + new User('Mary'), + new User('Shelley'), + new User('Igor') + ]; + filteredOptions: Observable; + + ngOnInit() { + this.filteredOptions = this.myControl.valueChanges + .startWith(null) + .map(user => user && typeof user === 'object' ? user.name : user) + .map(name => name ? this.filter(name) : this.options.slice()); + } + + filter(name: string): User[] { + return this.options.filter(option => new RegExp(name, 'gi').test(option)); + } + + displayFn(user: User): string { + return user ? user.name : user; + } +} +``` + + +#### Keyboard interaction: +- DOWN_ARROW: Next option becomes active. +- UP_ARROW: Previous option becomes active. +- ENTER: Select currently active item. diff --git a/src/lib/autocomplete/README.md b/src/lib/autocomplete/README.md index 1bc0814e9eec..73bddeb68ee6 100644 --- a/src/lib/autocomplete/README.md +++ b/src/lib/autocomplete/README.md @@ -1,5 +1 @@ - -## Not yet implemented! - -The autocomplete is not yet implemented. This is only a scaffold to make -subsequent PRs easier to read. Please do not try to use yet :) \ No newline at end of file +See documentation on [material.angular.io](https://material.angular.io/). \ No newline at end of file