docs(form-field): add docs, examples, and guide #7424

mmalerba · 2017-09-29T21:34:04Z

No description provided.

kara

Mostly comma nits

kara · 2017-09-29T21:39:48Z

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

@@ -0,0 +1,337 @@
+It is possible to create custom form field controls that can be used inside `<mat-form-field>`. This
+can be useful if you need to create a components that shares a lot of common behavior with a form


a components -> a component

kara · 2017-09-29T21:40:00Z

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

+can be useful if you need to create a components that shares a lot of common behavior with a form
+field, but adds some additional logic.
+
+In order to learn how to build custom form field controls, lets start with a simple input component


lets -> let's

kara · 2017-09-29T21:41:09Z

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

+        font: inherit;
+        text-align: center;
+      }
+    </style>


Q: why style tags instead of using the styles property?

for the sake of cramming it all into 1 markdown box. do you think it would be better to do 2 boxes?

```css ... ``` ```ts ... ```

kara · 2017-09-29T21:41:49Z

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

+}
+```
+
+### Providing our component as an MatFormFieldControl


kara · 2017-09-29T21:42:10Z

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

+
+### Providing our component as an MatFormFieldControl
+The first step is to provide our new component as an implementation of the `MatFormFieldControl`
+interface that the `<mat-form-field>` knows how to work with. To do this we will have our class


To do this we -> To do this, we

kara · 2017-09-29T22:15:33Z

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

+```
+
+#### `empty`
+This property indicates whether the form field control is empty. For our control we'll consider it


For our control we'll -> For our control, we'll

kara · 2017-09-29T22:16:40Z

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

+#### `shouldPlaceholderFloat`
+This property is used to indicate whether the placeholder should be in the floating position. We'll
+use the same logic as `matInput` and float the placeholder when the input is focused or non-empty.
+Since the placeholder will be overlapping our control when when its not floating, we should hide the


its not floating -> it's not floating

kara · 2017-09-29T22:16:48Z

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

+This property is used to indicate whether the placeholder should be in the floating position. We'll
+use the same logic as `matInput` and float the placeholder when the input is focused or non-empty.
+Since the placeholder will be overlapping our control when when its not floating, we should hide the
+`–` characters when its not floating.


its not floating -> it's not floating

kara · 2017-09-29T22:17:21Z

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

+
+#### `errorState`
+This property indicates whether the associated `NgControl` is in an error state. Since we're not
+using an `NgControl` in this example we don't need to do anything other than just set it to `false`.


in this example we -> in this example, we

kara · 2017-09-29T22:18:04Z

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

+
+### Trying it out
+Now that we've fully implemented the interface, we're ready to try our component out! All we need to
+do is place it inside of a `<mat-form-filed>`


mat-form-filed -> mat-form-field

mmalerba · 2017-10-02T21:15:29Z

comments addressed

benb7760 · 2017-10-03T13:18:47Z

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

+already has a value property, we don't need to do anything for this one.
+
+#### `stateChanges`
+Because the `<mat-form-field>` used the `OnPush` change detection strategy, we need to let it know


used -> uses?

benb7760 · 2017-10-03T13:20:27Z

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

