Events Reference

Events can be published, subscribed, or created by an custom service, component model, or component.

Publishing Events

Events can be published by calling the .publish method on the event object.

Services

Events are accessed in services through the messages property.

export default class CustomService extends ServiceBase {
    customIdentify() {
        // ... run a custom identify here.
        this.messages.events.tasks.identified.publish(someFeatures);
    }
}

Component Models

Events are accessed in component models through the messages property.

export default class ExampleComponentModel extends ComponentModelBase {
    customIdentify() {
        // ... run a custom identify here.
        this.messages.events.tasks.identified.publish(someFeatures);
    }
}

Components

Events in components are accessed through the UIContext.

export default function ExampleComponent(
    props: LayoutElementProperties<ExampleComponentModel>
) {
    const { events } = useContext(UIContext);

    const customIdentify = () => {
        // ... run a custom identify here.
        this.messages.events.tasks.identified.publish(someFeatures);
    };

    return (
        <LayoutElement {...props}>
            <p>Hello World</p>
        </LayoutElement>
    );
}

Subscribing to Events

Events can be subscribed to by calling the .subscribe method on the event object.

Important

It is vital that the event handles are cleaned up when the object is cleaned up, otherwise dangling references can occur.

Services

Events are accessed in services through the messages property.

export default class CustomService extends ServiceBase {
    handles: IHandle[] = [];

    protected async _onInitialize(): Promise<void> {
        await super._onInitialize();
        this.handles.push(
            this.messages.events.ui.activated.subscribe(
                (id: string) => {
                    console.log(`Component '${id}' activated.`);
                }
            )
        );
    }

    protected async _onDestroy(): Promise<void> {
        await super._onDestroy();
        this.handles.forEach((handle) => handle.remove());
    }
}

Component Models

Events are accessed in component models through the messages property.

export default class ExampleComponentModel extends ComponentModelBase {
    handles: IHandle[] = [];

    protected async _onInitialize(): Promise<void> {
        await super._onInitialize();
        this.handles.push(
            this.messages.events.ui.activated.subscribe(
                (id: string) => {
                    console.log(`Component '${id}' activated.`);
                }
            )
        );
    }

    protected async _onDestroy(): Promise<void> {
        await super._onDestroy();
        this.handles.forEach((handle) => handle.remove());
    }
}

Components

Events in components are accessed through the UIContext.

tip

If you need to subscribe to events in a component, it's best practice to use the component hooks instead of a useEffect, as the component hooks will automatically clean up the event handle.

export default function ExampleComponent(
    props: LayoutElementProperties<ExampleComponentModel>
) {
    const { events } = useContext(UIContext);

    useSubscribe(events.ui.activated, (id: string) => {
        console.log(`Component '${id}' activated.`);
    });

    return (
        <LayoutElement {...props}>
            <p>Hello World</p>
        </LayoutElement>
    );
}

Creating Custom Events

Creating custom events is as simple as referencing the custom event by name and publishing or subscribing to it. This is because the logic of creating an event is abstracted away; if an event is referenced in a publish or subscribe call that doesn't exist yet, it will be automatically created.

When the service calls the this.messages.events("my.custom-event"), this creates the event if it has not already been created. It can then be immediately subscribed to. Likewise, if the event has not been created, it will be when this.messages.event<string>("my-custom-event").publish(...) is called.

export default class CustomService extends ServiceBase {
    handles: IHandle[] = [];

    publishCustomEvent() {
        this.messages
            .event<string>("my-custom-event")
            .publish("some argument");
    }

    protected async _onInitialize(): Promise<void> {
        await super._onInitialize();
        this.handles.push(
            this.messages
                .event<string>("my-custom-event")
                .subscribe((someArg: string) => {
                    console.log(
                        `Event published with arg: '${someArg}'`
                    );
                })
        );
    }

    protected async _onDestroy(): Promise<void> {
        await super._onDestroy();
        this.handles.forEach((handle) => handle.remove());
    }
}

Event Arguments

Events optionally take a type argument, which represents the object associated with the event consumed by the subscriber. This can be a simple or complex object.

this.messages
    .event<string>("my-custom-event")
    .publish("Some String Arg")

this.messages
    .event<string>("my-custom-event")
    .subscribe((someArg: string) => { ... })

this.messages
    .event<CustomType>("another-custom-event")
    .publish(new CustomType("param"))