Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(aio): update architecture section #21569

Closed
wants to merge 2 commits into from
Closed

docs(aio): update architecture section #21569

wants to merge 2 commits into from

Conversation

jbogarthyde
Copy link
Contributor

PR Checklist

Please check if your PR fulfills the following requirements:

PR Type

What kind of change does this PR introduce?

[ ] Bugfix
[ ] Feature
[ ] Code style update (formatting, local variables)
[ ] Refactoring (no functional changes, no api changes)
[ ] Build related changes
[ ] CI related changes
[x] Documentation content changes
[ ] angular.io application / infrastructure changes
[ ] Other... Please describe:

What is the current behavior?

Issue Number: N/A

What is the new behavior?

Does this PR introduce a breaking change?

[ ] Yes
[x] No

Other information

Update doc with new section on architecture.

@jbogarthyde
Copy link
Contributor Author

jbogarthyde commented Jan 16, 2018 •
edited

@StephenFluin - The old PR was hopelessly munged. Please review this new PR with the changes we discussed, and some of the restored content that was lost in the previous PR.

@googlebot
Copy link

So there's good news and bad news.

👍 The good news is that everyone that needs to sign a CLA (the pull request submitter and all commit authors) have done so. Everything is all good there.

😕 The bad news is that it appears that one or more commits were authored by someone other than the pull request submitter. We need to confirm that all authors are ok with their commits being contributed to this project. Please have them confirm that here in the pull request.

Note to project maintainer: This is a terminal state, meaning the cla/google commit status will not change from this State. It's up to you to confirm consent of the commit author(s) and merge this pull request when appropriate.

@mary-poppins
Copy link

You can preview a324941 at https://pr21569-a324941.ngbuilds.io/.

@mary-poppins
Copy link

You can preview d720ba1 at https://pr21569-d720ba1.ngbuilds.io/.

@jenniferfell jenniferfell self-requested a review January 25, 2018 22:48
@gkalpak gkalpak added action: cleanup The PR is in need of cleanup, either due to needing a rebase or in response to comments from reviews target: patch This PR is targeted for the next patch release labels Jan 26, 2018
@gkalpak
Copy link
Member

gkalpak commented Jan 26, 2018

@jbogarthyde, can you please squash all commits into one and rebase on master?

@mary-poppins
Copy link

You can preview fdc0d52 at https://pr21569-fdc0d52.ngbuilds.io/.

@gkalpak gkalpak added cla: yes and removed cla: no labels Jan 26, 2018
@jenniferfell
Copy link
Contributor

jenniferfell commented Feb 1, 2018 •
edited

(wrong PR)

@jenniferfell jenniferfell mentioned this pull request Feb 2, 2018
Closed
2 tasks
@jenniferfell
Copy link
Contributor

I believe the rewrites in this PR also fix #21957 and #21955

@ngbot
Copy link

ngbot bot commented Feb 5, 2018

Hi @jbogarthyde! This PR has merge conflicts due to recent upstream merges.
Please help to unblock it by resolving these conflicts. Thanks!

1 similar comment
@ngbot
Copy link

ngbot bot commented Feb 5, 2018

Hi @jbogarthyde! This PR has merge conflicts due to recent upstream merges.
Please help to unblock it by resolving these conflicts. Thanks!

@mary-poppins
Copy link

You can preview 4e9e77f at https://pr21569-4e9e77f.ngbuilds.io/.

@mary-poppins
Copy link

You can preview ffa43f0 at https://pr21569-ffa43f0.ngbuilds.io/.

@wimgoeman
Copy link

I don't think #21957 is fixed with this. aio/content/guide/architecture-components.md still references <hero-detail> while the html in aio/content/examples/architecture/src/app/hero-list.component.html references <app-hero-detail>.

@mary-poppins
Copy link

You can preview 4ffe4bd at https://pr21569-4ffe4bd.ngbuilds.io/.

@jenniferfell jenniferfell mentioned this pull request Feb 15, 2018
Closed
@jenniferfell
Copy link
Contributor

This will also close issue #22158

@mary-poppins
Copy link

You can preview 7ccf9ac at https://pr21569-7ccf9ac.ngbuilds.io/.

@mary-poppins
Copy link

You can preview 784d54a at https://pr21569-784d54a.ngbuilds.io/.

gkalpak
gkalpak requested changes Mar 14, 2018
View reviewed changes
aio/content/guide/architecture-services.md Outdated

<code-example path="architecture/src/app/logger.service.ts" linenums="false" title="src/app/logger.service.ts (class)" region="class"></code-example>

Here's a `HeroService` that uses a [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) to fetch heroes.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Saying that it "uses a Promise to fetch" sounds weird.
It uses the Backend service, which in turns uses something else under the hood (e.g. XMLHttpRequest, fetch, etc.) and returns a Promise to represent the future result/response.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

aio/content/guide/architecture-services.md

<hr/>

## Dependency injection
Copy link
Member

@gkalpak gkalpak Mar 14, 2018 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section makes it sound a little bit as if DI only works on components, while it also works (and is extensively used) in other places, such as services, pipes, NgModules.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

aio/content/guide/architecture-modules.md Outdated

* `imports`&mdash;Other modules whose exported classes are needed by component templates declared in _this_ NgModule.

* `providers`&mdash;Creators of [services](guide/architecture-services) that this NgModule contributes to the global collection of services; they become accessible in all parts of the app.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

they become accessible in all parts of the app

Not true for lazy-loaded modules, which get their own injector 😁
But maybe this simplification is fine for this introductory guide.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

added note that you can specify providers at component level (which is now preferred, since it makes them tree-shakeable).

aio/content/guide/architecture-modules.md Outdated

<div class="l-sub-section">

The `export` of `AppComponent` is just to show how to export; it isn't actually necessary in this example. A root NgModule has no reason to _export_ anything because other components don't need to _import_ the root NgModule.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

because other components --> because other modules

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

aio/content/guide/architecture-modules.md Outdated

## NgModules and components

NgModules provide a _compilation context_ for their components. An NgModule has a root component, created during bootstrap, and any number of additional components that can be loaded (through the router) or created (through the template). The components that belong to an NgModule share a compilation context.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

An NgModule has a root component, created during bootstrap

This mostly applies to the root NgModule only.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this work?
NgModules provide a compilation context for their components. A root NgModule always has a root component that is created during bootstrap, but any NgModule can include any number of additional components, which can be loaded through the router or created through the template. The components that belong to an NgModule share a compilation context.

aio/content/guide/architecture-components.md Outdated

