bajaux

Module: bajaux/lifecycle/WidgetManager

WidgetManager's job is to manage the lifecycle of widgets, from the initial
"what kind of widget do I need?" question through to the destruction of
the unneeded widget.

new (require("bajaux/lifecycle/WidgetManager"))(params)

Parameters:
Name Type Description
params object
Properties
Name Type Description
registry module:bajaux/registry/Registry

the registry
responsible for looking up Widget types
Since:
  • Niagara 4.10

Methods

buildContext(params)

This method functions as the "starting point" for a Widget build. It
receives the parameters as given by the user, and calculates a build
context to be used during the rest of the initialize/load/destroy
lifecycle.

Parameters:
Name Type Description
params module:bajaux/lifecycle/WidgetManager~BuildParams
Returns:
Type
Promise.<module:bajaux/lifecycle/WidgetManager~BuildContext>

buildFor(params [, widget])

Instantiates, initializes, and loads a value into a new Widget as defined
by the input parameters.

Parameters:
Name Type Argument Description
params module:bajaux/lifecycle/WidgetManager~BuildParams
widget module:bajaux/Widget <optional>

if present, skip the instantiation
and just initialize/load the given widget instance.
Returns:

resolves to the widget after it
has been initialized and loaded.

Type
Promise.<module:bajaux/Widget>

deriveConfiguredConstructor(params)

Parameters:
Name Type Description
params module:bajaux/lifecycle/WidgetManager~BuildParams
Returns:

the constructor, as configured via
the type parameter, if present; otherwise undefined. Override to
define other methods of examining params to derive a directly-configured
constructor.

Type
function | Promise.<function()>

destroy(widget)

Destroy the widget.

Parameters:
Name Type Description
widget module:bajaux/Widget
Returns:
Type
Promise

error(err)

This method is called when an error is encountered with a Widget.

If there is an installed error hook on this manager, it will be invoked.

Parameters:
Name Type Description
err Error

the error from the Widget
Returns:

If an error hook is installed, this will
resolve once the error hook is finished. If no error hook is installed,
this will reject with the provided error.

Type
Promise

initialize(widget, buildContext)

Initialize the widget into the DOM element as specified in the build
context.

Parameters:
Name Type Description
widget module:bajaux/Widget
buildContext module:bajaux/lifecycle/WidgetManager~BuildContext
Returns:
Type
Promise

installHooks(hooks)

Install hooks to be invoked at various stages of a widget lifecycle.

Parameters:
Name Type Description
hooks module:bajaux/lifecycle/WidgetManager~BuildHooks

instantiate(buildContext)

Create a new Widget instance from the build context. If no widget
constructor was able to be determined, default to a ToStringWidget.

Parameters:
Name Type Description
buildContext module:bajaux/lifecycle/WidgetManager~BuildContext
Returns:
Type
module:bajaux/Widget | Promise.<module:bajaux/Widget>

load(widget, buildContext)

Load the value from the build context into the widget.

Parameters:
Name Type Description
widget module:bajaux/Widget
buildContext module:bajaux/lifecycle/WidgetManager~BuildContext
Returns:
Type
Promise

makeFor(params)

Resolves a new Widget instance as defined by the input parameters, but
does not initialize or load it anywhere.

Parameters:
Name Type Description
params module:bajaux/lifecycle/WidgetManager~BuildParams
Returns:
Type
Promise.<module:bajaux/Widget>

resolveConstructor(params)

Parameters:
Name Type Description
params module:bajaux/lifecycle/WidgetManager~BuildParams
Returns:

resolves the constructor to be
used to instantiate the widget, either as configured via params or as
looked up from the registry.

Type
Promise.<(function()|undefined)>

resolveFromRegistry(params)

Parameters:
Name Type Description
params module:bajaux/lifecycle/WidgetManager~BuildParams
Returns:

the constructor resolved from the registry.
By default, do a simple lookup by params.value; override to define how
registry lookups are performed.

Type
Promise.<function()>

Type Definitions

BuildContext

Object describing the configuration needed to construct, initialize, and
load a Widget in a DOM element.

Type:
  • Object
Properties:
Name Type Argument Description
widgetConstructor function <optional>

Widget constructor to instantiate.
If no constructor could be found it is up to the WidgetManager to decide
whether to instantiate a default Widget type or to reject.
constructorParams object

params object to pass to the Widget
constructor
initializeParams Object <optional>

params object to pass to the
initialize() method
layoutParams Object <optional>

params object to pass to the layout()
method
loadParams Object <optional>

params object to pass to the load() method
dom string | HTMLElement | JQuery | *

DOM element in which to build a
Widget. Will be translated by the WidgetManager to an appropriate type
for the Widget.
value * <optional>

the value to load into the Widget. null is an
acceptable loadable value. If undefined, no loading should be performed.
data object

any additional data passed by the caller into the
WidgetManager as the data property. This will be passed through the
build lifecycle untouched. Most useful when using lifecycle hooks to add
functionality to the WidgetManager instance.

BuildHooks}

Object describing hooks to be invoked at various points in a widget's
lifecycle. Each hook will be invoked with widget and buildContext
arguments.

Type:
  • Object
Properties:
Name Type Argument Description
instantiated function <optional>

called immediately after a widget is constructed
preInitialize function <optional>

called before initialize() is called
postInitialize function <optional>

called after initialize() completes
preLoad function <optional>

called before load() is called
postLoad function <optional>

called after load() completes
error module:bajaux/lifecycle/WidgetManager~error <optional>

called when
a widget encounters an error

BuildParams

Object describing the parameters that can be passed to WidgetManager to
define a build context. Subclasses of WidgetManager may support
additional parameters.

Type:
  • Object
Properties:
Name Type Argument Description
type String | function <optional>

a bajaux/Widget subclass constructor
function - if given, an instance of that Widget will always be
instantiated instead of dynamically looked up from the value. You can
also use a RequireJS module ID that resolves to a Widget subclass
constructor.
value * <optional>

the value to be loaded into the new widget, if
applicable.
dom string | HTMLElement | JQuery | * <optional>

the DOM element in which the
new widget should be initialized, if applicable.
properties Object <optional>

the bajaux Properties the new widget
should have.
enabled Boolean <optional>

set to false to cause the new widget to be
disabled. Not used for lookups.
readonly Boolean <optional>

set to true to cause the new widget to be
readonly. Not used for lookups.
formFactors String | Array.<String> <optional>

the possible form factors
the new widget should have. The created widget could match any of these
form factors depending on what is registered in the database. If no widget
is found that supports any of these form factors, then no widget will be
created (even if one is present that supports a different form factor). If
no form factor is given, then the widget created could be of any form
factor.
formFactor String <optional>

same as a formFactors array of length 1.
hooks module:bajaux/lifecycle/WidgetManager~BuildHooks <optional>

any
hooks you wish to run at various stages in this widget's lifecycle. They
will run immediately after any installed hooks.