module:bajaux/util/CommandButtonGroup

Extends

• module:bajaux/Widget

Methods

applyParams(paramsopt) → {Promise}

Description:

• Can re-apply certain params that can also be passed to the constructor.

Source:

• Widget.js, line 324

Since:

• Niagara 4.10

Inherited From:

• module:bajaux/Widget#applyParams

Parameters:

Returns:

Type

Promise

changed(name, value) → {Promise}

Description:

• Called whenever a Widget's Property is changed.

  If this Widget is not yet initialized, this is a no-op.

  This function should not typically be overridden.
  doChanged() should be overridden
  instead.

Source:

• Widget.js, line 1155

Inherited From:

• module:bajaux/Widget#changed

See:

• module:bajaux/Widget#properties

Parameters:

Returns:

Type

Promise

cleanupDom()

Description:

• 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.

Source:

• Widget.js, line 914

Inherited From:

• module:bajaux/Widget#cleanupDom

destroy(paramsopt) → {Promise}

Description:

• 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 be removed and the 'widget' data stored on the
  DOM element will be deleted.

Source:

• Widget.js, line 939

Inherited From:

• module:bajaux/Widget#destroy

See:

• module:bajaux/Widget#doDestroy

Parameters:

Returns:

Type

Promise

doChanged(name, value) → {Promise|*}

Description:

• Called by changed() when a Property
  is changed.

  This method is designed to be overridden by any subclasses.

Source:

• Widget.js, line 1173

Inherited From:

• module:bajaux/Widget#doChanged

Parameters:

Returns:

Type

Promise | *

doDestroy() → {Promise}

Description:

• Removes the ux-btn-tb-group class and destroys all child buttons.

Source:

• util/CommandButtonGroup.js, line 216

Overrides:

• module:bajaux/Widget#doDestroy

Returns:

Type

Promise

doEnabled(enabled) → {*|Promise}

Description:

• Called when the widget is enabled/disabled.

Source:

• Widget.js, line 1097

Inherited From:

• module:bajaux/Widget#doEnabled

Parameters:

Returns:

Type

* | Promise

doInitialize(dom)

Description:

• Adds the ux-btn-tb-group class to the DOM to turn this into a toolbar
  button group.

Source:

• util/CommandButtonGroup.js, line 145

Overrides:

• module:bajaux/Widget#doInitialize

Parameters:

doLayout(paramsopt) → {*|Promise}

Description:

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

Source:

• Widget.js, line 594

Inherited From:

• module:bajaux/Widget#doLayout

Parameters:

Returns:

Type

* | Promise

doLoad(group) → {Promise}

Description:

• Loads a CommandGroup, creating CommandButton widgets for each
  command in the group. Arms event handlers to hide elements for
  disabled buttons, as specified by the onDisabled parameter.

Source:

• util/CommandButtonGroup.js, line 174

Overrides:

• module:bajaux/Widget#doLoad

Parameters:

Returns:

Type

Promise

doModified(modified)

Description:

• 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.

Source:

• Widget.js, line 1255

Inherited From:

• module:bajaux/Widget#doModified

See:

• module:bajaux/Widget#setModified

Parameters:

doRead() → {*|Promise}

Description:

• 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.

Source:

• Widget.js, line 1536

Inherited From:

• module:bajaux/Widget#doRead

See:

• module:bajaux/Widget#read

Returns:

Type

* | Promise

doReadonly(readonly) → {*|Promise}

Description:

• Called when the widget is set to readonly or made writable.

Source:

• Widget.js, line 1639

Inherited From:

• module:bajaux/Widget#doReadonly

Parameters:

Returns:

Type

* | Promise

doSave(validValue, paramsopt) → {*|Promise}

Description:

• 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.

Source:

• Widget.js, line 1486

Inherited From:

• module:bajaux/Widget#doSave

Parameters:

Returns:

Type

* | Promise

generateId() → {String}

Description:

• Generate a unique DOM ID. The ID will include the name of this widget's
  constructor just for tracing/debugging purposes.

Source:

• Widget.js, line 536

Inherited From:

• module:bajaux/Widget#generateId

Returns:

Type

String

getChildWidgets(paramsopt) → {Array.<module:bajaux/Widget>}

Description:

• Returns an array of child widgets living inside this editor's DOM.
  This method will specifically not return child widgets of child widgets

  • for instance, if this widget has one child editor for a baja.Facets,
    you will only get a single widget back - it won't recurse down and give
    you all the tag editors, type editors etc.

  This is safer and easier than using $.find(), which recurses down,
  or carefully managing strings of $.children() calls.

  Pass in a jQuery instance to limit the child editor search to
  a particular set of elements. Otherwise, will search all child elements
  of this editor's DOM.

  If this editor has not initialized yet, you'll just get an empty array
  back.

  The returned array will have some utility functions attached that return
  promises. See example for details.

Source:

• Widget.js, line 1685

Since:

• Niagara 4.10

Inherited From:

• module:bajaux/Widget#getChildWidgets

Examples

var kids = ed.getChildWidgets();
  kids.setAllEnabled(false).then(function () {});
  kids.setAllModified(false).then(function () {});
  kids.setAllReadonly(false).then(function () {});
  kids.readAll().then(function (valuesArray) {});
  kids.validateAll().then(function (valuesArray) {});
  kids.saveAll().then(function () {});
  kids.destroyAll().then(function () {});

var stringEditors = ed.getChildWidgets({ type: StringEditor });

Parameters:

Returns:

Type

Array.<module:bajaux/Widget>

getCommandGroup() → {module:bajaux/commands/CommandGroup}

Description:

• Return the widget's command group.

Source:

• Widget.js, line 665

Inherited From:

• module:bajaux/Widget#getCommandGroup

Returns:

Type

module:bajaux/commands/CommandGroup

getFormFactor() → {String}

Description:

• 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.

Source:

• Widget.js, line 553

Inherited From:

• module:bajaux/Widget#getFormFactor

See:

• module:bajaux/Widget.formfactor

Returns:

Type

String

hasMixIn(mixin) → {Boolean}

Description:

• Return true if the widget implements the specified MixIn.

Source:

• Widget.js, line 1119

Inherited From:

• module:bajaux/Widget#hasMixIn

Parameters:

Returns:

Type

Boolean

initialize(dom, paramsopt, layoutParamsopt) → {Promise}

Description:

• Initializes the DOM element to be bound to this Widget.

  In a nutshell, initialize defines the following contract:

  • After initialize completes and resolves its Promise, 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 Widget.in(element).

  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 is a one-time operation. It will always reject if the widget has already been
  initialized once, or if it has been destroyed.

Source:

• Widget.js, line 798

Inherited From:

• module:bajaux/Widget#initialize

See:

• module:bajaux/Widget#doInitialize

Parameters:

Returns:

Type

Promise

isDesignTime() → {Boolean}

Description:

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

Source:

• Widget.js, line 1181

Inherited From:

• module:bajaux/Widget#isDesignTime

Returns:

Type

Boolean

isDestroyed() → {Boolean}

Description:

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

Source:

• Widget.js, line 719

Inherited From:

• module:bajaux/Widget#isDestroyed

Returns:

Type

Boolean

isEnabled() → {Boolean}

Description:

• Returns this widget's enabled state.

Source:

• Widget.js, line 1032

Inherited From:

• module:bajaux/Widget#isEnabled

See:

• module:bajaux/Widget#setEnabled

Returns:

Type

Boolean

isInitialized() → {Boolean}

Description:

• Return true if this Widget is initialized.

Source:

• Widget.js, line 709

Inherited From:

• module:bajaux/Widget#isInitialized

Returns:

Type

Boolean

isLoading() → {Boolean}

Description:

• 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.

Source:

• Widget.js, line 1409

Inherited From:

• module:bajaux/Widget#isLoading

Returns:

Type

Boolean

isModified() → {Boolean}

Description:

• Returns this widget's modified state.

Source:

• Widget.js, line 1190

Inherited From:

• module:bajaux/Widget#isModified

Returns:

Type

Boolean

isReadonly() → {Boolean}

Description:

• Returns this widget's readonly state.

Source:

• Widget.js, line 1574

Inherited From:

• module:bajaux/Widget#isReadonly

See:

• module:bajaux/Widget#setReadonly

Returns:

Type

Boolean

jq() → {JQuery|null}

Description:

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

Source:

• Widget.js, line 1021

Inherited From:

• module:bajaux/Widget#jq

Returns:

Type

JQuery | null

layout(paramsopt) → {Promise}

Description:

• 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.

Source:

• Widget.js, line 575

Inherited From:

• module:bajaux/Widget#layout

Parameters:

Returns:

Type

Promise

load(value, paramsopt) → {Promise}

Description:

• 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.

Source:

• Widget.js, line 1337

Inherited From:

• module:bajaux/Widget#load

See:

• module:bajaux/Widget#doLoad
• module:bajaux/Widget#value
• module:bajaux/mixin/batchLoadMixin