* The `*ngFor` directive tells Angular to iterate over a list.
* The `{{hero.name}}`, `(click)`, and `[hero]` bind program data to and from the DOM, responding to user input. See more about [data binding](#data-binding) below.
* The `<app-hero-detail>` tag in the example is a custom element that represents a new component, `HeroDetailComponent`. The `HeroDetailComponent` (code not shown) is a child component of the `HeroListComponent` that defines the Hero-detail view. Notice how custom components like this mix seamlessly with native HTML in the same layouts.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Calling a "custom element" is confusing (since people might think of https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

aio/content/guide/architecture-components.md Outdated

## Template syntax

A template looks like regular HTML, except that it also contains Angular [template syntax](guide/template-syntax), which alters the HTML before the view is rendered, based on your app's logic and the state of app and DOM data. Your template can use _data binding_ to coordinate the app and DOM data, _pipes_ to transform data before it is displayed, and _directives_ to apply app logic to what gets displayed.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

which alters the HTML before the view is rendered

It can modify the HTML at any time, not just before the view is rendered.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

aio/content/guide/architecture-components.md Outdated
* The `[hero]` [*property binding*](guide/template-syntax#property-binding) passes the value of `selectedHero` from
the parent `HeroListComponent` to the `hero` property of the child `HeroDetailComponent`.

* The `(click)` [*event binding*](guide/user-input#click) calls the component's `selectHero` method when the user clicks a hero's name.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why not link to https://pr21569-784d54a.ngbuilds.io/guide/user-input#binding-to-user-input-events instead?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

aio/content/guide/architecture-components.md Outdated

* The `(click)` [*event binding*](guide/user-input#click) calls the component's `selectHero` method when the user clicks a hero's name.

**Two-way data binding** is an important fourth form that combines property and event binding in a single notation, using the `ngModel` directive. Here's an example from the `HeroDetailComponent` template:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

using the ngModel directive

This makes it sound as if two-way data binding is using (or depends on) ngModel, which is not true. Two-way data binding has nothing to do with ngModel, except for the fact that two-way data binding is often used to bind to ngModel.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

done

aio/content/guide/architecture-components.md Outdated

`{{interpolated_value | pipe_name}}`

You can chain pipes, sending the output of one pipe function to be transformed by another pipe function.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might also be worth mentioning (or showing in the example code-snippet above) that pipes can also take arguments.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you provide an example?

Copy link
Member

@gkalpak gkalpak Mar 14, 2018 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://angular.io/api/common/DatePipe#examples

(I.e. {{ interpolated_value | pipe_name : arg1 : arg2 }})

@mary-poppins
Copy link

You can preview 96e6f45 at https://pr21569-96e6f45.ngbuilds.io/.

@mary-poppins
Copy link

You can preview ac2f558 at https://pr21569-ac2f558.ngbuilds.io/.

@mary-poppins
Copy link

You can preview 503647f at https://pr21569-503647f.ngbuilds.io/.

gkalpak
gkalpak approved these changes Mar 15, 2018
View reviewed changes
Copy link
Member

@gkalpak gkalpak left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A couple of minor comments.
Also the commits should be squashed together.

LGTM otherwise.

@mary-poppins
Copy link

You can preview 591b9a7 at https://pr21569-591b9a7.ngbuilds.io/.

@jenniferfell jenniferfell added the action: merge The PR is ready for merge by the caretaker label Mar 15, 2018
@jenniferfell
Copy link
Contributor

Okay..finally passing all checks. Don't touch anything. :-) Merge merge quick. :-)

mhevery pushed a commit that referenced this pull request Mar 15, 2018
@jbogarthyde @mhevery
docs(aio): update architecture section (#21569)
e1b82a0 
PR Close #21569
mhevery pushed a commit that referenced this pull request Mar 15, 2018
@jbogarthyde @mhevery
docs: incorporate suggestions and corrections from gkalpak (#21569)
2731eca 
PR Close #21569
@mhevery mhevery closed this in 04ca77e Mar 15, 2018
mhevery pushed a commit that referenced this pull request Mar 15, 2018
@jbogarthyde @mhevery
docs: incorporate suggestions and corrections from gkalpak (#21569)
02e6ac2 
PR Close #21569
leo6104 pushed a commit to leo6104/angular that referenced this pull request Mar 25, 2018
@jbogarthyde @leo6104
docs(aio): update architecture section (angular#21569)
9a669a6 
PR Close angular#21569
leo6104 pushed a commit to leo6104/angular that referenced this pull request Mar 25, 2018
@jbogarthyde @leo6104
docs: incorporate suggestions and corrections from gkalpak (angular#2…
c92de64 
…1569)

PR Close angular#21569
@jenniferfell jenniferfell mentioned this pull request Apr 25, 2018
Closed
@angular-automatic-lock-bot
Copy link

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.

@angular-automatic-lock-bot angular-automatic-lock-bot bot locked and limited conversation to collaborators Sep 13, 2019
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Reviewers

@StephenFluin StephenFluin StephenFluin approved these changes

@gkalpak gkalpak gkalpak approved these changes

@jenniferfell jenniferfell jenniferfell approved these changes

Assignees

@jbogarthyde jbogarthyde

Labels
action: merge The PR is ready for merge by the caretaker aio: preview cla: yes target: patch This PR is targeted for the next patch release
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
7 participants
@jbogarthyde @googlebot @mary-poppins @gkalpak @jenniferfell @wimgoeman @StephenFluin