Class: ContextControl

ContextControl(horizontalOffsetopt, verticalOffsetopt)

Simple implementation of an HTML DOM based context control. This class (lazily) creates a blank HTMLDivElement to hold the control's content, and applies class names corresponding to when the control is opened or closed. The control also repositions itself when the window is resized.

The first time a control is opened, the create event is fired. It is expected client code will listen for this event and populate the control's element with desired content. The control's element can be obtained in such a listener via event.target.getControlElement().

Upon being opened, this class will begin listening for window resize events and position itself upon receiving them. Upon being closed, this class will stop listening for resize events.

Of note, this class only sets element class names, and a limited set of CSS properties; most styling should be handled by dedicated stylesheets. The following is a baseline stylesheet that uses the default class names:

.context-control {
    position: absolute;
    opacity: 0;
    color: black;
    background-color: white;
    border: 1px solid black;
    padding: .5em;
}

.context-control.context-control-opened {
    opacity: 1;
    transition: opacity .5s;
}

.context-control.context-control-closed {
    display: none;
}

Constructor

new ContextControl(horizontalOffsetopt, verticalOffsetopt)

Parameters:
Name Type Attributes Default Description
horizontalOffset number <optional>
 ContextControl.defaultHorizontalOffset

Horizontal offset with respect to offset element passed to ContextControl#open.
verticalOffset number <optional>
 ContextControl.defaultVerticalOffset

Vertical offset with respect to offset element passed to ContextControl#open.
Source:

Extends

Classes

OffsetCoordinates

Members

(static) contextElementClassName :string

Class name assigned to ContextControl elements when they are first created. Default value is 'context-control'.

Type:
  • string
Source:

(static) defaultHorizontalOffset :number

Default horizontal offset in pixels. Default value is 10.

Type:
  • number
Source:

(static) defaultVerticalOffset :number

Default vertical offset in pixels. Default value is 10.

Type:
  • number
Source:

(static) dialogueClosedClassName :string

Class name added to ContextControl elements when ContextControl#close is called. Removed when ContextControl#open is called. Default value is 'context-control-closed'.

Type:
  • string
Source:

(static) dialogueOpenedClassName :string

Class name added to ContextControl elements when ContextControl#open is called. Removed when ContextControl#close is called. Default value is 'context-control-opened'.

Type:
  • string
Source:

(private, static, constant) EVENT_TYPE_CREATE :string

Name of the event fired the first time a ContextControl is opened. Value is 'create'.

Type:
  • string
Source:

(private) controlElement :HTMLDivElement

The underlying HTMLDivElement defining this control's content. Initially null; created/assigned the first time ContextControl#open is called.

Type:
  • HTMLDivElement
Source:

horizontalOffset :number

The offset in pixels to be applied to the left CSSStyleDeclaration of this control's element with respect to the current offset element (last passed to ContextControl#open).

Type:
  • number
Source:

(private) offsetElement :HTMLElement

Element relative to which this ContextControl#controlElement is to be positioned. Passed and stored on calls to ContextControl#open.

Type:
  • HTMLElement
Source:

verticalOffset :number

The offset in pixels to be applied to the top CSSStyleDeclaration of this control's element with respect to the current offset element (last passed to ContextControl#open).

Type:
  • number
Source:

Methods

(private, static) _getOffset(el, coordinates)

Recursive helper for ContextControl.getOffset.

Parameters:
Name Type Description
el HTMLElement

Current element.
coordinates ContextControl.OffsetCoordinates

Coordinates being processed.
Source:

(private, static) createControl() → {HTMLDivElement}

Creates an empty control element.

Source:
Returns:

An empty (detached) control element.

Type
HTMLDivElement

(private, static) getOffset(el) → {ContextControl.OffsetCoordinates}

Utility function for determining an element's absolute viewport offset.

Parameters:
Name Type Description
el HTMLElement

Element whose viewport offset is to be calculated.
Source:
Returns:

Coordinates of the given element's viewport offset.

Type
ContextControl.OffsetCoordinates

addEventListener(type, listener, useCaptureopt)

Adds the given listener for the given event type, provided it is not already registered for that type.

Parameters:
Name Type Attributes Default Description
type string

Event type for which the given listener is to be registered.
listener SimpleEventListener | function

Listener to register.
useCapture boolean <optional>
 false

Optional parameter added for consistency with the standard DOM EventTarget.addEventListener definition. If not Nothing, will print a warning on the console.
Inherited From:
Source:
Throws:

  • If type is not defined or is a zero-length string; if listener is not defined.

    Type
    ReferenceError

  • If type is not a string; if listener does not implement SimpleEventListener or is not a function.

    Type
    TypeError

close()

Closes this ContextControl. The ContextControl.dialogueOpenedClassName will be removed from this control's backing element, this ContextControl will remove itself as a listener for window resize events, and finally, the ContextControl.dialogueClosedClassName will be added to the backing element.

Source:

dispatchEvent(event)

Dispatches the given event to registered listeners. Listeners are called in the order they are added.

Parameters:
Name Type Description
event SimpleEventIntf

Event to dispatch.
Inherited From:
Source:
Throws:

  • If event is not defined.

    Type
    ReferenceError

  • If event does not implement SimpleEventIntf.

    Type
    TypeError

dispose()

Disposes this ContextControl by closing it and detaching the backing control element, if present.

Source:

getControlElement()

Returns this control's backing HTMLDivElement provided it has been opened and is not disposed, otherwise null.

Source:
Returns:

Backing HTMLDivElement provided this control has been opened and is not disposed.

handleEvent(event)

Implementation of DOM EventListener.

Parameters:
Name Type Description
event Event

Event being dispatched.
Source:

open(offsetElement)

Opens this ContextControl. If this is the first time the control is opened, the create event will be fired, where it is expected client code will populate the control with desired content. In any case, the ContextControl.dialogueClosedClassName class will be removed from the control element, it will be positioned relative to the given offsetElement, this ContextControl will add itself as a listener for window resize events, and finally, the ContextControl.dialogueOpenedClassName class will be added to the control element.

Parameters:
Name Type Description
offsetElement HTMLElement

Element relative to which this control's element is to be positioned.
Source:
Fires:
Throws:

If offsetElement is not defined.

Type
ReferenceError

position()

Positions this control. The left and top CSSStyleDeclaration properties will be set based upon the position of the current offset element (last passed to ContextControl#open) and the ContextControl#horizontalOffset and ContextControl#verticalOffset properties of this control.

Source:

removeEventListener(type, listener, useCaptureopt)

Removes the given listener for the given event type, provided it is currently registered for that type.

Parameters:
Name Type Attributes Default Description
type string

Event type for which the given listener is to be removed.
listener SimpleEventListener | function

Listener to be removed.
useCapture boolean <optional>
 false

Optional parameter added for consistency with the standard DOM EventTarget.removeEventListener definition. If not Nothing, will print a warning on the console.
Inherited From:
Source:
Throws:

  • If type is not defined or is a zero-length string.

    Type
    ReferenceError

  • If type is not a string.

    Type
    TypeError

Events

event:create

Fired the first time a ContextControl is opened. The target and currentTarget properties of the event are set to the ContextControl being opened. The control's backing element can be obtained via ContextControl#getControlElement.

Type:
Source: