class Component

extends ManagedObject

Component base class. Represents a managed object (see ManagedObject) that can be instantiated using a ‘preset’ constructor, i.e. the result of a call to the static with method.

When components are constructed, they are initialized with preset values for given properties, as well as preset bindings for properties which should automatically observe properties on the nearest parent component that (indirectly) references this component using the @managedBound decorator.

See also: Concepts > Components

Constructor

(): Component

.with() static

[1]. <TComponentCtor extends ComponentConstructor<Component>>(this: WithPresetType<TComponentCtor>, ...rest: PresetRestType<TComponentCtor>): TComponentCtor
[2]. <TComponentCtor extends ComponentConstructor<Component>>(this: WithPresetType<TComponentCtor>, presets: new () => any, ...rest: PresetRestType<TComponentCtor>): "INVALID_PRESET_ARGUMENT"
[3]. <TComponentCtor extends ComponentConstructor<Component>>(this: WithPresetType<...>, presets: PresetArgType<TComponentCtor>, ...rest: PresetRestType<TComponentCtor>): TComponentCtor

Create a new component constructor, which automatically initializes new instances with given properties, bindings, event handlers, and other values.

.preset() static

(presets: object, ...rest: unknown[]): Function

Add bindings, components, and event handlers from given presets to the current component constructor. This method is called by Component.with with the same arguments, and should not be called directly.

Component classes may override this method and return the result of super.preset(...), to add further presets and bindings using static methods on this component class.

Returns: A function (must be typed as Function even in derived classes) that is called by the constructor for each new instance, to apply remaining values from the preset object to the component object that is passed through this.

.presetBinding() static

<TComponent extends Component>(this: ComponentConstructor<TComponent>, propertyName: string, binding: Binding, applyBoundValue?: (this: TComponent, boundValue: any, oldValue?: any) => any): void

Add given binding to this component constructor, so that the property with given name on all instances will be updated with value(s) taken from the bound parent object. Optionally given function is used to set the property value using the updated (bound) value; otherwise, values are copied directly except for arrays, which are used to replace the values in a managed list (see ManagedList.replace).

Note: This method is used by preset when the argument to .with() includes a binding (see bind). This method should not be used directly unless passing a binding to .with() is not possible.

.presetBindingsFrom() static

(...constructors: ComponentConstructor<Component>[]): void

Inherit bindings from given component constructor(s) on this constructor. Inherited bindings will be bound to the same bound parent object as bindings passed to .with() directly, to update bound properties of (nested) child instances.

Note: This method must be used by a custom preset function if the preset component (may) have managed child objects (see @managedChild) of the given type and the constructor is not passed to super.preset(...) or presetBoundComponent(...). Alternatively, use the @component decorator on properties that refer to child components, which also presets bindings from a given component type.

.presetBoundComponent() static

(propertyName: string, ...constructors: ComponentConstructor<Component>[]): BoundComposition

Make this component the bound parent component for given child component type(s). When a component is assigned to given property, making it a child component, its bindings are bound to the current instance (i.e. the bound parent).

Returns: An object that represents the bound parent-child composition, and contains methods that can be used to fine-tune binding behavior.

Note: Given property must already be designated as a managed child property (see @managedChild decorator). Do not use this method on properties that are already decorated using the @component decorator.

.isPresetComponent() protected

(): boolean

Returns true if the class that this instance has been created from was itself created using Component.with somewhere along the prototype chain.

.delegateEvent() protected

(e: ManagedEvent, propertyName: string): boolean | void

Delegate given event by invoking a matching handler method, prefixing the event name with ‘on’. For example, events with name ‘Submit’ can be handled by a method named onSubmit(). The handler method is called with the same arguments as this method, and should return true if the event has been handled.

Additionally, if the event is of type ActionEvent, and if a handler method was not found, or if it did not return true, then the event is re-emitted on the component itself (also known as ‘propagated’) – allowing it to be handled by other components, usually by a parent component.

This method is used as a default handler for @delegateEvents. It can be overridden if events should be handled differently in specific cases. A return value other than true indicates that the event is neither handled by a method that returned true itself, nor propagated.

Note: In case the event name starts with a lowercase letter (a-z), the handler method should still include a capital letter (e.g. onDoSomething() for an event named ‘doSomething’). However, it is not recommended to use event names that start with lowercase letters.

.getParentComponent()

<TParent extends Component = Component>(ParentClass?: ComponentConstructor<TParent>): TParent

Returns the current parent component. If a class reference is specified, finds the nearest parent of given type. See @managedChild decorator.

.getBoundParentComponent()

<TParent extends Component>(ParentClass?: ComponentConstructor<TParent>): TParent

Returns the parent component that is the source of all bound values on this component. See @component decorator, and presetBoundComponent().

.emitAction()

(name: string, inner?: ManagedEvent, context?: ManagedObject): void

Emit an action event (see ActionEvent), to signal the result of a user action that should be handled by a parent component.

Note: The event is frozen using ManagedEvent.freeze() so that its properties cannot be modified even if the event is reused by parent component(s).

.propagateComponentEvent() deprecated

(name: string, inner?: ManagedEvent): void

Deprecated: in v3.1

NOTE: This method will be deprecated in favor of calling emit directly. Its name is confusing and after streamlining other parts it will serve no further purpose.

Create and emit an event with given name, a reference to this component, and an optional inner (propagated) event. The base implementation emits a plain ComponentEvent, but this method may be overridden to emit other events.

Note: If the component is already in the ‘destroyed’ state (see ManagedObject.managedState), then no event is emitted and this method returns immediately.

Note: This method is used by classes created using Component.with if an event handler is specified using the { ... onEventName: "OtherEvent" } pattern.

.managedId

number

Inherited from ManagedObject.managedId.

.managedState

ManagedState

Inherited from ManagedObject.managedState.

.getReferenceCount() protected

(): number

Inherited from ManagedObject.getReferenceCount.

.getManagedReferrers() protected

(): ManagedObject[]

Inherited from ManagedObject.getManagedReferrers.

.getManagedParent() protected

<TParent extends ManagedObject = ManagedObject>(ParentClass?: ManagedObjectConstructor<TParent>): TParent

Inherited from ManagedObject.getManagedParent.

.emit()

<TEvent extends ManagedEvent = ManagedEvent, TConstructorArgs extends any[] = any[]>(e: string | TEvent | (new (...args: TConstructorArgs) => TEvent), ...constructorArgs: TConstructorArgs): this

Inherited from ManagedObject.emit.

.emitChange()

(name?: string): void

Inherited from ManagedObject.emitChange.

.propagateChildEvents() protected deprecated

(...types: ((new (...args: any[]) => ManagedEvent) | ((e: ManagedEvent) => any))[]): this

Inherited from ManagedObject.propagateChildEvents.

.activateManagedAsync() protected

(): Promise<any>

Inherited from ManagedObject.activateManagedAsync.

.deactivateManagedAsync() protected

(): Promise<void>

Inherited from ManagedObject.deactivateManagedAsync.

.destroyManagedAsync() protected

(): Promise<void>

Inherited from ManagedObject.destroyManagedAsync.

.onManagedStateActivatingAsync() protected

(): Promise<void>

Inherited from ManagedObject.onManagedStateActivatingAsync.

.onManagedStateActiveAsync() protected

(): Promise<void>

Inherited from ManagedObject.onManagedStateActiveAsync.

.onManagedStateDeactivatingAsync() protected

(): Promise<void>

Inherited from ManagedObject.onManagedStateDeactivatingAsync.

.onManagedStateInactiveAsync() protected

(): Promise<void>

Inherited from ManagedObject.onManagedStateInactiveAsync.

.onManagedStateDestroyingAsync() protected

(): Promise<void>

Inherited from ManagedObject.onManagedStateDestroyingAsync.

---

Component.BoundComposition

Represents the relationship between a parent component class and a bound component class, to keep track of all bindings that are found on the bound component and its child components.

Constructor

(Composite: typeof Component, ...include: ComponentConstructor<Component>[]): BoundComposition

.getBindings()

(): Binding[]

Returns a list of all bindings that should be bound to the composite parent.

.limitBindings()

(...propertyNames: string[]): void

Remove all bindings that are to be bound to properties that are not included in the list of parameters; this causes any of those bindings on instances of the active component and its child component to be bound to the parent composite component instead.