File

core/src/rxjs/on-observer/directives/on-observer-finalized.directive.ts

Description

Documentation in OnObserverFinalizedDirective.onObserverFinalized to allow in-template tooltips.

Extends

OnObserverBaseDirective

Metadata

Index

Properties
Methods
Inputs
Accessors

Inputs

onObserverFinalized
Type : Observable<T>

Renders the template when the specified observable is either completed or errored. In case of an error, the error will be provided as the value in the context.

Features

View Context

Use the microsyntax as keyword to assign resolved values to a variable. Use the microsyntax let keyword to assign the full context object to a variable (e.g. let context).

Delayed rendering

Specify a value for showAfter to delay rendering.

Auto destroy

Specify showFor to automatically destroy the view after a certain duration.

Countdown updates

When showFor is specified, the view context will be updated with the time remaining until the view is destroyed and the time elapsed since it was rendered. This allows giving the user feedback in a progress bar, a spinner, a textual timer or any other UI component.

Remaining is provided by the remaining property. Elapsed time is provided by the elapsed property. Access it by assigning a variable using let, like so: let remaining = remaining

Multi view mode

Specify viewMode = 'multiple' to enable rendering a new view for each intercepted call instead of updating a single rendered view. This allows stacking logs, notification snackbars, or any other aggregation functionality. Combined with showFor, this is great for disappearing messages/notifications.

View index

In multi-view mode, the context will contain the index of the view, which can be used for calculations and styling.

onObserverFinalizedCountdownInterval
Type : DurationAnnotation | "animationFrames"

(Optional) The interval with which countdown updates should be made to the view's context before it auto destroys. The lower the value, the more updates will be made to the context, but the more resources your directive will consume.

You can specify a number, which will be treated as milliseconds, or a string with the format of <number><ms | s | ms>. Numbers can be either integers or floats. For example:

  • 3000 - 3 seconds between each update.
  • '10s' - 10 seconds between each update.
  • '0.5m' - 30 seconds between each update.
  • '100ms' - 100 milliseconds between each update.

You can also specify 'animationFrames' so the countdown gets updated each time the browser is working on animations.

When unspecified, the total duration of the countdown will be divided by DefaultCountdownUpdateCount to get a fixed interval which will make for DefaultCountdownUpdateCount countdown updates.

onObserverFinalizedShowAfter
Type : DurationAnnotation

(Optional) The duration for which the directive should wait before rendering the view once an intercepted call is made.

You can specify a number, which will be treated as milliseconds, or a string with the format of <number><ms | s | ms>. Numbers can be either integers or floats. For example:

  • 3000 - Wait for 3 seconds, then render the view.
  • '10s' - Wait for 10 seconds, then render the view.
  • '0.5m' - Wait for 30 seconds, then render the view.
  • '100ms' - Wait for 100 milliseconds, then render the view.

Default is 0, meaning immediately render the view.

TODO: ADD LINK TO TOUR OR FULL WIKI PAGE Read more About render flow.

onObserverFinalizedShowFor
Type : DurationAnnotation

(Optional) The duration for which the view should be rendered. When the duration passes, the view will be auto destroyed.

You can specify a number, which will be treated as milliseconds, or a string with the format of <number><ms | s | ms>. Numbers can be either integers or floats. For example:

  • 3000 - The view will be destroyed after 3 seconds.
  • '10s' - The view will be destroyed after 10 seconds.
  • '0.5m' - The view will be destroyed after 30 seconds.
  • '100ms' - The view will be destroyed after 100 milliseconds.

During the time the view is rendered, the context will be updated with a countdown object to facilitate any UI part used to indicate countdown to the user. The countdown will be exposed through the remaining property and the elapsed time through elapsed property in the view context and can both be accessed be declaring a let variable (e.g. let remaining = remaining). See countdownInterval for changing the updates interval.

When unspecified, the view will be destroyed immediately once the observer detects a call different to the intercepted ones.

TODO: ADD LINK TO TOUR OR FULL WIKI PAGE Read more About render flow.

onObserverFinalizedViewMode
Type : ViewMode

(Optional) The view mode the directive will operate in: 'single' - A single view will be rendered on intercepted calls. If a view has already been rendered when a call is intercepted, the existing view will be updated with data from the new call.

'multiple' - Every new intercepted call will render a new view with its own context and data encapsulated from the current call.

Default is 'single'.

Methods

Static ngTemplateContextGuard
ngTemplateContextGuard(directive: OnObserverFinalizedDirective<T>, context)
Type parameters:
  • T
