module:bajaux/Widget

module:bajaux/Widget

new (require("bajaux/Widget"))(paramsopt)

Description:

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

Source:
Examples

Construct a Widget, defining its initial configuration with an object literal.

const w = new Widget({
  readonly: true,
  properties: { foo: 'bar' },
  formFactor: 'compact'
});

Define a Widget subclass with an initial set of default values, while still allowing parameters to be passed to the constructor. This is the preferred method of calling a Widget super-constructor.

class MyButton extends Widget {
  constructor(params) {
    super({
      params,
      defaults: {
        moduleName: 'myModule',
        keyName: 'MyButton',
        properties: { borderRadius: 15, padding: 10 }
      }
    });
  }
}
const button = new MyButton({ properties: { padding: 20 } });
button.properties().getValue('borderRadius'); // 15, from defaults
button.properties().getValue('padding'); // 20, from constructor

params and defaults will be correctly processed even when subclassing.

class AWidget extends Widget {
  constructor(params) {
    super({ params, defaults: { properties: { name: 'A' } } });
  }
}
class BWidget extends AWidget {
  constructor(params) {
    // defaults will be merged in with superclass defaults.
    super({ params, defaults: { properties: { name: 'B' } } });
  }
}
new BWidget().properties().getValue('name'); // 'B'
new BWidget({ properties: { name: 'Bee' } }).properties().getValue('name'); // 'Bee'
Parameters:
Name Type Attributes Description
params Object <optional>

a parameters object.

Properties
Name Type Attributes Default Description
properties Object <optional>

properties to add to this editor's
underlying bajaux/Properties instance.
enabled Boolean <optional>

false to disable this editor
readonly Boolean <optional>

true to readonly this editor
formFactor String <optional>

form factor this editor should use
(c.f. Widget.formfactor)
keyName String <optional>

the key name that bajaux should use to
look up lexicon entries for this editor
moduleName String <optional>
 'bajaux'

the module name that
bajaux should use to look up lexicon entries for this editor
data Object <optional>

optional additional configuration data that
may be used on a per-widget basis. This will often be used in conjunction
with fe.
params Object <optional>

in conjunction with defaults, allows a
Widget subclass to accept parameters passed to the constructor as well as
an initial set of default values. See example.
defaults Object <optional>

in conjunction with params, allows a
Widget subclass to define an initial set of default values. See example.

Members

(static) css

Description:

  • Widget CSS class names.

Source:
Properties:
Name Type Description
initialized String

bajaux-initialized: applied after the
widget is initialized.
disabled String

bajaux-disabled: applied when the widget is
disabled.
designTime String

bajaux-design-time: Applied to an ancestor
DOM element to indicate the widget is running in a graphic design editor.
You can use this to style your widget differently between design time and
production.
readonly String

bajaux-readonly: Applied when the widget is
marked readonly.b
max String

bajaux-max: A large Widget (e.g. a View).
compact String

bajaux-compact: A medium sized Widget (e.g. a
dashboard Widget).
mini String

bajaux-mini: A small Widget (e.g. a Field
Editor).

Widget CSS class names.

(static) formFactor

Description:

  • Widget form-factors.

Source:
See:
Properties:
Name Type Description
max String

A large Widget (e.g. a View).
compact String

A medium sized Widget (e.g. a dashboard Widget).
mini String

A small Widget (e.g. a Field Editor).

Widget form-factors.

Methods

applyParams(paramsopt) → {Promise}

Description:

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

Source:
Since:
  • Niagara 4.10
Parameters:
Name Type Attributes Description
params Object <optional>
Properties
Name Type Attributes Default Description
readonly Boolean <optional>
enabled Boolean <optional>
 true

must explicitly set to false to
disable
properties Object <optional>
Returns:

promise to be resolved after any
setEnabled/setReadonly work is done. Note that these functions will not
be called if the value of enabled/readonly is not actually changing.

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:
See:
Parameters:
Name Type Description
name String

The name of the Property that's changed.
value *

The new Property value.
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:

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:
See:
Parameters:
Name Type Attributes Description
params object <optional>

optional parameters to be passed to doDestroy
Returns:

A promise to be resolved when the widget has been
destroyed

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:
Parameters:
Name Type Description
name String

The name of the Property that's changed.
value *

The new Property value.
Returns:
Type
Promise | *

doDestroy(paramsopt) → {*|Promise}

Description:

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

Source:
See:
Parameters:
Name Type Attributes 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) → {*|Promise}

Description:

  • Called when the widget is enabled/disabled.

Source:
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, paramsopt) → {*|Promise}

Description:

  • 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 to element 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. A DynamicEnum 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 maybe doLoad 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 neither doInitialize nor doLoad will not be very useful!)

    Tip: the promises returned by setEnabled and setReadonly can
    only ever resolve after initialize itself resolves. So
    return this.setEnabled(enabled) or return this.setReadonly(readonly)
    from doInitialize will result in a deadlock that will never resolve.
    They may be called, but not returned.

