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:

This method cancels the uncommitted change for given column of the row and restores its original value. If, after canceling this change, row does not have any other uncommited changes, then its state will be set to rsUnchanged.

Finally method fires DA_NOTIFICATION_TABLE_CHANGED and DA_NOTIFICATION_TABLE_INDEX_MUST_UPDATE events.

- (void) cancelChangeForKey:(id)key

Parameters:

  • key: name of the column for which we need to cancel changes

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

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

inEditMode

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

@property (readonly) BOOL inEditMode

initWithTable:andCapacity:

Returns DADataTableRow instance initialized with a given table and given capacity of the array that will hold the data.

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

Parameters:

  • table: Reference to the owned table.
  • capacity: Capacity for the array that will hold the data. It equals the fields count for the given table.

initWithTable:andData:

Returns DADataTableRow instance initialized with the given table and the given values array.

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

Parameters:

  • table: Reference to owned table.
  • rowData: Array that holds data for the row.

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:

This method allows you to use literals in accessing row values. Instead of usual

NSString *clientName = [row valueForKey:@"ClientName"];

you can use just

NSString *clientName = row[@"ClientName"];

- (id) objectForKeyedSubscript:(id)key

Parameters:

  • key: Field name from where you want to obtain the value

originalValueForKey:

Returns the original value for the given field name. If the row (or field) has not been changed, this value is identical to the return value of valuForKey:.

- (id) originalValueForKey:(id)key

Parameters:

  • key: Field name for which to obtain the original value.

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:

Reverts change for a given field in the row. If the field in question constituted the only change, the row returns to rsUnchanged state.

- (void) revertValueForKey:(id)aKey

Parameters:

  • aKey: Field name for which to revert the value.

rowState

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

@property (readonly) enum DADataTableRowState rowState

setObject:forKeyedSubscript:

This method allows you to use literals when change values in the row. Instead of usual

[row setValue:@"John" forKey:@"ClientName"];

you can use just

row[@"ClientName"] = @"John";

- (void) setObject:(id)obj forKeyedSubscript:(id<NSCopying>)key

Parameters:

  • obj: Value you want to set for given field
  • key: Field name for which you want to set the value

setValue:forKey:

Sets a new value for the given field name.

- (void) setValue:(id)value forKey:(id)key

Parameters:

  • value: New value we want to set.
  • key: Field name for which we want to set the new value.

table

Returns reference to the DADataTable that contains this row.

@property (readonly) DADataTable *table

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:

Returns the value for the given field name.

- (id) valueForKey:(id)key

Parameters:

  • key: Field name for which we want to get the current value.

 

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

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

Returns reference to the DADataTable that contains this row.

@property (readonly) 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:

This method cancels the uncommitted change for given column of the row and restores its original value. If, after canceling this change, row does not have any other uncommited changes, then its state will be set to rsUnchanged.

Finally method fires DA_NOTIFICATION_TABLE_CHANGED and DA_NOTIFICATION_TABLE_INDEX_MUST_UPDATE events.

- (void) cancelChangeForKey:(id)key

Parameters:

  • key: name of the column for which we need to cancel changes

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

initWithTable:andCapacity:

Returns DADataTableRow instance initialized with a given table and given capacity of the array that will hold the data.

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

Parameters:

  • table: Reference to the owned table.
  • capacity: Capacity for the array that will hold the data. It equals the fields count for the given table.

initWithTable:andData:

Returns DADataTableRow instance initialized with the given table and the given values array.

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

Parameters:

  • table: Reference to owned table.
  • rowData: Array that holds data for the row.

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:

This method allows you to use literals in accessing row values. Instead of usual

NSString *clientName = [row valueForKey:@"ClientName"];

you can use just

NSString *clientName = row[@"ClientName"];

- (id) objectForKeyedSubscript:(id)key

Parameters:

  • key: Field name from where you want to obtain the value

originalValueForKey:

Returns the original value for the given field name. If the row (or field) has not been changed, this value is identical to the return value of valuForKey:.

- (id) originalValueForKey:(id)key

Parameters:

  • key: Field name for which to obtain the original value.

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:

Reverts change for a given field in the row. If the field in question constituted the only change, the row returns to rsUnchanged state.

- (void) revertValueForKey:(id)aKey

Parameters:

  • aKey: Field name for which to revert the value.

setObject:forKeyedSubscript:

This method allows you to use literals when change values in the row. Instead of usual

[row setValue:@"John" forKey:@"ClientName"];

you can use just

row[@"ClientName"] = @"John";

- (void) setObject:(id)obj forKeyedSubscript:(id<NSCopying>)key

Parameters:

  • obj: Value you want to set for given field
  • key: Field name for which you want to set the value

setValue:forKey:

Sets a new value for the given field name.

- (void) setValue:(id)value forKey:(id)key

Parameters:

  • value: New value we want to set.
  • key: Field name for which we want to set the new value.

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:

Returns the value for the given field name.

- (id) valueForKey:(id)key

Parameters:

  • key: Field name for which we want to get the current value.