docs(tutorial): update to use v1.5.x and best practices

[gkalpak]

This is a major re-structuring of the tutorial app's codebase, aiming at applying established best practices (in terms of file naming/layout and code organization) and utilizing several new features and enhancements (most notably components) introduced in recent versions of Angular (especially v1.5).

Apart from the overall changes, two new chapters were introduced: one on components and one on code organization.

In the process, several other things were (incidentally) taken care of, including:

• Dependencies were upgraded to latest versions.
• Animations were polished.
• Outdated links were updated.
• The app's base URL was changed to / (instead of /app/).

BTW, this has been tested with the following versions of Node (on Windows 10) and everything worked fine:

• 0.11.16
• 4.2.6
• 4.4.2
• 5.10.0

This was inspired by (and loosely based on) #13834.
Again, mad props to @teropa for leading the way :)

Note:
The old version of the tutorial, that is compatible with Angular version 1.4 or older, has been saved on the pre-v1.5.0-snapshot branch of angular-phonecat. The v1.4.x version of the tutorial should be pointed to that branch instead of master.

Related to angular/angular-phonecat#326.
Related to angular/angular-seed#341.

---

Fixes #12755
Fixes #13312
Fixes #13623
Fixes #13632

Closes #8952
Closes #11726
Closes #12946
Closes #12947
Closes #13198
Closes #13284
Closes #13834
Closes #14178
Closes #14223

[gkalpak]

This has to get merged simultaneously with corresponding PRs on:

Repo	PRs
angular-phonecat	#326
angular-seed	#341
angular.io	#1106 (see Upgrading from 1.x)

Things that still need to be fixed:

• The images under docs/img/tutorial must be updated to match the new text/code.

Things that should/could be cosidered (potentially after this PR has been merged merged):

• Update the tutorial (and the necessary docs-app directives) on the v1.4.x branch, which will still contain the old version of the tutorial, to point to the pre-v1.5.0-snapshot branch of angular-phonecat.
• Adding an "advanced" section at the end, either pointing to resources (e.g. relevant Developer Guide sections) or as subsequent steps. Example topics:
  • Directives/DDO, 2-way/1-way/1-time bindings
  • Forms (+ ngMessages)
  • ngComponentRouter
  • (multi-slot) transclusion
  • Task runners/Build tools and best practices
  • Testing animations
• To discuss: Is it better to import the core module from the main phonecatApp module only, or on a per-view basis ?
• To discuss: Is it better to split up the CSS per component or keep it in a couple top-level files (e.g. one for animations and one for the rest) ? What about animation-related JS code ?
• To discuss: Do we want to mention/use Protractor's directConnect: true config option ?

[teropa]

@gkalpak I can look into getting angular.io updated. I'll need to look into this branch in more detail to see the extent of the changes need to that guide, but in any case I'll bring it up with the docs team tomorrow.

[gkalpak]

@teropa: Thx, that would be great ! Also, as you look through it, any feedback is more than welcome 😃

BTW, I tried to follow the structure that you used in the Upgrade Guide more closely, so hopefully you will be able to get rid of some of the noise in the guide and focus more on the new/different concepts.

Big 👍 for your work on both #13834 and the Upgrade Guide.

[petebacondarwin]

There is an annoying issue about corporate firewalls blocking git

angular/angular-phonecat#141
and probably
angular/angular-phonecat#235

Can we add this information into the guide?

[gkalpak]

Added

[petebacondarwin]

is it officially recommended practice to "reopen" the module to add in the component?
Given that you are creating a new file anyway, why not have a one module = one file bijection.
The benefits of this are:

• you don't have to sort the files when building a distribution file
• you can easily move a file to another project without having to bring along its module definition

[gkalpak]

I don't think it is explicitly mentioned anywhere, but this seems to be what john's styleguide is going throughout.
This is how I do it too fwiw 😛

Pros and cons of one module per file:

you don't have to sort the files when building a distribution file

👍

you can easily move a file to another project without having to bring along its module definition

The idea is that you are creating a module for the "least viable feature" - i.e. the smaller chunk of functionality that does something worth moving around or re-using in another project. So, there is no point in copying just the controller file of a component over to another project - you would copy the whole component directory instead(including the controller, controller spec, the module definition, the template etc).

Too many modules

👎

I don't think it's promoted as a good practice anywhere (at least I haven't seen it), so there might be few projects following this convention out there (I'm just speculating here).

👎

Could go either way (but only because I'm too tempted by not having to sort the files when bundling/testing 😛 )
I also have a slight concern about the overhead of creating a module for everything. I think there is a (tiny) bit of work involved in loading a module, which could add up.

Leaving it up to you 😁

[petebacondarwin]

Ohhh! It's so hard to decide...

I am generally not in favour of reopening anything. Especially old milk bottles!

So I think I would rather go with one module per file:

• I don't believe that there is not so much of a performance penalty, because there is a similar cost to looking up the module when reopening.
• I believe that having small modules that explicitly declare their dependencies makes them a bit more self documenting.
• My feeling is that if things are so tightly bound that they should be in a single module then they should be in the same file??

If you do feel strongly @gkalpak then don't do it. But if you are not bothered then I would be delighted to see this changed :-)

[petebacondarwin]

I think this warning should also appear in the introduction when setting up the environment. At least that is where I encountered this error.

[gkalpak]

I put it here, because we already have 8-9 alerts in the introduction. I can move it there if think it's better. (One more won't hurt I guess 😃)

[gkalpak]

Do you think would be better to move all the warnings in the introduction in a separate sections (at the bottom of introduction).

[petebacondarwin]

That might work. A kind of setup troubleshooting section?

[gkalpak]

Added a couple more fixups that move warning in a "Common Issues" section (in the introduction) and use ! as hash-prefix (angular-phonecat and angular-seed have been updated accordingly).
/cc @petebacondarwin

[gkalpak]

Tasks for after getting this in:

• Make appropriate modifications to the 1.4.x tutorial (see docs(tutorial): update to use v1.5.x and best practices #14416 (comment)).
• Use a more flat look in images - remove gradient.
• Switch to lite-server (with auto-reloading).

[petebacondarwin]

LGTM

[googlebot]

CLAs look good, thanks!

[googlebot]

CLAs look good, thanks!