Merge pull request #3706 from abpframework/docs/confirmation-toaster

Added ToasterService and ConfirmationService documentations

docs/en/UI/Angular/Confirmation-Service.md

@@ -0,0 +1,163 @@
+# Confirmation Popup
+
+You can use the `ConfirmationService` in @abp/ng.theme.shared package to display a confirmation popup by placing at the root level in your project.
+
+
+## Getting Started
+
+You do not have to provide the `ConfirmationService` at module or component level, because it is already **provided in root**. You can inject and start using it immediately in your components, directives, or services.
+
+
+```js
+import { ConfirmationService } from '@abp/ng.theme.shared';
+
+@Component({
+  /* class metadata here */
+})
+class DemoComponent {
+  constructor(private confirmation: ConfirmationService) {}
+}
+```
+
+## Usage
+
+You can use the `success`, `warn`, `error`, and `info` methods of `ConfirmationService` to display a confirmation popup.
+
+### How to Display a Confirmation Popup
+
+```js
+const confirmationStatus$ = this.confirmation.success('Message', 'Title');
+```
+
+- The `ConfirmationService` methods accept three parameters that are `message`, `title`, and `options`.
+- `success`, `warn`, `error`, and `info` methods return an [RxJS Subject](https://rxjs-dev.firebaseapp.com/guide/subject) to listen to confirmation popup closing event. The type of event value is [`Confirmation.Status`](https://github.com/abpframework/abp/blob/master/npm/ng-packs/packages/theme-shared/src/lib/models/confirmation.ts#L24) that is an enum.
+
+### How to Listen Closing Event
+
+You can subscribe to the confirmation closing event like below:
+
+```js
+import { Confirmation, ConfirmationService } from '@abp/ng.theme.shared';
+
+constructor(private confirmation: ConfirmationService) {}
+
+this.confirmation
+  .warn('::WillBeDeleted', { key: '::AreYouSure', defaultValue: 'Are you sure?' })
+  .subscribe((status: Confirmation.Status) => {
+    // your code here
+  });
+```
+
+
+- The `message` and `title` parameters accept a string, localization key or localization object. See the [localization document](./Localization.md)
+- `Confirmation.Status` is an enum and has three properties;
+    - `Confirmation.Status.confirm` is a closing event value that will be emitted when the popup is closed by the confirm button.
+    - `Confirmation.Status.reject` is a closing event value that will be emitted when the popup is closed by the cancel button.
+    - `Confirmation.Status.dismiss` is a closing event value that will be emitted when the popup is closed by pressing the escape.
+
+
+If you are not interested in the confirmation status, you do not have to subscribe to the returned observable:
+
+```js
+this.confirmation.error('You are not authorized.', 'Error');
+```
+
+### How to Display a Confirmation Popup With Given Options
+
+Options can be passed as the third parameter to `success`, `warn`, `error`, and `info` methods:
+
+```js
+const options: Partial<Confirmation.Options> = {
+  hideCancelBtn: false,
+  hideYesBtn: false,
+  cancelText: 'Close',
+  yesText: 'Confirm',
+  messageLocalizationParams: ['Demo'],
+  titleLocalizationParams: [],
+};
+
+this.confirmation.warn(
+  'AbpIdentity::RoleDeletionConfirmationMessage',
+  'Are you sure?',
+  options,
+);
+```
+
+- `hideCancelBtn` option hides the cancellation button when `true`. Default value is `false`
+- `hideYesBtn` option hides the confirmation button when `true`. Default value is `false`
+- `cancelText` is the text of the cancellation button. A localization key or localization object can be passed. Default value is `AbpUi::Cancel`
+- `yesText` is the text of the confirmation button. A localization key or localization object can be passed. Default value is `AbpUi::Yes`
+- `messageLocalizationParams` is the interpolation parameters for the localization of the message.
+- `titleLocalizationParams` is the interpolation parameters for the localization of the title.
+
+With the options above, the confirmation popup looks like this:
+
+![confirmation](./images/confirmation.png)
+
+### How to Remove a Confirmation Popup
+
+The open confirmation popup can be removed manually via the `clear` method:
+
+```js
+this.confirmation.clear();
+```
+
+## API
+
+### success
+
+```js
+success(
+  message: Config.LocalizationParam,
+  title: Config.LocalizationParam,
+  options?: Partial<Confirmation.Options>,
+): Observable<Confirmation.Status>
+```
+
+> See the [`Config.LocalizationParam` type](https://github.com/abpframework/abp/blob/master/npm/ng-packs/packages/core/src/lib/models/config.ts#L46) and [`Confirmation` namespace](https://github.com/abpframework/abp/blob/master/npm/ng-packs/packages/theme-shared/src/lib/models/confirmation.ts)
+
+
+### warn
+
+```js
+warn(
+  message: Config.LocalizationParam,
+  title: Config.LocalizationParam,
+  options?: Partial<Confirmation.Options>,
+): Observable<Confirmation.Status>
+```
+
+### error
+
+```js
+error(
+  message: Config.LocalizationParam,
+  title: Config.LocalizationParam,
+  options?: Partial<Confirmation.Options>,
+): Observable<Confirmation.Status>
+```
+
+### info
+
+```js
+info(
+  message: Config.LocalizationParam,
+  title: Config.LocalizationParam,
+  options?: Partial<Confirmation.Options>,
+): Observable<Confirmation.Status>
+```
+
+### clear
+
+```js
+clear(
+  status: Confirmation.Status = Confirmation.Status.dismiss
+): void
+```
+
+- `status` parameter is the value of the confirmation closing event.
+
+
+## What's Next?
+
+- [Toast Overlay](./Toaster-Service.md)

docs/en/UI/Angular/Permission-Management.md

@@ -76,4 +76,4 @@ Granted Policies are stored in the `auth` property of `ConfigState`.
 
 ## What's Next?
 
-* [Config State](./Config-State.md)
+- [Confirmation Popup](./Confirmation-Service.md)

docs/en/UI/Angular/Toaster-Service.md

@@ -0,0 +1,157 @@
+# Toast Overlay
+
+You can use the `ToasterService` in @abp/ng.theme.shared package to display messages in an overlay by placing at the root level in your project.
+
+
+## Getting Started
+
+You do not have to provide the `ToasterService` at module or component level, because it is already **provided in root**. You can inject and start using it immediately in your components, directives, or services.
+
+
+```js
+import { ToasterService } from '@abp/ng.theme.shared';
+
+@Component({
+  /* class metadata here */
+})
+class DemoComponent {
+  constructor(private toaster: ToasterService) {}
+}
+```
+
+## Usage
+
+You can use the `success`, `warn`, `error`, and `info` methods of `ToasterService` to display an overlay.
+
+### How to Display a Toast Overlay
+
+```js
+this.toast.success('Message', 'Title');
+```
+
+- The `ToasterService` methods accept three parameters that are `message`, `title`, and `options`.
+- `success`, `warn`, `error`, and `info` methods return the id of opened toast overlay. The toast can be removed with this id.
+
+### How to Display a Toast Overlay With Given Options
+
+Options can be passed as the third parameter to `success`, `warn`, `error`, and `info` methods:
+
+```js
+import { Toaster, ToasterService } from '@abp/ng.theme.shared';
+//...
+
+constructor(private toaster: ToasterService) {}
+
+//...
+const options: Partial<Toaster.ToastOptions> = {
+    life: 10000,
+    sticky: false,
+    closable: true,
+    tapToDismiss: true,
+    messageLocalizationParams: ['Demo', '1'],
+    titleLocalizationParams: []
+  };
+
+  this.toaster.error('AbpUi::EntityNotFoundErrorMessage', 'AbpUi::Error', options);
+```
+
+- `life` option is the closing time in milliseconds. Default value is `5000`.
+- `sticky` option keeps toast overlay on the screen by ignoring the `life` option when `true`. Default value is `false`.
+- `closable` option displays the close icon on the toast overlay when it is `true`. Default value is `true`.
+- `tapToDismiss` option, when `true`, allows closing the toast overlay by clicking over it. Default value is `false`.
+- `yesText` is the text of the confirmation button. A localization key or localization object can be passed. Default value is `AbpUi::Yes`.
+- `messageLocalizationParams` is the interpolation parameters for the localization of the message.
+- `titleLocalizationParams` is the interpolation parameters for the localization of the title.
+
+With the options above, the toast overlay looks like this:
+
+![toast](./images/toast.png)
+
+### How to Remove a Toast Overlay
+
+The open toast overlay can be removed manually via the `remove` method by passing the `id` of toast:
+
+```js
+const toastId = this.toast.success('Message', 'Title')
+
+this.toast.remove(toastId);
+```
+
+### How to Remove All Toasts
+
+The all open toasts can be removed manually via the `clear` method:
+
+```js
+this.toast.clear();
+```
+
+## API
+
+### success
+
+```js
+success(
+  message: Config.LocalizationParam,
+  title: Config.LocalizationParam,
+  options?: Partial<Toaster.ToastOptions>,
+): number
+```
+
+- `Config` namespace can be imported from `@abp/ng.core`.
+- `Toaster` namespace can be imported from `@abp/ng.theme.shared`.
+
+> See the [`Config.LocalizationParam` type](https://github.com/abpframework/abp/blob/master/npm/ng-packs/packages/core/src/lib/models/config.ts#L46) and [`Toaster` namespace](https://github.com/abpframework/abp/blob/master/npm/ng-packs/packages/theme-shared/src/lib/models/toaster.ts)
+
+
+### warn
+
+```js
+warn(
+  message: Config.LocalizationParam,
+  title: Config.LocalizationParam,
+  options?: Partial<Toaster.ToastOptions>,
+): number
+```
+
+### error
+
+```js
+error(
+  message: Config.LocalizationParam,
+  title: Config.LocalizationParam,
+  options?: Partial<Toaster.ToastOptions>,
+): number
+```
+
+### info
+
+```js
+info(
+  message: Config.LocalizationParam,
+  title: Config.LocalizationParam,
+  options?: Partial<Toaster.ToastOptions>,
+): number
+```
+
+### remove
+
+```js
+remove(id: number): void
+```
+
+Removes an open toast by the given id.
+
+### clear
+
+```js
+clear(): void
+```
+
+Removes all open toasts.
+
+## See Also
+- [Confirmation Popup](./Confirmation-Service.md)
+
+## What's Next?
+
+- [Config State](./Config-State.md)

docs/en/docs-nav.json

@@ -337,6 +337,14 @@
               "text": "Permission Management",
               "path": "UI/Angular/Permission-Management.md"
             },
+            {
+              "text": "Confirmation Popup",
+              "path": "UI/Angular/Confirmation-Service.md"
+            },
+            {
+              "text": "Toast Overlay",
+              "path": "UI/Angular/Toaster-Service.md"
+            },
             {
               "text": "Config State",
               "path": "UI/Angular/Config-State.md"