The base Widget class, used for loading Web based Niagara Widgets.
new (require("bajaux/Widget"))(moduleName, keyName, formFactor)
A Widget contains the most basic mechanisms necessary for displaying user interface
upon a DOM element. It should not be instantiated directly,
but rather subclassed with the specific functionality you need.
At a bare minimum, either the doInitialize
or doLoad
function will need
to be implemented by your subclass.
Parameters:
Name | Type | Description |
---|---|---|
moduleName |
String | The module name used for accessing values from the lexicon. |
keyName |
String | The key name used for accessing values from the lexicon. |
formFactor |
String | The widget's form factor. Should be a member of |
Requires
- module:lex
- module:jquery
- module:bajaux/events
- module:bajaux/Properties
- module:bajaux/Validators
Methods
-
<static> in(el)
-
Find the Widget instance living in this DOM element.
Parameters:
Name Type Description el
JQuery | HTMLElement - Since:
-
- Niagara 4.6
Returns:
- Type
- module:bajaux/Widget | undefined
-
changed(name, value)
-
Called whenever a Widget's Property is changed.
This function should not typically be overridden.
doChanged() should be overridden
instead.Parameters:
Name Type Description name
String The name of the Property that's changed.
value
* The new Property value.
-
cleanupDom()
-
Called to clean up the DOM when the widget is being destroyed.
This method can be overridden if DOM clean up needs to be
handled in a different way. -
destroy()
-
Indicates that a widget is no longer needed and is in the process of being
removed. In this function, subclasses can deallocate any resources, event
handlers, etc. that they may be holding. Delegates the actual work todoDestroy
.This method will not typically be overridden.
doDestroy()
should be
overridden instead.Triggers a
bajaux:destroy
orbajaux:destroyfail
event, as appropriate.Please note, after
doDestroy
has resolved, the DOM will be emptied,
all event handlers will removed and the 'widget' data stored on the
DOM element will be deleted.Returns:
A promise to be resolved when the widget has been
destroyed- Type
- Promise
-
doChanged(name, value)
-
Called by changed() when a Property
is changed.This method is designed to be overridden by any subclasses.
Parameters:
Name Type Description name
String The name of the Property that's changed.
value
* The new Property value.
-
doDestroy( [params])
-
Called by
destroy
so this widget has a chance to clean up after itself
and release any resources it is holding.Notably, any jQuery event handlers registered on child elements of the
widget's DOM element should be unregistered here. Also, you may want to
remove any CSS classes you've added to the widget's DOM element.Parameters:
Name Type Argument Description params
Object <optional>
Optional params object passed to
destroy()
Returns:
An optional promise that's resolved once the widget
has been destroyed.- Type
- * | Promise
-
doEnabled(enabled)
-
Called when the widget is enabled/disabled.
Parameters:
Name Type Description enabled
Boolean the new enabled state.
Returns:
An optional Promise that can be returned if
the state change is asynchronous.- Type
- * | Promise
-
doInitialize(element [, params])
-
Performs the actual work of initializing the DOM element in which this
widget will live. This function should be overridden by subclasses - the
subclass function should append elements toelement
as
necessary and then optionally return a promise.Most commonly, this will involve building up the HTML structure
necessary to load in a value. If this widget will display/edit a String,
for example,doInitialize
might append a text input element to
the target element. ADynamicEnum
might include a<select>
dropdown.In some cases, no initialization may be required at all. This
might be the case if you are binding the widget to an HTML element that is
already pre-populated with all the necessary structure to load a value,
or maybedoLoad
will empty out the element completely
and rebuild it from scratch every time a new value is loaded. In this
case, you do not need to override this method. (However, a widget that
overrides neitherdoInitialize
nordoLoad
will not be very useful!)Tip: the promises returned by
setEnabled
andsetReadonly
can
only ever resolve afterinitialize
itself resolves. Soreturn this.setEnabled(enabled)
orreturn this.setReadonly(readonly)
fromdoInitialize
will result in a deadlock that will never resolve.
They may be called, but not returned.Parameters:
Name Type Argument Description element
jQuery The element in which this Widget should build its
HTML.params
Object <optional>
Optional params object passed into
initialize()
.Returns:
An optional promise to be resolved once the Widget
has initialized.- Type
- * | Promise
-
doLayout()
-
Called when the layout of the Widget changes. This method is designed
to be overridden.Returns:
This method may optionally return a promise once the
Widget has been laid out.- Type
- * | Promise
-
doLoad(value [, params])
-
Performs the actual work of populating the widget's HTML to reflect the
input value.This function should be overridden by subclasses. The subclass function
should manipulate the DOM jq() and,
optionally,return a promise to indicate that the work of loading the value
has completed.Parameters:
Name Type Argument Description value
* The value to be loaded.
params
Object <optional>
Optional params object passed to
load()
Returns:
An optional promise that's resolved once the widget has
loaded.- Type
- Promise
-
doModified(modified)
-
The actual implementation for
setModified
. This function
should do any work necessary when the widget is set to a modified or
"dirty" state - typically enabling a save button, arming awindow.onbeforeunload
handler, etc. Likewise, it should do
the opposite when setting modified to false.Note that this is synchronous, as is
setModified
. Async work can be
performed, butsetModified
will not wait for it.Parameters:
Name Type Description modified
Boolean -
doRead()
-
Does the work of reading the widget's current representation.
This might mean reading a series of text inputs and assembling their
values into an array. It might mean instantiating a copy of the backingbaja.Component
and setting slot values on the new copy.
It might mean simply returning the boolean value of a checkbox. If your
widget is composed of pure text/HTML and is not actually backed by an
external value, it might mean returning nothing.When saving a modified widget, the output of this function will be passed
directly into this widget's validation process, so all your validation
steps should be expecting to receive this. It will also be passed todoSave
, so yourdoSave
implementation should also expect this value.The default behavior of
doRead
is simply to use the widget's current
value.Returns:
The read value, or a promise to be resolved with the
read value- Type
- * | Promise
-
doReadonly(readonly)
-
Called when the widget is set to readonly or made writable.
Parameters:
Name Type Description readonly
Boolean the new readonly state.
Returns:
An optional Promise that can be returned if
the state change is asynchronous.- Type
- * | Promise
-
doSave(validValue [, params])
-
Performs the actual work of saving the widget. This function should
be overridden by subclasses to save the value. The subclass function
should save the value and then, optionally, return a promise to indicate
that the work of saving the widget has completed.Parameters:
Name Type Argument Description validValue
* The value to be used for saving. This value will have
been read from the widget usingread()
and validated usingvalidate()
.params
Object <optional>
Optional params object passed to
save()
Returns:
An optional promise that's resolved once
the widget has saved.- Type
- * | Promise
-
getCommandGroup()
-
Return the widget's command group.
Returns:
-
getFormFactor()
-
Return the widget's form-factor. The form-factor
is normally passed in from the Widget's constructor. However,
it can be set from a 'formFactor' property if required.A widget's form-factor typically doesn't change during a widget's
life-cycle.- See:
-
- module:bajaux/Widget.formfactor
Returns:
The form-factor.
- Type
- String
-
hasMixIn(mixin)
-
Return true if the widget implements the specified MixIn.
Parameters:
Name Type Description mixin
String the name of the mixin to test for.
Returns:
- Type
- Boolean
-
initialize(element)
-
Initializes the DOM element to be bound to this Widget.
In a nutshell,
initialize
defines the following contract:- After
initialize
completes and callsdeferred.resolve
, the target element will be fully initialized,
structured, and ready to load in a value. It will be accessible by
callingthis.jq()
. - If this is an editor,
load
may not be called untilinitialize
's promise is resolved. Attempting
to load a value prior to initialization will result in failure. - This widget will be set as a jQuery data value on the initialized
DOM element. It can be retrieved by callingelement.data('widget')
.
initialize
delegates the actual work of building the
HTML structure (if any) to thedoInitialize
function. When
subclassing Widget, you should not overrideinitialize
.doInitialize
should be overridden.After
initialize
completes, anbajaux:initialize
orbajaux:initializefail
event will be triggered, as appropriate.initialize
will always reject if the widget has already been destroyed.Parameters:
Name Type Description element
jQuery The jQuery DOM element in which this widget should
build its HTML (will be passed directly todoInitialize
)Returns:
A promise to be resolved once the widget has
initialized- Type
- Promise
- After
-
isDesignTime()
-
Returns true if the Widget is in a graphic design editor.
Returns:
- Type
- Boolean
-
isDestroyed()
-
Return true if this Widget has already been destroyed. After destruction,
initialize()
will always reject: the widget cannot be reused.Returns:
- Type
- Boolean
-
isEnabled()
-
Returns this widget's enabled state.
Returns:
- Type
- Boolean
-
isInitialized()
-
Return true if this Widget is initialized.
Returns:
- Type
- Boolean
-
isLoading()
-
Check if this widget is currently in the process of loading. This will
returntrue
immediately afterload
is called, and returnfalse
after theload
promise resolves.Returns:
- Type
- Boolean
-
isModified()
-
Returns this widget's modified state.
Returns:
- Type
- Boolean
-
isReadonly()
-
Returns this widget's readonly state.
Returns:
- Type
- Boolean
-
jq()
-
Returns the jQuery DOM element in which this widget has been initialized.
Ifinitialize()
has not yet been called, then this will returnnull
.Returns:
the DOM element in which this widget has been
initialized, ornull
if not yet initialized.- Type
- jQuery | null
-
layout()
-
A widget may need to do its own layout calculation. It might need
to statically position elements, or show/hide them based
on the shape of its container.This function gives a widget an opportunity to do that. It's called once
the Widget has been initialized and once the form factor has changed.
Also it may be called when the widget's container changes shape
or size, or is shown/hidden.This method should not typically be overridden. Override
doLayout() instead.Returns:
A promise that's resolved once the layout has
completed.- Type
- Promise
-
load(value [, params])
-
Updates the widget's HTML with the given value. An widget for editing a
string, for example, might load the string into a text input. A view for
editing aDynamicEnum
might programmatically set a<select>
dropdown's value.load()
may not be called untilinitialize()
has completed its work.
Ifinitialize()
is not finished,load()
will reject.After
load()
completes its work, the value loaded will be accessible
viathis.value()
.load()
delegates the work of loading the HTML values todoLoad()
.
Subclasses will typically not overrideload
, but more commonly will
overridedoLoad
.After
load()
completes, abajaux:load
orbajaux:loadfail
event will
be triggered, as appropriate.While this method is performing its work,
this.isLoading()
will returntrue
.Parameters:
Name Type Argument Description value
* The value to be loaded
params
Object <optional>
additional parameters to be passed to
doLoad()
Returns:
A promise to be resolved with the loaded value after
the widget has been loaded, or rejected if the widget fails to load the
value.- Type
- Promise
-
properties()
-
Return the Properties for a widget.
Returns:
The Properties for a widget.
-
read()
-
Read the current representation of the widget. For instance, if the widget
is made up from two text input boxes, this might resolve an object with
two strings from those text boxes.Note the word "representation" - this function does not necessarily
return the widget's actual value, but might assemble a different
object, or array, or number, based on current user-entered values.read
will not typically be overridden.
doRead() should be overridden instead.Returns:
A promise that will be resolved with a value read from
the widget as specified bydoRead
, or rejected if the read fails.- Type
- Promise
-
resolve(data [, resolveParams])
-
Resolve a value from some data. Please note, this will not load the value
but will resolve some data that could then be loaded by the widget.By default, this will treat the data as an ORD so it can be resolved via
BajaScript.Parameters:
Name Type Argument Description data
* | String | baja.Ord Specifies some data used to resolve a
load value soload(value)
can be called on the widget.resolveParams
Object <optional>
An Object Literal used for ORD resolution.
This parameter is designed to be used internally by bajaux and
shouldn't be used by developers.Returns:
a promise to be resolved with the value resolved from
the given data object- Type
- Promise
-
save( [params])
-
Saves any outstanding user-entered changes to this widget. Triggers a
bajaux:save
orbajaux:savefail
event, as appropriate.In order to save the widget, its current value will be validated using
validate()
, then the validated value will be passed todoSave()
.This method will not typically be overridden.
doSave() should be overridden instead.Parameters:
Name Type Argument Description params
Object <optional>
Additional parameters to be passed to
doSave()
Returns:
A promise to be resolved once the widget has been saved,
or rejected if the save fails.- Type
- Promise
-
setCommandGroup(commandGroup)
-
Set this widget's command group. Triggers a
bajaux:changecommandgroup
event.Parameters:
Name Type Description commandGroup
module:bajaux/commands/CommandGroup -
setEnabled(enabled)
-
Set this widget's enabled state.
Setting of the internal flag will be synchronous, so
isEnabled
will
return the expected value immediately after calling this function. However,
the actual work of updating the DOM cannot be performed until after the
widget has finished initializing, so this method will return a promise.This method will not typically be overridden.
doEnabled()
should be
overridden instead.Parameters:
Name Type Description enabled
Boolean the new enabled state
Returns:
A promise to resolve immediately if
initialize
has
not yet been called, that will resolve once the work ofinitialize
followed bydoEnabled
have both been completed. It will reject ifinitialize
ordoEnabled
fail.- Type
- Promise
-
setModified(modified)
-
Sets this widget's modified or "dirty" status, to indicate that the user
has made changes to this widget that may need to be saved.The modification status will only be set if the widget is initialized
and the widget is not loading a new value.Triggers
bajaux:modify
orbajaux:unmodify
depending on the input value.
Any arguments passed to this function after the first will be passed
through to the triggered event.This method should not typically be overridden.
doModified() should be overridden
instead.Parameters:
Name Type Description modified
Boolean | * (a non-Boolean will be checked for truthiness)
Example
Say I have collection of nested widgets in my DOM element. Whenever one of those widgets is modified, I want to mark myself modified but also provide the originally modified editor. For example, when a Property Sheet is modified, I want to know which row caused the modification.
var that = this; dom.on(events.MODIFY_EVENT, function (e, modifiedEd) { that.setModified(true, modifiedEd); return false; });
-
setReadonly(readonly)
-
Set this widget's readonly state.
Setting of the internal flag will be synchronous, so
isReadonly
will
return the expected value immediately after calling this function. However,
the actual work of updating the DOM cannot be performed until after the
widget has finished initializing, so this method will return a promise.This method will not typically be overridden.
doReadonly()
should be
overridden instead.Parameters:
Name Type Description readonly
Boolean the new readonly state.
Returns:
A promise to resolve immediately if
initialize
has
not yet been called, that will resolve once the work ofinitialize
followed bydoReadonly
have both been completed. It will reject ifinitialize
ordoReadonly
fail.- Type
- Promise
-
toDescription()
-
Access the widget's icon asynchronously.
By default this will attempt to access the widget's icon from
the originating Lexicon. The Lexicon key should be in the format ofkeyName.desciption
. If an entry can't be found then a blank string
will be used.Returns:
A promise to be resolved with the widget's description
- Type
- Promise
-
toDisplayName()
-
Access the widget's display name asynchronously.
By default, this will attempt to access the widget's display name from
the originating Lexicon. The Lexicon key should be in the format ofkeyName.displayName
. If an entry can't be found then the Type's
name will be used.Returns:
A promise to be resolved with the widget's display name
- Type
- Promise
-
toIcon()
-
Access the widget's icon asynchronously.
By default, this will attempt to access the widget's description from
the originating Lexicon. The Lexicon key should be in the format ofkeyName.icon
. If an entry can't be found then a blank String will be
returned.Returns:
A promise to be resolved with the widget's icon URI.
- Type
- Promise
-
trigger()
-
Trigger a widget event. By default this fires a DOM event on the associated
widget's DOM element. -
validate()
-
Read the current value from the widget and validate it.
Returns:
A promise to be resolved with the value read from the
widget and passed through all validators, or rejected if the value could
not be read or validated.- Type
- Promise
-
validators()
-
Return the widget's Validators.
Returns:
- Type
- Validators
-
value()
-
Returns the widget's current loaded value. This the value that was last
loaded viaload()
. To read a widget's current representation, reflecting
any user-entered changes, callread()
. If no value has been loaded yet,null
is returned.Returns:
the loaded value, or
null
if a value hasn't been
loaded yet.- Type
- * | null