docs(cookbook/graphql): Fix for @kapunahelewong review

Author: Urigo

public/docs/_examples/heroes-graphql/ts/src/app/heroes.component.2.ts

@@ -0,0 +1,113 @@
+// #docregion
+import { Component, OnInit } from '@angular/core';
+import { Router }            from '@angular/router';
+
+// #docregion import-apollo
+import { Apollo } from 'apollo-angular';
+// #enddocregion import-apollo
+// #docregion import-graphql-tag
+import gql from 'graphql-tag';
+// #enddocregion import-graphql-tag
+import { ApolloQueryResult } from 'apollo-client';
+import { Hero }              from './hero';
+
+@Component({
+  moduleId: module.id,
+  selector: 'my-heroes',
+  templateUrl: './heroes.component.html',
+  styleUrls: [ './heroes.component.css' ]
+})
+export class HeroesComponent implements OnInit {
+  // #docregion this-heroes
+  heroes: Hero[];
+  selectedHero: Hero;
+  // #enddocregion this-heroes
+
+// #docregion inject-apollo
+  constructor(
+    private apollo: Apollo,
+    private router: Router) { }
+  // #enddocregion inject-apollo
+
+  // #docregion query-heroes
+  getHeroes(): void {
+    this.apollo.watchQuery({
+      query: gql`
+        query allHeroes {
+          heroes {
+            id
+            name
+          }
+        }
+      `,
+      forceFetch: true
+    }).subscribe((queryResult: ApolloQueryResult<{ heroes: Hero[] }>) => {
+      this.heroes = queryResult.data.heroes;
+    });
+    // #enddocregion query-heroes
+  }
+
+  // #docregion add
+  add(name: string): void {
+    name = name.trim();
+    if (!name) { return; }
+
+    // #docregion add-mutation
+    this.apollo.mutate({
+      mutation: gql`
+        mutation addHero($heroName: String!) {
+          addHero(heroName: $heroName) {
+            id
+            name
+          }
+        }
+      `,
+      variables: {
+        heroName: name
+      }
+    }).subscribe((mutationResult: ApolloQueryResult<{ addHero: Hero }>) => {
+      this.heroes.push({
+        // #docregion access-mutation-result
+        id: mutationResult.data.addHero.id,
+        name: mutationResult.data.addHero.name
+        // #enddocregion access-mutation-result
+      });
+    });
+    // #enddocregion add-mutation
+  }
+  // #enddocregion add
+
+  // #docregion delete
+  delete(hero: Hero): void {
+
+    this.apollo.mutate({
+      mutation: gql`
+        mutation deleteHero($id: Int!) {
+          deleteHero(id: $id) {
+            id
+            name
+          }
+        }
+      `,
+      variables: {
+        id: hero.id
+      }
+    }).subscribe((mutationResult: ApolloQueryResult<{ deleteHero: Hero }>) => {
+      this.heroes = this.heroes.filter(h => h !== hero);
+      if (this.selectedHero === hero) { this.selectedHero = null; }
+    });
+  }
+  // #enddocregion delete
+
+  ngOnInit(): void {
+    this.getHeroes();
+  }
+
+  onSelect(hero: Hero): void {
+    this.selectedHero = hero;
+  }
+
+  gotoDetail(): void {
+    this.router.navigate(['/detail', this.selectedHero.id]);
+  }
+}

public/docs/_examples/heroes-graphql/ts/src/app/heroes.component.ts

@@ -67,8 +67,10 @@ export class HeroesComponent implements OnInit {
       }
     }).subscribe((mutationResult: ApolloQueryResult<{ addHero: Hero }>) => {
       this.heroes.push({
+        // #docregion access-mutation-result
         id: mutationResult.data.addHero.id,
         name: mutationResult.data.addHero.name
+        // #enddocregion access-mutation-result
       });
       this.selectedHero = null;
     });

public/docs/_examples/heroes-graphql/ts/src/app/in-memory-graphql.ts

@@ -10,12 +10,13 @@ import { execute } from 'graphql';
 // #enddocregion import-graphql
 // #docregion graphql-schema
 const typeDefinitions = `
+# the model
 type Hero {
   id: Int!
   name: String!
 }
 
-# the schema allows the following query:
+# the schema allows the following queries:
 type Query {
   heroes(search: String): [Hero]
 
@@ -38,8 +39,8 @@ type Mutation {
   ): Hero
 }
 
-# we need to tell the server which types represent the root query
-# and root mutation types. We call them RootQuery and RootMutation by convention.
+# you need to tell the server which types represent the root query
+# and root mutation types. you call them RootQuery and RootMutation by convention.
 schema {
   query: Query
   mutation: Mutation

public/docs/ts/latest/cookbook/graphql.jade

@@ -376,9 +376,29 @@ code-example(language="json").
 :marked
   Now for the fun part. Inside of the `add()` function, add an `addHero` mutation 
   using the `apollo.mutate` function as follows:
-+makeExample('heroes-graphql/ts/src/app/heroes.component.ts', 'add-mutation', 'heroes.component.ts')
++makeExample('heroes-graphql/ts/src/app/heroes.component.2.ts', 'add-mutation', 'heroes.component.ts')
 :marked
   The mutation requires and variable and we pass it to the `mutate` function through the `variables` param.
+
+  As mentioned above, with GraphQL mutations, you specify the result you want to get back from the server.
+
+  Apollo's `mutate` function returns the result as an Observable.
+  The Observable returns a `mutationResult` variable that is structured 
+  like the `ApolloQueryResult` Typescript Type, where the generic `T` type is a `Hero` type:
+code-example(language="json").
+  type ApolloQueryResult<T> = {
+    data: T;
+    loading: boolean;
+    networkStatus: NetworkStatus;
+  };
+:marked
+  and that's also how you reference that result variable in Typescript.
+  So in order the get the actual hero data being returned, you access those values like so:
++makeExample('heroes-graphql/ts/src/app/heroes.component.ts', 'access-mutation-result', 'heroes.component.ts')
+:marked
+  and then push them into the `heroes` array.
+
+
 .alert.is-important
   :marked
     Uri: Could you explain this above segment section by section? 
@@ -393,11 +413,17 @@ code-example(language="json").
     of what an observable is...I see we are pushing the `id` and `name` but
     don't quite understand how/when. The subscribe syntax loses me. Lastly, 
     I don't know why we are setting the `selectedHero` to `null`.
+    :Kapunahele - changed above
 
 :marked
   Just like a query, the mutate function returns an Observable you can subscribe to 
   that handles the data you request.
 
+  At this point, your heroes existing heroes app can also add a hero:
+figure.image-display
+  img(src='/resources/images/cookbooks/heroes-graphql/heroes- graphql-mutation.gif' alt="Heroes GraphQL Mutation")
+
+
 .alert.is-important
   :marked
     Uri: Let's say something here about how we can now add a hero. Can the 
@@ -407,6 +433,7 @@ code-example(language="json").
     Imagine the reader coming to this page and giving it a cursory scroll 
     to see how long it is in deciding whether or not to work through it. 
     A gif (especially) or screenshot could help them decide to do it.
+    ::Kapunahele - great point. added.
 
 .l-main-section
 <a id="resources"></a>
@@ -436,13 +463,16 @@ code-example(language="json").
   Running the server in the browser helps you start using 
   GraphQL on your frontend without having a GraphQL backend. 
   If you don't have the option of running GraphQL on the server, 
-  this method makes it easier to handle multiple REST 
-  requests and join logic on the client.
+  this method makes it possible to still use GraphQL in your app with the
+  benefits for not needing to sync multiple REST requests and join logic 
+  on the client.
 
 .alert.is-important
   :marked
     Uri: Can you tell me why it makes it easier? We should say 
     "...logic on the client because..."
+    :Kapunahele - changed above
+
 
 .l-sub-section
   :marked
@@ -451,14 +481,15 @@ code-example(language="json").
     it is almost identical to the local server in this appendix.
     Everything you learn here applies to writing an actual GraphQL backend server.
 
-    Additionally, there are a few GraphQL based backend-as-a-service platforms available, 
-    such as Firebase, but they are based on the GraphQL API.  For help on getting
-    up and running, see [Scaphold](https://www.scaphold.io/) and [Graphcool](https://www.graph.cool/).
+    Additionally, there are a few GraphQL backend-as-a-service platforms available, 
+    similar to Firebase, but based on the GraphQL API spec.
+    For help on getting up and running, see [Scaphold](https://www.scaphold.io/) and [Graphcool](https://www.graph.cool/).
 
 .alert.is-important
   :marked
     Uri: Can you explain why the GraphQL API makes using things like Firebase different? 
     There's a "but" in that sentence, but I don't know what it implies.
+    :Kapunahele - the word `but` was wrong. fixed and edited a bit
 
 :marked
   In order to create a GraphQL schema, you need the `graphql-tools` library.
@@ -477,7 +508,7 @@ code-example(language="sh" class="code-shell").
 .alert.is-important
   :marked
     Uri: Could you change the use of "we" in the above comments to "you" or the imperative (command without 
-    "you")?
+    "you")? :Kapunahele - done.
 .l-sub-section
   :marked
     While the schema includes the major points covered in this cookbook, 
@@ -502,13 +533,16 @@ code-example(language="sh" class="code-shell").
 :marked
   You may have noticed some functions from `lodash` such as `lodashFind()` so don't 
   forget to install them from npm and import them:
+code-example(language="sh" class="code-shell").
+    npm install lodash --save  
 +makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'import-lodash', 'in-memory-graphql.ts (imports)')
 
 .alert.is-important
   :marked
     Uri: What is the npm install command for the lodash functions? 
     Do we install the whole lodash library or just the functions? 
     (I've never used lodash before).
+    :Kapunahele - fixed. for ease of use I've installed all of lodash
 
 
 :marked
@@ -517,7 +551,8 @@ code-example(language="sh" class="code-shell").
 
   This mechanism makes writing simple GraphQL servers straightforward&mdash;you simply 
   resolve a specific type of data. 
-  This removes the coupling between frontend and backend.
+  This removes the coupling between frontend and backend because if you don't need to know the specific
+  query the client makes to create the server Implementation.
 
 .alert.is-important
   :marked
@@ -526,6 +561,7 @@ code-example(language="sh" class="code-shell").
     I'm right about "This removes the coupling between frontend and backend".
     I was trying to make it clearer by breaking it into smaller ideas, but 
     I'm not sure what those ideas should be.
+    :Kapunahele - expanded on that, let me know if that works
 
 :marked
   Now, connect the schema to the resolvers with the `makeExecutableSchema` function from
@@ -537,28 +573,42 @@ code-example(language="sh" class="code-shell").
   In the constant `schema`, `makeExecutableSchema` has two properties, 
   `typeDefs` and `resolvers`. Here, you define them with the `typeDefinitions` 
   and `resolveFunctions` that you created earlier in `in-memory-graphql.ts`. 
-  This way, your app/GraphQL? (Uri - can you correct me here?) knows where to look 
-  for definitions and resolvers.
+  This way, your GraphQL server knows where to look for definitions and resolvers.
 
 :marked
   Now that you have an executable schema, execute it using the `graphql` 
   library and export it so you can use it with the Apollo Client. 
   First, `npm install`:
+code-example(language="sh" class="code-shell").
+    npm install graphql --save    
 
 .alert.is-important
   :marked
     Uri: can you provide the npm install command?
+    :Kapunahele - done
 
 :marked
   Next, add an import statement for `execute`.
 
 +makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'import-graphql', 'in-memory-graphql.ts (excerpt)')
+:marked
+  Now create a new `networkInterface` class and call it `InBrowserNetworkInterface`.
+
+  That class will have a `schema` property which it will initialize in the constructor.
 
+  Then create a `query` function that will recieve a query as a variable and execute that query using
+  `graphql` execute function against the schema property.
+
+  You send empty objects to the `rootValue` and `contextValue` arguments of the function and send the 
+  `variables` and `operationName` arguments that are related to the query request.
+  
+  Now export the new `InBrowserNetworkInterface` class in order to import it to Apollo Client.
 .alert.is-important
   :marked
     Uri: Could you explain what's happening in the below? 
     This will probably take 2-3 short paragraphs. Just a 
     general tour from top to bottom.
+    :Kapunahele - let me know if that works
 +makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'execute-and-export', 'in-memory-graphql.ts (excerpt)')
 :marked
   Now all that's left is to connect the new in-memory server to the Apollo Client configuration 
@@ -578,18 +628,21 @@ code-example(language="sh" class="code-shell").
   :marked
     Uri: Let's add a conclusion showing what was accomplished in the doc. 
     Maybe something like (please add anything I've missed):
+    :Kapunahele - done, but not sure if its enough?
 
 .l-main-section
 :marked
   ## Conclusion
 
   This cookbook covered:
 
+  - What is GraphQL and why it can benefit Angular developers.
   - How to create a basic GraphQL query.
   - How to create a basic GraphQL mutation.
   - How to build a GraphQL server.
+  - Resources to dive deeper.
 
-
+  
 
 .l-main-section
 <a id="example"></a>