Class HandlebarsApplication

The mixed application class augmented with Handlebars template rendering behavior.

Hierarchy (View Summary)

Properties

options position tabGroups _appId _maxZ BASE_APPLICATION DEFAULT_OPTIONS emittedEvents PARTS RENDER_STATES TABS

Accessors

classList element form hasFrame id minimized parts rendered state title window

Methods

_awaitTransition _configureRenderOptions _doEvent _preRender _tearDown addEventListener bringToFront changeTab close dispatchEvent maximize minimize removeEventListener render setPosition submit toggleControls _attachFrameListeners _attachPartListeners _canRender _configureRenderParts _createContextMenu _getHeaderControls _getTabsConfig _headerControlButtons _initializeApplicationOptions _insertElement _onChangeForm _onClickAction _onClickTab _onClose _onFirstRender _onPosition _onRender _onSubmitForm _postRender _preClose _preFirstRender _prepareContext _preparePartContext _prepareTabs _prePosition _preSyncPartState _removeElement _renderFrame _renderHeaderControl _renderHTML _replaceHTML _syncPartState _updateFrame _updatePosition inheritanceChain parseCSSDimension waitForImages

Properties

options

options: Readonly<ApplicationConfiguration>

Application instance configuration options.

position

position: ApplicationPosition = ...

The current position of the application with respect to the window.document.body.

tabGroups

tabGroups: Record<string, null | string> = ...

If this Application uses tabbed navigation groups, this mapping is updated whenever the changeTab method is called. Reports the active tab for each group, with a value of null indicating no tab is active. Subclasses may override this property to define default tabs for each group.

Static Internal_appId

_appId: number = 0

An incrementing integer Application ID.

Static Internal_maxZ

_maxZ: number = ...

The current maximum z-index of any displayed Application.

StaticBASE_APPLICATION

BASE_APPLICATION: typeof ApplicationV2 = ApplicationV2

Designates which upstream Application class in this class' inheritance chain is the base application. Any DEFAULT_OPTIONS of super-classes further upstream of the BASE_APPLICATION are ignored. Hook events for super-classes further upstream of the BASE_APPLICATION are not dispatched.

StaticDEFAULT_OPTIONS

DEFAULT_OPTIONS: Configuration = ...

The default configuration options which are assigned to every instance of this Application class.

StaticemittedEvents

emittedEvents: readonly ["render", "close", "position"] = ...

StaticPARTS

PARTS: Record<string, HandlebarsTemplatePart> = {}

Configure a registry of template parts which are supported for this application for partial rendering.

StaticRENDER_STATES

RENDER_STATES: Record<string, number> = ...

The sequence of rendering states that describe the Application life-cycle.

StaticTABS

TABS: Record<string, ApplicationTabsConfiguration> = {}

Configuration of application tabs, with an entry per tab group.

Accessors

classList

  • get classList(): DOMTokenList

    The CSS class list of this Application instance

    Returns DOMTokenList

element

  • get element(): HTMLElement

    The HTMLElement which renders this Application into the DOM.

    Returns HTMLElement

form

  • get form(): null | HTMLFormElement

    Does this Application have a top-level form element?

    Returns null | HTMLFormElement

hasFrame

  • get hasFrame(): boolean

    Does this Application instance render within an outer window frame?

    Returns boolean

id

  • get id(): string

    The HTML element ID of this Application instance. This provides a readonly view into the internal ID used by this application. This getter should not be overridden by subclasses, which should instead configure the ID in DEFAULT_OPTIONS or by defining a uniqueId during _initializeApplicationOptions.

    Returns string

minimized

  • get minimized(): boolean

    Is this Application instance currently minimized?

    Returns boolean

parts

  • get parts(): Record<string, HTMLElement>

    A record of all rendered template parts.

    Returns Record<string, HTMLElement>

rendered

  • get rendered(): boolean

    Is this Application instance currently rendered?

    Returns boolean

state

  • get state(): number

    The current render state of the Application.

    Returns number

title

  • get title(): string

    A convenience reference to the title of the Application window.

    Returns string

