Copy edits to User Input chapter of Guide. #2397

niceredfrog · 2016-09-17T23:05:01Z

No description provided.

- Add some more space to the right on desktop - Remove `text-decoration` - Use correct `line-height` for the icon

Footer logo was overflowing at ~960px wide viewport. Added `background-size: contain` (shorthand), and `max-width: 100%` to contain wrapper, and background image within grid.

googlebot · 2016-09-17T23:05:07Z

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed, please reply here (e.g. I signed it!) and we'll verify. Thanks.

If you've already signed a CLA, it's possible we don't have your GitHub username or you're using a different email address. Check your existing CLA data and verify that your email is set on your git commits.
If you signed the CLA as a corporation, please let us know the company's name.

googlebot · 2016-09-17T23:05:08Z

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

📝 Please visit https://cla.developers.google.com/ to sign.

Once you've signed, please reply here (e.g. I signed it!) and we'll verify. Thanks.

If you've already signed a CLA, it's possible we don't have your GitHub username or you're using a different email address. Check your existing CLA data and verify that your email is set on your git commits.
If you signed the CLA as a corporation, please let us know the company's name.

) * fixed spelling of ActivateRoute to ActivatedRoute * dont do cache

angular@69ae63c changed `public/docs/_examples/webpack/ts/config/webpack.common.js` and `public/docs/_examples/webpack/ts/config/webpack.test.js` and replaced `ts` with `awesome-typescript-loader`. So we can remove `"ts-loader": "^0.8.1",` from the `public/docs/_examples/webpack/ts/package.webpack.json`.

…ngular#2342) Add missing app.module.js source example in Basics > Forms dev guide - File is missing for JavaScript, but present for TypeScript

kwalrath

Yay, your changes are looking good. I have some feedback—some of which is very similar to feedback I gave Kapunahele, so I'd like her to review this, too.

@kapunahelewong could you please work with Jessica to make sure that (1) your work is consistent and (2) common issues are in the checklist? Thanks!

In the meantime, I'll try to build this to see what it looks like.

kwalrath · 2016-09-19T20:29:50Z

public/docs/ts/latest/guide/user-input.jade


