docs(input, select): update docs and create more examples #7673

mmalerba · 2017-10-09T23:40:06Z

No description provided.

willshowell · 2017-10-10T15:27:11Z

src/material-examples/input-error-state-matcher/input-error-state-matcher-example.ts

+    Validators.email,
+  ]);
+
+  matcher = new MyErrorStateMatcher();


In my experience, the custom matchers are very practical for showing errors when a parent FormGroup is invalid. As in,

Password/confirm must be equal

end date must be after begin date.

This requires either checking control.parent.valid or using a class property in the method. Maybe consider expanding the example? Or I'd be happy to give it a shot in a followup.

Yeah that sounds like a good thing to add. I'd like to keep this example around too since it's a little less complex and we don't have to worry about also making a custom validator

willshowell · 2017-10-10T15:32:49Z

src/lib/select/select.md

+using any of the form directives from the core `FormsModule` or `ReactiveFormsModule`: `ngModel`,
+`formControl`, etc. As with native `<select>`, `<mat-select>` also supports a `compareWith`
+function. (Additional information about using a custom `compareWith` function can be found in the
+[angular forms documentation](https://angular.io/api/forms/SelectControlValueAccessor#caveat-option-selection)).


Capitalize 'Angular'?

crisbeto · 2017-10-10T18:07:24Z

src/lib/input/input.md

+either the user has interacted with (touched) the element or the parent form has been submitted. If
+you wish to override this behavior (e.g. to show the error as soon as the invalid control is dirty
+or when a parent form group is invalid), you can use the `errorStateMatcher` property of the
+`matInput`. The property takes an instance of an `ErrorStateMatcher` object. An `ErrorStateMatcher`


I think the more common use-case for customizing the ErrorStateMatcher is overriding the global one, rather than doing it per-control. Maybe we should have an example for that case as well?

Unfortunately our examples aren't that flexible atm. We don't get to mess with the module. That's why I left an inline code snippet showing how to do it globally.

crisbeto · 2017-10-10T18:09:24Z

src/lib/select/select.md

-`mat-option` tag. Note that you can disable items by adding the `disabled` boolean attribute or
-binding to it.
+The select component is set up as a custom value accessor, so you can manipulate the select's value
+using any of the form directives from the core `FormsModule` or `ReactiveFormsModule`: `ngModel`,


The select also supports setting the value via the value input which doesn't require forms.

done and added example

crisbeto · 2017-10-10T18:11:16Z

src/lib/select/select.md

+
+### Changing when error messages are shown
+
+The `<mat-form-field>` allows you to


A few of these sections are going to be the same between the select and input. Maybe we should consider (not necessarily now) having a common page for them?

Yes, I'd also like to consolidate the code itself so we're not duplicating it in input and select, just need to find a good way to make it work with change detection

crisbeto · 2017-10-10T18:12:29Z

src/lib/select/select.ts

@@ -461,6 +464,12 @@ export class MatSelect extends _MatSelectMixinBase implements AfterContentInit,
    }
  }