Parameters:

Returns:

Type

Promise

loadAndModify(value, paramsopt) → {Promise.<*>}

Description:

• Loads in a new value, and sets the widget modified as well. Use this
  convenience method when you wish to load in a new value as if a user had
  done it, thereby triggering the necessary modify event handlers.

Source:

• Widget.js, line 1374

Since:

• Niagara 4.12

Inherited From:

• module:bajaux/Widget#loadAndModify

Parameters:

Returns:

Type

Promise.<*>

properties() → {module:bajaux/Properties}

Description:

• Return the Properties for a widget.

Source:

• Widget.js, line 1136

Inherited From:

• module:bajaux/Widget#properties

Returns:

Type

module:bajaux/Properties

read() → {Promise}

Description:

• 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.

Source:

• Widget.js, line 1506

Inherited From:

• module:bajaux/Widget#read

See:

• module:bajaux/Widget#doRead

Returns:

Type

Promise

requestFocus()

Description:

• Attempts to place the cursor focus on this editor. For instance, if
  showing a simple string editor in a dialog, it should request focus so
  that the user can simply begin typing without having to move the mouse
  over to it and click.

  Override this as necessary; by default, will place focus on the first
  input or textarea element in this editor's element.

Source:

• Widget.js, line 1702

Since:

• Niagara 4.10

Inherited From:

• module:bajaux/Widget#requestFocus

resolve(data, resolveParamsopt) → {Promise}

Description:

• 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.

Source:

• Widget.js, line 1274

Inherited From:

• module:bajaux/Widget#resolve

Parameters:

Returns:

Type

Promise

save(paramsopt) → {Promise}

Description:

• 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.

Source:

• Widget.js, line 1449

Inherited From:

• module:bajaux/Widget#save

See:

• module:bajaux/Widget#doSave
• module:bajaux/mixin/batchSaveMixin

Parameters:

Returns:

Type

Promise

setCommandGroup(commandGroup)

Description:

• Set this widget's command group. Triggers a bajaux:changecommandgroup
  event.

Source:

• Widget.js, line 675

Inherited From:

• module:bajaux/Widget#setCommandGroup

Parameters:

setEnabled(enabled) → {Promise}

Description:

• 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.

Source:

• Widget.js, line 1056

Inherited From:

• module:bajaux/Widget#setEnabled

See:

• module:bajaux/Widget#isEnabled

Parameters:

Returns:

Type

Promise

setModified(modified)

Description:

• 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.

Source:

• Widget.js, line 1226

Inherited From:

• module:bajaux/Widget#setModified

See:

• module:bajaux/Widget#doModified

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;
  });

Parameters:

setReadonly(readonly) → {Promise}

Description:

• 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.

Source:

• Widget.js, line 1598

Inherited From:

• module:bajaux/Widget#setReadonly

See:

• module:bajaux/Widget#isReadonly

Parameters:

Returns:

Type

Promise

toDescription() → {Promise}

Description:

• 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.description. If an entry can't be found then a blank string
  will be used.

Source:

• Widget.js, line 627

Inherited From:

• module:bajaux/Widget#toDescription

Returns:

Type

Promise

toDisplayName() → {Promise}

Description:

• 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.

Source:

• Widget.js, line 607

Inherited From:

• module:bajaux/Widget#toDisplayName

Returns:

Type

Promise

toIcon() → {Promise}

Description:

• 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.

Source:

• Widget.js, line 647

Inherited From:

• module:bajaux/Widget#toIcon

Returns:

Type

Promise

trigger()

Description:

• Trigger a widget event. By default, this fires a DOM event on the associated
  widget's DOM element.

Source:

• Widget.js, line 1105

Inherited From:

• module:bajaux/Widget#trigger

validate() → {Promise}

Description:

• Read the current value from the widget and validate it.

Source:

• Widget.js, line 1560

Inherited From:

• module:bajaux/Widget#validate

See:

• module:bajaux/Validators#validate

Returns:

Type

Promise

validators() → {module:bajaux/Validators}

Description:

• Return the widget's Validators.

Source:

• Widget.js, line 1547

Inherited From:

• module:bajaux/Widget#validators

See:

• module:bajaux/Validators

Returns:

Type

module:bajaux/Validators

value() → {*|null}

Description:

• 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.

Source:

• Widget.js, line 1426

Inherited From:

• module:bajaux/Widget#value

See:

• module:bajaux/Widget#load
• module:bajaux/Widget#doLoad
• module:bajaux/Widget#read

Returns:

Type

* | null