Editor

Displays an input field, optionally editing a field of a record at a particular position.

Offers events to signal edit completion upon ENTER or focus loss (if configured to do so), or edit cancellation on ESC, or focus loss if configured that way.

Configs

103

Common

listenersEvents

Other

align: AlignSpec= {"align":"t0-t0","offset":""}

The alignment config for how this editor aligns to a target when asked to startEdit

appendToTargetParent: Boolean= false

Set to true to automatically append the Editor's element to the parent element of the element being edited.

blurAction: complete | cancel | null= complete

What action should be taken when focus moves out of the editor, either by TAB or clicking outside. May be 'complete' or 'cancel'. Any other value results in no action being taken upon focus leaving the editor leaving the application to listen for the focusOut event.

cancelKey: String= Escape

The name of the key which cancels the edit.

See https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values for key names.

completeKey: String= Enter

The name of the key which completes the edit.

See https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key/Key_Values for key names.

completeOnChange: Boolean= false

Configure as true to have editing complete as soon as the field fires its change event.

fitTargetContent: Boolean= false

Controls whether the editor should expand its width if the input field has overflow startEdit

floating: Boolean= false

Set to true to render the editor field outside the cell element in the browser viewport space, aligned to bottom of the cell. This will also default scrollAction to realign and matchSize to false. It is also recommended to set a minHeight and/or minWidth property on the align config.

hideTarget: Boolean= false

Controls whether to hide the target element when asked to startEdit

A config object, or the type string of the widget (usually a Field subclass, i.e. TextField) which this editor will encapsulate.

invalidAction: block | allow | revert= block

How to handle a request to complete the edit if the field is invalid. There are three choices:

  • block The default. The edit is not exited, the field remains focused.
  • allow Allow the edit to be completed.
  • revert The field value is reverted and the edit is completed.
matchFont: Boolean= true

Controls whether the editor should match target element's font when asked to startEdit

matchSize: Boolean | Object= true

By default, an Editor matches both dimensions, width and height of the element it is targeted at in the startEdit function.

Configure this as false to allow the editor's configured dimensions, or its CSS-imposed dimensions size it.

This may also operate with more granularity by specifying both dimensions in an object:

    // Editor can exceed its target's height
    matchSize : {
        width  : true,
        height : false
    }
ParameterTypeDescription
widthBoolean

true to match width

heightBoolean

trueto match height

columnWidget
defaultFocusContainer
labelPositionContainer
renditionContainer
rtlRTL
spanWidget

Accessibility

ariaLabelWidget
keyMapKeyMap

Content

defaultsContainer
itemsContainer
lazyItemsContainer
namedItemsContainer
textContentContainer

CSS

borderContainer
clsWidget
colorWidget
htmlClsWidget
itemClsContainer
styleWidget
uiWidget

DOM

adoptWidget
appendToWidget
contentWidget
datasetWidget
htmlWidget
idWidget
tagWidget
titleWidget

Float & align

anchorWidget
centeredWidget
draggableWidget
xWidget
yWidget

Layout

alignSelfWidget
dockWidget
flexWidget
heightWidget
hiddenWidget
hideWhenEmptyContainer
layoutContainer
layoutStyleContainer
marginWidget
maxHeightWidget
maxWidthWidget
minHeightWidget
minWidthWidget
textAlignWidget
weightWidget
widthWidget

misc

tabBarItemsContainer

Misc

dataFieldWidget
disabledWidget
localeClassLocalizable
localizableLocalizable
maskedWidget
ownerWidget
readOnlyWidget
refWidget
rippleWidget
tabWidget
tooltipWidget

Record

recordContainer

Scrolling

Properties

83

Class hierarchy

isEditor: Boolean= truereadonly
Identifies an object as an instance of Editor class, or subclass thereof.
isEditor: Boolean= truereadonlystatic
Identifies an object as an instance of Editor class, or subclass thereof.
isContainerContainer
isDelayableDelayable
isEventsEvents
isKeyMapKeyMap
isLocalizableLocalizable
isWidgetWidget

Other

A config object, or the type string of the widget (usually a Field subclass, i.e. TextField) which this editor will encapsulate.

$namestaticWidget
columnWidget
firstItemContainer
hasChangesContainer
isValidContainer
itemsContainer
labelPositionContainer
lastItemContainer
renditionContainer
rtlRTL
spanWidget
typestaticWidget
valuesContainer

Accessibility

keyMapKeyMap

CSS

clsWidget

DOM

appendToWidget
contentWidget
datasetWidget
elementWidget
htmlWidget
idWidget
styleWidget

Float & align

xWidget
yWidget

Layout

alignSelfWidget
flexWidget
heightWidget
layoutContainer
layoutStyleContainer
marginWidget
maxHeightWidget
maxWidthWidget
minHeightWidget
minWidthWidget
widthWidget

Lifecycle

configBase

Misc

cellInfoWidget
disabledWidget
localeHelperLocalizable
localeManagerLocalizable
readOnlyWidget
refWidget
tabWidget
tooltipWidget

Record

recordContainer

Visibility

hiddenWidget
isVisibleWidget

Widget hierarchy

ownerWidget
parentWidget
widgetMapContainer

Functions

70

Other

Cancel the edit and hide the editor.

Complete the edit, and, if associated with a record, update the record if possible. If editing is completed, the editor is hidden.

If the field is invalid, the invalidAction config is used to decide upon the course of action.

If a beforeComplete handler returns false then editing is not completed.

If the field's values has not been changed, then editing is terminated through cancelEdit.

Returns: Boolean -

true if editing ceased, false if the editor is still active.

Start editing

ParameterTypeDescription
editObjectObject

An object containing details about what to edit.

editObject.targetHTMLElement | Rectangle

the element or Rectangle to align to.

editObject.alignString

How to align to the target.

editObject.matchSizeBoolean

Match editor size to target size.

editObject.matchFontBoolean

Match editor's font-size size to target's font-size.

editObject.recordModel

The record to edit.

editObject.fieldString

The field name in the record to edit. This defaults to the name of the inputField. Also if record has method set + capitalized field, method will be called, e.g. if record has method named setFoobar and this config is foobar, then instead of record.foobar = value, record.setFoobar(value) will be called.

editObject.valueObject

The value to edit.

editObject.focusBoolean

Focus the field.

editObject.fitTargetContentBoolean

Pass true to allow the Editor to expand beyond the width of its target element if its content overflows horizontally. This is useful if the editor has triggers to display, such as a combo.

Returns: Promise -

Resolved promise returnstrue if editing has been started, false if an beforeStart listener has vetoed the edit.

addContainer
composeWidget
createOnFrameDelayable
disableWidget
enableWidget
focusWidget
getAtContainer
getWidgetByIdContainer
insertContainer
LstaticLocalizable
maskWidget
onEvents
recomposeWidget
relayAllEvents
removeContainer
removeAllContainer
resetValuesContainer
setValuesContainer
triggerEvents
unEvents
unmaskWidget

Configuration

applyDefaultsstaticBase

Events

Float & align

alignToWidget
setXYWidget
showByWidget
toFrontWidget

Lifecycle

createstaticWidget
destroystaticBase
initClassstaticWidget

Misc

attachTooltipstaticWidget
fromElementstaticWidget
fromSelectorstaticWidget
getByIdstaticWidget
isOfTypeNamestaticBase
mixinstaticBase
optionalLstaticLocalizable

Visibility

hideWidget
showWidget

Widget hierarchy

closestWidget
containsWidget
ownsWidget
queryWidget
queryAllWidget
upWidget

Events

24

Fired after the editor is finalized and hidden, regardless whether it was completed or aborted.

// Adding a listener using the "on" method
editor.on('afterEdit', ({ source, record }) => {

});
ParameterTypeDescription
sourceEditor

The Editor that triggered the event.

recordModel

The record that was edited.

Fired when cancellation has been requested, either by ESC, or focus loss (if configured to cancel on blur). The cancellation may be vetoed, in which case, focus is moved back into the editor.

// Adding a listener using the "on" method
editor.on('beforeCancel', ({ oldValue, value, event, source }) => {

});
ParameterTypeDescription
oldValueObject

The original value.

valueObject

The new value.

eventEvent

Included if the cancellation was triggered by a DOM event

sourceEditor

The Editor that triggered the event.

Fired when an edit completion has been requested, either by ENTER, or focus loss (if configured to complete on blur). The completion may be vetoed, in which case, focus is moved back into the editor.

// Adding a listener using the "on" method
editor.on('beforeComplete', ({ oldValue, value, source, finalize, finalize.context }) => {

});
ParameterTypeDescription
oldValueObject

The original value.

valueObject

The new value.

sourceEditor

The Editor that triggered the event.

finalizefunction

An async function may be injected into this property which performs asynchronous finalization tasks such as complex validation of confirmation. The value true or false must be returned.

finalize.contextObject

An object describing the editing context upon requested completion of the edit.

Fired before the editor is shown to start an edit operation. Returning false from a handler vetoes the edit operation.

// Adding a listener using the "on" method
editor.on('beforeStart', ({ target, record, field, value, align, hideTarget, matchSize, matchSize.width, matchSize.height, matchFont, focus }) => {

});
ParameterTypeDescription
targetHTMLElement

The element which the Editor is to overlay to edit its content.

recordModel

The record being edited.

fieldString

The name of the field if a record is being edited.

valueObject

The value to be edited.

alignString | AlignSpec

How to align the editor.

hideTargetBoolean

true if the target is to be hidden during the edit.