+  ngOnChanges(changes: SimpleChanges) {
+    if (changes.disabled) {


Did these changes make it through as a part of another branch?

This was fixing a bug I noticed when making one of the demos

Add a comment here?

crisbeto · 2017-10-10T18:14:24Z

src/material-examples/select-error-state-matcher/select-erorr-state-matcher-example.html

+  </mat-select>
+  <mat-hint>Errors appear instantly!</mat-hint>
+  <mat-error *ngIf="selected.hasError('required')">You must make a selection</mat-error>
+  <mat-error *ngIf="selected.hasError('pattern') && !selected.hasError('required')">


I'm not sure how common of a use case it is to have pattern validation on a select since the developer provides the possible values beforehand.

Yeah its not the most practical example, but I just wanted to show a couple different error states

kara

Mostly missing CSS links and comma nits. (We should either remove the file itself or add the link to it in the TS)

kara · 2017-10-10T18:20:12Z

src/material-examples/select-reset/select-reset-example.ts

+/** @title Select with reset option */
+@Component({
+  selector: 'select-reset-example',
+  templateUrl: 'select-reset-example.html',


Missing the link to the example CSS file.

kara · 2017-10-10T18:20:54Z

src/material-examples/select-optgroup/select-optgroup-example.ts

+/** @title Select with option groups */
+@Component({
+  selector: 'select-optgroup-example',
+  templateUrl: 'select-optgroup-example.html',


Missing link to CSS file

kara · 2017-10-10T18:21:07Z

src/material-examples/select-no-ripple/select-no-ripple-example.ts

+/** @title Select with cno option ripple */
+@Component({
+  selector: 'select-no-ripple-example',
+  templateUrl: 'select-no-ripple-example.html',


Link to CSS file

kara · 2017-10-10T18:21:16Z

src/material-examples/select-no-ripple/select-no-ripple-example.ts

@@ -0,0 +1,8 @@
+import {Component} from '@angular/core';
+
+/** @title Select with cno option ripple */


Typo: cno -> no

kara · 2017-10-10T18:21:41Z

src/material-examples/select-multiple/select-multiple-example.ts

+/** @title Select with multiple selection */
+@Component({
+  selector: 'select-multiple-example',
+  templateUrl: 'select-multiple-example.html',


Missing CSS link here

kara · 2017-10-10T18:40:21Z

src/lib/select/select.md

+
+This error occurs if you attempt to assign something other than a function to the `compareWith`
+property. For more information on proper usage of `compareWith` see the
+[angular forms documentation](https://angular.io/api/forms/SelectControlValueAccessor#caveat-option-selection)).


Nit: angular -> Angular

kara · 2017-10-10T18:41:38Z

src/lib/select/select.md


-Global default placeholder options can be specified by setting the `MAT_PLACEHOLDER_GLOBAL_OPTIONS` provider. This setting will apply to all components that support the floating placeholder.
+By default when a user clicks on a `<mat-option>` a ripple animation is shown. This can be disabled


By default, when a user clicks on a mat-option, a ripple animation is shown.

kara · 2017-10-10T18:41:52Z

src/lib/select/select.md

+
+### Selecting multiple options
+
+By default the `<mat-select>` only supports selecting a single option at a time. However you can use


By default, the mat-select

kara · 2017-10-10T18:42:03Z

src/lib/select/select.md

+
+### Selecting multiple options
+
+By default the `<mat-select>` only supports selecting a single option at a time. However you can use


However, you can use

crisbeto · 2017-10-10T19:03:50Z

src/material-examples/select-vlaue-binding/select-value-binding-example.ts

+/** @title Select with 2-way value binding */
+@Component({
+  selector: 'select-value-binding-example',
+  templateUrl: 'select-value-binding-example.html',


Missing link to the CSS file.

crisbeto

LGTM

mmalerba · 2017-10-10T20:20:28Z

comments addressed. @kara we can't remove the empty CSS files because the example generator will barf. I added the links to the no-op files though

jelbourn

Looked at the

jelbourn · 2017-10-11T15:49:26Z

guides/creating-a-custom-form-field-control.md

-the `MatFormFieldControl` interface, see its
-[definition](https://github.com/angular/material2/blob/master/src/lib/form-field/form-field-control.ts).
+the `MatFormFieldControl` interface, see the
+[form field API documentation](https://material.angular.io/components/form-field/api).
 (Unfortunately generated API docs are not available yet, but we'll go through the methods and
 properties in this guide.) 


Remove the Unfortunately... bit? I'd rather just get into the content than draw attention to it.

Actually meant to delete this since it's not true anymore

jelbourn · 2017-10-11T15:53:30Z

src/lib/input/input.md


-<!-- example(input-prefix-suffix) -->
+The `<mat-form-field>` allows you to


Should this be moved to the mat-form-field docs?

Ideally yes, in the future once the functionality is extracted into the form field, but currently this is up to the individual FormFieldControl to add support for custom error state matchers (and the attribute goes on the <input> not the <mat-form-field>).

jelbourn · 2017-10-11T15:57:06Z

src/lib/select/select.md

-In your template, create an `mat-select` element. For each option you'd like in your select, add an
-`mat-option` tag. Note that you can disable items by adding the `disabled` boolean attribute or
-binding to it.
+The select component is set up as a custom value accessor, so you can manipulate the select's value


"is set up as..." -> "supports all directives from @angular/forms"?

jelbourn · 2017-10-11T15:57:33Z

src/lib/select/select.md


-### Getting and setting the select value
+`<mat-select>` also supports 2-way binding to the `value` property without the need for Angular


Swap the order of using value and forms?

jelbourn · 2017-10-11T15:58:20Z

src/lib/select/select.md

+be specified either via a `placeholder` attribute on the `<mat-select>` or a `<mat-placeholder>`
+element in the same form field as the `<mat-select>`. The `<mat-form-field>` also has additional
+options for changing the behavior of the placeholder. For more information see the
+[form field placeholder documentation](https://material.angular.io/components/form-field/overview#floating-placeholder).


Could this section be folded into the "Form field features" section?

I'd like to keep it here too since placeholder is an attribute that you place on the <mat-select> (in the future when we split the placeholder and label into separate concepts it can be completely handled by the form field).

jelbourn · 2017-10-11T16:00:13Z

src/lib/select/select.md

+
+### Selecting multiple options
+
+By default, the `<mat-select>` only supports selecting a single option at a time. However, you can 


"By default, the <mat-select> only supports selecting a single option at a time. "
->
"<mat-select> defaults to single-selection mode, but can be configured..."

jelbourn · 2017-10-11T16:02:55Z

src/lib/select/select.md

+
+#### Error: Cannot change `multiple` mode of select after initialization
+
+This error is thrown if you attempt to bind the `multiple` property on `<mat-select>` to a dynamic


Why can't we change this at run-time?

I put that in place when I initially implemented multiple selection. It's there because there's some ambiguity about what to do with the selected values when you're switching modes. Also it's unlikely that you'll need to toggle it after init anyway (we haven't had any issues about it yet).

jelbourn · 2017-10-11T16:03:57Z

src/lib/select/select.md

+</mat-select>
+```
+
+#### Error: Cannot assign truthy non-array value to select in `multiple` mode


Rename this error "Value must be an array in multiple-selection mode" ?

jelbourn · 2017-10-11T16:04:14Z

src/lib/select/select.md

+a `<mat-select multiple>`. For example, something like `mySelect.value = 'option1'`. What you likely
+meant to do was `mySelect.value = ['option1']`.
+
+#### Error: Cannot assign a non-function value to `compareWith`


Rename this error "compareWith must be a function"?

jelbourn · 2017-10-11T16:04:52Z

src/lib/select/select.ts

@@ -461,6 +464,12 @@ export class MatSelect extends _MatSelectMixinBase implements AfterContentInit,
    }
  }

+  ngOnChanges(changes: SimpleChanges) {
+    if (changes.disabled) {


Add a comment here?

mmalerba

comments addressed

mmalerba · 2017-10-11T18:00:11Z

src/lib/input/input.md


-<!-- example(input-prefix-suffix) -->
+The `<mat-form-field>` allows you to


Ideally yes, in the future once the functionality is extracted into the form field, but currently this is up to the individual FormFieldControl to add support for custom error state matchers (and the attribute goes on the <input> not the <mat-form-field>).

mmalerba · 2017-10-11T18:06:26Z

src/lib/select/select.md

+be specified either via a `placeholder` attribute on the `<mat-select>` or a `<mat-placeholder>`
+element in the same form field as the `<mat-select>`. The `<mat-form-field>` also has additional
+options for changing the behavior of the placeholder. For more information see the
+[form field placeholder documentation](https://material.angular.io/components/form-field/overview#floating-placeholder).


I'd like to keep it here too since placeholder is an attribute that you place on the <mat-select> (in the future when we split the placeholder and label into separate concepts it can be completely handled by the form field).

jelbourn

LGTM

angular-automatic-lock-bot · 2019-09-07T09:03:01Z

This issue has been automatically locked due to inactivity.
Please file a new issue if you are encountering a similar or related problem.

Read more about our automatic conversation locking policy.

_{This action has been performed automatically by a bot.}

mmalerba added docs This issue is related to documentation pr: merge safe labels Oct 9, 2017

mmalerba assigned jelbourn and kara Oct 9, 2017

mmalerba requested review from jelbourn and kara October 9, 2017 23:40

mmalerba requested review from amcdnl and crisbeto as code owners October 9, 2017 23:40

googlebot added the cla: yes PR author has agreed to Google's Contributor License Agreement label Oct 9, 2017

mmalerba force-pushed the ff-docs branch 2 times, most recently from 84c55ba to b110cdd Compare October 9, 2017 23:56

willshowell reviewed Oct 10, 2017

View reviewed changes

crisbeto reviewed Oct 10, 2017

View reviewed changes

kara reviewed Oct 10, 2017

View reviewed changes

willshowell mentioned this pull request Oct 10, 2017

Update disabled for mat-select does not fully work #7683

Closed

mmalerba force-pushed the ff-docs branch from 52964a9 to b9dcfb5 Compare October 10, 2017 18:48

crisbeto reviewed Oct 10, 2017

View reviewed changes

crisbeto approved these changes Oct 10, 2017

View reviewed changes

mmalerba force-pushed the ff-docs branch from b9dcfb5 to b4cb61b Compare October 10, 2017 20:19

mmalerba force-pushed the ff-docs branch from b4cb61b to 69a2471 Compare October 10, 2017 20:21

jelbourn reviewed Oct 11, 2017

View reviewed changes

mmalerba added 5 commits October 11, 2017 10:54

update input docs

3097d52

input examples

b4941c7

select docs & examples

9ed432c

add troubleshooting section for select

f17f34d

address comments

50d2f11

mmalerba removed the pr: merge safe label Oct 11, 2017

address more comments

5c95ecd

mmalerba force-pushed the ff-docs branch from 69a2471 to 5c95ecd Compare October 11, 2017 18:54

mmalerba commented Oct 11, 2017

View reviewed changes

jelbourn approved these changes Oct 11, 2017

View reviewed changes

jelbourn added pr: lgtm action: merge The PR is ready for merge by the caretaker and removed pr: needs review labels Oct 11, 2017

andrewseguin merged commit e129e3d into angular:master Oct 12, 2017

angular-automatic-lock-bot bot locked and limited conversation to collaborators Sep 7, 2019


		### Changing when error messages are shown

		The `<mat-form-field>` allows you to

		@@ -0,0 +1,8 @@
		import {Component} from '@angular/core';

		/** @title Select with cno option ripple */


		Global default placeholder options can be specified by setting the `MAT_PLACEHOLDER_GLOBAL_OPTIONS` provider. This setting will apply to all components that support the floating placeholder.
		By default when a user clicks on a `<mat-option>` a ripple animation is shown. This can be disabled


		### Selecting multiple options

		By default the `<mat-select>` only supports selecting a single option at a time. However you can use


		<!-- example(input-prefix-suffix) -->
		The `<mat-form-field>` allows you to


		### Getting and setting the select value
		`<mat-select>` also supports 2-way binding to the `value` property without the need for Angular


		### Selecting multiple options

		By default, the `<mat-select>` only supports selecting a single option at a time. However, you can


		#### Error: Cannot change `multiple` mode of select after initialization

		This error is thrown if you attempt to bind the `multiple` property on `<mat-select>` to a dynamic

docs(input, select): update docs and create more examples #7673

docs(input, select): update docs and create more examples #7673

Uh oh!

Conversation

mmalerba commented Oct 9, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kara left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

crisbeto left a comment

Choose a reason for hiding this comment

Uh oh!

mmalerba commented Oct 10, 2017

Uh oh!

jelbourn left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

crisbeto Oct 11, 2017 •

edited

Loading