Skip to content

Commit

Permalink
feat(docs): properly load README into http docs (#1088)
Browse files Browse the repository at this point in the history
  • Loading branch information
@emoralesb05
emoralesb05 authored Jan 16, 2018
1 parent 14d0e7a commit 8bcfdf4
Show file tree
Hide file tree
Showing 3 changed files with 184 additions and 397 deletions.
224 changes: 2 additions & 222 deletions src/app/components/components/http/http.component.html
View file
Original file line number Diff line number Diff line change
@@ -1,222 +1,2 @@
<mat-card>
<mat-card-title>HttpInterceptorService</mat-card-title>
<mat-card-subtitle>How to use this service</mat-card-subtitle>
<mat-divider></mat-divider>
<mat-card-content>
<h2><code>HttpInterceptorService</code></h2>
<p>Service provided with methods that wrap the @angular [Http] service and provide an easier experience for interceptor implementation.</p>
<p>To add a desired interceptor, it needs to implement the [IHttpInterceptor] interface.</p>
<td-highlight lang="typescript">
<![CDATA[
export interface IHttpInterceptor {
onRequest?: (requestOptions: RequestOptionsArgs) => RequestOptionsArgs;
onRequestError?: (requestOptions: RequestOptionsArgs) => RequestOptionsArgs;
onResponse?: (response: Response) => Response;
onResponseError?: (error: Response) => Response;
}
]]>
</td-highlight>
<h3>Methods:</h3>
<p>The [HttpInterceptorService] service has {{interceptorServiceMethods.length}} properties:</p>
<mat-list>
<ng-template let-attr let-last="attr" ngFor [ngForOf]="interceptorServiceMethods">
<a mat-list-item layout-align="row">
<h3 matLine> {{attr.name}}: <span>{{attr.type}}</span></h3>
<p matLine> {{attr.description}} </p>
</a>
<mat-divider *ngIf="!last"></mat-divider>
</ng-template>
</mat-list>
<h3>Setup:</h3>
<p>Create your custom interceptors by implementing [IHttpInterceptor]:</p>
<td-highlight lang="typescript">
<![CDATA[
import { Injectable } from '@angular/core';
import { IHttpInterceptor } from '@covalent/http';

@Injectable()
export class CustomInterceptor implements IHttpInterceptor {

onRequest(requestOptions: RequestOptionsArgs): RequestOptionsArgs {
... // do something to requestOptions before a request
... // if something is wrong, throw an error to execute
... // onRequestError (if there is an onRequestError hook)
if (/*somethingWrong*/) {
throw new Error('error message for subscription error callback');
}
return requestOptions;
}

onRequestError(requestOptions: RequestOptionsArgs): RequestOptionsArgs {
... // do something to try and recover from an error thrown `onRequest`
... // and return the requestOptions needed for the request
... // else return 'undefined' or throw an error to execute the
... // error callback of the subscription
if (cantRecover) {
throw new Error('error message for subscription error callback'); // or return undefined;
}
return requestOptions;
}

onResponse(response: Response): Response {
... // check response status and do something
return response;
}

onResponseError(error: Response): Response {
... // check error status and do something
return error;
}
}
]]>
</td-highlight>
<p>Then, import the [CovalentHttpModule] using the <code>forRoot()</code> method with the desired interceptors and paths to intercept in your NgModule:</p>
<td-highlight lang="typescript">
<![CDATA[
import { NgModule, Type } from '@angular/core';
import { HttpModule } from '@angular/http';
import { CovalentHttpModule, IHttpInterceptor } from '@covalent/http';
import { CustomInterceptor } from 'dir/to/interceptor';

const httpInterceptorProviders: Type<IHttpInterceptor>[] = [
CustomInterceptor,
...
];

@NgModule({
imports: [
HttpModule,
CovalentHttpModule.forRoot({
interceptors: [{
interceptor: CustomInterceptor, paths: ['**'],
}],
}),
...
],
providers: [
httpInterceptorProviders,
...
],
...
})
export class MyModule {}
]]>
</td-highlight>
<p>After that, just inject [HttpInterceptorService] and use it for your requests.</p>
<h3>Paths:</h3>
<p>The following characters are accepted as a path to intercept:</p>
<td-markdown>
<pre><code>
- `**` is a wildcard for `[a-zA-Z0-9-_]` (including `/`)
- `*` is a wildcard for `[a-zA-Z0-9-_]` (excluding `/`)
- `[a-zA-Z0-9-_]`
</code></pre>
</td-markdown>
<h3>Examples:</h3>
<td-markdown>
<pre><code>
Example 1

`/users/*/groups` intercepts:
- `www.url.com/users/id-of-user/groups`
- `www.url.com/users/id/groups`

`/users/*/groups` DOES NOT intercept:
- `www.url.com/users/id-of-user/groups/path`
- `www.url.com/users/id-of-user/path/groups`
- `www.url.com/users/groups`

Example 2

`/users/**/groups` intercepts:
- `www.url.com/users/id-of-user/groups`
- `www.url.com/users/id/groups`
- `www.url.com/users/id-of-user/path/groups`

`/users/**/groups` DOES NOT intercept:
- `www.url.com/users/id-of-user/groups/path`
- `www.url.com/users/groups`

Example 3

`/users/**` intercepts:
- `www.url.com/users/id-of-user/groups`
- `www.url.com/users/id/groups`
- `www.url.com/users/id-of-user/path/groups`
- `www.url.com/users/id-of-user/groups/path`
- `www.url.com/users/groups`

`/users/**` DOES NOT intercept:
- `www.url.com/users`

Example 4

`/users**` intercepts:
- `www.url.com/users/id-of-user/groups`
- `www.url.com/users/id/groups`
- `www.url.com/users/id-of-user/path/groups`
- `www.url.com/users/id-of-user/groups/path`
- `www.url.com/users/groups`
- `www.url.com/users`
</code></pre>
</td-markdown>
</mat-card-content>
</mat-card>
<mat-card>
<mat-card-title>RESTService</mat-card-title>
<mat-card-subtitle>How to use this class</mat-card-subtitle>
<mat-divider></mat-divider>
<mat-card-content>
<h2><code>RESTService</code></h2>
<p>Abstract class provided with methods that wraps http services to facilitate REST API calls.</p>
<h3>Methods:</h3>
<p>The <code>RESTService</code> class has {{restServiceMethods.length}} methods:</p>
<mat-list>
<ng-template let-attr let-last="attr" ngFor [ngForOf]="restServiceMethods">
<a mat-list-item layout-align="row">
<h3 matLine> {{attr.name}}: <span>{{attr.type}}</span></h3>
<p matLine> {{attr.description}} </p>
</a>
<mat-divider *ngIf="!last"></mat-divider>
</ng-template>
</mat-list>
<h3>Example:</h3>
<p>Typescript:</p>
<td-highlight lang="typescript">
<![CDATA[
import { Injectable } from '@angular/core';
import { Response, Http, Headers } from '@angular/http';
import { RESTService, HttpInterceptorService } from '@covalent/http';

@Injectable()
export class CustomRESTService extends RESTService<any> {

constructor(private _http: Http /* or HttpInterceptorService */) {
super(_http, {
baseUrl: 'www.api.com',
path: '/path/to/endpoint',
headers: new Headers(),
dynamicHeaders: () => new Headers(),
transform: (res: Response): any => res.json(),
});
}
}
]]>
</td-highlight>
<p>Note: the constructor takes any object that implements the methods in [IHttp] interface.</p>
<p>This can be the angular [Http] service, the covalent [HttpInterceptorService] or a custom service.</p>
<td-highlight lang="typescript">
<![CDATA[
export interface IHttp {
delete: (url: string, options?: RequestOptionsArgs) => Observable<Response>;
get: (url: string, options?: RequestOptionsArgs) => Observable<Response>;
head: (url: string, options?: RequestOptionsArgs) => Observable<Response>;
patch: (url: string, body: any, options?: RequestOptionsArgs) => Observable<Response>;
post: (url: string, body: any, options?: RequestOptionsArgs) => Observable<Response>;
put: (url: string, body: any, options?: RequestOptionsArgs) => Observable<Response>;
request: (url: string | Request, options: RequestOptionsArgs) => Observable<Response>;
}
]]>
</td-highlight>
</mat-card-content>
</mat-card>
<td-readme-loader resourceUrl="platform/http/interceptors/README.md"></td-readme-loader>
<td-readme-loader resourceUrl="platform/http/README.md"></td-readme-loader>
Loading

0 comments on commit 8bcfdf4

Please sign in to comment.