Options
All
  • Public
  • Public/Protected
  • All
Menu

Class OnBuilder<E>

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

Index

Constructors

Properties

Methods

Constructors

Private constructor

  • Type parameters

    • E: HTMLElement = HTMLElement

    Returns OnBuilder<E>

Properties

Private _callback

_callback: any

Private Optional _clauses

_clauses?: any

Private _forceCapture

_forceCapture: any

Private _forcePreventDefault

_forcePreventDefault: any

Private _forceStopPropagation

_forceStopPropagation: any

Private _isShadow

_isShadow: any

Private Optional _selector

_selector?: any

Private Optional _target

_target?: any

Methods

Protected build

  • This API is dedicated for developer of Builders.

    Parameters

    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

    • Optional prefix: string

      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

  • Provide a fresh builder.

    Type parameters

    • E: HTMLElement

      the type of the Custom Element

    Parameters

    • Optional clauses: string

      the clauses separated by ,, it's optional only when the decorator API (i.e. OnBuilder.decorate) is used

    Returns OnBuilder<E>

Generated using TypeDoc