+
+set value(tel: MyTel | null) {
+  ...
+  stateChanges.next();


this.stateChanges.next()

benb7760 · 2017-10-03T13:20:37Z

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

+}
+
+ngOnDestory() {
+  stateChanges.destroy();


ngOnDestory -> ngOnDestroy

this.stateChanges.complete()

Thanks for catching these!

@mmalerba As far as I'm aware, there is no destroy method on Subject. Should it not be complete?

jelbourn · 2017-10-04T16:32:24Z

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

+<!--
+  TODO(mmalerba): Link to Plunker/StackBlitz with complete example code after beta 12.
+  (Beta 11 is missing some of the features used in the example).
+-->


We can embed live examples in guides too, so it doesn't have to be an external link.

jelbourn · 2017-10-04T16:34:02Z

src/lib/form-field/form-field.md

+<!-- example(form-field-overview) -->
+
+### Floating placeholder
+The floating placeholder is an indicative text label displayed on top of the form field control when


Omit "indicative"?

jelbourn · 2017-10-04T16:34:36Z

src/lib/form-field/form-field.md

+the control does not contain any text. By default, when text is present the floating placeholder
+floats above the form field control.
+
+The placeholder text can be specified using the `placeholder` property on the form field control, or


"The placeholder text" -> "Placeholder text" ?

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

src/lib/form-field/form-field.md

+has interacted with the element or the parent form has been submitted. Since the errors occupy the
+same space as the hints, the hints are hidden when the errors are shown.
+
+If an form field can have more than one error state, it is up to the consumer to toggle which


an form field -> a form field

jelbourn · 2017-10-04T16:36:57Z

src/lib/form-field/form-field.md

+<!-- example(form-field-error) -->
+
+### Prefix & suffix
+HTML can be included before and after the input tag, as a prefix or suffix. It will be underlined


HTML -> Custom content?

jelbourn · 2017-10-04T16:39:17Z

src/lib/form-field/form-field.md

+<!-- example(form-field-error) -->
+
+### Prefix & suffix
+HTML can be included before and after the input tag, as a prefix or suffix. It will be underlined


It will be underlined... -> It will be included within the visual container that wraps the form control.

Since the new style inputs are more than just the underline style

jelbourn · 2017-10-04T16:39:44Z

src/lib/form-field/form-field.md

+
+### Theming
+`<mat-form-field>` has a `color` property which can be set to `primary`, `accent`, or `warn`. This
+will set the color ofr the form field underline and floating placeholder based on the theme colors


ofr -> of

mmalerba · 2017-10-04T20:25:11Z

comments addressed

jelbourn

LGTM

mmalerba · 2017-10-04T22:38:49Z

@kara rebased

angular-automatic-lock-bot · 2019-09-07T08:02:29Z

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 Sep 29, 2017

mmalerba assigned jelbourn and kara Sep 29, 2017

mmalerba requested review from jelbourn and kara September 29, 2017 21:34

mmalerba requested a review from amcdnl as a code owner September 29, 2017 21:34

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

kara reviewed Sep 29, 2017

View reviewed changes

kara removed their assignment Sep 29, 2017

mmalerba force-pushed the ff-docs branch from 5c60d74 to 8f8ee0b Compare October 2, 2017 19:09

benb7760 suggested changes Oct 3, 2017

View reviewed changes

mmalerba force-pushed the ff-docs branch 2 times, most recently from 2912f4a to 39fbfd9 Compare October 4, 2017 16:33

jelbourn reviewed Oct 4, 2017

View reviewed changes

jelbourn approved these changes Oct 4, 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 4, 2017

mmalerba force-pushed the ff-docs branch 5 times, most recently from 40dbe1d to 468f1e1 Compare October 4, 2017 21:59

mmalerba requested a review from devversion as a code owner October 4, 2017 21:59

kara added pr: needs rebase and removed action: merge The PR is ready for merge by the caretaker labels Oct 4, 2017

kara assigned mmalerba and unassigned jelbourn Oct 4, 2017

mmalerba added 7 commits October 4, 2017 15:35

Add form field docs & examples

95a5300

Add form field guide

a7c49aa

update md --> mat

cd94716

do grammar good

c36812c

fix some errors in guide code

0d448e4

minor text fixes

86f0253

add full example code to guide

8d10b0f

mmalerba force-pushed the ff-docs branch from 468f1e1 to 8d10b0f Compare October 4, 2017 22:36

mmalerba added action: merge The PR is ready for merge by the caretaker and removed pr: needs rebase labels Oct 4, 2017

move styles out of template

f942945

kara merged commit adf9b5b into angular:master Oct 4, 2017

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

		@@ -0,0 +1,337 @@
		It is possible to create custom form field controls that can be used inside `<mat-form-field>`. This
		can be useful if you need to create a components that shares a lot of common behavior with a form

docs(form-field): add docs, examples, and guide #7424

docs(form-field): add docs, examples, and guide #7424

Uh oh!

Conversation

mmalerba commented Sep 29, 2017

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!

Choose a reason for hiding this comment

Uh oh!

mmalerba commented Oct 2, 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!

mmalerba commented Oct 4, 2017

Uh oh!

jelbourn left a comment

Choose a reason for hiding this comment

Uh oh!

mmalerba commented Oct 4, 2017

Uh oh!

angular-automatic-lock-bot bot commented Sep 7, 2019

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants