Class: module:bajaux/util/CommandButton

module:bajaux/util/CommandButton


new module:bajaux/util/CommandButton()

A widget for displaying and invoking a Command.

Extends:

Extends

Methods


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.

Inherited From:
See:

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.

Inherited From:

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 to
doDestroy.

This method will not typically be overridden. doDestroy() should be
overridden instead.

Triggers a bajaux:destroy or bajaux: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.

Inherited From:
See:
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.

Inherited From:

doDestroy()

Removes the click handler and CSS class from doInitialize.

Overrides:

doEnabled(enabled)

Adds or removes the disabled property from the DOM.

Parameters:
Name Type Description
enabled Boolean
Overrides:

doInitialize(dom)

Arms a click handler that will invoke the loaded Command. Adds a
CommandButton CSS class.

Technically, this widget can be initialized in any DOM element, but makes
the most sense in a button element.

Parameters:
Name Type Description
dom JQuery
Overrides:

doLayout()

Called when the layout of the Widget changes. This method is designed
to be overridden.

Inherited From:
Returns:

This method may optionally return a promise once the
Widget has been laid out.

Type
* | Promise

doLoad(cmd)

Loads a Command. Binds an event handler to update the DOM whenever the
Command's properties are changed.

Parameters:
Name Type Description
cmd module:bajaux/commands/Command
Overrides:
Returns:

promise to be resolved when the Command is
loaded, or rejected if no Command given

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 a
window.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, but setModified will not wait for it.

Parameters:
Name Type Description
modified Boolean
Inherited From:
See:

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 backing
baja.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 to
doSave, so your doSave implementation should also expect this value.

The default behavior of doRead is simply to use the widget's current
value.

Inherited From:
See:
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.

Inherited From:
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 using read() and validated using validate().

params Object <optional>

Optional params object passed to save()

Inherited From:
Returns:

An optional promise that's resolved once
the widget has saved.

Type
* | Promise

getCommandGroup()

Return the widget's command group.

Inherited From:
Returns:
Type
module:bajaux/commands/CommandGroup

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.

Inherited From:
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.

Inherited From:
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 calls
    deferred.resolve, the target element will be fully initialized,
    structured, and ready to load in a value. It will be accessible by
    calling this.jq().
  • If this is an editor, load may not be called until
    initialize'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 calling element.data('widget').

initialize delegates the actual work of building the
HTML structure (if any) to the doInitialize function. When
subclassing Widget, you should not override initialize.
doInitialize should be overridden.

After initialize completes, an bajaux:initialize or
bajaux: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 to doInitialize)

Inherited From:
See:
Returns:

A promise to be resolved once the widget has
initialized

Type
Promise

isDesignTime()

Returns true if the Widget is in a graphic design editor.

Inherited From:
Returns:
Type
Boolean

isDestroyed()

Return true if this Widget has already been destroyed. After destruction,
initialize() will always reject: the widget cannot be reused.

Inherited From:
Returns:
Type
Boolean

isEnabled()

Returns this widget's enabled state.

Inherited From:
See:
Returns:
Type
Boolean

isInitialized()

Return true if this Widget is initialized.

Inherited From:
Returns:
Type
Boolean

isLoading()

Check if this widget is currently in the process of loading. This will
return true immediately after load is called, and return false
after the load promise resolves.

Inherited From:
Returns:
Type
Boolean

isModified()

Returns this widget's modified state.

Inherited From:
Returns:
Type
Boolean

isReadonly()

Returns this widget's readonly state.

Inherited From:
See:
Returns:
Type
Boolean

jq()

Returns the jQuery DOM element in which this widget has been initialized.
If initialize() has not yet been called, then this will return null.

Inherited From:
Returns:

the DOM element in which this widget has been
initialized, or null 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.

Inherited From:
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 a DynamicEnum might programmatically set a <select>
dropdown's value.

load() may not be called until initialize() has completed its work.
If initialize() is not finished, load() will reject.

After load() completes its work, the value loaded will be accessible
via this.value().

load() delegates the work of loading the HTML values to doLoad().
Subclasses will typically not override load, but more commonly will
override doLoad.

After load() completes, a bajaux:load or bajaux:loadfail event will
be triggered, as appropriate.

While this method is performing its work, this.isLoading() will return
true.

Parameters:
Name Type Argument Description
value *

The value to be loaded

params Object <optional>

additional parameters to be passed to doLoad()

Inherited From:
See:
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.

Inherited From:
Returns:

The Properties for a widget.

Type
module:bajaux/Properties

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.

Inherited From:
See:
Returns:

A promise that will be resolved with a value read from
the widget as specified by doRead, 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 so load(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.

Inherited From:
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 or bajaux: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 to doSave().

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()

Inherited From:
See:
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
Inherited From:

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

Inherited From:
See:
Returns:

A promise to resolve immediately if initialize has
not yet been called, that will resolve once the work of initialize
followed by doEnabled have both been completed. It will reject if
initialize or doEnabled 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 or bajaux: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)

Inherited From:
See:
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.

Inherited From:
See:
Returns:

A promise to resolve immediately if initialize has
not yet been called, that will resolve once the work of initialize
followed by doReadonly have both been completed. It will reject if
initialize or doReadonly 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 of
keyName.desciption. If an entry can't be found then a blank string
will be used.

Inherited From:
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 of
keyName.displayName. If an entry can't be found then the Type's
name will be used.

Inherited From:
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 of
keyName.icon. If an entry can't be found then a blank String will be
returned.

Inherited From:
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.

Inherited From:

validate()

Read the current value from the widget and validate it.

Inherited From:
See:
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.

Inherited From:
See:
Returns:
Type
Validators

value()

Returns the widget's current loaded value. This the value that was last
loaded via load(). To read a widget's current representation, reflecting
any user-entered changes, call read(). If no value has been loaded yet,
null is returned.

Inherited From:
See:
Returns:

the loaded value, or null if a value hasn't been
loaded yet.

Type
* | null