Parameters:
Name Type Optional
directive OnObserverFinalizedDirective<T> No
context No
ngOnInit
ngOnInit()
Inherited from OnObserverBaseDirective
Returns: void
ngOnDestroy
ngOnDestroy()
Inherited from Destroyable
Returns: void
Protected subscribe
subscribe(observable: Observable, next?: (value?: T) => void, error?: (undefined) => void, complete?: () => void)
Inherited from Destroyable
Type parameters:
  • T

Subscribes to an observable and stores the subscription for automatic disposal. When ngOnDestroy() is called, all subscriptions created with this method will unsubscribe.

Parameters:
Name Type Optional Description
observable Observable<T> No

The observable to subscribe to.

next function Yes

(Optional) A callback function to execute on each emission of the observable.

error function Yes

(Optional) A callback function to execute when the observable errors.

complete function Yes

(Optional) A callback function to execute when the observable completes.

Returns: Subscription

The subscription created for the observable.

Properties

Protected renderOnCallsTo
Type: ObserverName[]
Default value: ['error', 'complete']
Inherited from OnObserverBaseDirective
Protected selector
Type: string
Default value: 'onObserverFinalized'
Inherited from OnObserverBaseDirective
Protected Optional countdownInterval
Type: DurationAnnotation | "animationFrames"
Inherited from OnObserverBaseDirective

(Optional) The interval with which countdown updates should be made to the view's context before it auto destroys. The lower the value, the more updates will be made to the context, but the more resources your directive will consume.

You can specify a number, which will be treated as milliseconds, or a string with the format of <number><ms | s | ms>. Numbers can be either integers or floats. For example:

  • 3000 - 3 seconds between each update.
  • '10s' - 10 seconds between each update.
  • '0.5m' - 30 seconds between each update.
  • '100ms' - 100 milliseconds between each update.

You can also specify 'animationFrames' so the countdown gets updated each time the browser is working on animations.

When unspecified, the total duration of the countdown will be divided by DefaultCountdownUpdateCount to get a fixed interval which will make for DefaultCountdownUpdateCount countdown updates.

⚠️ Extending classes should:

  1. Declare an @Input() setter named {selector}CountdownInterval (e.g. onObserverCompleteCountdownInterval) which will set this value.
  2. Provide the above documentation for the setter property.
Protected Readonly input
Type: BehaviorSubject<Observable | null>
Default value: new BehaviorSubject(null as Observable<T> | null)
Inherited from OnObserverBaseDirective

Why BehaviorSubject<... | null> and not Subject<...>

input is set from @Input properties. For some reason, Angular passes-in the first value BEFORE ngOnInit, even though other @Input properties (e.g. showAfter, showFor) are passed AFTER ngOnInit. If subscription occurs in the constructor, input will emit the first observable too fast, which might lead to pipes breaking or misbehaving if they rely on properties to be instantiated first.

This leads to subscribing in ngOnInit, to allow Angular time to initialize those. BUT, if input is a Subject, as the first value was already emitted BEFORE ngOnInit, it will not be captured by our subscription to input. Hence the BehaviorSubject - To allow capturing that first observable.

Protected showAfter
Type: DurationAnnotation
Default value: 0
Inherited from OnObserverBaseDirective

(Optional) The duration for which the directive should wait before rendering the view once an intercepted call is made.

You can specify a number, which will be treated as milliseconds, or a string with the format of <number><ms | s | ms>. Numbers can be either integers or floats. For example:

  • 3000 - Wait for 3 seconds, then render the view.
  • '10s' - Wait for 10 seconds, then render the view.
  • '0.5m' - Wait for 30 seconds, then render the view.
  • '100ms' - Wait for 100 milliseconds, then render the view.

Default is 0, meaning immediately render the view.

TODO: ADD LINK TO TOUR OR FULL WIKI PAGE Read more About render flow.

⚠️ Extending classes should:

  1. Declare an @Input() setter named {selector}ShowAfter (e.g. onObserverCompleteShowAfter) which will set this value.
  2. Provide the above documentation for the setter property.
Protected Optional showFor
Type: DurationAnnotation
Inherited from OnObserverBaseDirective

(Optional) The duration for which the view should be rendered. When the duration passes, the view will be auto destroyed.

You can specify a number, which will be treated as milliseconds, or a string with the format of <number><ms | s | ms>. Numbers can be either integers or floats. For example:

  • 3000 - The view will be destroyed after 3 seconds.
  • '10s' - The view will be destroyed after 10 seconds.
  • '0.5m' - The view will be destroyed after 30 seconds.
  • '100ms' - The view will be destroyed after 100 milliseconds.

