DADataTableRow

Overview

The DADataTableRow class represents a single data row in DADataTable. Each DADataTableRow not only maintains its data, but also keeps track of any changes made to its values, until they have been successfully applied back to the server.

The value for individual fields can be obtained in a Key-Value-Coding (KVC) compliant manner by sending a valueForKey: message, and changed by sending setValue:forKey:. Changed values will be cached locally on the row until one of the applyChanges or beginApplyChanges methods on the RemoteDataAdapter is used to send them back to the server.

Pending changes can be reverted by sending a revertValueForKey: message to revert a single field, or revert to revert all changes to the row in question. You can also obtain the current or original value for a specified field by using valueForKey: and originalValueForKey: respectively. The rowState property can be evaluated to see if a given row contains changes and whether these changes consist of the row being modified, newly inserted, or deleted.

DADataTableRow allows to change its data in several ways:

a) direct changing data

First approach (usual) you can change the data inside the row directly. After that you can or cancel your changes by calling cancel method, or send them to the server using applyChanges/beginApplyChanges methods of the DARemoteDataAdapter

b) two-phase editing data (edit, post & discard)

Another approach is that we can set a row into the edit mode by calling edit method and begin to change the data. In the edit mode, row will store its current values including pending changes that was made previously. In order to confirm or discard changes made in edit mode you will need to use post or discard methods respectively.

Second approach can be very useful for cases when you need to implement UI editor for the row and show it as the sheet. In this case any changes that was made in the editor should be done in bounds of independent editor session. And in case of editor cancellation the row should revert its state to which it was prior to opening the editor, including previous unconfirmed changes.

Read more about the Data Table Rows at Remote Data Adapter and Data Tables (Xcode).

Tasks

Working with Values

  • valueForKey:
  • setValue:forKey:
  • originalValueForKey:
  • revertValueForKey:
  • revert

Two-phase Editing Data

  • inEditMode
  • edit
  • post
  • discard

Location

 

cancel

This method cancels the uncommitted changes for all fields of the row and restores the original values.

It also set the row state to rsUnchanged and fires
DA_NOTIFICATION_TABLE_CHANGED and DA_NOTIFICATION_TABLE_INDEX_MUST_UPDATE events.

Note that cancel method just rollback the changes for given row. If you call it to the newly created row, it does not lead to its removal from an array of table rows. Cancel method usualy used when at some stage you want to cancel any changes you have made and start editing from the scratch.

In the case when you need to cancel adding new row, then you will need to use other cancelChangeForRow: of the DADataTabe class.

- (void) cancel

cancelChangeForKey:

- (void) cancelChangeForKey:(nonnull NSString *)key

Parameters:

  • key:

cancelChangeForPosition:

- (void) cancelChangeForPosition:(NSUInteger)position

Parameters:

  • position:

changed

Returns a boolean flag indicating whether it has any changes (rowstate != rsUnchanged), or not.

@property (readonly) BOOL changed

changedColumns2

- (NSArray *) changedColumns2

changeId  assign

Returns the change identifier for the row. This ID is used internally for tracking the row when sending changes back to the server, and consolidating server responses on success or failure.

@property (assign) int changeId

checkModifiedFlags

- (BOOL) checkModifiedFlags

clearModifiedFlags

- (void) clearModifiedFlags

commit

- (void) commit

commitChangeForPosition:

- (void) commitChangeForPosition:(NSUInteger)position

Parameters:

  • position:

data  retain

@property (retain) NSArray *data

discard

This method cancels the changes for a row in edit mode and restores the original values. Finaly method turns off edit mode for the row.

It is similar to cancel method but rollback changes only for row in edit mode

- (void) discard

edit

method moves the row into the edit mode. Edit Mode allows you to make any changes which will not be visible outside until you perform post call at the record. Thus commiting changes goes in two separate phases. At the first stage you are entering edit mode and make changes, then posting them. And at the second stage you can apply changes at the server side.

- (void) edit

fieldCount

Returns the number of fields in the row.

@property (readonly) NSUInteger fieldCount

getModifiedFlagForFieldIndex:

- (BOOL) getModifiedFlagForFieldIndex:(NSUInteger)fieldIndex

Parameters:

  • fieldIndex:

inEditMode

Boolean flag that shows is given row in Edit Mode or not

@property (readonly) BOOL inEditMode

initModifiedFlags

- (void) initModifiedFlags

initWithTable:andCapacity:

- (nonnull instancetype) initWithTable:(nonnull DADataTable *)table andCapacity:(NSUInteger)capacity

Parameters:

  • table:
  • capacity:

initWithTable:andData:

- (nonnull instancetype) initWithTable:(nonnull DADataTable *)table andData:(nonnull NSArray *)rowData

Parameters:

  • table:
  • rowData:

lock

method lock row and prevent any future changes there. Lock is used internally by the DARemoteDataAdapter. Locking is important in case of asynchronous updating data. We need to be sure that pending changes will not be modified at the client side while they trying to apply at the server

- (void) lock

locked

Boolean flag that shows is the row in the locked state or not.

@property (readonly) BOOL locked

objectForKeyedSubscript:

- (nullable id) objectForKeyedSubscript:(nonnull NSString *)key

Parameters:

  • key:

originalValueForKey:

- (nullable id) originalValueForKey:(nonnull NSString *)key

Parameters:

  • key:

originalValueForPosition:

- (id) originalValueForPosition:(NSUInteger)position

Parameters:

  • position:

post

Method post changes and exit edit mode.

- (void) post

revert

Reverts all changes in the row and returns it to rsUnchanged state.

- (void) revert

revertValueForKey:

- (void) revertValueForKey:(nonnull NSString *)aKey

Parameters:

  • aKey:

rowState

Returns the current state (Unchanged, Modified, Added, Deleted) for the row.

@property (readonly) enum DADataTableRowState rowState

setModifiedFlag:forFieldIndex:

- (void) setModifiedFlag:(BOOL)changed forFieldIndex:(NSUInteger)fieldIndex

Parameters:

  • changed:
  • fieldIndex:

setObject:forKeyedSubscript:

- (void) setObject:(nullable id)obj forKeyedSubscript:(nonnull NSString *)key

Parameters:

  • obj:
  • key:

setRowState:

- (void) setRowState:(enum DADataTableRowState)newState

Parameters:

  • newState:

setTable:

- (void) setTable:(DADataTable *)newTable

Parameters:

  • newTable:

setValue:forKey:

- (void) setValue:(nullable id)value forKey:(nonnull NSString *)key

Parameters:

  • value:
  • key:

setValue:forPosition:

- (void) setValue:(id)value forPosition:(NSUInteger)position

Parameters:

  • value:
  • position:

silentlySetValue:forPosition:

- (void) silentlySetValue:(id)value forPosition:(NSUInteger)position

Parameters:

  • value:
  • position:

table

@property (readonly) nonnull DADataTable *table

testNewValue:forPosition:

- (BOOL) testNewValue:(id)value forPosition:(NSUInteger)position

Parameters:

  • value:
  • position:

testPosition:forWriting:

- (void) testPosition:(NSUInteger)position forWriting:(BOOL)forWriting

Parameters:

  • position:
  • forWriting:

unlock

This method is used internally by DARemoteDataAdapter to unlock the row and allows their future changes. Unlock is called after the server returns a response if the request was successful or unsuccessful

- (void) unlock

valueForKey:

- (nullable id) valueForKey:(nonnull NSString *)key

Parameters:

  • key:

valueForPosition:

- (id) valueForPosition:(NSUInteger)position

Parameters:

  • position:

valueForPosition:getOriginal:

- (id) valueForPosition:(NSUInteger)position getOriginal:(BOOL)getOriginal

Parameters:

  • position:
  • getOriginal:

 

changed

Returns a boolean flag indicating whether it has any changes (rowstate != rsUnchanged), or not.

@property (readonly) BOOL changed

changeId  assign

Returns the change identifier for the row. This ID is used internally for tracking the row when sending changes back to the server, and consolidating server responses on success or failure.

@property (assign) int changeId

data  retain

@property (retain) NSArray *data

fieldCount

Returns the number of fields in the row.

@property (readonly) NSUInteger fieldCount

inEditMode

Boolean flag that shows is given row in Edit Mode or not

@property (readonly) BOOL inEditMode

locked

Boolean flag that shows is the row in the locked state or not.

@property (readonly) BOOL locked

rowState

Returns the current state (Unchanged, Modified, Added, Deleted) for the row.

@property (readonly) enum DADataTableRowState rowState

table

@property (readonly) nonnull DADataTable *table

 

cancel

This method cancels the uncommitted changes for all fields of the row and restores the original values.

It also set the row state to rsUnchanged and fires
DA_NOTIFICATION_TABLE_CHANGED and DA_NOTIFICATION_TABLE_INDEX_MUST_UPDATE events.

Note that cancel method just rollback the changes for given row. If you call it to the newly created row, it does not lead to its removal from an array of table rows. Cancel method usualy used when at some stage you want to cancel any changes you have made and start editing from the scratch.

