SMART datagrid v.1 > Concepts

Concepts.Undoing Overview  Preparing...

1. Overview

Dataludi Grid provides options of Undoing and Redoing user input or data set updates stage by stage. Data Set Updates can occur in Grid and Data Set levels. In the grid, it will occur when the user updates and appends rows, and in the data set updates, it will occur when the data edited in the grid is transferred to data set or directly call data set API methods. 

If you want to enable Undo/Redo during grid row editing, you should specify GridBase.undoable as true. And, if you want to enable Undo/Redo within data set, you should specify DataSet.undoable as true. In most cases, when provide Undo/Redo UI to the user, you can specify both properties as true. If change undoable property during the run time or call DataSet.clearUndo, GridBase.clearUndo, Undo stack will be emptied and Undo history will be started newly. 

    dataset.setUndoable(true);
    grid.setUndoable(true);

If enable Undo/Redo, the user can run Undoing and Redoing by typing Ctrl+Z and Ctrl+Y keys during the run time. In the script, it calls GridBase.undo and redo to run Undo and Redo. In addition, you can call GridBase.canUndo and canRedo to check whether you can run Undo and Redo now. If the state of canUndo and canRedo is changed, onUndoStateChanged event will be fired. 

    grid.onUndoStateChanged = function (grid, canUndo, canRedo) {
        document.getElementById("btnUndo").disabled = !canUndo;  
        document.getElementById("btnRedo").disabled = !canRedo;  
    };
    $("#btnUndo").click = function () {
        grid.undo();
    };
    $("#btnReco").click = function () {
        grid.redo();
    };

The way to maintain Undo and Redo lists is the same as handling in the common document application. If each change call is added in Undo stack and call Undo, next Undo location will be moved to prior change call. If it has moved to the bottom of Undo stack, canUndo will become false. Redo call moves in the opposite direction of Undo and runs until the latest change call point. In addition, if Redo is not done in the midpoint of Undo stack and a new change call is added, Redo calls being kept from that point to the latest will be removed. 

2. Data Set Editing

If data set is undoable, all methods of official Grid Data Set and Tree Data Set changing data set will be managed in Undo stack of data set. In other words, you can Undo and Redo data set change. The user can use Ctrl+Z, Ctrl+Y keys during the run time, and can also directly call undo, redo method. 

In the table below, it has listed methods being managed in two data sets. 

Method	UI	Description
clearRows		Clear all existing rows.
setRows		Clear all existing rows, and append new rows.
setXmlRows		Clear all existing rows, and append new rows with XML source.
setRowCount		Change the number of data rows.
setValue		Change the value of one row, one field.
updateRow		Change the value of one row.
updateRows		Change multiple rows at the same time.
updateXmlRows		Change the value of multiple rows at the same time with XML source.
updateValues		Change the value of rows matching the criteria.
deleteRow		Delete one row.
deleteRows		Delete multiple rows.
insertRow		Insert one row.
appendRow		Append one row to the end.
insertRows		Insert multiple rows.
insertXmlRows		Insert multiple rows with XML source.
appendRows		Append multiple rows to the end.
appendXmlRows		Append multiple rows to the end with XML source.
moveRow		Move one row to another location.
moveRows		Move multiple rows to another location at the same time.
setRowState		Force to change the state of one row.
setRowStates		Force to change the state of multiple rows at the same time.
clearRowStates		Reset the state of all rows.
restoreUpdatedStates		Restore the state of updated rows.
restoreUpdatedRows		Restore the value of updated rows.
setRowTag		Set the tag of one row.
setRowTags		Set the tag of multiple rows.
unsetRowTags		Remove the tag of one or more rows.
clearRowTags		Remove the tag of all rows.

Method	UI	Description
clearRows		Clear all existing rows.
setRows		Clear all existing rows, and append new rows.
setXmlRows		Clear all existing rows, and append new rows with XML source.
setJsonRows		Clear all existing rows, and append new rows with JSON array.
insertDataRows		Insert new rows in the specified location with array.
insertJsonRows		Insert new rows in the specified location with JSON array.
insertXmlRows		Insert new rows in the specified location with XML source.
appendDataRows		Append new rows to the end with array.
appendJsonRows		Append new rows to the end with JSON array.
appendXmlRows		Append new rows to the end with XML source.
insertRow		Insert one row in the specified location.
addRow		Append one row to the end.
insertRows		Insert multiple rows in the specified location.
addRows		Append multiple rows to the end.
deleteRow		Delete one row.
deleteRows		Delete multiple rows.
setValue		Update the value of one row, one field.
updateRow		Update one row.
setRowTag		Set the tag of one row.
setRowTags		Set the tag of multiple rows at the same time.
unsetRowTags		Remove the tag of specified rows.
clearRowTags		Remove the tag of all rows.
setRowState		Force to change the state of one row.
setRowStates		Force to change the state of multiple rows.
clearRowStates		Reset the state of all rows.

3. Grid Row Editing

If specify grid undoable as true, when the user updates or appends rows during the run time, it will manage cell editing activity in grid Undo stack. The user can Undo and Redo by Ctrl+Z and Ctrl+Y keys respectively. And, he can also directly call undo and redo. In general, it will proceed as in the process below. 

