1
0
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:
Oscar Hinton
2023-05-08 14:46:59 +02:00
committed by GitHub
parent f51ed1092d
commit d53f79e325
14 changed files with 313 additions and 218 deletions

View File

@@ -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>

View File

@@ -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?

View File

@@ -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.