new (require("nmodule/webEditors/rc/fe/BaseWidget"))( [params])
Base class for all webEditors
widgets. This widget includes lots of
sugar for the Widget
constructor, utilities for managing nested
collections of Widget
s, etc.
Note that this widget has no idea what BajaScript is; for more
Baja-specific editor functionality, reach for BaseEditor
.
Extends:
- module:bajaux/Widget
Parameters:
Name | Type | Argument | Description | ||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params |
Object |
<optional> |
Properties
|
- Mixes In:
- tinyevents
Members
-
<static> SHOULD_VALIDATE :string
-
String
Property
name used byshouldValidate()
.Type:
- string
-
<static> VALIDATE_ON_READ :number
-
The
shouldValidate
Property
should match this value if this editor
should always validate on read.Type:
- number
-
<static> VALIDATE_ON_SAVE :number
-
The
shouldValidate
Property
should match this value if this editor
should always validate on save.Type:
- number
-
<static> VALUE_READY_EVENT :string
-
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 forVALUE_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
- See:
-
- module:webEditors/rc/fe/feDialogs
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
-
applyParams( [params])
-
Can re-apply certain params that can also be passed to the constructor.
Parameters:
Name Type Argument Description params
Object <optional>
Properties
Name Type Argument Default Description readonly
Boolean <optional>
enabled
Boolean <optional>
true must explicitly set to false to
disableproperties
module:bajaux/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 ofenabled
/readonly
is not actually changing.- Type
- Promise
-
destroy()
-
Removes the
editor
class and emits adestroyed
tinyevent.Returns:
call to module:bajaux/Widget#destroy
- Type
- Promise
-
generateId()
-
Generate a unique DOM ID. The ID will include the name of this editor's
constructor just for tracing/debugging purposes.Returns:
- Type
- String
-
getChildWidgets( [params])
-
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.Parameters:
Name Type Argument Description params
Object | jQuery <optional>
Properties
Name Type Argument 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, forinstanceof
checksReturns:
an array
of child editors- Type
- Array.<module:nmodule/webEditors/rc/fe/BaseWidget>
Examples
var kids = ed.getChildEditors(); 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.getChildEditors({ type: StringEditor });
- for instance, if this widget has one child editor for a
-
initialize(dom)
-
Every
BaseWidget
will add theeditor
class to the element and emit aninitialized
tinyevent when initialized.Parameters:
Name Type Description dom
JQuery Returns:
call to module:bajaux/Widget#initialize
- Type
- Promise
-
load(value [, params])
-
Will emit a
loaded
tinyevent.Parameters:
Name Type Argument Description value
* params
Object <optional>
Returns:
call to module:bajaux/Widget#load
- Type
- Promise
-
requestFocus()
-
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
ortextarea
element in this editor's element. -
shouldValidate( [flag])
-
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 ashouldValidate
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 theshouldValidate
Property
will return true only if the value bitwise matches the
parameter. SeeBaseWidget.SHOULD_VALIDATE_ON_SAVE
, etc.Parameters:
Name Type Argument Description flag
Number <optional>
Returns:
- Type
- Boolean