During the time the view is rendered, the context will be updated with a countdown object to facilitate any UI part used to indicate countdown to the user. The countdown will be exposed through the remaining property and the elapsed time through elapsed property in the view context and can both be accessed be declaring a let variable (e.g. let remaining = remaining). See countdownInterval for changing the updates interval.

When unspecified, the view will be destroyed immediately once the observer detects a call different to the intercepted ones.

TODO: ADD LINK TO TOUR OR FULL WIKI PAGE Read more About render flow.

⚠️ Extending classes should:

  1. Declare an @Input() setter named {selector}ShowFor (e.g. onObserverCompleteShowFor) which will set this value.
  2. Provide the above documentation for the setter property.
Protected viewMode
Type: ViewMode
Default value: 'single'
Inherited from OnObserverBaseDirective

(Optional) The view mode the directive will operate in: 'single' - A single view will be rendered on intercepted calls. If a view has already been rendered when a call is intercepted, the existing view will be updated with data from the new call.

'multiple' - Every new intercepted call will render a new view with its own context and data encapsulated from the current call.

Default is 'single'.

⚠️ Extending classes should:

  1. Declare an @Input() setter named {selector}ViewMode (e.g. onObserverCompleteViewMode) which will set this value.
  2. Provide the above documentation for the setter property.
Protected Readonly destroyed
Type: Subject<void>
Default value: new Subject()
Inherited from Destroyable

Emits a value when ngOnDestroy() is called. Pipe together with takeUntil() to auto unsubscribe from your observables.

observable.pipe(takeUntil(this.destroyed)).subscribe(...);
Protected Readonly subscriptions
Type: Subscription
Default value: new Subscription()
Inherited from Destroyable

A list of all subscriptions manually added using the subscribe() method. These are automatically unsubscribed when ngOnDestroy() is called.

Accessors

onObserverFinalized
setonObserverFinalized(value: Observable)

Renders the template when the specified observable is either completed or errored. In case of an error, the error will be provided as the value in the context.

Features

View Context

Use the microsyntax as keyword to assign resolved values to a variable. Use the microsyntax let keyword to assign the full context object to a variable (e.g. let context).

Delayed rendering

Specify a value for showAfter to delay rendering.

Auto destroy

Specify showFor to automatically destroy the view after a certain duration.

Countdown updates

When showFor is specified, the view context will be updated with the time remaining until the view is destroyed and the time elapsed since it was rendered. This allows giving the user feedback in a progress bar, a spinner, a textual timer or any other UI component.

Remaining is provided by the remaining property. Elapsed time is provided by the elapsed property. Access it by assigning a variable using let, like so: let remaining = remaining

Multi view mode

Specify viewMode = 'multiple' to enable rendering a new view for each intercepted call instead of updating a single rendered view. This allows stacking logs, notification snackbars, or any other aggregation functionality. Combined with showFor, this is great for disappearing messages/notifications.

View index

In multi-view mode, the context will contain the index of the view, which can be used for calculations and styling.

Parameters :
Name Type Optional
value Observable<T> No
Returns: void
onObserverFinalizedViewMode
setonObserverFinalizedViewMode(viewMode: ViewMode)

(Optional) The view mode the directive will operate in: 'single' - A single view will be rendered on intercepted calls. If a view has already been rendered when a call is intercepted, the existing view will be updated with data from the new call.

'multiple' - Every new intercepted call will render a new view with its own context and data encapsulated from the current call.

Default is 'single'.

Parameters :
Name Type Optional
viewMode ViewMode No
Returns: void
onObserverFinalizedShowAfter
setonObserverFinalizedShowAfter(duration: DurationAnnotation)

(Optional) The duration for which the directive should wait before rendering the view once an intercepted call is made.

You can specify a number, which will be treated as milliseconds, or a string with the format of <number><ms | s | ms>. Numbers can be either integers or floats. For example:

  • 3000 - Wait for 3 seconds, then render the view.
  • '10s' - Wait for 10 seconds, then render the view.
  • '0.5m' - Wait for 30 seconds, then render the view.
  • '100ms' - Wait for 100 milliseconds, then render the view.

Default is 0, meaning immediately render the view.

TODO: ADD LINK TO TOUR OR FULL WIKI PAGE Read more About render flow.

Parameters :
Name Type Optional
duration DurationAnnotation No
Returns: void
onObserverFinalizedShowFor
setonObserverFinalizedShowFor(duration: DurationAnnotation)

(Optional) The duration for which the view should be rendered. When the duration passes, the view will be auto destroyed.

