[WIP]:Create Tour of Heroes chapter on http #1044
Conversation
|
I like where you're going. Remember that the tour is a gentle introduction to A2. It's meant to reassure the reader that A2 covers the application ground that they need it to cover. It's not supposed to be comprehensive. It's not supposed to be contentious or risk confusing the reader with choices. Let's keep the http chapter in that spirit. The chapter should also be short. Not too short but I'd definitely err on the side of brief and breezy. The promise/observable trade-off is the most vexing to me. With my preamble in mind, I think we stick with promises at the boundary between the This is not the place to lead readers on a scary adventure into the uncertainties of observables and other competing data strategies. There is no reason for ToH to get into the observable weeds. We should say just enough to let the reader know that _we know observables are there_. Yes the A2-in-mem-web-api is the way to go. It handles all the CUD methods you need. No reason to go too deep though. Remember that the in-mem-web-ai exists for demos and early development only. We want the reader to know that we're using it to make their learning experience easier (they won't need to set up a server to learn A2's http). We don't want to go overboard. They should know that using a real web api involves no more than a change of URL. Please make sure that we give a nod to error handling. We must write error catching. We don't have to do anything grand with the errors: writing to console is probably sufficient. But we absolutely must have catch in the |
|
a2-in-memory-web-api promises vs observables Also add a quick note/callout pointing out that we are using toPromise because natively the Then, the next chapter can show how to take http and turn things to an observable. Following this pattern it feeds what the reader is craving .... they walk into the chapter wanting to know http, they don't realize they may want Rx later quite yet. So they learn http, see a small mention of Rx, and then they are primed for the next chapter which will swap out promises for Rx. error handling Looking forward to seeing what you do, Tor! |
|
I totally agree with John here regarding promises. As long as we make very clear that we will cover observables in the next part or something. |
|
John's plan to introduce Observables sounds great. Maybe the next chapter should be about application state, and shows how to change state on Component A via service calls on the unrelated Component B. Then it would make a lot of sense to change the promises to subscribes. |
|
Thanks everyone. This is great feedback! I will keep you in the loop and let you know when this is in a more finished state. |
thelgevold
force-pushed
the
toh-6-http-tor
branch
7 times, most recently
from
66128d7 to
ea69be7
Compare
closes angular#972 chore(toh): change inputs array for input decorator/hero now a class docs(dart): update to b12 Also update dart_to_js_script_rewriter dependency to ^1.0.1, and change most angular2.dart imports to be core.dart instead. The pipes example broke without the angular2.dart import, so I let it be. The server-communication sample has never worked for me, so I changed it but might have broken it further. closes angular#1007 docs: update to style-guide links closes angular#995 Fixed links to John Papa style guide to new repo location. docs(cb-ts-to-js): add cookbook about applying TypeScript examples to ES5 closes angular#893 docs(dart): change imports from bootstrap.dart to platform/browser.dart closes angular#1013 samples(dart): add info file for dart-doc-syncer to template-syntax closes angular#1018 samples(dart): add link to documentation chapter closes angular#1019 docs(toh-1): remove public access modifiers closes angular#1009 Remove public access modifier on AppComponent properties to be consistent throughout code tutorial docs(dependency-injection): tweak Dart wording closes angular#1017 docs(dart): tweak homepage banner closes angular#1016 docs(quickstart): fixed "hurray" typo. closes angular#1021 docs: update to beta.13 docs(dart/quickstart): merge 2 examples into 1 closes angular#1031 docs(dart): update to beta.13.1 closes angular#1032 Add additional tags to the angular.io dgeni package for the new api doc style proposal. Closes angular#1030 chore: remove angulardart.org link from footer closes angular#1034 fix(api-builder): add missing git package dependency This was causing the api-builder tests to fail chore(typo): quide -> guide in cheatsheets closes angular#1039 docs:Create Tour of Heroes chapter on http some text changes wired up web api text adding saving wired up CRUD remove unused files fixed toggle whitespace text text text updates text text tweaks added tests test fixed button click images fixed test tweaks docs(toh): add missing nav path to diagram per angular#1041 chore: fix typo in ts-to-js intro closes angular#1025 chore(bio): add Deborah's bio closes angular#1024 docs(bio): fixes Jules' bio links closes angular#1027 fix(e2e): fix race condition docs(toh-4): reword the getHeroesSlowly instructions closes angular#1011 rewording to: "replace `_heroService.getHeroes` with `_heroService.getHeroesSlowly`" docs: add DI cookbook chore: replace VSCode-specific settings.json with broadly recommended .editorconfig closes angular#1022 docs(template-syntax): fixed "a id" typo in basics section. closes angular#1048 chore: add "homepage" property to package.json closes angular#1038 docs(testing): update testing to use toh-5 closes angular#1003 docs(unit-testing): fix the path to node_modules & steps for adding a new spec closes angular#1043 package(harp): update harp version to fix async errors docs(component-styles): add chapter about styling components closes angular#1047 docs(lifecycle-hooks): Fixed missing ":marked" typo closes angular#1051 docs(todo app): replace remaining tasks reduce func with filter.length closes angular#1050 docs(component-styles): mark `__moduleName` experimental; use alert instead of callout. closes angular#1054 docs(pipes): Fixed "If follows..." typo closes angular#1053 Fixed typo in **pipes** section of guide. chore: update to beta.14
thelgevold
force-pushed
the
toh-6-http-tor
branch
from
ea69be7 to
760658d
Compare
|
Closed this one due to branch issue. Opened new PR here: #1066 |
*** DO NOT MERGE ***
This branch very much a Work in progress and mainly here for feedback before I do the full implementation.
@wardbell
Started looking at the Tour of Heroes chapter on Http. I am assuming this chapter will pick up where the router chapter left off and start with the application that was created there.
I have added a rough outline with some ideas in the jade file. Let's discuss if this is headed in the right direction.
Highlevel:
"Backstory" and the motivation behind the move to Http
Show how to configure a2-in-mem-web-api. This is already explained in the Dev guide appendix, but thinking we need to show how to use it in the context of our TOH AppComponent.
Convert HeroService to use http instead of hard coded response. Do we stick to promise based http calls? Could do Observables, but have to teach observables too then. Besides the existing components already expect promises from HeroService. The code in this PR uses http with promises, but I can easily change it.
Add ability to edit and add new heroes using a2-in-mem-web-api. Thinking we can reuse HeroDetailComponent to support edit and add scenarios. This includes adding a post method to HeroService. Did a quick tests and a2-in-mem-web-api seems to handle post requests without any issues.
Are there other topics/features we should include as well?