docs(http): improve docs and add example for RequestOptions

This commit is contained in:
Jeff Cross 2015-09-21 15:54:13 -07:00
parent a554f1c45d
commit 707e6f7671
1 changed files with 52 additions and 11 deletions

View File

@ -6,31 +6,51 @@ import {Injectable} from 'angular2/src/core/di';
import {URLSearchParams} from './url_search_params'; import {URLSearchParams} from './url_search_params';
/** /**
* Creates a request options object similar to the `RequestInit` description * Creates a request options object to be optionally provided when instantiating a
* in the [Fetch
* Spec](https://fetch.spec.whatwg.org/#requestinit) to be optionally provided when instantiating a
* {@link Request}. * {@link Request}.
* *
* All values are null by default. * This class is based on the `RequestInit` description in the [Fetch
* Spec](https://fetch.spec.whatwg.org/#requestinit).
*
* All values are null by default. Typical defaults can be found in the {@link BaseRequestOptions}
* class, which sub-classes `RequestOptions`.
*
* ### Example ([live demo](http://plnkr.co/edit/7Wvi3lfLq41aQPKlxB4O?p=preview))
*
* ```typescript
* import {RequestOptions, Request, RequestMethods} from 'angular2/http';
*
* var options = new RequestOptions({
* method: RequestMethods.Post,
* url: 'https://google.com'
* });
* var req = new Request(options);
* console.log('req.method:', RequestMethods[req.method]); // Post
* console.log('options.url:', options.url); // https://google.com
* ```
*/ */
export class RequestOptions { export class RequestOptions {
/** /**
* Http method with which to execute the request. * Http method with which to execute a {@link Request}.
* * Acceptable methods are defined in the {@link RequestMethods} enum.
* Defaults to "GET".
*/ */
method: RequestMethods; method: RequestMethods;
/** /**
* Headers object based on the `Headers` class in the [Fetch * {@link Headers} to be attached to a {@link Request}.
* Spec](https://fetch.spec.whatwg.org/#headers-class).
*/ */
headers: Headers; headers: Headers;
/** /**
* Body to be used when creating the request. * Body to be used when creating a {@link Request}.
*/ */
// TODO: support FormData, Blob, URLSearchParams // TODO: support FormData, Blob, URLSearchParams
body: string; body: string;
/**
* Url with which to perform a {@link Request}.
*/
url: string; url: string;
/**
* Search parameters to be included in a {@link Request}.
*/
search: URLSearchParams; search: URLSearchParams;
constructor({method, headers, body, url, search}: RequestOptionsArgs = {}) { constructor({method, headers, body, url, search}: RequestOptionsArgs = {}) {
this.method = isPresent(method) ? method : null; this.method = isPresent(method) ? method : null;
@ -44,7 +64,28 @@ export class RequestOptions {
/** /**
* Creates a copy of the `RequestOptions` instance, using the optional input as values to override * Creates a copy of the `RequestOptions` instance, using the optional input as values to override
* existing values. * existing values. This method will not change the values of the instance on which it is being
* called.
*
* Note that `headers` and `search` will override existing values completely if present in
* the `options` object. If these values should be merged, it should be done prior to calling
* `merge` on the `RequestOptions` instance.
*
* Example ([live demo](http://plnkr.co/edit/6w8XA8YTkDRcPYpdB9dk?p=preview))
*
* ```typescript
* import {RequestOptions, Request, RequestMethods} from 'angular2/http';
*
* var options = new RequestOptions({
* method: RequestMethods.Post
* });
* var req = new Request(options.merge({
* url: 'https://google.com'
* }));
* console.log('req.method:', RequestMethods[req.method]); // Post
* console.log('options.url:', options.url); // null
* console.log('req.url:', req.url); // https://google.com
* ```
*/ */
merge(options?: RequestOptionsArgs): RequestOptions { merge(options?: RequestOptionsArgs): RequestOptions {
return new RequestOptions({ return new RequestOptions({