window

  • get window(): {
        close: HTMLButtonElement;
        content: HTMLElement;
        controls: HTMLButtonElement;
        controlsDropdown: HTMLDivElement;
        header: HTMLElement;
        icon: HTMLElement;
        onDrag: Function;
        onResize: Function;
        pointerMoveThrottle: boolean;
        pointerStartPosition: ApplicationPosition;
        resize: HTMLElement;
        title: HTMLHeadingElement;
    }

    Convenience references to window header elements.

    Returns {
        close: HTMLButtonElement;
        content: HTMLElement;
        controls: HTMLButtonElement;
        controlsDropdown: HTMLDivElement;
        header: HTMLElement;
        icon: HTMLElement;
        onDrag: Function;
        onResize: Function;
        pointerMoveThrottle: boolean;
        pointerStartPosition: ApplicationPosition;
        resize: HTMLElement;
        title: HTMLHeadingElement;
    }

Methods

_awaitTransition

  • _awaitTransition(element: HTMLElement, timeout: number): Promise<void>
    Internal

    Wait for a CSS transition to complete for an element.

    Parameters

    • element: HTMLElement

      The element which is transitioning

    • timeout: number

      A timeout in milliseconds in case the transitionend event does not occur

    Returns Promise<void>

_configureRenderOptions

  • _configureRenderOptions(options: any): void

    Parameters

    • options: any

    Returns void

    Inherit Doc

_doEvent

  • _doEvent(
        handler: Function,
        options?: {
            async?: boolean;
            debugText?: string;
            eventName?: string;
            handlerArgs?: any[];
            hookArgs?: any[];
            hookName?: string;
            hookResponse?: boolean;
            parentClassHooks?: boolean;
        },
    ): void
    | Promise<void>
    Internal

    Perform an event in the application life-cycle. Await an internal life-cycle method defined by the class. Optionally dispatch an event for any registered listeners.

    Parameters

    • handler: Function

      A handler function to call

    • options: {
          async?: boolean;
          debugText?: string;
          eventName?: string;
          handlerArgs?: any[];
          hookArgs?: any[];
          hookName?: string;
          hookResponse?: boolean;
          parentClassHooks?: boolean;
      } = {}

      Options which configure event handling

      • Optionalasync?: boolean

        Await the result of the handler function?

      • OptionaldebugText?: string

        Debugging text to log for the event

      • OptionaleventName?: string

        An event name to dispatch for registered listeners

      • OptionalhandlerArgs?: any[]

        Arguments passed to the handler function

      • OptionalhookArgs?: any[]

        Arguments passed to the requested hook function

      • OptionalhookName?: string

        A hook name to dispatch for this and all parent classes

      • OptionalhookResponse?: boolean

        Add the handler response to hookArgs

      • OptionalparentClassHooks?: boolean

        Call hooks for parent classes in the inheritance chain?

    Returns void | Promise<void>

    A promise which resoles once the handler is complete if async is true

_preRender

  • _preRender(context: any, options: any): Promise<void>

    Parameters

    • context: any
    • options: any

    Returns Promise<void>

    Inherit Doc

_tearDown

  • _tearDown(options: any): void

    Parameters

    • options: any

    Returns void

    Inherit Doc

addEventListener

  • addEventListener(
        type: string,
        listener: EmittedEventListener,
        options?: { once?: boolean },
    ): void

    Add a new event listener for a certain type of event.

    Parameters

    • type: string

      The type of event being registered for

    • listener: EmittedEventListener

      The listener function called when the event occurs

    • Optionaloptions: { once?: boolean } = {}

      Options which configure the event listener

      • Optionalonce?: boolean

        Should the event only be responded to once and then removed

    Returns void

    See

    https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener

bringToFront

  • bringToFront(): void

    Bring this Application window to the front of the rendering stack by increasing its z-index. Once ApplicationV1 is deprecated we should switch from _maxZ to ApplicationV2#maxZ We should also eliminate ui.activeWindow in favor of only ApplicationV2#frontApp

    Returns void

changeTab

  • changeTab(
        tab: string,
        group: string,
        options?: {
            event?: Event;
            force?: boolean;
            navElement?: HTMLElement;
            updatePosition?: boolean;
        },
    ): void

    Change the active tab within a tab group in this Application instance.

    Parameters

    • tab: string

      The name of the tab which should become active

    • group: string

      The name of the tab group which defines the set of tabs

    • Optionaloptions: {
          event?: Event;
          force?: boolean;
          navElement?: HTMLElement;
          updatePosition?: boolean;
      } = {}

      Additional options which affect tab navigation

      • Optionalevent?: Event

        An interaction event which caused the tab change, if any

      • Optionalforce?: boolean

        Force changing the tab even if the new tab is already active

      • OptionalnavElement?: HTMLElement

        An explicit navigation element being modified

      • OptionalupdatePosition?: boolean

        Update application position after changing the tab?

    Returns void

close

dispatchEvent

maximize

  • maximize(): Promise<void>

    Restore the Application to its original dimensions.

    Returns Promise<void>

minimize

  • minimize(): Promise<void>

    Minimize the Application, collapsing it to a minimal header.

    Returns Promise<void>

removeEventListener

render

  • render(
        options?: boolean | HandlebarsRenderOptions,
        _options?: HandlebarsRenderOptions,
    ): Promise<HandlebarsApplication>

    Render the Application, creating its HTMLElement and replacing its innerHTML. Add it to the DOM if it is not currently rendered and rendering is forced. Otherwise, re-render its contents.

    Parameters

    • Optionaloptions: boolean | HandlebarsRenderOptions = {}

      Options which configure application rendering behavior. A boolean is interpreted as the "force" option.

    • Optional_options: HandlebarsRenderOptions = {}

      Legacy options for backwards-compatibility with the original ApplicationV1#render signature.

    Returns Promise<HandlebarsApplication>

    A Promise which resolves to the rendered Application instance

setPosition

submit

  • submit(submitOptions?: object): Promise<any>

    Programmatically submit an ApplicationV2 instance which implements a single top-level form.

    Parameters

    • OptionalsubmitOptions: object = {}

      Arbitrary options which are supported by and provided to the configured form submission handler.

    Returns Promise<any>

    A promise that resolves to the returned result of the form submission handler, if any.

toggleControls

  • toggleControls(
        expanded?: boolean,
        options?: { animate?: boolean },
    ): Promise<void>

    Toggle display of the Application controls menu. Only applicable to window Applications.

    Parameters

    • Optionalexpanded: boolean

      Set the controls visibility to a specific state. Otherwise, the visible state is toggled from its current value

    • Optionaloptions: { animate?: boolean } = {}

      Options to configure the toggling behavior.

      • Optionalanimate?: boolean

        Animate the controls toggling.

    Returns Promise<void>

    A Promise which resolves once the control expansion animation is complete

Protected_attachFrameListeners

  • _attachFrameListeners(): void
    Protected

    Attach event listeners to the Application frame.

    Returns void

Protected_attachPartListeners

  • _attachPartListeners(
        partId: string,
        htmlElement: HTMLElement,
        options: ApplicationRenderOptions,
    ): void
    Protected

    Attach event listeners to rendered template parts.

    Parameters

    • partId: string

      The id of the part being rendered

    • htmlElement: HTMLElement

      The rendered HTML element for the part

    • options: ApplicationRenderOptions

      Rendering options passed to the render method

    Returns void

Protected_canRender

  • _canRender(options: HandlebarsRenderOptions): false | void
    Protected

    Test whether this Application is allowed to be rendered.

    Parameters

    Returns false | void

    Return false to prevent rendering

    Throws

    An Error to display a warning message

Protected_configureRenderParts

Protected_createContextMenu

  • _createContextMenu(
        handler: () => ContextMenuEntry[],
        selector: string,
        options?: {
            container?: HTMLElement;
            hookName?: string;
            parentClassHooks?: boolean;
        },
    ): null
    | ContextMenu
    Protected

    Create a ContextMenu instance used in this Application.

    Parameters

    • handler: () => ContextMenuEntry[]

      A handler function that provides initial context options

    • selector: string

      A CSS selector to which the ContextMenu will be bound

    • Optionaloptions: { container?: HTMLElement; hookName?: string; parentClassHooks?: boolean } = {}

      Additional options which affect ContextMenu construction

      • Optionalcontainer?: HTMLElement

        A parent HTMLElement which contains the selector target

      • OptionalhookName?: string

        The hook name

      • OptionalparentClassHooks?: boolean

        Whether to call hooks for the parent classes in the inheritance chain.

    Returns null | ContextMenu

    A created ContextMenu or null if no menu items were defined

Protected_getHeaderControls

Protected_getTabsConfig

Protected_headerControlButtons

  • _headerControlButtons(): Generator<ApplicationHeaderControlsEntry, any, any>
    Protected

    Iterate over header control buttons, filtering for controls which are visible for the current client.

    Returns Generator<ApplicationHeaderControlsEntry, any, any>

    Yields

Protected_initializeApplicationOptions

  • _initializeApplicationOptions(
        options: Partial<ApplicationConfiguration>,
    ): ApplicationConfiguration
    Protected

    Initialize configuration options for the Application instance. The default behavior of this method is to intelligently merge options for each class with those of their parents.

    • Array-based options are concatenated
    • Inner objects are merged
    • Otherwise, properties in the subclass replace those defined by a parent

    Parameters

    Returns ApplicationConfiguration

    Configured options for the application instance

Protected_insertElement

  • _insertElement(element: HTMLElement): void
    Protected

    Insert the application HTML element into the DOM. Subclasses may override this method to customize how the application is inserted.

    Parameters

    • element: HTMLElement

      The element to insert

    Returns void

Protected_onChangeForm

  • _onChangeForm(formConfig: ApplicationFormConfiguration, event: Event): void
    Protected

    Handle changes to an input element within the form.

    Parameters

    • formConfig: ApplicationFormConfiguration

      The form configuration for which this handler is bound

    • event: Event

      An input change event within the form

    Returns void

Protected_onClickAction

  • _onClickAction(event: PointerEvent, target: HTMLElement): void
    Protected

    A generic event handler for action clicks which can be extended by subclasses. Action handlers defined in DEFAULT_OPTIONS are called first. This method is only called for actions which have no defined handler.

    Parameters

    • event: PointerEvent

      The originating click event

    • target: HTMLElement

      The capturing HTML element which defined a [data-action]

    Returns void

Protected_onClickTab

  • _onClickTab(event: PointerEvent): void
    Protected

    Handle click events on a tab within the Application.

    Parameters

    • event: PointerEvent

    Returns void

Protected_onClose

  • _onClose(options: HandlebarsRenderOptions): void
    Protected

    Actions performed after closing the Application. Post-close steps are not awaited by the close process.

    Parameters

    Returns void

Protected_onFirstRender

Protected_onPosition

  • _onPosition(position: ApplicationPosition): void
    Protected

    Actions performed after the Application is re-positioned.

    Parameters

    Returns void

Protected_onRender

Protected_onSubmitForm

  • _onSubmitForm(
        formConfig: ApplicationFormConfiguration,
        event: Event | SubmitEvent,
    ): Promise<void>
    Protected

    Handle submission for an Application which uses the form element.

    Parameters

    • formConfig: ApplicationFormConfiguration

      The form configuration for which this handler is bound

    • event: Event | SubmitEvent

      The form submission event

    Returns Promise<void>

Protected_postRender

Protected_preClose

  • _preClose(options: HandlebarsRenderOptions): Promise<void>
    Protected

    Actions performed before closing the Application. Pre-close steps are awaited by the close process.

    Parameters

    Returns Promise<void>

Protected_preFirstRender

Protected_prepareContext

  • _prepareContext(
        options: HandlebarsRenderOptions,
    ): Promise<ApplicationRenderContext>
    Protected

    Prepare application rendering context data for a given render request. If exactly one tab group is configured for this application, it will be prepared automatically.

    Parameters

    Returns Promise<ApplicationRenderContext>

    Context data for the render operation

Protected_preparePartContext

  • _preparePartContext(
        partId: string,
        context: ApplicationRenderContext,
        options: HandlebarsRenderOptions,
    ): Promise<ApplicationRenderContext>
    Protected

    Prepare context that is specific to only a single rendered part.

    It is recommended to augment or mutate the shared context so that downstream methods like _onRender have visibility into the data that was used for rendering. It is acceptable to return a different context object rather than mutating the shared context at the expense of this transparency.

    Parameters

    • partId: string

      The part being rendered

    • context: ApplicationRenderContext

      Shared context provided by _prepareContext

    • options: HandlebarsRenderOptions

      Options which configure application rendering behavior

    Returns Promise<ApplicationRenderContext>

    Context data for a specific part

Protected_prepareTabs

  • _prepareTabs(group: string): Record<string, ApplicationTab>
    Protected

    Prepare application tab data for a single tab group.

    Parameters

    • group: string

      The ID of the tab group to prepare

    Returns Record<string, ApplicationTab>

Protected_prePosition

  • _prePosition(position: ApplicationPosition): void
    Protected

    Actions performed before the Application is re-positioned. Pre-position steps are not awaited because setPosition is synchronous.

    Parameters

    Returns void

Protected_preSyncPartState

  • _preSyncPartState(
        partId: string,
        newElement: HTMLElement,
        priorElement: HTMLElement,
        state: object,
    ): void
    Protected

    Prepare data used to synchronize the state of a template part.

    Parameters

    • partId: string

      The id of the part being rendered

    • newElement: HTMLElement

      The new rendered HTML element for the part

    • priorElement: HTMLElement

      The prior rendered HTML element for the part

    • state: object

      A state object which is used to synchronize after replacement

    Returns void

Protected_removeElement

  • _removeElement(element: HTMLElement): void
    Protected

    Remove the application HTML element from the DOM. Subclasses may override this method to customize how the application element is removed.

    Parameters

    • element: HTMLElement

      The element to be removed

    Returns void

Protected_renderFrame

  • _renderFrame(options: HandlebarsRenderOptions): Promise<HTMLElement>
    Protected

    Render the outer framing HTMLElement which wraps the inner HTML of the Application.

    Parameters

    Returns Promise<HTMLElement>

Protected_renderHeaderControl

Protected_renderHTML

  • _renderHTML(
        context: ApplicationRenderContext,
        options: HandlebarsRenderOptions,
    ): Promise<Record<string, HTMLElement>>
    Protected

    Render each configured application part using Handlebars templates.

    Parameters

    • context: ApplicationRenderContext

      Context data for the render operation

    • options: HandlebarsRenderOptions

      Options which configure application rendering behavior

    Returns Promise<Record<string, HTMLElement>>

    A single rendered HTMLElement for each requested part

Protected_replaceHTML

  • _replaceHTML(
        result: Record<string, HTMLElement>,
        content: HTMLElement,
        options: HandlebarsRenderOptions,
    ): void
    Protected

    Replace the HTML of the application with the result provided by Handlebars rendering.

    Parameters

    • result: Record<string, HTMLElement>

      The result from Handlebars template rendering

    • content: HTMLElement

      The content element into which the rendered result must be inserted

    • options: HandlebarsRenderOptions

      Options which configure application rendering behavior

    Returns void

Protected_syncPartState

  • _syncPartState(
        partId: string,
        newElement: HTMLElement,
        priorElement: HTMLElement,
        state: object,
    ): void
    Protected

    Synchronize the state of a template part after it has been rendered and replaced in the DOM.

    Parameters

    • partId: string

      The id of the part being rendered

    • newElement: HTMLElement

      The new rendered HTML element for the part

    • priorElement: HTMLElement

      The prior rendered HTML element for the part

    • state: object

      A state object which is used to synchronize after replacement

    Returns void

Protected_updateFrame

  • _updateFrame(options: HandlebarsRenderOptions): void
    Protected

    When the Application is rendered, optionally update aspects of the window frame.

    Parameters

    Returns void

Protected_updatePosition

  • _updatePosition(position: ApplicationPosition): ApplicationPosition
    Protected

    Translate a requested application position updated into a resolved allowed position for the Application. Subclasses may override this method to implement more advanced positioning behavior.

    Parameters

    Returns ApplicationPosition

    Resolved Application positioning data

StaticinheritanceChain

  • inheritanceChain(): Generator<typeof ApplicationV2, void, unknown>

    Iterate over the inheritance chain of this Application. The chain includes this Application itself and all parents until the base application is encountered.

    Returns Generator<typeof ApplicationV2, void, unknown>

    See

    ApplicationV2.BASE_APPLICATION

    Yields

StaticparseCSSDimension

  • parseCSSDimension(style: string, parentDimension: number): number | void

    Parse a CSS style rule into a number of pixels which apply to that dimension.

    Parameters

    • style: string

      The CSS style rule

    • parentDimension: number

      The relevant dimension of the parent element

    Returns number | void

    The parsed style dimension in pixels

StaticwaitForImages

  • waitForImages(element: HTMLElement): Promise<void>

    Wait for any images in the given element to load.

    Parameters

    • element: HTMLElement

      The element.

    Returns Promise<void>

Settings

Member Visibility

On This Page

Properties
Accessors
Methods