docs(tutorial/3 - Components): Adding Tag to Angular Mapping Info

[joej164]

I was confused when reading the tutorial on how the HTML phone-list tag was mapped to the AngularJS component name. Once I figured out it was the line of code that did this and how, I figured clarification would be helpful to other people.

Also, I initially thought the tag mapping was done at the filename since that was the only thing in the javascript that matched the HTML tags.

What kind of change does this PR introduce? (Bug fix, feature, docs update, ...)

What is the current behavior? (You can also link to an open issue here)

What is the new behavior (if this is a feature change)?

Does this PR introduce a breaking change?

Please check if the PR fulfills these requirements

• [ X] The commit message follows our guidelines
• Fix/Feature: Docs have been added/updated
• Fix/Feature: Tests have been added; existing tests pass

Other information:

[googlebot]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project (if not, look below for help). 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 (or fixed any issues), please reply here (e.g. I signed it!) and we'll verify it.

---

What to do if you already signed the CLA

Individual signers

• It's possible we don't have your GitHub username or you're using a different email address on your commit. Check your existing CLA data and verify that your email is set on your git commits.

Corporate signers

• Your company has a Point of Contact who decides which employees are authorized to participate. Ask your POC to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the Google project maintainer to go/cla#troubleshoot (Public version).
• The email used to register you as an authorized contributor must be the email used for the Git commit. Check your existing CLA data and verify that your email is set on your git commits.
• The email used to register you as an authorized contributor must also be attached to your GitHub account.

[googlebot]

Thanks for your pull request. It looks like this may be your first contribution to a Google open source project (if not, look below for help). 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 (or fixed any issues), please reply here (e.g. I signed it!) and we'll verify it.

---

What to do if you already signed the CLA

Individual signers

• It's possible we don't have your GitHub username or you're using a different email address on your commit. Check your existing CLA data and verify that your email is set on your git commits.

Corporate signers

• Your company has a Point of Contact who decides which employees are authorized to participate. Ask your POC to be added to the group of authorized contributors. If you don't know who your Point of Contact is, direct the Google project maintainer to go/cla#troubleshoot (Public version).
• The email used to register you as an authorized contributor must be the email used for the Git commit. Check your existing CLA data and verify that your email is set on your git commits.
• The email used to register you as an authorized contributor must also be attached to your GitHub account.

[joej164]

I signed it!

[googlebot]

CLAs look good, thanks!

[googlebot]

CLAs look good, thanks!

[gkalpak]

It is super-awesome that you came back to improve things for others once you figured it out yourself. A true bridge builder 💯

That said, I feel that this is adequately explained earlier in that step:

Remember that (since components are also directives) the name of the component is in camelCase
(e.g. myAwesomeComponent), but we will use kebab-case (e.g. my-awesome-component) when
referring to it in our HTML. (See [here][case-styles] for a description of different case styles.)

Then, a little further below:

Let's see an example:

...
component('greetUser', { ... });

Now, every time we include <greet-user></greet-user> in our view, AngularJS will expand it into a
DOM sub-tree constructed using the provided template and managed by an instance of the specified
controller.

WDYT?

[joej164]

Hello, My big issue with that was, in hindsight the documentation made sense, but reading the first time it was not clear. I was thinking a concrete code example showing the mapping of the Javascript to the html tag would be helpful for initial understanding. When I was trying to figure out how the mapping worked, I initially thought that the mapping was occurring at the file level because the javascript file (phone-list.component.js) name was the only thing that had the HTML tag (<phone-list></phone-list>) in it. It took me having the code up and changing things(trial and error) in the javascript file before I realized that there was a CamelCase to Kebab case conversion that was not clear on first read. Even maybe a Note in the first section linked above stating that the "Camel Case component name in line 6 of phone-list.component.js is what defines the kebab-case phone-list tag in line 15 of index.html" something like that would have made the understanding for a first time reader a bit easier I think. My background... I'm a former telephony engineer moved into a Python Developer role in my company within the last year. The project I'm working on is using Angular.js 1.5 for the front end, so I'm having to learn Angular.js and I'm not coming into it with alot of understanding software documentation background. Let me know what you think. Hopefully providing a bit of my thought process and the problems I was having at that point might help with what I was trying to get at. I'm happy to tweak/modify if you think a better way can be found. Also if you'd rather not merge the PR, I understand as well. Thanks for your time reviewing my PR either way. Joe

…

On Wed, Oct 24, 2018 at 7:25 AM George Kalpakas ***@***.***> wrote: It is super-awesome that you came back to improve things for others once you figured it out yourself. A true bridge builder ***@***.***/become-a-bridge-builder-dc45824e590e> 💯 That said, I feel that this is adequately explained earlier in that step <https://github.com/angular/angular.js/blob/4a0208ea73c1d44628bcd00e3e0bde3b132e195b/docs/content/tutorial/step_03.ngdoc#L70-L72> : Remember that (since components are also directives) the name of the component is in camelCase (e.g. myAwesomeComponent), but we will use kebab-case (e.g. my-awesome-component) when referring to it in our HTML. (See [here][case-styles] for a description of different case styles.) Then, a little further below <https://github.com/angular/angular.js/blob/4a0208ea73c1d44628bcd00e3e0bde3b132e195b/docs/content/tutorial/step_03.ngdoc#L78-L93> : Let's see an example: ...component('greetUser', { ... }); Now, every time we include <greet-user></greet-user> in our view, AngularJS will expand it into a DOM sub-tree constructed using the provided template and managed by an instance of the specified controller. WDYT? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#16740 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AX9nrHA-Ohj-9kpdF4Of5nfQGW6vx2-xks5uoHhggaJpZM4XxAPJ> .

[gkalpak]

Sorry for the late response, @joej164. (On the bright side, the tutorial is now updated (using newer versions of Angular/jQuery, using npm for monaging dependencies (instead of the deprecated bower), etc.) 🎉)

I can't argue with the fact that you missed this bit of information on first read, so making sure people don't miss this link is important.
But, instead of adding a third mention of it, I would rather make it more clear in one of the previous mentions (see #16740 (comment)).

WDYT, about adding a more explicit explanation or alert-info div there?

[joej164]

Yes, that works, i think all that is missing in the alert-info div for a newbie is an explicit example of the new element used in some HTML. I'll take a stab that and update my PR and see what you think.

[googlebot]

We found a Contributor License Agreement for you (the sender of this pull request), but were unable to find agreements for all the commit author(s) or Co-authors. 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.
In order to pass this check, please resolve this problem and have the pull request author add another comment and the bot will run again. If the bot doesn't comment, it means it doesn't think anything has changed.

[googlebot]

We found a Contributor License Agreement for you (the sender of this pull request), but were unable to find agreements for all the commit author(s) or Co-authors. 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.
In order to pass this check, please resolve this problem and have the pull request author add another comment and the bot will run again. If the bot doesn't comment, it means it doesn't think anything has changed.

[joej164]

Alright so I did an update from my work computer and it now has my work email address listed as a contributer. While I could sign the CLA, i'm not sure that's a good idea from my work account, so i'm going to close this PR and open another one and reference this from that one.

[joej164]

#16768

As shown above, I updated the changes for this PR in #16768 to remove a work account of mine as a contributer of the PR.