You can specify a number, which will be treated as milliseconds, or a string with the format of <number><ms | s | ms>. Numbers can be either integers or floats. For example:

  • 3000 - The view will be destroyed after 3 seconds.
  • '10s' - The view will be destroyed after 10 seconds.
  • '0.5m' - The view will be destroyed after 30 seconds.
  • '100ms' - The view will be destroyed after 100 milliseconds.

During the time the view is rendered, the context will be updated with a countdown object to facilitate any UI part used to indicate countdown to the user. The countdown will be exposed through the remaining property and the elapsed time through elapsed property in the view context and can both be accessed be declaring a let variable (e.g. let remaining = remaining). See countdownInterval for changing the updates interval.

When unspecified, the view will be destroyed immediately once the observer detects a call different to the intercepted ones.

TODO: ADD LINK TO TOUR OR FULL WIKI PAGE Read more About render flow.

Parameters :
Name Type Optional
duration DurationAnnotation No
Returns: void
onObserverFinalizedCountdownInterval
setonObserverFinalizedCountdownInterval(duration: DurationAnnotation | "animationFrames")

(Optional) The interval with which countdown updates should be made to the view's context before it auto destroys. The lower the value, the more updates will be made to the context, but the more resources your directive will consume.

You can specify a number, which will be treated as milliseconds, or a string with the format of <number><ms | s | ms>. Numbers can be either integers or floats. For example:

  • 3000 - 3 seconds between each update.
  • '10s' - 10 seconds between each update.
  • '0.5m' - 30 seconds between each update.
  • '100ms' - 100 milliseconds between each update.

You can also specify 'animationFrames' so the countdown gets updated each time the browser is working on animations.

When unspecified, the total duration of the countdown will be divided by DefaultCountdownUpdateCount to get a fixed interval which will make for DefaultCountdownUpdateCount countdown updates.

Parameters :
Name Type Optional
duration DurationAnnotation | "animationFrames" No
Returns: void
import { Observable       } from 'rxjs';
import { Directive, Input } from '@angular/core';

import { DurationAnnotation, ObserverName, ViewMode } from '../abstraction/types/general';
import { OnObserverContext                          } from '../abstraction/types/on-observer-context';
import { OnObserverBaseDirective                    } from '../abstraction/on-observer-base.directive';

/**
 * Documentation in {@link OnObserverFinalizedDirective.onObserverFinalized} to allow in-template tooltips.
 *
 * @export
 * @class OnObserverFinalizedDirective
 * @extends {OnObserverBaseDirective<T>}
 * @template T The type of value the observable emits.
 */
@Directive({
    // eslint-disable-next-line @angular-eslint/directive-selector
    selector: '[onObserverFinalized]'
})
export class OnObserverFinalizedDirective<T> extends OnObserverBaseDirective<T>
{
    protected selector                        = 'onObserverFinalized';
    protected renderOnCallsTo: ObserverName[] = ['error', 'complete'];
    
    /**
     * Renders the template when the specified observable is either completed or errored. In case of an error, the error will be
     * provided as the value in the context.
     * 
     * ## Features
     * 
     * #### View Context
     * Use the microsyntax `as` keyword to assign resolved values to a variable.
     * Use the microsyntax `let` keyword to assign the {@link OnObserverContext full context object} to a variable (e.g. `let context`).
     *  
     * #### Delayed rendering
     * Specify a value for {@link OnObserverBaseDirective.showAfter `showAfter`} to delay rendering.
     * 
     * #### Auto destroy
     * Specify {@link OnObserverBaseDirective.showFor `showFor`} to automatically destroy the view after a certain duration.
     * 
     * #### Countdown updates
     * When {@link OnObserverBaseDirective.showFor `showFor`} is specified, the view context will be updated with the time remaining until the view
     * is destroyed and the time elapsed since it was rendered. This allows giving the user feedback in a progress bar, a spinner, a textual timer
     * or any other UI component. 
     * 
     * Remaining is provided by the {@link OnObserverContext.remaining `remaining`} property. Elapsed time is provided by the {@link OnObserverContext.elapsed `elapsed`}
     * property. Access it by assigning a variable using `let`, like so:  
     * `let remaining = remaining`
     * 
     * #### Multi view mode
     * Specify {@link OnObserverBaseDirective.viewMode `viewMode = 'multiple'`} to enable rendering a new view for each intercepted call
     * instead of updating a single rendered view. This allows stacking logs, notification snackbars, or any other aggregation functionality.
     * Combined with {@link OnObserverBaseDirective.showFor `showFor`}, this is great for disappearing messages/notifications.
     * 
     * #### View index
     * In multi-view mode, the context will contain the index of the view, which can be used for calculations and styling.
     */
    @Input() public set onObserverFinalized(value: Observable<T>) { this.input.next(value); }