Source:
See:
Parameters:
Name Type Attributes 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(paramsopt) → {*|Promise}

Description:

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

Source:
Parameters:
Name Type Attributes Description
params * <optional>

as of Niagara 4.10, any parameters passed to
layout() will also be passed to doLayout().
Returns:

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

Type
* | Promise

doLoad(value, paramsopt) → {Promise}

Description:

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

Source:
See:
Parameters:
Name Type Attributes 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)

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:
See:
Parameters:
Name Type Description
modified Boolean

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:
See:
Returns:

The read value, or a promise to be resolved with the
read value

Type
* | Promise

doReadonly(readonly) → {*|Promise}

Description:

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

Source:
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, 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:
Parameters:
Name Type Attributes 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()
Returns:

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

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:
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:
Since:
  • Niagara 4.10
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:
Name Type Attributes Description
params Object | jQuery <optional>
Properties
Name Type Attributes Default Description
dom JQuery <optional>
 this.jq().children()

the dom element to search
type function <optional>

the widget type to search for - pass in the
actual constructor, for instanceof checks
Returns:

an array of child widgets

Type
Array.<module:bajaux/Widget>

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

Description:

  • Return the widget's command group.

Source:
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:
See:
  • module:bajaux/Widget.formfactor
Returns:

The form-factor.

Type
String

hasMixIn(mixin) → {Boolean}

Description:

  • Return true if the widget implements the specified MixIn.

Source:
Parameters:
Name Type Description
mixin String

the name of the mixin to test for.
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:
See:
Parameters:
Name Type Attributes Description
dom JQuery

The jQuery DOM element in which this widget should
build its HTML (will be passed directly to doInitialize)
params * <optional>

optional parameters object to be passed through to
doInitialize
layoutParams * <optional>

as of Niagara 4.10, optional parameters object to
be passed through to layout
Returns:

A promise to be resolved once the widget has
initialized

Type
Promise

isDesignTime() → {Boolean}

Description:

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

Source:
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:
Returns:
Type
Boolean

isEnabled() → {Boolean}

Description:

  • Returns this widget's enabled state.

Source:
See:
Returns:
Type
Boolean

isInitialized() → {Boolean}

Description:

  • Return true if this Widget is initialized.

Source:
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:
Returns:
Type
Boolean

isModified() → {Boolean}

Description:

  • Returns this widget's modified state.

Source:
Returns:
Type
Boolean

isReadonly() → {Boolean}

Description:

  • Returns this widget's readonly state.

Source:
See:
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:
Returns:

the DOM element in which this widget has been
initialized, or null if not yet initialized.

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:
Parameters:
Name Type Attributes Description
params * <optional>

as of Niagara 4.10, any parameters passed to
layout() will also be passed to doLayout().
Returns:

A promise that's resolved once the layout has
completed.

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:
See:
Parameters:
Name Type Attributes 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

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:
Since:
  • Niagara 4.12
Parameters:
Name Type Attributes Description
value *
params * <optional>
Returns:
Type
Promise.<*>

properties() → {module:bajaux/Properties}

Description:

  • Return the Properties for a widget.

Source:
Returns:

The Properties for a widget.

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:
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

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:
Since:
  • Niagara 4.10

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:
Parameters:
Name Type Attributes 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.
Returns:

a promise to be resolved with the value resolved from
the given data object

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:
See:
Parameters:
Name Type Attributes 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)

Description:

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

Source:
Parameters:
Name Type Description
commandGroup module:bajaux/commands/CommandGroup

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:
See:
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 of initialize
followed by doEnabled have both been completed. It will reject if
initialize or doEnabled fail.

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:
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;
  });
Parameters:
Name Type Description
modified Boolean | *

(a non-Boolean will be checked for truthiness)

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:
See:
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 of initialize
followed by doReadonly have both been completed. It will reject if
initialize or doReadonly fail.

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:
Returns:

A promise to be resolved with the widget's description

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:
Returns:

A promise to be resolved with the widget's display name

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:
Returns:

A promise to be resolved with the widget's icon URI.

Type
Promise

trigger()

Description:

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

Source:

validate() → {Promise}

Description:

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

Source:
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() → {module:bajaux/Validators}

Description:

  • Return the widget's Validators.

Source:
See:
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:
See:
Returns:

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

Type
* | null

(static) in(el) → {module:bajaux/Widget|undefined}

Description:

  • Find the Widget instance living in this DOM element.

    Or: "what Widget is in this element?"

Source:
Since:
  • Niagara 4.6
See:
Parameters:
Name Type Description
el JQuery | HTMLElement
Returns:
Type
module:bajaux/Widget | undefined

(static) owning(el) → {module:bajaux/Widget|undefined}

Description:

  • Walk up the DOM tree to find the closest Widget instance. Will find a Widget that is
    initialized directly into the given element, or is initialized into one of its ancestors.

    Or: "what Widget is this element in?"

Source:
Since:
  • Niagara 4.15
See:
Parameters:
Name Type Description
el JQuery | HTMLElement
Returns:
Type
module:bajaux/Widget | undefined