Options
All
  • Public
  • Public/Protected
  • All
Menu

The builder handles the addition and removal of DOM event listeners.

The DOM event listeners are simple callback functions, c.f. OnListener. They can be registered with OnBuilder.invoke. The registered event listeners are added on connectedCallback and removed on disconnectedCallback.

The DOM event listeners are invoked according to provided clauses. A clause is an event name to which an optional CSS selector can be associate. The pattern is EVENT_NAME <CSS_SELECTOR>. For instance, the clause click adds an event listener to the node of the Custom Element and, listen to click. About the optional CSS selector, it is way to add the event listener to a child node of the Custom Element. For instance, the clause click div button adds an event listener to the node which matches the CSS selector div button.

Alternatively, {@link OnBuilder.target} can also be used to specify the target. Moreover, it can also be used to listen to global events. For instance, the hashchange events dispatched on window.

The event listeners can be configured to be invoked on the capture phase with OnBuilder.capture.

Once the event is received, its method preventDefault() can be dynamically invoked with OnBuilder.prevent. The method stopPropagation() can also be dynamically invoked with OnBuilder.stop. Both methods can be dynamically invoked with OnBuilder.skip.

The event delegation (c.f. jQuery) can be configured with OnBuilder.delegate.

By default, the CSS selectors are applied to the Light DOM. However, they can be applied into the Shadow DOM with OnBuilder.shadow.

Finally, the builder can be registered using the method ElementBuilder.builder of the main builder (i.e. ElementBuilder). However, it can also be registered with the decorative style using the decorator OnBuilder.decorate.

Type parameters

  • E: HTMLElement = HTMLElement

    the type of the Custom Element

Hierarchy

  • OnBuilder

Implements

  • Builder<E>

Index

Constructors

Private constructor

  • new OnBuilder<E>(_clauses?: string, _target?: TargetSelector<E>, _callback?: OnListener<HTMLElement, Event, Element>, _forceCapture?: boolean, _forcePreventDefault?: boolean, _forceStopPropagation?: boolean, _selector?: string, _isShadow?: boolean): OnBuilder<E>
  • Type parameters

    • E: HTMLElement = HTMLElement

    Parameters

    • Optional _clauses: string
    • Optional _target: TargetSelector<E>
    • _callback: OnListener<HTMLElement, Event, Element> = noop
    • _forceCapture: boolean = false
    • _forcePreventDefault: boolean = false
    • _forceStopPropagation: boolean = false
    • Optional _selector: string
    • _isShadow: boolean = false

    Returns OnBuilder<E>

Methods

Protected build

  • build(Constructor: CustomElementConstructor<E>, hooks: HooksRegistration<E & { __ceb_on_handlers: any[] }>): void
  • This API is dedicated for developer of Builders.

    Parameters

    • Constructor: CustomElementConstructor<E>
    • hooks: HooksRegistration<E & { __ceb_on_handlers: any[] }>

    Returns void

capture

  • Force the listener execution on the capture phase.

    example
    import {ElementBuilder} from "@tmorin/ceb-elements-core"
    import {OnBuilder} from "@tmorin/ceb-elements-builders"
    class HelloWorld extends HTMLElement {
    connectedCallback() {
    this.innerHTML = `<button>Click here</button>`
    }
    }
    ElementBuilder.get(HelloWorld).builder(
    OnBuilder.get("click").capture()
    ).register()

    Returns OnBuilder<E>

decorate

  • decorate(prefix?: string): MethodDecorator
  • Decorate the listener method which is invoked according to the clauses.

    When the clause is not specified by OnBuilder.get, then the event name to listen to is discovered from the decorated method name. The pattern is <prefix><event-name-in-kebab-case>, where <prefix> is by default on.

    example

    Discovery of the event name

    import {ElementBuilder} from "@tmorin/ceb-elements-core"
    import {OnBuilder} from "@tmorin/ceb-elements-builders"
    @ElementBuilder.get<HelloWorld>().decorate()
    class HelloWorld extends HTMLElement {
    connectedCallback() {
    this.innerHTML = `<button>Click here</button>`
    }
    @OnBuilder.get().decorate()
    onClick(evt) {
    console.info(`Hello, World!`)
    }
    }
    example

    Discovery of the event name with a custom prefix

    import {ElementBuilder} from "@tmorin/ceb-elements-core"
    import {OnBuilder} from "@tmorin/ceb-elements-builders"
    @ElementBuilder.get<HelloWorld>().decorate()
    class HelloWorld extends HTMLElement {
    connectedCallback() {
    this.innerHTML = `<button>Click here</button>`
    }
    @OnBuilder.get().decorate("listen")
    listenClick(evt) {
    console.info(`Hello, World!`)
    }
    }
    example

    Skip the attribute name discovery

    import {ElementBuilder} from "@tmorin/ceb-elements-core"
    import {OnBuilder} from "@tmorin/ceb-elements-builders"
    @ElementBuilder.get<HelloWorld>().decorate()
    class HelloWorld extends HTMLElement {
    connectedCallback() {
    this.innerHTML = `<button>Click here</button>`
    }
    @OnBuilder.get("click").decorate("listen")
    foo(evt) {
    console.info(`Hello, World!`)
    }
    }

    Parameters

    • prefix: string = "on"

      the prefix used to discover the event name from the method name

    Returns MethodDecorator