In the case when you need to cancel adding new row, then you will need to use other cancelChangeForRow: of the DADataTabe class.

- (void) cancel

cancelChangeForKey:

- (void) cancelChangeForKey:(nonnull NSString *)key

Parameters:

  • key:

cancelChangeForPosition:

- (void) cancelChangeForPosition:(NSUInteger)position

Parameters:

  • position:

changedColumns2

- (NSArray *) changedColumns2

checkModifiedFlags

- (BOOL) checkModifiedFlags

clearModifiedFlags

- (void) clearModifiedFlags

commit

- (void) commit

commitChangeForPosition:

- (void) commitChangeForPosition:(NSUInteger)position

Parameters:

  • position:

discard

This method cancels the changes for a row in edit mode and restores the original values. Finaly method turns off edit mode for the row.

It is similar to cancel method but rollback changes only for row in edit mode

- (void) discard

edit

method moves the row into the edit mode. Edit Mode allows you to make any changes which will not be visible outside until you perform post call at the record. Thus commiting changes goes in two separate phases. At the first stage you are entering edit mode and make changes, then posting them. And at the second stage you can apply changes at the server side.

- (void) edit

getModifiedFlagForFieldIndex:

- (BOOL) getModifiedFlagForFieldIndex:(NSUInteger)fieldIndex

Parameters:

  • fieldIndex:

initModifiedFlags

- (void) initModifiedFlags

initWithTable:andCapacity:

- (nonnull instancetype) initWithTable:(nonnull DADataTable *)table andCapacity:(NSUInteger)capacity

Parameters:

  • table:
  • capacity:

initWithTable:andData:

- (nonnull instancetype) initWithTable:(nonnull DADataTable *)table andData:(nonnull NSArray *)rowData

Parameters:

  • table:
  • rowData:

lock

method lock row and prevent any future changes there. Lock is used internally by the DARemoteDataAdapter. Locking is important in case of asynchronous updating data. We need to be sure that pending changes will not be modified at the client side while they trying to apply at the server

- (void) lock

objectForKeyedSubscript:

- (nullable id) objectForKeyedSubscript:(nonnull NSString *)key

Parameters:

  • key:

originalValueForKey:

- (nullable id) originalValueForKey:(nonnull NSString *)key

Parameters:

  • key:

originalValueForPosition:

- (id) originalValueForPosition:(NSUInteger)position

Parameters:

  • position:

post

Method post changes and exit edit mode.

- (void) post

revert

Reverts all changes in the row and returns it to rsUnchanged state.

- (void) revert

revertValueForKey:

- (void) revertValueForKey:(nonnull NSString *)aKey

Parameters:

  • aKey:

setModifiedFlag:forFieldIndex:

- (void) setModifiedFlag:(BOOL)changed forFieldIndex:(NSUInteger)fieldIndex

Parameters:

  • changed:
  • fieldIndex:

setObject:forKeyedSubscript:

- (void) setObject:(nullable id)obj forKeyedSubscript:(nonnull NSString *)key

Parameters:

  • obj:
  • key:

setRowState:

- (void) setRowState:(enum DADataTableRowState)newState

Parameters:

  • newState:

setTable:

- (void) setTable:(DADataTable *)newTable

Parameters:

  • newTable:

setValue:forKey:

- (void) setValue:(nullable id)value forKey:(nonnull NSString *)key

Parameters:

  • value:
  • key:

setValue:forPosition:

- (void) setValue:(id)value forPosition:(NSUInteger)position

Parameters:

  • value:
  • position:

silentlySetValue:forPosition:

- (void) silentlySetValue:(id)value forPosition:(NSUInteger)position

Parameters:

  • value:
  • position:

testNewValue:forPosition:

- (BOOL) testNewValue:(id)value forPosition:(NSUInteger)position

Parameters:

  • value:
  • position:

testPosition:forWriting:

- (void) testPosition:(NSUInteger)position forWriting:(BOOL)forWriting

Parameters:

  • position:
  • forWriting:

unlock

This method is used internally by DARemoteDataAdapter to unlock the row and allows their future changes. Unlock is called after the server returns a response if the request was successful or unsuccessful

- (void) unlock

valueForKey:

- (nullable id) valueForKey:(nonnull NSString *)key

Parameters:

  • key:

valueForPosition:

- (id) valueForPosition:(NSUInteger)position

Parameters:

  • position:

valueForPosition:getOriginal:

- (id) valueForPosition:(NSUInteger)position getOriginal:(BOOL)getOriginal

Parameters:

  • position:
  • getOriginal: