docs(cookbook/graphql): More fixes from @kapunahelewong review

Include systemjs config in the docs, changing wording of the article

Author: Urigo

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

@@ -35,8 +35,7 @@ export class DashboardComponent implements OnInit {
             name
           }
         }
-      `,
-      forceFetch: true
+      `
     }).subscribe((queryResult: ApolloQueryResult<{ heroes: Hero[] }>) => {
       this.heroes = queryResult.data.heroes.slice(1, 5);
     });

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

@@ -60,8 +60,7 @@ export class HeroSearchComponent implements OnInit {
         search: this.searchTerms
           .debounceTime(300)        // wait 300ms after each keystroke before considering the term
           .distinctUntilChanged()   // ignore if next search term is same as previous
-      },
-      forceFetch: true
+      }
     });
   }
   // #enddocregion search

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

@@ -8,14 +8,14 @@ <h2>My Heroes</h2>
   </button>
 </div>
 <!-- #enddocregion add -->
+<!-- #docregion render-heroes -->
 <ul class="heroes">
-  <!-- #docregion render-heroes -->
   <li *ngFor="let hero of heroes">
     <span class="badge">{{hero.id}}</span>
     <span>{{hero.name}}</span>
   </li>
-  <!-- #enddocregion render-heroes -->
 </ul>
+<!-- #enddocregion render-heroes -->
 <div *ngIf="selectedHero">
   <h2>
     {{selectedHero.name | uppercase}} is my hero

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

@@ -43,8 +43,8 @@ export class HeroesComponent implements OnInit {
     }).subscribe((queryResult: ApolloQueryResult<{ heroes: Hero[] }>) => {
       this.heroes = queryResult.data.heroes;
     });
-    // #enddocregion query-heroes
   }
+  // #enddocregion query-heroes
 
   // #docregion add
   add(name: string): void {

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

@@ -39,8 +39,7 @@ export class HeroesComponent implements OnInit {
             name
           }
         }
-      `,
-      forceFetch: true
+      `
     }).subscribe((queryResult: ApolloQueryResult<{ heroes: Hero[] }>) => {
       this.heroes = queryResult.data.heroes;
     });

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

@@ -8,7 +8,9 @@ import { Apollo } from 'apollo-angular';
 // #docregion import-graphql-tag
 import gql from 'graphql-tag';
 // #enddocregion import-graphql-tag
+// #docregion import-apollo-query-result
 import { ApolloQueryResult } from 'apollo-client';
+// #enddocregion import-apollo-query-result
 import { Hero }              from './hero';
 
 @Component({
@@ -39,8 +41,7 @@ export class HeroesComponent implements OnInit {
             name
           }
         }
-      `,
-      forceFetch: true
+      `
     }).subscribe((queryResult: ApolloQueryResult<{ heroes: Hero[] }>) => {
       this.heroes = queryResult.data.heroes;
     });

public/docs/_examples/heroes-graphql/ts/src/systemjs.config.extras.js

@@ -3,30 +3,51 @@
 System.config({
 
   map: {
+    // #docregion systemjs-apollo-client-map
+    // ..
     'apollo-client':                      'npm:apollo-client/apollo.umd.js',
     'apollo-client-rxjs':                 'npm:apollo-client-rxjs/build/bundles/apollo-rxjs.umd.js',
     'apollo-angular':                     'npm:apollo-angular/build/bundles/apollo.umd.js',
 
-    'graphql':                            'npm:graphql',
     'whatwg-fetch':                       'npm:whatwg-fetch',
+    'graphql-anywhere':                   'npm:graphql-anywhere',
     'graphql-tag':                        'npm:graphql-tag',
     'symbol-observable':                  'npm:symbol-observable',
     'redux':                              'npm:redux/dist/redux.min.js',
+    // ..
+    // #enddocregion systemjs-apollo-client-map
+
+    // #docregion systemjs-graphql-server-map
+    // ..
+    'graphql':                            'npm:graphql',
     'graphql-tools':                      'npm:graphql-tools',
-    'graphql-anywhere':                   'npm:graphql-anywhere',
 
     'deprecated-decorator':               'npm:deprecated-decorator',
     'node-uuid':                          'npm:node-uuid',
     'uuid':                               'npm:uuid',
     'iterall':                            'npm:iterall',
 
     'lodash':                             'npm:lodash'
+    // ..
+    // #enddocregion systemjs-graphql-server-map
   },
   packages: {
+    // #docregion systemjs-apollo-client-packages
+    // ..
     'whatwg-fetch':               { main: './fetch.js', defaultExtension: 'js' },
     'redux':                      { format: 'cjs', defaultExtension: 'js' },
     'graphql-tag':                { main: './index.js', defaultExtension: 'js' },
 
+    'graphql-anywhere':           {
+      main: '/lib/src/index.js',
+      defaultExtension: 'js'
+    },
+    'symbol-observable':          { main: './index.js', defaultExtension: 'js' },
+    // ..
+    // #enddocregion systemjs-apollo-client-packages
+
+    // #docregion systemjs-graphql-server-packages
+    // ..
     'graphql':     {
       main: './index.js',
       defaultExtension: 'js',
@@ -43,18 +64,13 @@ System.config({
       main: '/dist/index.js',
       defaultExtension: 'js'
     },
-    'graphql-anywhere':           {
-      main: '/lib/src/index.js',
-      defaultExtension: 'js'
-    },
-
-
     'deprecated-decorator':       { main: '/bld/index.js', defaultExtension: 'js' },
     'node-uuid':                  { main: './uuid.js', defaultExtension: 'js' },
     'uuid':                       { main: './lib/rng-browser.js', defaultExtension: 'js' },
     'iterall':                    { main: './index.js', defaultExtension: 'js' },
-    'symbol-observable':          { main: './index.js', defaultExtension: 'js' },
-
     'lodash':                     { main: './index.js', defaultExtension: 'js' }
+
+    // ..
+    // #enddocregion systemjs-graphql-server-packages
   }
 });

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

@@ -66,7 +66,11 @@ include ../_util-fns
 .l-sub-section
   :marked
     You can check out [this](https://www.youtube.com/watch?v=Xx39bv-5ojA&t=1s) talk by [Jeff Cross](https://twitter.com/jeffbcross) and
-    [Uri Goldshtein](https://twitter.com/UriGoldshtein) that summarizes this part
+    [Uri Goldshtein](https://twitter.com/UriGoldshtein) that summarizes this part:
+
+iframe(type='text/html' width='560' height='315'
+    src='https://www.youtube.com/embed/Xx39bv-5ojA'
+    frameborder='0')    
 
 :marked
   ### Component based API
@@ -219,7 +223,7 @@ a#http-heroes
     The full documentation can be found on the [Apollo Client docs website](http://dev.apollodata.com/).
 
 :marked
-  The starting point for the app is the [Tour of Heroes tutorial](https://github.com/johnpapa/angular2-tour-of-heroes/archive/master.zip) app at its end state.
+  The starting point for the app is the [Tour of Heroes tutorial](https://github.com/Urigo/quickstart/archive/graphql-start.zip) app at its end state.
 
   This guide shows you how to migrate that app from REST to GraphQL.
 
@@ -232,6 +236,22 @@ a#http-heroes
 
 code-example(language="sh" class="code-shell").
     npm install apollo-client apollo-angular graphql-tag --save
+
+.l-sub-section
+  :marked
+    This example uses `system.js` so you need to also add the configuration to it.
+    With other build systems, the following process will be different and maybe easier.
+
+:marked
+  Add the following configuration to your `systemjs.config.js` file under the `map` key:
+
++makeExample('heroes-graphql/ts/src/systemjs.config.extras.js', 'systemjs-apollo-client-map', 'under map: {')
+
+:marked
+  and the following configuration to your `systemjs.config.js` file under the `packages` key:
+
++makeExample('heroes-graphql/ts/src/systemjs.config.extras.js', 'systemjs-apollo-client-packages', 'under packages: {')  
+
 :marked
   Next, initialize the client by creating a new file called `client.ts` and 
   pasting in the following code:
@@ -245,21 +265,11 @@ code-example(language="sh" class="code-shell").
 .l-sub-section
   :marked
     ### To use a different URI for the Apollo Client
-    You don't need the following code snippet to work through this cookbook, 
-    but it's good to know how to configure the client to use a URI. 
+    For this cookbook we would use the default `/graphql` endpoint,
+    but it's good to know it is possible to change those settings.
     To change the [settings](http://dev.apollodata.com/core/apollo-client-api.html#ApolloClient\.constructor) 
     of `ApolloClient`, call its constructor with different parameters. 
-    You can alter the endpoint by importing `createNetworkInterface` and configuring the 
-    `networkInterface` property of `ApolloClient` to 
-    use a URI:
-
-+makeExample('heroes-graphql/ts/src/app/client.2.ts', 'network-initialization', 'app/client.ts')
-.l-sub-section
-  :marked
-    For instructions on running a GraphQL server, 
-    see [Appendix: Setting up a GraphQL server](#server).
-    The appendix shows you how to run a GraphQL server in-memory 
-    on the client, which is helpful for testing.
+    Go to the [Apollo Docs](http://dev.apollodata.com/angular2/initialization.html#creating-client) for further resources.
 
 :marked
   After initializing the Apollo client, import the `ApolloModule` 
@@ -273,27 +283,37 @@ code-example(language="sh" class="code-shell").
 
 +makeExample('heroes-graphql/ts/src/app/app.module.ts', 'apollo-ngmodule', 'app.module.ts (excerpt)')
 
+:marked
+  Now Apollo is initialized and ready for use in the app. 
+
 .l-main-section
 <a id="querying"></a>
 :marked
   ## Performing a query
 
   With GraphQL you query a schema, which is organized into types and fields,
   that represents the data you can query. 
-  
-  The server for this guide is based on the [Tour of Heroes](ts/latest/tutorial/). 
-  Copy the schema that follows into a file named `in-memory-graphql.ts` in the `app` directory:
 
-:marked
   The schema begins with data types and fields followed by the specific queries 
   you can perform on the data. These are in turn followed by 
   mutations, which are _actions_ that you 
   can call on the server, similar to a POST request in REST.
 
-+makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'graphql-schema', 'app/in-memory-graphql.ts')
+  Here is an example schema:
+
++makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'graphql-schema', 'Tour of heroes schema')  
+
+.l-sub-section
+  :marked
+    Usually you need to query an existing server.
+
+    The server for this guide is based on the [Tour of Heroes](ts/latest/tutorial/) app.
+
+    In order to create the GraphQL server for this example, follow the instructions on 
+    [Appendix: Setting up a GraphQL server](#server).
 
 :marked
-  To start querying data, begin by importing `Apollo` into `heroes.component.ts`,
+  Once you have a server, to start querying data, begin by importing `Apollo` into `heroes.component.ts`,
   and injecting it into the constructor:
 +makeExample('heroes-graphql/ts/src/app/heroes.component.ts', 'import-apollo', 'heroes.component.ts (excerpt)')
 +makeExample('heroes-graphql/ts/src/app/heroes.component.ts', 'inject-apollo', 'heroes.component.ts (excerpt)')
@@ -305,6 +325,11 @@ code-example(language="sh" class="code-shell").
 
 +makeExample('heroes-graphql/ts/src/app/heroes.component.ts', 'import-graphql-tag', 'heroes.component.ts')
 
+:marked
+  In order to specify the TypeScript type of the data that is recieved, import `ApolloQueryResult` from `apollo-client`:
+
++makeExample('heroes-graphql/ts/src/app/heroes.component.ts', 'import-apollo-query-result', 'import type')
+  
 :marked
   To query data with the Apollo Client, pass a GraphQL query with the 
   data and structure that you want to the `Apollo` `watchQuery` function. 
@@ -436,8 +461,9 @@ figure.image-display
 :marked
   ## Appendix: Setting up a GraphQL server
 
-  Running the server in the browser helps you start using 
-  GraphQL on your frontend without having a GraphQL backend. 
+  This example shows how to run a GraphQL in the browser but running a GraphQL server on 
+  Node.js or in the browser is very similar.
+  
   If you don't have the option of running GraphQL on the server, 
   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 
@@ -459,9 +485,31 @@ figure.image-display
   It allows you to write a GraphQL schema as a string and make it executable. 
   In a terminal window, issue the following command:
 
+.l-sub-section
+  :marked
+    This example uses `system.js` so you need to also add the configuration to it.
+    With other build systems, or when running on Node, the following process will be different and 
+    maybe easier.  
+
 code-example(language="sh" class="code-shell").
     npm install graphql-tools --save
 
+.l-sub-section
+  :marked
+    This example uses `system.js` so you need to also add the configuration to it.
+    With other build systems, or when running on Node, the following process will be different and 
+    maybe easier.
+
+:marked
+  Add the following configuration to your `systemjs.config.js` file under the `map` key:
+
++makeExample('heroes-graphql/ts/src/systemjs.config.extras.js', 'systemjs-graphql-server-map', 'under map: {')
+
+:marked
+  and the following configuration to your `systemjs.config.js` file under the `packages` key:
+
++makeExample('heroes-graphql/ts/src/systemjs.config.extras.js', 'systemjs-graphql-server-packages', 'under packages: {')  
+
 :marked
   Next, create a file called `in-memory-graphql.ts` in the `app` directory 
   and paste in the following schema:
@@ -486,6 +534,13 @@ code-example(language="sh" class="code-shell").
   Hence, the GraphQL server consists of _resolver 
   functions_ that correspond to the _types_ of the schema.
 
+  In some server functions you use the `lodash` library 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)')
+
+:marked
   To create the resolvers, copy the following code and add it to `in-memory-graphql.ts`.
 +makeExample('heroes-graphql/ts/src/app/in-memory-graphql.ts', 'resolvers', 'in-memory-graphql.ts')
 
@@ -494,13 +549,6 @@ code-example(language="sh" class="code-shell").
     For the full explanation about how GraphQL resolvers work see
     [Execution](http://graphql.org/learn/execution/) on [GraphQL.org](http://graphql.org/).
 
-: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)')
-
 :marked
   Notice that the server includes functions that correspond to each 
   type in the schema _and_ the mutations.