    /**
     * (Optional) The view mode the directive will operate in:  
     * `'single'` - A single view will be rendered on intercepted calls. If a view has already been rendered when a call is intercepted,
     * the existing view will be updated with data from the new call.
     * 
     * `'multiple'` - Every new intercepted call will render a new view with its own context and data encapsulated from the current call.
     * 
     * Default is `'single'`.
     */
    @Input() public set onObserverFinalizedViewMode         (viewMode: ViewMode          ) { this.viewMode          = viewMode; }
    /**
     * (Optional) The duration for which the directive should wait before rendering the view once an intercepted call is made.
     * 
     * You can specify a number, which will be treated as milliseconds, or a string with the format of `<number><ms | s | ms>`.
     * Numbers can be either integers or floats.
     * For example:
     * - `3000` - Wait for 3 seconds, then render the view.
     * - `'10s'` - Wait for 10 seconds, then render the view.
     * - `'0.5m'` - Wait for 30 seconds, then render the view.
     * - `'100ms'` - Wait for 100 milliseconds, then render the view.
     * 
     * Default is `0`, meaning immediately render the view.
     *
     * TODO: ADD LINK TO TOUR OR FULL WIKI PAGE
     * Read more {@link OnObserverBaseDirective About render flow}.
     **/
    @Input() public set onObserverFinalizedShowAfter        (duration: DurationAnnotation) { this.showAfter         = duration; }
    /**
     * (Optional) The duration for which the view should be rendered. When the duration passes, the view will be auto destroyed.
     *
     * You can specify a number, which will be treated as milliseconds, or a string with the format of `<number><ms | s | ms>`.
     * Numbers can be either integers or floats.
     * For example:
     * - `3000` - The view will be destroyed after 3 seconds.
     * - `'10s'` - The view will be destroyed after 10 seconds.
     * - `'0.5m'` - The view will be destroyed after 30 seconds.
     * - `'100ms'` - The view will be destroyed after 100 milliseconds.
     * 
     * During the time the view is rendered, the context will be updated with a countdown object to facilitate any UI part used to
     * indicate countdown to the user. The countdown will be exposed through the {@link OnObserverContext.remaining `remaining`}
     * property and the elapsed time through {@link OnObserverContext.elapsed `elapsed`} property in the view context and can both
     * be accessed be declaring a `let` variable (e.g. `let remaining = remaining`).
     * See {@link OnObserverBaseDirective.countdownInterval `countdownInterval`} for changing the updates interval.
     * 
     * When unspecified, the view will be destroyed immediately once the observer detects a call different to the intercepted ones.
     * 
     * TODO: ADD LINK TO TOUR OR FULL WIKI PAGE
     * Read more {@link OnObserverBaseDirective About render flow}.
     **/
    @Input() public set onObserverFinalizedShowFor          (duration: DurationAnnotation) { this.showFor           = duration; };
    /**
     * ### Only used when passing a value to {@link OnObserverBaseDirective.showFor `showFor`}.
     * 
     * (Optional) The interval with which countdown updates should be made to the view's context before it auto destroys.
     * The lower the value, the more updates will be made to the context, but the more resources your directive will consume.
     * 
     * You can specify a number, which will be treated as milliseconds, or a string with the format of `<number><ms | s | ms>`.
     * Numbers can be either integers or floats.
     * For example:
     * - `3000` - 3 seconds between each update.
     * - `'10s'` - 10 seconds between each update.
     * - `'0.5m'` - 30 seconds between each update.
     * - `'100ms'` - 100 milliseconds between each update.
     * 
     * You can also specify `'animationFrames'` so the countdown gets updated each time the browser is working on animations.
     * 
     * When unspecified, the total duration of the countdown will be divided by {@link DefaultCountdownUpdateCount `DefaultCountdownUpdateCount`}
     * to get a fixed interval which will make for {@link DefaultCountdownUpdateCount `DefaultCountdownUpdateCount`} countdown updates.
     */
    @Input() public set onObserverFinalizedCountdownInterval(duration: DurationAnnotation | 'animationFrames') { this.countdownInterval = duration; };
 
    static ngTemplateContextGuard<T>(directive: OnObserverFinalizedDirective<T>, context: unknown): context is OnObserverContext<T> { return true; }
}

results matching ""

    No results matching ""