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
Configs
103Common
Other
The alignment config for how this editor aligns to a target when asked to startEdit
Set to true to automatically append the Editor's element to the parent element of the element being edited.
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.
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.
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.
Configure as true to have editing complete as soon as the field fires its change event.
Controls whether the editor should expand its width if the input field has overflow startEdit
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.
Controls whether to hide the target element when asked to startEdit
How to handle a request to complete the edit if the field is invalid. There are three choices:
blockThe default. The edit is not exited, the field remains focused.allowAllow the edit to be completed.revertThe field value is reverted and the edit is completed.
Controls whether the editor should match target element's font when asked to startEdit
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
}
| Parameter | Type | Description |
|---|---|---|
width | Boolean |
|
height | Boolean |
|
CSS
DOM
Float & align
Layout
misc
Misc
Scrolling
Properties
83
Properties
83Class hierarchy
Other
CSS
DOM
Layout
Misc
Widget hierarchy
Functions
70
Functions
70Other
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.
true if editing ceased, false if the editor is still active.
Start editing
| Parameter | Type | Description |
|---|---|---|
editObject | Object | An object containing details about what to edit. |
editObject.target | HTMLElement | Rectangle | the element or Rectangle to align to. |
editObject.align | String | How to align to the target. |
editObject.matchSize | Boolean | Match editor size to target size. |
editObject.matchFont | Boolean | Match editor's font-size size to target's font-size. |
editObject.record | Model | The record to edit. |
editObject.field | String | The field name in the record to edit. This defaults to the |
editObject.value | Object | The value to edit. |
editObject.focus | Boolean | Focus the field. |
editObject.fitTargetContent | Boolean | Pass |
Resolved promise returnstrue if editing has been started, false if an
beforeStart listener has vetoed the edit.
Configuration
Events
Misc
Widget hierarchy
Events
24
Events
24Fired 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 }) => {
});| Parameter | Type | Description |
|---|---|---|
source | Editor | The Editor that triggered the event. |
record | Model | 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 }) => {
});| Parameter | Type | Description |
|---|---|---|
oldValue | Object | The original value. |
value | Object | The new value. |
event | Event | Included if the cancellation was triggered by a DOM event |
source | Editor | 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 }) => {
});| Parameter | Type | Description |
|---|---|---|
oldValue | Object | The original value. |
value | Object | The new value. |
source | Editor | The Editor that triggered the event. |
finalize | function | An async function may be injected into this property
which performs asynchronous finalization tasks such as complex validation of confirmation. The
value |
finalize.context | Object | 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 }) => {
});| Parameter | Type | Description |
|---|---|---|
target | HTMLElement | The element which the Editor is to overlay to edit its content. |
record | Model | The record being edited. |
field | String | The name of the field if a record is being edited. |
value | Object | The value to be edited. |
align | String | AlignSpec | How to align the editor. |
hideTarget | Boolean |
|
matchSize | Boolean | Object | Whether to match the target size. See matchSize |
matchSize.width | Boolean | Match width |
matchSize.height | Boolean | Match height |
matchFont | Boolean | Whether to match the target's font. See matchFont |
focus | Boolean | 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 }) => {
});| Parameter | Type | Description |
|---|---|---|
oldValue | Object | The original value. |
value | Object | The value of the field. |
event | Event | Included if the cancellation was triggered by a DOM event |
source | Editor | 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 }) => {
});| Parameter | Type | Description |
|---|---|---|
oldValue | Object | The original value. |
value | Object | The new value. |
source | Editor | 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 }) => {
});| Parameter | Type | Description |
|---|---|---|
event | Event | The key event. |
Fired when an edit operation has begun.
// Adding a listener using the "on" method
editor.on('start', ({ value, source }) => {
});| Parameter | Type | Description |
|---|---|---|
value | Object | The starting value of the field. |
source | Editor | The Editor that triggered the event. |
Event handlers
24
Event handlers
24Called after the editor is finalized and hidden, regardless whether it was completed or aborted.
new Editor({
onAfterEdit({ source, record }) {
}
});| Parameter | Type | Description |
|---|---|---|
source | Editor | The Editor that triggered the event. |
record | Model | 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 }) {
}
});| Parameter | Type | Description |
|---|---|---|
oldValue | Object | The original value. |
value | Object | The new value. |
event | Event | Included if the cancellation was triggered by a DOM event |
source | Editor | 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 }) {
}
});| Parameter | Type | Description |
|---|---|---|
oldValue | Object | The original value. |
value | Object | The new value. |
source | Editor | The Editor that triggered the event. |
finalize | function | An async function may be injected into this property
which performs asynchronous finalization tasks such as complex validation of confirmation. The
value |
finalize.context | Object | 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 }) {
}
});| Parameter | Type | Description |
|---|---|---|
target | HTMLElement | The element which the Editor is to overlay to edit its content. |
record | Model | The record being edited. |
field | String | The name of the field if a record is being edited. |
value | Object | The value to be edited. |
align | String | AlignSpec | How to align the editor. |
hideTarget | Boolean |
|
matchSize | Boolean | Object | Whether to match the target size. See matchSize |
matchSize.width | Boolean | Match width |
matchSize.height | Boolean | Match height |
matchFont | Boolean | Whether to match the target's font. See matchFont |
focus | Boolean | 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 }) {
}
});| Parameter | Type | Description |
|---|---|---|
oldValue | Object | The original value. |
value | Object | The value of the field. |
event | Event | Included if the cancellation was triggered by a DOM event |
source | Editor | 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 }) {
}
});| Parameter | Type | Description |
|---|---|---|
oldValue | Object | The original value. |
value | Object | The new value. |
source | Editor | The Editor that triggered the event. |
Fire to relay a keydown event from the field.
new Editor({
onKeyDown({ event }) {
}
});| Parameter | Type | Description |
|---|---|---|
event | Event | The key event. |
Called when an edit operation has begun.
new Editor({
onStart({ value, source }) {
}
});| Parameter | Type | Description |
|---|---|---|
value | Object | The starting value of the field. |
source | Editor | The Editor that triggered the event. |
Typedefs
6
Typedefs
6CSS variables
32
CSS variables
32| Name | Description |
|---|---|
--b-editor-background | Editor background |