matchSizeBoolean | Object

Whether to match the target size. See matchSize

matchSize.widthBoolean

Match width

matchSize.heightBoolean

Match height

matchFontBoolean

Whether to match the target's font. See matchFont

focusBoolean

Whether to focus the editor's field.

Edit has been canceled without updating the associated record or element.

// Adding a listener using the "on" method
editor.on('cancel', ({ oldValue, value, event, source }) => {

});
ParameterTypeDescription
oldValueObject

The original value.

valueObject

The value of the field.

eventEvent

Included if the cancellation was triggered by a DOM event

sourceEditor

The Editor that triggered the event.

Edit has been completed, and any associated record or element has been updated.

// Adding a listener using the "on" method
editor.on('complete', ({ oldValue, value, source }) => {

});
ParameterTypeDescription
oldValueObject

The original value.

valueObject

The new value.

sourceEditor

The Editor that triggered the event.

Fire to relay a keydown event from the field.

// Adding a listener using the "on" method
editor.on('keyDown', ({ event }) => {

});
ParameterTypeDescription
eventEvent

The key event.

Fired when an edit operation has begun.

// Adding a listener using the "on" method
editor.on('start', ({ value, source }) => {

});
ParameterTypeDescription
valueObject

The starting value of the field.

sourceEditor

The Editor that triggered the event.

catchAllEvents
destroyEvents
focusInWidget
focusOutWidget
hideWidget
paintWidget
readOnlyWidget
recomposeWidget
resizeWidget
showWidget

Event handlers

24

Called after the editor is finalized and hidden, regardless whether it was completed or aborted.

new Editor({
    onAfterEdit({ source, record }) {

    }
});
ParameterTypeDescription
sourceEditor

The Editor that triggered the event.

recordModel

The record that was edited.

Called when cancellation has been requested, either by ESC, or focus loss (if configured to cancel on blur). The cancellation may be vetoed, in which case, focus is moved back into the editor.

new Editor({
    onBeforeCancel({ oldValue, value, event, source }) {

    }
});
ParameterTypeDescription
oldValueObject

The original value.

valueObject

The new value.

eventEvent

Included if the cancellation was triggered by a DOM event

sourceEditor

The Editor that triggered the event.

Called when an edit completion has been requested, either by ENTER, or focus loss (if configured to complete on blur). The completion may be vetoed, in which case, focus is moved back into the editor.

new Editor({
    onBeforeComplete({ oldValue, value, source, finalize }) {

    }
});
ParameterTypeDescription
oldValueObject

The original value.

valueObject

The new value.

sourceEditor

The Editor that triggered the event.

finalizefunction

An async function may be injected into this property which performs asynchronous finalization tasks such as complex validation of confirmation. The value true or false must be returned.

finalize.contextObject

An object describing the editing context upon requested completion of the edit.

Called before the editor is shown to start an edit operation. Returning false from a handler vetoes the edit operation.

new Editor({
    onBeforeStart({ target, record, field, value, align, hideTarget, matchSize, matchFont, focus }) {

    }
});
ParameterTypeDescription
targetHTMLElement

The element which the Editor is to overlay to edit its content.

recordModel

The record being edited.

fieldString

The name of the field if a record is being edited.

valueObject

The value to be edited.

alignString | AlignSpec

How to align the editor.

hideTargetBoolean

true if the target is to be hidden during the edit.

matchSizeBoolean | Object

Whether to match the target size. See matchSize

matchSize.widthBoolean

Match width

matchSize.heightBoolean

Match height

matchFontBoolean

Whether to match the target's font. See matchFont

focusBoolean

Whether to focus the editor's field.

Edit has been canceled without updating the associated record or element.

new Editor({
    onCancel({ oldValue, value, event, source }) {

    }
});
ParameterTypeDescription
oldValueObject

The original value.

valueObject

The value of the field.

eventEvent

Included if the cancellation was triggered by a DOM event

sourceEditor

The Editor that triggered the event.

Edit has been completed, and any associated record or element has been updated.

new Editor({
    onComplete({ oldValue, value, source }) {

    }
});
ParameterTypeDescription
oldValueObject

The original value.

valueObject

The new value.

sourceEditor

The Editor that triggered the event.

Fire to relay a keydown event from the field.

new Editor({
    onKeyDown({ event }) {

    }
});
ParameterTypeDescription
eventEvent

The key event.

Called when an edit operation has begun.

new Editor({
    onStart({ value, source }) {

    }
});
ParameterTypeDescription
valueObject

The starting value of the field.

sourceEditor

The Editor that triggered the event.

onDestroyEvents
onFocusInWidget
onHideWidget
onPaintWidget
onResizeWidget
onShowWidget

Typedefs

6

CSS variables

32
NameDescription
--b-editor-backgroundEditor background

Inherited