1. Home
  2. Classes
  3. NexusHoratio.widget.Widget

new Widget( instanceName, element )

Description

Base class for rendering widgets.

Subclasses should NOT override methods here, except for constructor(). Instead they should register listeners for appropriate events.

Generally, methods will fire two event verbs. The first, in present tense, will instruct what should happen (build, destroy, etc). The second, in past tense, will describe what should have happened (built, destroyed, etc). Typically, subclasses will act upon the present tense, and users of the class may act upon the past tense.

Methods should generally be able to be chained.

If a variable holding a widget is set to a new value, the previous widget should be explicitly destroyed.

When a Widget is instantiated, it should only create a container of the requested type (done in this base class). And install any widget styles it needs in order to function. The container property can then be placed into the DOM.

If a Widget needs specific CSS to function, that CSS should be shared across all instances of the Widget by using the same values in a call to installStyle(). Anything used for presentation should include the Widget's id as part of the style's id.

The build method will fire build/built events. Subclasses then populate the container with HTML as appropriate. Widgets should generally be designed to not update the internal HTML until the event is received.

The destroy method will fire destroy/destroyed events and also clear the innerHTML of the container. Subclasses are responsible for any internal cleanup, such as nested Widgets.

The verify method will fire verify/verified events. Subclasses can handle these to validate any internal structures they need. For example, Widgets that have ARIA support can ensure appropriate attributes are in place. If a Widget fails, it should throw an Error with a detailed cause.

Parameters
Name Type Description
instanceName string

Name for this instance.
element string

Type of element to use for the container.
Details

lib/widget.js, line 108

Members

<static> classHidden :string

Details
string

lib/widget.js, line 133

container :external:Element

Details
external:Element

lib/widget.js, line 138

id :string

Details
string

lib/widget.js, line 143

logger :NexusHoratio.base.Logger

Details
NexusHoratio.base.Logger

lib/widget.js, line 148

name :string

Details
string

lib/widget.js, line 153

visible :boolean

Details
boolean

lib/widget.js, line 158

Methods

build() → {NexusHoratio.widget.Widget}

Description

Materialize the contents into the container.

Each time this is called, the Widget should repopulate the contents.

Returns

This instance, for chaining.

Fires
Details

lib/widget.js, line 170

destroy() → {NexusHoratio.widget.Widget}

Description

Tears down internals. E.g., any Widget that has other Widgets should call their destroy() method as well.

Returns

This instance, for chaining.

Fires
Details

lib/widget.js, line 184

show() → {NexusHoratio.widget.Widget}

Description

Shows the Widget by removing a CSS class.

Returns

This instance, for chaining.

Fires
Details

lib/widget.js, line 197

hide() → {NexusHoratio.widget.Widget}

Description

Hides the Widget by adding a CSS class.

Returns

This instance, for chaining.

Fires
Details

lib/widget.js, line 212

verify() → {NexusHoratio.widget.Widget}

Description

Verifies a Widget's internal state.

For example, a Widget may use this to enforce certain ARIA criteria.

Returns

This instance, for chaining.

Fires
Details

lib/widget.js, line 228

clear()

Description

Clears the container element.

Details

true

lib/widget.js, line 239

on( eventType, func ) → {NexusHoratio.widget.Widget}

Description

Attach a function to an eventType.

Parameters
Name Type Description
eventType string

Event type to connect with.
func NexusHoratio.base.Dispatcher~Handler

Single argument function to call.
Returns

This instance, for chaining.

Details

lib/widget.js, line 251

off( eventType, func ) → {NexusHoratio.widget.Widget}

Description

Remove all instances of a function registered to an eventType.

Parameters
Name Type Description
eventType string

Event type to disconnect from.
func NexusHoratio.base.Dispatcher~Handler

Function to remove.
Returns

This instance, for chaining.

Details

lib/widget.js, line 263

attrText( attr, value ) → {NexusHoratio.widget.Widget}

Description

Helper that sets an attribute to value.

If value is null, the attribute is removed.

Parameters
Name Type Attributes Description
attr string

Name of the attribute.
value string <nullable>

Value to assign.
Returns

This instance, for chaining.

Examples
w.attrText('aria-label', 'Information about the application.')
Details

lib/widget.js, line 278

attrElements( attr, ...values ) → {NexusHoratio.widget.Widget}

Description

Helper that sets an attribute to space separated Element ids.

This will collect the appropriate id from each value passed then assign that collection to the attribute. If any value is null, the everything up to that point will be reset. If the collection ends up being empty (e.g., no values were passed or the last was null), the attribute will be removed.

Parameters
Name Type Attributes Description
attr string

Name of the attribute.
values NexusHoratio.widget~Content <nullable>
<repeatable>

Value to assign.
Returns

This instance, for chaining.

Details

lib/widget.js, line 300

installStyle( id, rules ) → {external:HTMLStyleElement}

Description

Install a style if not already present.

It will NOT overwrite an existing one.

Parameters
Name Type Description
id string

Base to use for the style id.
rules Array.<string>

CSS rules in 'selector { declarations }'.
Returns

Resulting style element.

Details

lib/widget.js, line 333

Events

build

Details

lib/widget.js, line 357

built

Details

lib/widget.js, line 360

verify

Details

lib/widget.js, line 363

verified

Details

lib/widget.js, line 366

destroy

Details

lib/widget.js, line 369

destroyed

Details

lib/widget.js, line 372

show

Details

lib/widget.js, line 375

showed

Details

lib/widget.js, line 378

hide

Details

lib/widget.js, line 381

hidden

Details

lib/widget.js, line 384