Components API

#Component Class

Components are the primary building block for constructing CodeOnly applications. They encapsulate program logic, a DOM template and an optional a set of CSS styles.

Components can be used either in the templates of other components or mounted onto the document DOM to appear in a web page.

#create()

Ensures this component's DomTree has been created.

Calling this method does nothing if the DomTree is already created.

create(): void;

#created

Returns true if this component's DomTree has been created.

get created(): boolean;

#destroy()

Destroys this component's DomTree returning it to the constructed, but non-created state.

A destroyed component can be re-created by remounting it or by calling its create method.

destroy(): void;

#domTree

Gets the DomTree for this component, creating it if necessary.

get domTree(): DomTree;

#domTreeConstructor (static)

Gets the DomTreeConstructor for this component class.

The DomTreeConstructor is the constructor function used to create DomTree instances for this component class.

The first time this property is accessed, it calls the static onProvideDomTreeConstructor method to provide the instance.

static get domTreeConstructor(): DomTreeConstructor;

#invalid

Indicates if this component in invalid.

A component is invalid if it has been invalidated by a previous call to invalidate and hasn't yet be updated.

get invalid(): boolean;

#invalidate()

Invalidates this component, marking it as requiring a DOM update.

Does nothing if the component hasn't yet been created.

This method is bound to the component instance and can be used directly as the handler for an event listener to invalidate the component when an event is triggered.

invalidate(): void;

#isSingleRoot (static)

Returns true if every instance of this component class will only ever have a single root node.

static get isSingleRoot(): boolean;

#isSingleRoot

Returns true if this component instance is guaranteed to always only have a single root node.

get isSingleRoot(): boolean;

#listen()

Registers an event listener to be automatically added to an object when when the component is mounted, and removed when unmounted.

listen(target: object, event: string, handler?: Function): void;

target Any object that supports addEventListener and removeEventListener
event The event to listen to
handler The event handler to add. If not provided, the component's invalidate method is used.

#load()

Performs an async data load operation.

The callback function is an async function that performs an async data load. While in the callback, the loading property returns true.

If the callback throws an error, it will be captured to the loadError property.

Before calling and after returning from the callback, the component is invalidated so visual elements (eg: spinners) can be updated.

If the silent parameter is true the loading property isn't set and the component is only invalidated after returning from the callback.

load(callback: () => Promise<any>, silent?: boolean): Promise<any>;

callback The callback to perform the load operation
silent Whether to perform a silent update

#loadError

Gets the error object thrown during the last call to load.

get loadError(): Error | null;

Sets the error object associated with the current call to load.

set loadError(value: Error | null);

value The new error object

#loading

Indicates if the component is currently in an load operation.

get loading(): boolean;

#mount()

Mounts this component against an element in the document.

mount(el: Element | string): void;

el The element or an element selector that specifies where to mount the component

#mounted

Returns true if the component is currently mounted.

get mounted(): boolean;

#onMount()

Notifies a component that is has been mounted.

Override this method to receive the notification. External resources should be acquired when the component is mounted. (eg: adding event listeners to external objects)

onMount(): void;

#onProvideDomTreeConstructor() (static)

Provides the DomTreeConstructor to be used by this component class.

This method is called once per component class and should provide a constructor function that can create DomTree instances.

static onProvideDomTreeConstructor(): DomTreeConstructor;

#onProvideTemplate() (static)

Provides the template to be used by this component class.

This method is called once per component class and should provide the template to be compiled for this component class.

static onProvideTemplate(): {};

#onUnmount()

Notifies a component that is has been unmounted.

Override this method to receive the notification. External resources should be released when the component is unmounted. (eg: removing event listeners from external objects)

onUnmount(): void;

#rootNode

Returns the single root node of this component (if it is a single root node component).

get rootNode(): Node;

#rootNodes

Returns an array of root DOM nodes for this element, creating them if necessary.

get rootNodes(): Node[];

#setMounted()

Notifies the object it has been mounted or unmounted

setMounted(mounted: boolean): void;

mounted true if the object has been mounted, false if unmounted

#template (static)

The template to be used by this component class

static template: {};

#unlisten()

Removes an event listener previously registered with listen

unlisten(target: object, event: string, handler?: Function): void;

target Any object that supports addEventListener and removeEventListener
event The event being listened to
handler The event handler to remove. If not provided, the component's invalidate method is used.

#unmount()

Unmounts this component

unmount(): void;

#update()

Immediately updates this component's DOM elements - even if the component is not marked as invalid.

Does nothing if the component's DOM elements haven't been created.

If the component has been invalidated, returns it to the valid state.

This method is bound to the component instance and can be used directly as the handler for an event listener to update the component when an event is triggered.

update(): void;

#validate()

Updates this component if it has been marked as invalid by a previous call to invalidate.

validate(): void;