module:nmodule/webEditors/rc/fe/BaseWidget

module:nmodule/webEditors/rc/fe/BaseWidget

new (require("nmodule/webEditors/rc/fe/BaseWidget"))(paramsopt)

Description:

  • Base class for all webEditors widgets. This widget includes lots of
    sugar for the Widget constructor, utilities for managing nested
    collections of Widgets, etc.

    Note that this widget has no idea what BajaScript is; for more
    Baja-specific editor functionality, reach for BaseEditor.

Source:
Mixes In:
  • tinyevents
Extends:
  • module:bajaux/Widget
Parameters:
Name Type Attributes Description
params Object <optional>
Properties
Name Type Attributes Default Description
properties module:bajaux/Properties | Object <optional>

properties to
add to this editor's underlying bajaux/Properties instance. This can be
either a Properties instance or an object literal.
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>
 'webEditors'

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.

Extends

  • module:bajaux/Widget

Members

(static) SHOULD_VALIDATE :string

Description:

  • String Property name used by shouldValidate().

Source:

String Property name used by shouldValidate().

Type:
  • string

(static) VALIDATE_ON_READ :number

Description:

  • The shouldValidate Property should match this value if this editor
    should always validate on read.

Source:

The shouldValidate Property should match this value if this editor
should always validate on read.

Type:
  • number

(static) VALIDATE_ON_SAVE :number

Description:

  • The shouldValidate Property should match this value if this editor
    should always validate on save.

Source:

The shouldValidate Property should match this value if this editor
should always validate on save.

Type:
  • number

(static) VALUE_READY_EVENT :string

Description:

  • VALUE_READY_EVENT is a completely optional event. You may choose to
    trigger this event when the user has taken some action to indicate that
    the given value is the desired one, without actually saving the editor.

    Why would you want to trigger this event? Currently the best reason would
    be if your editor is shown in a dialog, and it has some kind of selection
    mechanism (dropdown, radio buttons, list etc.). This would allow the user
    to simply select a value and allow the dialog to close, without actually
    making the user click OK to save.

    For instance, feDialogs listens for VALUE_READY_EVENT when showing an
    editor in a dialog. When the event is emitted, the dialog will
    automatically be saved and closed.

    To illustrate, an OrdChooser in a dialog will show a station nav tree. When
    the user double-clicks a file, VALUE_READY_EVENT will be emitted.
    Therefore all the user must do is double-click the file to select it.
    Without the event, the user would have to click to select the file, then
    manually go down and click OK to commit the changes.

    You may also respond to this event when fired directly on the editor
    itself. Why would you do this? Certain framework modules may invert this
    pattern, that is, the framework may notify the editor itself that the user
    has chosen a value he or she is satisfied with, without saving the editor.
    An example of this is, again, feDialogs: when the user clicks OK, the
    current value will be read and used elsewhere, although the editor may not
    itself be saved.

    The two uses refer to the same use case (the user likes this value even
    without wishing to commit it to the station yet); they just go in two
    different directions: one is the editor notifying the framework, the other
    is the framework notifying the editor. Be careful not to re-trigger one in
    a handler for the other, or you may get an infinite loop!

Source:
See:
  • module:webEditors/rc/fe/feDialogs

VALUE_READY_EVENT is a completely optional event. You may choose to
trigger this event when the user has taken some action to indicate that
the given value is the desired one, without actually saving the editor.

Why would you want to trigger this event? Currently the best reason would
be if your editor is shown in a dialog, and it has some kind of selection
mechanism (dropdown, radio buttons, list etc.). This would allow the user
to simply select a value and allow the dialog to close, without actually
making the user click OK to save.

For instance, feDialogs listens for VALUE_READY_EVENT when showing an
editor in a dialog. When the event is emitted, the dialog will
automatically be saved and closed.

To illustrate, an OrdChooser in a dialog will show a station nav tree. When
the user double-clicks a file, VALUE_READY_EVENT will be emitted.
Therefore all the user must do is double-click the file to select it.
Without the event, the user would have to click to select the file, then
manually go down and click OK to commit the changes.

You may also respond to this event when fired directly on the editor
itself. Why would you do this? Certain framework modules may invert this
pattern, that is, the framework may notify the editor itself that the user
has chosen a value he or she is satisfied with, without saving the editor.
An example of this is, again, feDialogs: when the user clicks OK, the
current value will be read and used elsewhere, although the editor may not
itself be saved.

The two uses refer to the same use case (the user likes this value even
without wishing to commit it to the station yet); they just go in two
different directions: one is the editor notifying the framework, the other
is the framework notifying the editor. Be careful not to re-trigger one in
a handler for the other, or you may get an infinite loop!

Type:
  • string
Examples
dom.on('dblclick', '.listItem', function (e) {
    var value = $(this).text();
    dom.trigger(BaseWidget.VALUE_READY_EVENT, [ value ]);
  });
function MyEditor() {
  ...
  var that = this;
  that.on(VALUE_READY_EVENT, function (newValue) {
    console.log('The user has chosen to commit this value: ' + newValue);
    //...even though it may not be written to the station yet.
    return that.saveToMostRecentlyUsedValues(newValue);
  });
}

Methods

destroy() → {Promise}

Description:

  • Removes the editor class and emits a destroyed tinyevent.

Source:
Returns:

call to module:bajaux/Widget#destroy

Type
Promise

initialize(dom) → {Promise}

Description:

  • Every BaseWidget will add the editor class to the element and emit an
    initialized tinyevent when initialized.

Source:
Parameters:
Name Type Description
dom JQuery
Returns:

call to module:bajaux/Widget#initialize

Type
Promise

shouldValidate(flagopt) → {Boolean}

Description:

  • This provides an extra hook for an editor to declare itself as needing to
    be validated before saving or not. The default behavior is to return true
    if this editor is modified, or if a shouldValidate bajaux Property
    is present and truthy. If neither of these conditions is true, it will
    check all known child editors, and return true if it has a child editor
    that should validate.

    If flag is given, then the check against the shouldValidate
    Property will return true only if the value bitwise matches the
    parameter. See BaseWidget.SHOULD_VALIDATE_ON_SAVE, etc.

Source:
Parameters:
Name Type Attributes Description
flag Number <optional>
Returns:
Type
Boolean