-  When writing a binding we must be aware of a template statement's **execution context**.
+  NOTE: A [template statement](./template-syntax.html#template-statements) is a subset


That's not how we format notes. You should be able to find an example to follow by grepping other .jade files for "Note:".

kwalrath · 2016-09-19T20:31:28Z

public/docs/ts/latest/guide/user-input.jade

 +makeExample('user-input/ts/app/keyup.components.ts', 'key-up-component-1-template', 'app/keyup.components.ts (template v.1)')(format=".")
 :marked
  Angular makes an event object available in the **`$event`** variable,
-  which we pass to the component's `onKey()` method.
-  The user data we want is in that variable somewhere.
+  which it passes to the component's `onKey()` method.


Angular doesn't pass it, our code does. Maybe:

which the code passes as a parameter to ...

kwalrath · 2016-09-19T20:33:12Z

public/docs/ts/latest/guide/user-input.jade

-  to display the accumulating `values` property back on screen.
+  The `onKey()` component method extracts the user's input
+  from the event object, adding that input to the list of user data that is accumulating in the component's `values` property.
+  [Interpolation](./template-syntax.html#interpolation)


Interpolation doesn't display it, it's how we make it be displayed. Um... maybe:

The code uses interpolation to ...

Then the interpolation displays the accumulating values property.

No need for "back onto the screen".

kwalrath · 2016-09-19T20:33:49Z

public/docs/ts/latest/guide/user-input.jade

  +makeExample('user-input/ts/app/keyup.components.ts', 'key-up-component-1-class', 'app/keyup.components.ts (class v.1 - strongly typed )')(format=".")
  :marked
    <br>Strong typing reveals a serious problem with passing a DOM event into the method:
    too much awareness of template details, too little separation of concerns.

-    We'll address this problem in our next try at processing user keystrokes.
+    You'll address this problem in our next try at processing user keystrokes.


Grep for "our", replace with "your" or "the" or whatever you deem appropriate.

(grep for "we", while you're at it)

And "let's" and "us"

kwalrath · 2016-09-19T20:35:05Z

public/docs/ts/latest/guide/user-input.jade

@@ -37,27 +40,27 @@ include ../_util-fns
 .l-main-section
 :marked
  ## Get user input from the $event object
-  We can bind to all kinds of events. Let's bind to the keyup event of an input box and replay
+  You can bind to all kinds of events. In this case, you'll bind to the keyup event of an input box and replay


This page has a lot of "will/'ll" in it, which is counter to our style... I think our editor gave up on doing the kind of rewrite it'd take to eradicate it, but you should feel free to go further (as long as doing so doesn't make the text unfriendly or hard to read).

kwalrath · 2016-09-19T20:39:03Z

public/docs/ts/latest/guide/user-input.jade

-    We're binding to the number 0, the shortest statement we can think of.
-    That is all it takes to keep Angular happy. We said it would be clever!
+    By binding the `keyup` event
+    to the number 0, the shortest statement we can think of, the statement


Change to avoid "we"

the shortest statement imaginable,

kwalrath · 2016-09-19T20:39:31Z

public/docs/ts/latest/guide/user-input.jade

-  Our previous example won't transfer the current state of the input box if the user mouses away and clicks
-  elsewhere on the page. We update the component's `values` property only when the user presses Enter
+  If the user mouses away and clicks elsewhere on the page,
+  the previous example won't transfer the current state of the input box.


won't -> doesn't

kwalrath · 2016-09-19T20:40:09Z

public/docs/ts/latest/guide/user-input.jade

-  elsewhere on the page. We update the component's `values` property only when the user presses Enter
+  If the user mouses away and clicks elsewhere on the page,
+  the previous example won't transfer the current state of the input box.
+  You update the component's `values` property only when the user presses Enter


Let's rewrite this to avoid "You" and be more accurate. Maybe:

The component's values property updates only when...

kwalrath · 2016-09-19T20:40:31Z

public/docs/ts/latest/guide/user-input.jade


 +makeExample('user-input/ts/app/keyup.components.ts', 'key-up-component-4' ,'app/keyup.components.ts (v4)')(format=".")

 .l-main-section
 :marked
  ## Put it all together
-  We learned how to [display data](./displaying-data.html) in the previous chapter.
-  We've acquired a small arsenal of event binding techniques in this chapter.
+  The previous chapter showed how to [display data](./displaying-data.html).


chapter -> page
(global)

@kwalrath We've been consistently calling these things "chapters". When did they become "pages"?

@wardbell We started that when we switched to the new style guide. I don't remember the history of the decision (Naomi might), but it's in the checklist. I've added it to the word list.

kwalrath · 2016-09-19T20:41:24Z

public/docs/ts/latest/guide/user-input.jade

-  Instead, we grab the input box *value* and pass *that* to `addHero`.
-  The component knows nothing about HTML or the DOM, which is the way we like it.
+  Instead of passing the `newHero` into the component's `addHero` method,
+  grab the input box *value* and pass *that* to `addHero`.

  ### Keep template statements simple
  We bound `(blur)` to *two* JavaScript statements.


We -> (rewrite)

In the section that follows, there are lots of "we" and some sentences similar to this one: "The second statement exists for a good reason" that could be cut or minimized.

This paragraph, "Although the example works, we are rightly wary of JavaScript in HTML. Template statements are powerful. We're supposed to use them responsibly. Complex JavaScript in HTML is irresponsible" and "Should we reconsider our reluctance to pass the input box into the component?", could be reworked.

How about something along these lines:

"This example works and is fine for a demonstration, but a better practice is to separate the JavaScript and HTML. Refactor using NgModel as covered in the Forms page."

niceredfrog · 2016-09-19T22:13:50Z

I signed it!

googlebot · 2016-09-19T22:13:55Z

We found a Contributor License Agreement for you (the sender of this pull request), but were unable to find agreements for the commit author(s). If you authored these, maybe you used a different email address in the git commits than was used to sign the CLA (login here to double check)? If these were authored by someone else, then they will need to sign a CLA as well, and confirm that they're okay with these being contributed to Google.

googlebot · 2016-09-19T22:13:55Z

We found a Contributor License Agreement for you (the sender of this pull request), but were unable to find agreements for the commit author(s). If you authored these, maybe you used a different email address in the git commits than was used to sign the CLA (login here to double check)? If these were authored by someone else, then they will need to sign a CLA as well, and confirm that they're okay with these being contributed to Google.

* docs: fix {ts,dart,js}/latest/_data.json Fixes angular#2384. Fixes angular#2385. * post-review updates Addressing angular#2407.

An initial multilang cleanup for ng2.io

No net effect on the generated docs. Preparatory work for ng2.io.

…r#2389) ng2.io preparatory work.

wardbell

I like what you've done. Please incorporate (or improve upon) these suggestions and we can quickly move this PR into production.

wardbell · 2016-09-20T04:25:36Z

public/docs/ts/latest/guide/user-input.jade

+  The `(click)`, to the left of the equals sign, identifies the button's click event as the **target of the binding**.
+  The text in quotes, to the right of the equals sign,
+  is the **template statement**, which responds
+  respond to the click event by calling the component's `onClickMe` method.


"responds respond" ?

wardbell · 2016-09-20T04:27:26Z

public/docs/ts/latest/guide/user-input.jade

@@ -37,27 +40,27 @@ include ../_util-fns
 .l-main-section
 :marked
  ## Get user input from the $event object
-  We can bind to all kinds of events. Let's bind to the keyup event of an input box and replay
+  You can bind to all kinds of events. In this case, you'll bind to the keyup event of an input box and replay


Yup. "In this case, bind to"

wardbell · 2016-09-20T04:28:47Z

public/docs/ts/latest/guide/user-input.jade

  what the user types back onto the screen.

-  This time we'll (1) listen to an event and (2) grab the user's input.
+  This time, you'll listen to an event and grab the user's input.


The imperative mood can help here and many places, don't you think.

As in "This time, listen to an event"

The only problem with using imperative here is that the reader might think that they're being ordered to do something (which they don't know yet how to do yet). This is the one case where future tense (and possibly even "let's") might be the way to go.

wardbell · 2016-09-20T04:32:07Z

public/docs/ts/latest/guide/user-input.jade

  [`HTMLInputElement`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement), which
-  has a `value` property that contains our user input data.
+  has a `value` property containing the user input data.


Curious about the penchant for the present participle. Is "containing the" really better than "that contains the"?

This is a genuine uncertainty on my part. Maybe it's a matter of mixing the two forms so that neither dominates and tires the ear.

I don't know why, either. They seemed equivalent to me. I can ask the editor to explain.

wardbell · 2016-09-20T04:34:39Z

public/docs/ts/latest/guide/user-input.jade

-  to display the accumulating `values` property back on screen.
+  The `onKey()` component method extracts the user's input
+  from the event object, adding that input to the list of user data that is accumulating in the component's `values` property.
+  [Interpolation](./template-syntax.html#interpolation)


Then the interpolation displays the accumulating values property.

No need for "back onto the screen".

wardbell · 2016-09-20T05:50:37Z

public/docs/ts/latest/guide/user-input.jade


-  Angular can filter the key events for us. Angular has a special syntax for keyboard events.
-  We can listen for just the Enter key by binding to Angular's `keyup.enter` pseudo-event.
+  However, you can listen for just the Enter key by binding to Angular's `keyup.enter` pseudo-event.


We should keep the reason for the keyup.enter alternative. How about this?

Sometimes only the Enter key matters because it signals that the user has finished typing. The event handler could examine every `$event.keyCode` and pounce on the Enter key. But there's an easier way: bind to the `keyup.enter` pseudo-event and Angular will call the handler for that key alone. +makeExample('user-input/ts/app/keyup.components.ts', 'key-up-component-3' ,'app/keyup.components.ts (v3)')(format=".") .l-sub-section :marked In this example, the data binding expression handles the event. It's a better practice to minimize JavaScript in HTML and move this code into the component.

Agreed that the reason for the keyup.enter alternative should be in there (as succinctly as possible, while still being clear).

wardbell · 2016-09-20T05:57:42Z

public/docs/ts/latest/guide/user-input.jade

  while the focus is inside the input box.

-  Let's fix that by listening to the input box's blur event as well.
+  To fix that, listen to the input box's blur event as well.


Let's crisp up the entire intro. What do you think of this:

In the previous example, the current state of the input box is lost if the user mouses away and clicks elsewhere on the page without first pressing Enter.

To fix that, listen for both the Enter key and the blur event.

wardbell · 2016-09-20T05:58:58Z

public/docs/ts/latest/guide/user-input.jade


 +makeExample('user-input/ts/app/keyup.components.ts', 'key-up-component-4' ,'app/keyup.components.ts (v4)')(format=".")

 .l-main-section
 :marked
  ## Put it all together
-  We learned how to [display data](./displaying-data.html) in the previous chapter.
-  We've acquired a small arsenal of event binding techniques in this chapter.
+  The previous chapter showed how to [display data](./displaying-data.html).


@kwalrath We've been consistently calling these things "chapters". When did they become "pages"?

wardbell · 2016-09-20T06:05:08Z

public/docs/ts/latest/guide/user-input.jade


-  There should be a better third way. And there is, as we'll see when we learn about `NgModel` in the [Forms](forms.html) chapter.
+  Although the example *works*, it makes use of JavaScript in HTML,


Although the example works, it relies on JavaScript in the HTML. That's a bad practice. Move the JavaScript to the component class.

wardbell · 2016-09-20T06:17:24Z

public/docs/ts/latest/guide/user-input.jade

-  Angular has a two-way binding called `NgModel`, which we'll learn about
-  in the `Forms` chapter.
+  Angular has a two-way binding called `NgModel`, which is explained in
+  the `Forms` chapter.


You have mastered the basic primitives for responding to user input and gestures.

They quickly become verbose and clumsy when handling large amounts of user input. Two-way data binding is a more elegant and compact way to move values between data entry fields and model properties. The next chapter, "Forms", explains how to write two-way bindings with NgModel .

wardbell · 2016-09-20T06:31:02Z

We can't merge until you have a CLA that Github recognizes.

Normally I take care of that by adding you to our IdeaBlade google group (you're covered under our CLA). But that isn't working here because you're github contributions are in the name of "niceredfrog" which doesn't have an associated email address.

I can enroll you in our group but only with a github-recognized email address. I've sent you an invitation to join that group using the email associated with your commits. You may have to update the niceredfrog profile with that address.

If you don't want to do that (not clear why; anyone looking at your commits can see the email address as I did), you can sign your own personal CLA.

wardbell · 2016-09-20T06:42:20Z

Travis reports that this jade doc is broken. Confirmed by running gulp serve-and-sync-devguide and going to the "User Input" chapter.

The cause in this case is a blank line after :marked (line 177). That's a familiar problem for Harp. I'll leave it to you to fix. Please know that we generally can't merge PRs that Travis rejects and certainly can't merge broken jade pages.

.htm => .html

The `end_of_line` setting causes issues on Windows machines that have `autocrlf` set to true (the default): https://git-scm.com/book/tr/v2/Customizing-Git-Git-Configuration#Formatting-and-Whitespace

niceredfrog · 2016-10-19T18:58:38Z

Confirm.

On Saturday, October 1, 2016 1:03 AM, googlebot <[email protected]> wrote:

We found a Contributor License Agreement for you (the sender of this pull request) and all commit authors, but as best as we can tell these commits were authored by someone else. If that's the case, please add them to this pull request and have them confirm that they're okay with these commits being contributed to Google. If we're mistaken and you did author these commits, just reply here to confirm.—
You are receiving this because you authored the thread.
Reply to this email directly, view it on GitHub, or mute the thread.

s s

* added example of feature module pre-loading * added transition aliases for route animations

…#2630)

closes issue angular#2598

- gulp task: don’t copy over internal libraries. - Adjust anchor hrefs rather than use `<base href>` in generated API pages. The net effect is the same.

* chore: update examples to @types * fix toh-6 aot and add types link

Technically 'nestled' still makes sense in this context, but is a little too Christmas-y! - I assume you meant 'nested' :P

…s well (angular#2652)

chalin · 2016-10-26T19:21:20Z

Superseded by #2683. Jessica: consider closing this PR (which still has CLA issues) in favor of using #2683.

Jacob Müller and others added 4 commits August 10, 2016 08:42

fix(footer): Improve styleguide trigger positioning

47b6dc2

Further improve styleguide trigger styles

18dba19

- Add some more space to the right on desktop - Remove `text-decoration` - Use correct `line-height` for the icon

Fixed footer logo overflowing

6c2ec82

Footer logo was overflowing at ~960px wide viewport. Added `background-size: contain` (shorthand), and `max-width: 100%` to contain wrapper, and background image within grid.

Copy edits to User Input chapter of Guide.

20a5e38

googlebot added the CLA: no label Sep 17, 2016

johnpapa and others added 6 commits September 18, 2016 18:34

docs(toh): fix spelling of ActivateRoute to ActivatedRoute (angular#2400

159b196

) * fixed spelling of ActivateRoute to ActivatedRoute * dont do cache

docs(testing): fix small typo (angular#2401)

40f320d

docs(webpack): move to core-js in testing (angular#2404)

c17f859

docs(forms): remove deprecated forms notice for js (angular#2395)

45fec1c

docs(devguide): add missing app.module.js source in Basics > Forms (a…

d07d428

…ngular#2342) Add missing app.module.js source example in Basics > Forms dev guide - File is missing for JavaScript, but present for TypeScript

kwalrath suggested changes Sep 19, 2016

View reviewed changes

chalin and others added 9 commits September 20, 2016 00:52

docs: fix {ts,dart,js}/latest/_data.json (angular#2387)

d26007a

* docs: fix {ts,dart,js}/latest/_data.json Fixes angular#2384. Fixes angular#2385. * post-review updates Addressing angular#2407.

docs(tutorial): don't use shredder for intro page (angular#2388)

e016f3f

An initial multilang cleanup for ng2.io

about(shannon): add shannon's bio

1027e3e

docs(testing): more scenarios (angular#2396)

7b5244c

docs: use Jade include rather than Harp partial (angular#2392)

0c678c2

No net effect on the generated docs. Preparatory work for ng2.io.

docs(lang/latest): parameterize landing page Jade by language (angula…

98efced

…r#2389) ng2.io preparatory work.

docs(ts-to-js): change angular2 to @angular (angular#2403)

730c93b

chore: rename Angular 2 to simply Angular (angular#2402)

693f6ae

docs(overview): update to new organization (angular#2405)

7d45d60

wardbell approved these changes Sep 20, 2016

View reviewed changes

wardbell added the action: review label Sep 20, 2016

bampakoa and others added 6 commits October 18, 2016 15:11

docs(cb-aot): fix typo in tab names. (angular#2621)

3508b79

docs(toh-5): fix typo in link (angular#2622)

e89ba6f

.htm => .html

docs(testing): fix broken links (angular#2624)

6ece848

docs(server-communication): grammar fix (angular#2626)

fdc1b04

docs(webpack): change resolve ordering (angular#2628)

b17c5c0

chore: remove end_of_line from editorconfig (angular#2635)

dc5fc21

The `end_of_line` setting causes issues on Windows machines that have `autocrlf` set to true (the default): https://git-scm.com/book/tr/v2/Customizing-Git-Git-Configuration#Formatting-and-Whitespace

Eric Jimenez and others added 19 commits October 19, 2016 21:49

chore: rename Developer Guides to Guide in _data.json(angular#2563)

1fe6434

docs(aot-cb):bundle in-mem-web-api with esm and umd (angular#2617)

3eb7a41

s s

docs(router): Added example of feature module pre-loading (angular#2595)

2f5306f

* added example of feature module pre-loading * added transition aliases for route animations

docs(HTTP Client): edit copy to conform to G-doc guidelines. (angular…

c28b003

…#2630)

chore(testing): fix broken input/output link (angular#2638)

101265c

docs(template-syntax): explain basic two-way binding (angular#2639)

870ce12

closes issue angular#2598

chore: Dart API doc gen cleanup and refactoring (angular#2641)

75f37b7

- gulp task: don’t copy over internal libraries. - Adjust anchor hrefs rather than use `<base href>` in generated API pages. The net effect is the same.

chore: update to @types (angular#1872)

0d49fec

* chore: update examples to @types * fix toh-6 aot and add types link

docs(change-log): update for move to @typings (angular#2643)

82933ba

docs(change-log): notes in-mem-web-api breaking change (angular#2644)

14c01fb

chore: update to 2.1.1 (angular#2650)

4c85f0a

docs(animation): add note about aliases (angular#2629)

bfd08c0

chore(tsconfig): add compileOnSave (angular#2658)

c5a1b3f

Typo fix (angular#2657)

c746c73

Technically 'nestled' still makes sense in this context, but is a little too Christmas-y! - I assume you meant 'nested' :P

docs(security): improve xsrf description and add it to http chapter a…

ea7dff4

…s well (angular#2652)

Copy edits to User Input chapter of Guide.

f47a403

docs: copy edits on User Input page of Guide

7c010bb

docs: copy edits on User Input page of Guide

31f85a1

docs: copy edits on User Input page of Guide

df4b033

chalin mentioned this pull request Oct 26, 2016

[WIP] docs(user-input): Jessica's user input edits #2683

Merged

niceredfrog closed this Nov 18, 2016

niceredfrog deleted the user-input-edits branch November 18, 2016 03:27


		When writing a binding we must be aware of a template statement's execution context.
		NOTE: A [template statement](./template-syntax.html#template-statements) is a subset


		There should be a better third way. And there is, as we'll see when we learn about `NgModel` in the [Forms](forms.html) chapter.
		Although the example works, it makes use of JavaScript in HTML,

Copy edits to User Input chapter of Guide. #2397

Copy edits to User Input chapter of Guide. #2397

Conversation

niceredfrog commented Sep 17, 2016

googlebot commented Sep 17, 2016

googlebot commented Sep 17, 2016

kwalrath left a comment

Choose a reason for hiding this comment

kwalrath Sep 19, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kwalrath Sep 19, 2016 • edited Loading

Choose a reason for hiding this comment

kapunahelewong Sep 20, 2016 • edited Loading

Choose a reason for hiding this comment

kwalrath Sep 19, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kwalrath Sep 20, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

niceredfrog commented Sep 19, 2016

googlebot commented Sep 19, 2016

googlebot commented Sep 19, 2016

wardbell left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kwalrath Sep 20, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wardbell Sep 20, 2016 • edited Loading

Choose a reason for hiding this comment

wardbell commented Sep 20, 2016

wardbell commented Sep 20, 2016

niceredfrog commented Oct 19, 2016

chalin commented Oct 26, 2016

kwalrath Sep 19, 2016 •

edited

Loading

kwalrath Sep 19, 2016 •

edited

Loading

kapunahelewong Sep 20, 2016 •

edited

Loading

kwalrath Sep 19, 2016 •

edited

Loading

kwalrath Sep 20, 2016 •

edited

Loading

kwalrath Sep 20, 2016 •

edited

Loading

wardbell Sep 20, 2016 •

edited

Loading