mirror of
https://github.com/bitwarden/browser
synced 2025-12-13 23:03:32 +00:00
Update CL documentation (#5379)
This commit is contained in:
@@ -4,10 +4,12 @@ import { Meta } from "@storybook/addon-docs";
|
||||
|
||||
# Async Actions In Forms
|
||||
|
||||
These directives should be used when building forms with buttons that trigger long running tasks in the background,
|
||||
eg. Submit or Delete buttons. For buttons that are not associated with a form see [Standalone Async Actions](?path=/story/component-library-async-actions-standalone-documentation--page).
|
||||
These directives should be used when building forms with buttons that trigger long running tasks in
|
||||
the background, eg. Submit or Delete buttons. For buttons that are not associated with a form see
|
||||
[Standalone Async Actions](?path=/story/component-library-async-actions-standalone-documentation--page).
|
||||
|
||||
There are two separately supported use-cases: Submit buttons and standalone form buttons (eg. Delete buttons).
|
||||
There are two separately supported use-cases: Submit buttons and standalone form buttons (eg. Delete
|
||||
buttons).
|
||||
|
||||
## Usage: Submit buttons
|
||||
|
||||
@@ -15,17 +17,19 @@ Adding async actions to submit buttons requires the following 3 steps
|
||||
|
||||
### 1. Add a handler to your `Component`
|
||||
|
||||
A handler is a function that returns a promise or an observable. Functions that return `void` are also supported which is
|
||||
useful because `return;` can be used to abort an action.
|
||||
A handler is a function that returns a promise or an observable. Functions that return `void` are
|
||||
also supported which is useful because `return;` can be used to abort an action.
|
||||
|
||||
**NOTE:** Defining the handlers as arrow-functions assigned to variables is mandatory if the handler needs access to the parent
|
||||
component using the variable `this`.
|
||||
**NOTE:** Defining the handlers as arrow-functions assigned to variables is mandatory if the handler
|
||||
needs access to the parent component using the variable `this`.
|
||||
|
||||
**NOTE:** `formGroup.invalid` will always return `true` after the first `await` operation, event if the form is not actually
|
||||
invalid. This is due to the form getting disabled by the `bitSubmit` directive while waiting for the async action to complete.
|
||||
**NOTE:** `formGroup.invalid` will always return `true` after the first `await` operation, event if
|
||||
the form is not actually invalid. This is due to the form getting disabled by the `bitSubmit`
|
||||
directive while waiting for the async action to complete.
|
||||
|
||||
**NOTE:** Handlers do not need to check if any previous requests have finished because the directives have built in protection against
|
||||
users attempting to trigger new actions before the previous ones have finished.
|
||||
**NOTE:** Handlers do not need to check if any previous requests have finished because the
|
||||
directives have built in protection against users attempting to trigger new actions before the
|
||||
previous ones have finished.
|
||||
|
||||
```ts
|
||||
@Component({...})
|
||||
@@ -51,8 +55,8 @@ class Component {
|
||||
|
||||
Add the `bitSubmit` directive and supply the handler defined in step 1.
|
||||
|
||||
**NOTE:** The `directive` is defined using the input syntax: `[input]="handler"`.
|
||||
This is different from how submit handlers are usually defined with the output syntax `(ngSubmit)="handler()"`.
|
||||
**NOTE:** The `directive` is defined using the input syntax: `[input]="handler"`. This is different
|
||||
from how submit handlers are usually defined with the output syntax `(ngSubmit)="handler()"`.
|
||||
|
||||
**NOTE:** `[bitSubmit]` is used instead of `(ngSubmit)`. Using both is not supported.
|
||||
|
||||
@@ -76,14 +80,15 @@ Adding async actions to standalone form buttons requires the following 3 steps.
|
||||
|
||||
### 1. Add a handler to your `Component`
|
||||
|
||||
A handler is a function that returns a promise or an observable. Functions that return `void` are also supported which is
|
||||
useful for aborting an action.
|
||||
A handler is a function that returns a promise or an observable. Functions that return `void` are
|
||||
also supported which is useful for aborting an action.
|
||||
|
||||
**NOTE:** Defining the handlers as arrow-functions assigned to variables is mandatory if the handler needs access to the parent
|
||||
component using the variable `this`.
|
||||
**NOTE:** Defining the handlers as arrow-functions assigned to variables is mandatory if the handler
|
||||
needs access to the parent component using the variable `this`.
|
||||
|
||||
**NOTE:** Handlers do not need to check if any previous requests have finished because the directives have built in protection against
|
||||
users attempting to trigger new actions before the previous ones have finished.
|
||||
**NOTE:** Handlers do not need to check if any previous requests have finished because the
|
||||
directives have built in protection against users attempting to trigger new actions before the
|
||||
previous ones have finished.
|
||||
|
||||
```ts
|
||||
@Component({...})
|
||||
@@ -113,7 +118,8 @@ The `bitSubmit` directive is required because of its coordinating role inside of
|
||||
|
||||
### 3. Add directives to the `button` element
|
||||
|
||||
Add `bitButton`, `bitFormButton`, `bitAction` directives to the button. Make sure to supply a handler.
|
||||
Add `bitButton`, `bitFormButton`, `bitAction` directives to the button. Make sure to supply a
|
||||
handler.
|
||||
|
||||
**NOTE:** A summary of what each directive does can be found inside the source code.
|
||||
|
||||
@@ -124,7 +130,8 @@ Add `bitButton`, `bitFormButton`, `bitAction` directives to the button. Make sur
|
||||
|
||||
## `[bitSubmit]` Disabled Form Submit
|
||||
|
||||
If you need your form to be able to submit even when the form is disabled, then add `[allowDisabledFormSubmit]="true"` to your `<form>`
|
||||
If you need your form to be able to submit even when the form is disabled, then add
|
||||
`[allowDisabledFormSubmit]="true"` to your `<form>`
|
||||
|
||||
```html
|
||||
<form [formGroup]="formGroup" [bitSubmit]="submit" [allowDisabledFormSubmit]="true">...</form>
|
||||
|
||||
@@ -4,14 +4,14 @@ import { Meta } from "@storybook/addon-docs";
|
||||
|
||||
# Async Actions
|
||||
|
||||
The directives in this module makes it easier for developers to reflect the progress of async actions in the UI when using
|
||||
buttons, while also providing robust and standardized error handling.
|
||||
The directives in this module makes it easier for developers to reflect the progress of async
|
||||
actions in the UI when using buttons, while also providing robust and standardized error handling.
|
||||
|
||||
These buttons can either be standalone (such as Refresh buttons), submit buttons for forms or as standalone buttons
|
||||
that are part of a form (such as Delete buttons).
|
||||
These buttons can either be standalone (such as Refresh buttons), submit buttons for forms or as
|
||||
standalone buttons that are part of a form (such as Delete buttons).
|
||||
|
||||
These directives are meant to replace the older `appApiAction` directive, providing the option to use `observables` and reduce
|
||||
clutter inside our view `components`.
|
||||
These directives are meant to replace the older `appApiAction` directive, providing the option to
|
||||
use `observables` and reduce clutter inside our view `components`.
|
||||
|
||||
## When to use?
|
||||
|
||||
|
||||
@@ -4,8 +4,9 @@ import { Meta } from "@storybook/addon-docs";
|
||||
|
||||
# Standalone Async Actions
|
||||
|
||||
These directives should be used when building a standalone button that triggers a long running task in the background,
|
||||
eg. Refresh buttons. For non-submit buttons that are associated with forms see [Async Actions In Forms](?path=/story/component-library-async-actions-in-forms-documentation--page).
|
||||
These directives should be used when building a standalone button that triggers a long running task
|
||||
in the background, eg. Refresh buttons. For non-submit buttons that are associated with forms see
|
||||
[Async Actions In Forms](?path=/story/component-library-async-actions-in-forms-documentation--page).
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -13,14 +14,15 @@ Adding async actions to standalone buttons requires the following 2 steps
|
||||
|
||||
### 1. Add a handler to your `Component`
|
||||
|
||||
A handler is a function that returns a promise or an observable. Functions that return `void` are also supported which is
|
||||
useful because `return;` can be used to abort an action.
|
||||
A handler is a function that returns a promise or an observable. Functions that return `void` are
|
||||
also supported which is useful because `return;` can be used to abort an action.
|
||||
|
||||
**NOTE:** Defining the handlers as arrow-functions assigned to variables is mandatory if the handler needs access to the parent
|
||||
component using the variable `this`.
|
||||
**NOTE:** Defining the handlers as arrow-functions assigned to variables is mandatory if the handler
|
||||
needs access to the parent component using the variable `this`.
|
||||
|
||||
**NOTE:** Handlers do not need to check if any previous requests have finished because the directives have built in protection against
|
||||
users attempting to trigger new actions before the previous ones have finished.
|
||||
**NOTE:** Handlers do not need to check if any previous requests have finished because the
|
||||
directives have built in protection against users attempting to trigger new actions before the
|
||||
previous ones have finished.
|
||||
|
||||
#### Example using promises
|
||||
|
||||
@@ -48,8 +50,8 @@ class Component {
|
||||
|
||||
Add the `bitAction` directive and supply the handler defined in step 1.
|
||||
|
||||
**NOTE:** The `directive` is defined using the input syntax: `[input]="handler"`.
|
||||
This is different from how click handlers are usually defined with the output syntax `(click)="handler()"`.
|
||||
**NOTE:** The `directive` is defined using the input syntax: `[input]="handler"`. This is different
|
||||
from how click handlers are usually defined with the output syntax `(click)="handler()"`.
|
||||
|
||||
**NOTE:** `[bitAction]` is used instead of `(click)`. Using both is not supported.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user