add HTTP Error Handling section to HTTP Requests document

5 years ago · 202af0eb50
3 changed files with 96 additions and 3 deletions
--- a/docs/en/UI/Angular/HTTP-Requests.md
+++ b/docs/en/UI/Angular/HTTP-Requests.md
@ -27,13 +27,13 @@ An `HttpInterceptor` is able to catch `HttpErrorResponse`  and can be used for

 ## RestService

-ABP core module has a utility service for HTTP requests: `RestService`. Unless explicitly configured otherwise, it catches HTTP errors and dispatches a `RestOccurError` action. This action is then captured by the `ErrorHandler` introduced by the `ThemeSharedModule`. Since you should already import this module in your app, when the `RestService` is used, all HTTP errors get automatically handled by deafult.
+ABP core module has a utility service for HTTP requests: `RestService`. Unless explicitly configured otherwise, it catches HTTP errors and dispatches a `RestOccurError` action. This action is then captured by the `ErrorHandler` introduced by the `ThemeSharedModule`. Since you should already import this module in your app, when the `RestService` is used, all HTTP errors get automatically handled by default.



 ### Getting Started with RestService

-In order to use the  `RestService`, you must inject it in your class as a dependency.
+In order to use the `RestService`, you must inject it in your class as a dependency.

 ```js
 import { RestService } from '@abp/ng.core';
@ -200,6 +200,99 @@ getSomeCustomHeaderValue() {
 }
 ```

+You may find `Rest.Observe` enum [here](https://github.com/abpframework/abp/blob/dev/npm/ng-packs/packages/core/src/lib/models/rest.ts#L10).


-You may find `Rest.Observe` enum [here](https://github.com/abpframework/abp/blob/dev/npm/ng-packs/packages/core/src/lib/models/rest.ts#L10).
+## HTTP Error Handling
+
+When the `RestService` is used, all HTTP errors are automatically handled by `ErrorHandler` which is a service that exposed by the `@abp/ng.theme.shared` package.
+
+### Custom HTTP Error Handler
+
+A custom HTTP error handler can be registered to an injection token named `HTTP_ERROR_HANDLER`. If a custom handler function is registered, the `ErrorHandler` executes that function.
+
+See an example:
+
+```js
+// http-error-handler.ts
+import { ContentProjectionService, PROJECTION_STRATEGY } from '@abp/ng.core';
+import { ToasterService } from '@abp/ng.theme.shared';
+import { HttpErrorResponse } from '@angular/common/http';
+import { Injector } from '@angular/core';
+import { throwError } from 'rxjs';
+import { Error404Component } from './error404/error404.component';
+
+export function handleHttpErrors(injector: Injector, httpError: HttpErrorResponse) {
+  if (httpError.status === 400) {
+    const toaster = injector.get(ToasterService);
+    toaster.error(httpError.error?.error?.message || 'Bad request!', '400');
+    return;
+  }
+
+  if (httpError.status === 404) {
+    const contentProjection = injector.get(ContentProjectionService);
+    contentProjection.projectContent(PROJECTION_STRATEGY.AppendComponentToBody(Error404Component));
+    return;
+  }
+
+  return throwError(httpError);
+}
+
+// app.module.ts
+import { Error404Component } from './error404/error404.component';
+import { handleHttpErrors } from './http-error-handling';
+import { HTTP_ERROR_HANDLER, ... } from '@abp/ng.theme.shared';
+
+@NgModule({
+  // ...
+  providers: [
+    // ...
+    { provide: HTTP_ERROR_HANDLER, useValue: handleHttpErrors }
+  ],
+  declarations: [
+   //...
+   Error404Component],
+})
+export class AppModule {}
+```
+
+In the example above:
+
+ - Created a function named `handleHttpErrors` and defined as value of the `HTTP_ERROR_HANDLER` provider in app.module. After this, the function executes when an HTTP error occurs.
+ - 400 bad request errors is handled. When a 400 error occurs, backend error message will be displayed as shown below:
+  
+  ![custom-error-handler-toaster-message](images/custom-error-handler-toaster-message.jpg)
+
+ - 404 not found errors is handled. When a 404 error occurs, `Error404Component` will be appended to the `<body>` as shown below:
+
+![custom-error-handler-404-component](images/custom-error-handler-404-component.jpg)
+
+ - Since `throwError(httpError)` is returned at bottom of the `handleHttpErrors`, the `ErrorHandler` will handle the HTTP errors except 400 and 404 errors.
+
+
+**Note 1:** If you put `return` to next line of handling an error, default error handling will not work for that error.
+
+```js
+export function handleHttpErrors(injector: Injector, httpError: HttpErrorResponse) {
+  if (httpError.status === 403) {
+    // handle 403 errors here
+    return; // put return to skip default error handling
+  }
+}
+```
+
+**Note 2:** If you put `return throwError(httpError)`, default error handling will work.
+  - `throwError` is a function. It can be imported from `rxjs`.
+  - `httpError` is the second parameter of the error handler function which is registered to the `HTTP_ERROR_HANDLER` provider. Type of the `httpError` is `HttpErrorResponse`.
+
+```js
+export function handleHttpErrors(injector: Injector, httpError: HttpErrorResponse) {
+  if (httpError.status === 500) {
+    // handle 500 errors here
+    return;
+  }
+
+  // you can return the throwError(httpError) at bottom of the function to run the default handler of ABP for HTTP errors that you didn't handle above.
+  return throwError(httpError)
+}
+```
--- a/docs/en/UI/Angular/images/custom-error-handler-404-component.jpg
+++ b/docs/en/UI/Angular/images/custom-error-handler-404-component.jpg
--- a/docs/en/UI/Angular/images/custom-error-handler-toaster-message.jpg
+++ b/docs/en/UI/Angular/images/custom-error-handler-toaster-message.jpg