delegate

  • Event delegation allows us to attach a single event listener, to a parent element, that will fire for all descendants matching a CSS selector, whether those descendants exist now or are added in the future. c.f. the jQuery doc

    example
    import {ElementBuilder} from "@tmorin/ceb-elements-core"
    import {OnBuilder} from "@tmorin/ceb-elements-builders"
    class HelloWorld extends HTMLElement {
    connectedCallback() {
    this.innerHTML = `<button>Click here</button>`
    }
    }
    ElementBuilder.get(HelloWorld).builder(
    OnBuilder.get("click").delegate("button")
    ).register()

    Parameters

    • selector: string

      the CSS selector

    Returns OnBuilder<E>

from

  • Override the default target, for instance to listen to global events, i.e. window.document or window.document.

    example
    import {ElementBuilder} from "@tmorin/ceb-elements-core"
    import {OnBuilder} from "@tmorin/ceb-elements-builders"
    class HelloWorld extends HTMLElement {
    }
    ElementBuilder.get(HelloWorld).builder(
    OnBuilder.get("hashchange").from(window)
    ).register()

    Parameters

    Returns OnBuilder<E>

invoke

  • Register the listener.

    example
    import {ElementBuilder} from "@tmorin/ceb-elements-core"
    import {OnBuilder} from "@tmorin/ceb-elements-builders"
    class HelloWorld extends HTMLElement {
    connectedCallback() {
    this.innerHTML = `<button>Click here</button>`
    }
    }
    ElementBuilder.get(HelloWorld).builder(
    OnBuilder.get("click")
    .invoke((el, data) => console.info(`Hello, World!`))
    ).register()

    Type parameters

    • V: Event = Event

      the type of the Event

    • T: Element = Element

      the type of the target

    Parameters

    Returns OnBuilder<E>

prevent

  • Force the usage of preventDefault() once the event is received.

    example
    import {ElementBuilder} from "@tmorin/ceb-elements-core"
    import {OnBuilder} from "@tmorin/ceb-elements-builders"
    class HelloWorld extends HTMLElement {
    connectedCallback() {
    this.innerHTML = `<button>Click here</button>`
    }
    }
    ElementBuilder.get(HelloWorld).builder(
    OnBuilder.get("click").prevent()
    ).register()

    Returns OnBuilder<E>

shadow

  • By default, the selection of the target element is done in the light DOM. This option forces the selection into the shadow DOM.

    example
    import {ElementBuilder} from "@tmorin/ceb-elements-core"
    import {OnBuilder} from "@tmorin/ceb-elements-builders"
    class HelloWorld extends HTMLElement {
    connectedCallback() {
    this.attachShadow({mode: "open"})
    this.shadowRoot.innerHTML = `<button>Click here</button>`
    }
    }
    ElementBuilder.get(HelloWorld).builder(
    OnBuilder.get("click button").shadow()
    ).register()

    Returns OnBuilder<E>

skip

  • Apply .prevent() and .stop() at the same time.

    example
    import {ElementBuilder} from "@tmorin/ceb-elements-core"
    import {OnBuilder} from "@tmorin/ceb-elements-builders"
    class HelloWorld extends HTMLElement {
    connectedCallback() {
    this.innerHTML = `<button>Click here</button>`
    }
    }
    ElementBuilder.get(HelloWorld).builder(
    OnBuilder.get("click").skip()
    ).register()

    Returns OnBuilder<E>

stop

  • Force the usage of stopPropagation() once the event is received.

    example
    import {ElementBuilder} from "@tmorin/ceb-elements-core"
    import {OnBuilder} from "@tmorin/ceb-elements-builders"
    class HelloWorld extends HTMLElement {
    connectedCallback() {
    this.innerHTML = `<button>Click here</button>`
    }
    }
    ElementBuilder.get(HelloWorld).builder(
    OnBuilder.get("click").stop()
    ).register()

    Returns OnBuilder<E>

Static get

Generated using TypeDoc