• When start editing, it will create grid Undo stack.
• Whenever the user updates cells, editing history will be added in the stack.
• Use Ctrl+Z keys to run Undoing, and move the focus to the corresponding cell.
• Use Ctrl+Y keys to run Redoing, and move the focus to the corresponding cell.
• If type Ctrl+Z keys in the state of reverting to the first editing history by Undoing, it will Cancel Row Editing according to EditOptions.cancelWhenUndo settings.
• Only the editing directly entered by the user will be added in the stack.
• If type Ctrl+Z when the editor is being displayed, Undoing of editor level will be run, and if type Ctrl+Z again in the same state of start value, Undoing will be run.

Like data set, if anything changes in grid Undo stack, onUndoStateChanged event will be fired. You can check whether Undoing and Redoing are possible within this event, and can also know through canUndo and canRedo directly. 

4. Group Action

When SMART datagrid implements a special UI needed in the application besides the default UI, it may need to call more than one data set method at the same time, so that they can be considered as one call from the user's perspective. In other words, if should only use Ctrl+Z and Ctrl+Y keys to run Undoing and Redoing, you can use GroupAction. 

As in the code below, there are two ways to create and run GroupAction. First, request GroupAction from data set and add methods which will be run in the returned GroupAction. And then, request data set to run GroupAciton. 

    // Request new group action
    var ga = ds.createActionGroup();
    // Add change operations
    ga.updateRow(0, values);
    ga.deleteRows([1, 2]);
    ga.insertRow(1, newValues[0]);
    ga.insertRow(2, newValues[1]);
    // Request to run.
    ds.execute(ga);

Similarly, you can use beginActions and endActions of data set to implement it. Differently from createActionGroup, it will not be able to call other change method of the corresponding data set except through GroupAction returned implicitly between beginActions and endActions. 

    // Request new group action
    ds.beginActions();
    // Add change operations
    ds.updateRow(0, values);
    ds.deleteRows([1, 2]);
    ds.insertRow(1, newValues[0]);
    ds.insertRow(2, newValues[1]);
    // Request to run.
    ds.endActions();

The important thing is, GroupAction will not be proceeded together with DB transaction. In other words, not all change requests being contained in the group will be run or failed. Changes will be reflected in the data set until failure occurs, and the history up to that point will be kept in data set stack. 

5. Edit Actions

Besides user data cell editing, Delete Selection and Erase Selection can also be returned. And, data editing can also be returned with using AutoFill handle. 

All these things will be internally defined by Unit Edit Action, and Unit Actions will be managed through Undo/Redo stack. Data Update API functions of DataSet are also manged by Actions. 

6. Bookmark

7. Exception Handling

In most cases, the methods being called depending on user change will fire check event before running the change and commit event after the change. For example, GridDataSet.deleteRow will fire onRowDeleting event before deleting rows, and if explicitly return Boolean false within event handler or throw an exception, delete operation will be terminated. And, it will fire onRowDeleted event after committing delete operation. 

If DataSet is undoable, you should consider to prevent the distortion of data set in the flow of change methods being run continuously and Undone/Redone. And, you should keep run history as much as possible. To do this, SMART datagrid implements a concise policy associated with exception. 

Exception during execution

• Before the change, if explicitly return false within check event handler, it will be ignored and will not be added in the stack.
• If throw an exception in check event handler, it will not be added in the stack and transfer the exception.
• If throw an exception in commit event handler, it will be added in the stack and transfer the exception. Run history after being added will be all removed.
• If throw an exception in other time, it will not be added in the stack, and run history from this point will be all removed from the stack.
• If run normally, the stack after running will also be removed.

Exception during Undo/Redo

• Check event before the change will not be fired during Undoing and Redoing.
• Commit event, teamed with the event before the change, will be fired only if eventsOnStack is specified as true, and if throw an exception in the event handler, it will only transfer the exception and proceed Undo/Redo.
• Other commit events are being fired always and handled equally.
• If throw an exception in other time, stack histories from this point will be removed.

8. Exception Handling in Group Action

As described above, GroupAction is unit activity only for end user, but data set change will be run in request unit being contained in the group. 

Exception during execution

• When run the requests being contained in the group, if throw an exception in commit event, it will be maintained as a group containing requests only before this and contained in the stack, and will transfer the exception.
• If throw an exception in other time, the group will not be contained in the stack of data set, and the histories of data set stack after this point will also be removed. And, the exception will be transferred.

Exception during Undo/Redo

• If throw an exception in each running commit event, it will maintain the group to only contain the previous histories and proceed Undoing and Redoing, and will transfer the exception.
• If throw an exception outside commit event, it will remove all from this group in data set stack and transfer the exception.

9. UI Issue

Since "Editing begins after open the document." is the common user experience, Undoable state of DataSet should be started after loading the first data set as possible. In addition, it can be an appropriate UI to empty Undo stack and newly start by calling DataSet.clearUndo or GridBase.clearUndo after uploading the changed data set to the server. 

10. Performance Issue

If DataSet is changed to undoable state, all unit call histories which change the value of data set will be saved in Undo stack basically together with necessary information needed for restoration. It will all contain parameters used in function call and values to be stored. Therefore, be careful not to even store unnecessary data from user interface. In particular, undoable should be enabled after loading the initial data set, and the stack should be initialized through clearUndo after transferring edit data set to server. 

See Also

DataSet.undoable

DataSet.clearUndo

GridBase.undoable

GridBase.clearUndo

GridBase.undo

GridBase.redo

GridBase.canUndo

GridBase.canRedo

GridBase.onUndoStateChanged

EditOptions.undoable

EditOptions.deletable

EditOptions.erasable

EditOptions.cancelWhenUndo

GridBase.deleteSelection

GridBase.eraseSelection

AutoFill

Examples

Undo & Redo