docs(http): show how to override default RequestOptions like headers (#2978)

Author: wardbell

public/docs/_examples/server-communication/ts/app/app.module.1.ts

@@ -16,7 +16,8 @@ import { AppComponent } from './app.component';
   declarations: [ AppComponent ],
   bootstrap:    [ AppComponent ]
 })
-export class AppModule { }
+export class AppModule {
+}
 
 
 

public/docs/_examples/server-communication/ts/app/app.module.ts

@@ -1,9 +1,12 @@
+// #docplaster
 // #docregion
 import { NgModule } from '@angular/core';
 import { BrowserModule } from '@angular/platform-browser';
 import { FormsModule } from '@angular/forms';
-import { HttpModule, JsonpModule }  from '@angular/http';
+// #docregion override-default-options
+import { HttpModule, JsonpModule, RequestOptions }  from '@angular/http';
 
+// #enddocregion override-default-options
 import { InMemoryWebApiModule }     from 'angular-in-memory-web-api';
 import { HeroData }                 from './hero-data';
 
@@ -34,8 +37,14 @@ import { WikiSmartComponent } from './wiki/wiki-smart.component';
   ],
   bootstrap: [ AppComponent ]
 })
-export class AppModule { }
-
+// #docregion override-default-request-options
+export class AppModule {
+  constructor(requestOptions: RequestOptions) {
+    // Set the default 'Content-Type' header
+    requestOptions.headers.set('Content-Type', 'application/json');
+  }
+}
+// #enddocregion override-default-request-options
 
 
 

public/docs/ts/latest/guide/change-log.jade

@@ -5,6 +5,10 @@ block includes
   The Angular documentation is a living document with continuous improvements.
   This log calls attention to recent significant changes.
 
+  ## Http: how to set default request headers (and other request options) (2016-12-14)
+  Added section on how to set default request headers (and other request options) to 
+  [Http](server-communication.html#override-default-request-options) guide.
+
   ## Testing: added component test plunkers (2016-12-02)
   Added two plunkers that each test _one simple component_ so you can write a component test plunker of your own: <live-example name="setup" plnkr="quickstart-specs">one</live-example> for the QuickStart seed's `AppComponent` and <live-example name="testing" plnkr="banner-specs">another</live-example> for the Testing guide's `BannerComponent`. 
   Linked to these plunkers in [Testing](testing.html#live-examples) and [Setup anatomy](setup-systemjs-anatomy) guides.

public/docs/ts/latest/guide/server-communication.jade

@@ -33,6 +33,7 @@ block includes
       <li> [More fun with observables](#more-observables).</li>
     </ul>
   - [Guarding against Cross-Site Request Forgery](#xsrf).
+  - [Override default request headers (and other request options)](#override-default-request-options).
   - [Appendix: Tour of Heroes _in-memory web api_](#in-mem-web-api).
 
   A <live-example>live example</live-example> illustrates these topics.
@@ -647,10 +648,42 @@ a#xsrf
 
   See the [XSRF topic on the Security page](security.html#xsrf) for more information about XSRF and Angular's `XSRFStrategy` counter measures.
 
+a#override-default-request-options
+.l-main-section
+:marked
+  ## Override default request headers (and other request options)
+
+  Request options (such as headers) are merged into the
+  [default _RequestOptions_](https://angular.io/docs/ts/latest/api/http/index/BaseRequestOptions-class.html "API: BaseRequestOptions") 
+  before the request is processed.
+  The `HttpModule` provides these default options via the `RequestOptions` token.
+
+  You can override these defaults to suit your application needs.
+  The API docs suggest creating a custom sub-class of `RequestOptions`
+  and providing that as a replacement class for the `RequestOptions` token.
+
+  Perhaps an easier way is to inject the current `RequestOptions` instance
+  into an application module constructor and re-set its values directly.
+  This sample sets the default `Content-Type` header to JSON in the root `AppModule` constructor:
++makeExample('server-communication/ts/app/app.module.ts', 'override-default-request-options', 'app/app.module.ts (default request header override)')(format=".")
+:marked
+  After this change, the `header` option setting in `HeroService.addHero` is no longer necessary,
+
++makeExample('server-communication/ts/app/toh/hero.service.ts', 'addhero', 'app/toh/hero.service.ts (addHero)')(format=".")
+:marked
+  You can confirm this works by looking at the network tab.
+  If you're short-circuiting the server call with something like the [_in-memory web api_](#in-mem-web-api),
+  try commenting-out the `addHero` header option, 
+  set a breakpoint on the POST call, and step through to the backend request
+  to verify the header is there.
+  
+  Individual requests options, like this one, take precedence over the default `RequestOptions`.
+  It might be wise to keep the `addHero` request header setting for extra safety.
+
 a#in-mem-web-api
 .l-main-section
 :marked
-  ## Appendix: Tour of Heroes in-memory server
+  ## Appendix: Tour of Heroes _in-memory web api_
 
   If the app only needed to retrieve data, you could get the heroes from a `heroes.json` file:
 - var _heroesJsonPath = (_docsFor == 'dart' ? 'web' : 'app') + '/heroes.json';