|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
public interface Editing
Data being displayed by a grid may be edited within the grid, by showing editing interfaces embedded inside the cells of the grid.
Enabling editing
Editing is enabled when canEdit
is true
. When enabled,
the user can begin editing via the
editEvent
, typically click or double-click. Editing can also be triggered
programmatically by a call to ListGrid.startEditing()
or
ListGrid.startEditingNew()
.
New record creation
By default, editing is restricted to existing records. Setting listEndEditAction
to
"next" allows the user to create new records by simply navigating off the end of the dataset
with the keyboard. Editing of new records can also be initiated with
ListGrid.startEditingNew()
, for example, from a button outside the grid.
Saving changes
Saving of changes is triggered automatically when the user navigates out of the row or cell
being edited (based on saveByCell
) or when the user ends editing. For
a "mass update" interface, automatic saving of changes can be disabled entirely via
autoSaveEdits
, in which case a manual call to
com.smartgwt.client.widgets.grid.ListGrid#saveEdits
or ListGrid.saveAllEdits()
is required
to trigger saving.
If a grid has no DataSource, saving means that the properties of the ListGridRecord
s
in data
are directly changed.
For a grid with a DataSource, saving will be accomplished by using DataSource "update"
operations for existing records, and DataSource "add" operations for new records. If multiple
records have been edited and ListGrid.saveAllEdits()
is called,
RPCManager.startQueue()
will be automatically used to enable all
edits to be saved in one HTTP turnaround (if using the SmartGWT Server).
By default, a grid will send only updated fields and the primaryKey field as part of
data
so that the server can discern which fields the user actually changed.
However, the grid always includes the original field values in the
dsRequest as oldValues
.
Note that although it is possible to load DataSource data without actually declaring a
primaryKey
, a primaryKey must be declared for
editing and saving. The primaryKey value is how SmartGWT identifies the changed
record to the server.
Validation
Any time saving is attempted, validation is automatically triggered. Values entered by the
user will be checked against the validators
and the
validators
. Any invalid values abort an attempted save.
Similar to editing and saving, validation can be done on row transitions or on cell
transitions by setting validateByCell
, or can be disabled entirely
via neverValidate
.
Editability of cells
Editors will either be shown for the complete row or for a single cell based on
ListGrid
. Whether a cell can be edited can be controlled on a
per field basis by setting canEdit
, or on a per-record basis
by setting recordEditProperty
on a
${isc.DocUtils.linkForRef('object:ListGridRecord','record')}, or can be controlled on an arbitrary, programmatic basis via
an override of ListGrid.canEditCell(int, int)
.
Cells which are not editable just display the cell's current value.
Keyboard Navigation
Full keyboard navigation is supported by default, including Tab and Shift-Tab to navigate between cells in a row, and Up Arrow and Down Arrow to traverse rows. Several properties on both grids and fields, all named *EditAction, control navigation behavior of certain keys (eg Enter).
You can use ListGrid.startEditing()
to
programmatically move editing to a particular cell, for example, during a
ListGridField.addChangedHandler(com.smartgwt.client.widgets.grid.events.ChangedHandler)
event.
editValues (unsaved changes)
The term "editValues" means changes that the user has made to the dataset which have not been saved. The grid manages and stores editValues separately from the data itself in order to allow the user to revert to original values, and in order to enable to grid to send only updated fields to the server.
Because editValues are stored separately, if you directly access the dataset (eg via
grid.data.get()
) you will see the records without the user's unsaved changes.
Many APIs exist for retrieving and managing editValues (search for editValue).
For the common case of needing to access the record-as-edited, you can call
ListGrid.getEditedRecord(int)
.
When accessing and manipulating edited data, you should think carefully about whether you want to be working with the original data or with the edited version. Values entered by the user may not have been validated yet, or may have failed validation, hence you may find a String value in a field of type "date" or "int", which could cause naive formatters or totalling functions to crash.
Setting editValues is fully equivalent to the user making changes to data via the editing UI. If you also allow editing external to the grid, setting editValues is one way to combine changes from external editors into the grid's edits, so that you can do a single save.
Customizing Cell Editors
When a cell is being edited, the editor displayed in the cell will be a FormItem
.
The editor type for the cell will be determined by com.smartgwt.client.widgets.grid.ListGrid#getEditorType
based on the
specified editorType
or type
for the field in
question.
You can customize the editor by setting editorProperties
to a set of
properties that is valid for that FormItem type. Custom FormItem classes are also allowed,
for example, you may use icons
to create an icon that launches a separate
Dialog
in order to provide an arbitrary interface that allows the user to select the
value for a field.
Events
Editing triggers several events which you can provide handlers for in order to customize
editing behavior. Some of the most popular are ListGridField.addChangeHandler(com.smartgwt.client.widgets.grid.events.ChangeHandler)
,
ListGridField.addChangedHandler(com.smartgwt.client.widgets.grid.events.ChangedHandler)
for detecting changes made by the user,
com.smartgwt.client.widgets.grid.ListGrid#addCellChangedHandler
for detecting changes that have been successfully saved,
and ListGrid.addEditorEnterHandler(com.smartgwt.client.widgets.grid.events.EditorEnterHandler)
and ListGrid.addEditorExitHandler(com.smartgwt.client.widgets.grid.events.EditorExitHandler)
for detecting user
navigation during editing.
You can also install event handlers directly on the FormItem-based editors used in the grid
via editorProperties
as mentioned above. When handling
events on items, or which involve items, be aware that in addition to standard
FormItem
APIs, editors have the following properties:
- rowNum
: The rowNum of the record being edited.
- colNum
: The colNum of the cell being edited.
- grid
: A pointer back to the listGrid containing the record.
com.smartgwt.client.widgets.form.DynamicForm#getEditorType
,
com.smartgwt.client..CubeGrid#setEditValue
,
com.smartgwt.client..CubeGrid#getEditValue
,
com.smartgwt.client..CubeGrid#getEditedRecord
,
com.smartgwt.client..CubeGrid#getEditedCell
,
com.smartgwt.client..CubeGrid#getEditValues
,
com.smartgwt.client..CubeGrid#clearEditValue
,
com.smartgwt.client..CubeGrid#saveEdits
,
com.smartgwt.client..CubeGrid#getAllEditCells
,
com.smartgwt.client..CubeGrid#discardAllEdits
,
com.smartgwt.client..CubeGrid#recordHasChanges
,
com.smartgwt.client..CubeGrid#hasChanges
,
com.smartgwt.client..CubeGrid#saveAllEdits
,
com.smartgwt.client.widgets.grid.ListGridField#defaultDynamicValue
,
com.smartgwt.client.widgets.grid.ListGridField#editorEnter
,
com.smartgwt.client.widgets.grid.ListGridField#editorExit
,
com.smartgwt.client.widgets.grid.ListGridField#cellChanged
,
com.smartgwt.client.widgets.grid.ListGridField#formatEditorValue
,
com.smartgwt.client.widgets.grid.ListGridField#parseEditorValue
,
com.smartgwt.client.widgets.grid.ListGridField#change
,
com.smartgwt.client.widgets.grid.ListGridField#changed
,
ListGrid.canEditCell(int, int)
,
ListGrid.startEditing()
,
com.smartgwt.client.widgets.grid.ListGrid#getEditorValueMap
,
com.smartgwt.client.widgets.grid.ListGrid#setEditorValueMap
,
com.smartgwt.client.widgets.grid.ListGrid#getEditorType
,
ListGrid.startEditingNew()
,
com.smartgwt.client.widgets.grid.ListGrid#getAllEditRows
,
ListGrid.getEditValues(int)
,
ListGrid.getEditedRecord(int)
,
ListGrid.getEditedCell(int, java.lang.String)
,
ListGrid.setEditValue(int, int, java.lang.String)
,
ListGrid.getEditValue(int, int)
,
ListGrid.clearEditValue(int, java.lang.String)
,
ListGrid.getEditRow()
,
ListGrid.getEditCol()
,
com.smartgwt.client.widgets.grid.ListGrid#getEditField
,
ListGrid.cancelEditing()
,
ListGrid.endEditing()
,
ListGrid.discardAllEdits()
,
ListGrid.discardEdits(int, int)
,
com.smartgwt.client.widgets.grid.ListGrid#saveEdits
,
ListGrid.rowHasChanges(int)
,
ListGrid.hasChanges()
,
ListGrid.cellHasChanges(int, int)
,
ListGrid.saveAllEdits()
,
com.smartgwt.client.widgets.grid.ListGrid#cellChanged
,
com.smartgwt.client.widgets.grid.ListGrid#editComplete
,
com.smartgwt.client.widgets.grid.ListGrid#editFailed
,
com.smartgwt.client.widgets.grid.ListGrid#editorEnter
,
com.smartgwt.client.widgets.grid.ListGrid#rowEditorEnter
,
com.smartgwt.client.widgets.grid.ListGrid#editorExit
,
com.smartgwt.client.widgets.grid.ListGrid#rowEditorExit
,
com.smartgwt.client.widgets.grid.ListGrid#formatEditorValue
,
com.smartgwt.client.widgets.grid.ListGrid#parseEditorValue
,
ListGridField.getEditorImageURLPrefix()
,
ListGridField.getEditorImageURLSuffix()
,
com.smartgwt.client.widgets.grid.ListGridField#getIcons
,
ListGridField.getEditorIconWidth()
,
ListGridField.getEditorIconHeight()
,
ListGridField.getDefaultIconSrc()
,
ListGridField.getIconVAlign()
,
ListGridField.getCanEdit()
,
com.smartgwt.client.widgets.grid.ListGridField#getDefaultValue
,
ListGridField.getEnterKeyEditAction()
,
ListGridField.getEscapeKeyEditAction()
,
com.smartgwt.client.widgets.grid.ListGridField#getEditorType
,
com.smartgwt.client.widgets.grid.ListGridField#getEditorProperties
,
ListGrid.getModalEditing()
,
com.smartgwt.client.widgets.grid.ListGridField#getEditorValueMap
,
ListGrid.getCanEdit()
,
ListGrid.getRecordEditProperty()
,
ListGrid.getEditByCell()
,
ListGrid.getSaveByCell()
,
ListGrid.getWaitForSave()
,
ListGrid.getStopOnErrors()
,
ListGrid.getAutoSaveEdits()
,
ListGrid.getConfirmCancelEditing()
,
ListGrid.getCancelEditingConfirmationMessage()
,
ListGrid.getConfirmDiscardEdits()
,
ListGrid.getConfirmDiscardEditsMessage()
,
ListGrid.getDiscardEditsSaveButtonTitle()
,
ListGrid.getRowEndEditAction()
,
ListGrid.getListEndEditAction()
,
ListGrid.getEnterKeyEditAction()
,
ListGrid.getEscapeKeyEditAction()
,
ListGrid.getEditEvent()
,
ListGrid.getEditOnFocus()
,
ListGrid.getSelectOnEdit()
,
ListGridField.getCanToggle()
,
ListGrid.getLongTextEditorThreshold()
,
ListGrid.getLongTextEditorType()
,
Calendar.getEventSnapGap()
,
Calendar.getShowQuickEventDialog()
,
com.smartgwt.client.widgets.calendar.Calendar#getEventEditorFields
,
com.smartgwt.client.widgets.calendar.Calendar#getEventDialogFields
,
RowEndEditAction
,
EnterKeyEditAction
,
EscapeKeyEditAction
,
EditCompletionEvent
,
ListGridEditEvent
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |