SCArrayOfItemsSection Class Reference
Inherits from | SCTableViewSection : NSObject |
Conforms to | SCTableViewControllerDelegate SCViewControllerDelegate |
Declared in | SCTableViewSection.h |
Overview
This class functions as an SCTableViewModel section that is able to represent an array of any kind of items and automatically generate its cells from these items. The section is also able to handle all end-user interaction with the generated cells, including adding, editing, deleting, and moving the cells. When cells are added or edited, detail views are automatically generated for this purpose. To enable adding cells, the class' user should set the addButtonItem property of the section to a valid UIBarButtonItem, the section then will automatically add new items when the button is tapped.
When adding new items to the array, the section starts by first asking the model’s data source to provide a new item using its tableViewModel:newItemForArrayOfItemsSectionAtIndex: SCTableViewModelDataSource protocol method.
This class is an abstract base class. Subclasses of this class must override the buildDetailTableModel method. This method should return a model for the detail view to display.
Warning: This is an abstract base class, you should never make any direct instances of it.
Tasks
Creation and Initialization
-
+ sectionWithHeaderTitle:dataStore:
Allocates and returns an initialized ‘SCArrayOfItemsSection’ given a data store.
-
– initWithHeaderTitle:dataStore:
Returns an initialized ‘SCArrayOfItemsSection’ given a data store.
Configuration
-
dataStore
The data store that’s used to store and fetch the section’s items.
property -
dataFetchOptions
The options used to fetch the section’s items from dataStore.
property -
items
The items fetched from dataStore.
property -
autoFetchItems
Set to FALSE to disable the section from automatically fetching its items from dataStore. Default: TRUE.
property -
isFetchingItems
This property is TRUE when the section is in a state of fetching its items from their dataStore.
property -
itemsAccessoryType
The accessory type of the generated cells.
property -
allowAddingItems
Allows/disables adding new cells/items to the items array. Default: TRUE.
property -
allowDeletingItems
Allows/disables deleting new cells/items from the items array. Default: TRUE.
property -
allowMovingItems
Allows/disables moving cells/items from one row to another. Default: TRUE.
property -
allowEditDetailView
Allows/disables a detail view for editing items' values. Default: TRUE.
property -
allowRowSelection
Allows/disables row selection. Default: TRUE.
property -
skipNewItemDetailView
Set to TRUE to directly add the new item without displaying a detail view. This is useful in situations where the item details will be filled in programmatically by implementing the SCTableViewModelDelegate ‘tableViewModel:itemAddedForSectionAtIndexPath:item:’ method. Default: FALSE.
property -
autoSelectNewItemCell
Allows/disables automatic cell selection of newly created items. Default: TRUE.
property -
addButtonItem
Set this property to a valid UIBarButtonItem. When addButtonItem is tapped and allowAddingItems is TRUE, a detail view is automatically generated for the user to enter the new items properties. If the properties are commited, a new item is added to the array.
property -
cellCountLimitForAutoHeight
When the cell count of ‘SCArrayOfItemsSection’ reaches this limit, it will automatically calculate the first cell height and use it for all remaining cells, instead of calculating the height for each cell separately. This dratically improves performance for sections with a huge number of cells. Default: 100.
property
Configuring Special Cells
-
fetchItemsCell
This cell is automatically displayed when more section items need to be fetched. This is typically the case when the section’s dataFetchOptions has specified a batchSize.
property -
placeholderCell
When set to a valid cell object, ‘placeholderCell’ will be displayed when no items exist in the section. As soon as any items are added, this cell automatically disappears. Default: nil.
property -
addNewItemCell
When set to a valid cell object, ‘addNewItemCell’ will be displayed as the last cell of the section, and will add a new item to the section whenever it gets tapped by the user. This cell can be used as an alternative to addButtonItem. Default: nil.
property -
addNewItemCellExistsInNormalMode
When TRUE, addNewItemCell will be displayed in Normal Mode. Default: TRUE.
property -
addNewItemCellExistsInEditingMode
When TRUE, addNewItemCell will be displayed in Editing Mode. Default: TRUE.
property
Manual Event Control
-
– dispatchEventAddNewItem
User can call this method to dispatch an AddNewItem event, the same event dispached when the end-user taps addButtonItem.
-
– dispatchEventSelectRowAtIndexPath:
User can call this method to dispatch a SelectRow event, the same event dispached when the end-user selects a cell.
-
– dispatchEventRemoveRowAtIndexPath:
User can call this method to dispatch a RemoveRow event, the same event dispached when the end-user taps the delete button on a cell.
Internal Properties & Methods (should only be used by the framework or when subclassing)
-
selectedCellIndexPath
Called internally by framework to store the currently selected cell index path.
property -
cellIdentifier
Subclasses should use this property when creating new dequeable cells
property -
– mutableItems
Used internally by the framework.
-
– setMutableItems:
Used internally by the framework.
-
– fetchItems:
Used internally by the framework.
-
– didFetchItems:sender:
Used internally by the framework.
-
– addSpecialCellsToItems
Used internally by the framework.
-
– removeSpecialCellsFromItems
Used internally by the framework.
-
– createCellAtIndex:
Subclasses should override this method to handle the creation of section cells
-
– setPropertiesForCell:withIndex:
Subclasses should override this method to manage setting the properties cells after being dequed from the table view
-
– textForCellAtIndex:
Subclasses should override this method to set the text for each generated cell
-
– detailTextForCellAtIndex:
Subclasses should override this method to set the detail text for each generated cell
-
– didSelectCellAtIndexPath:
Method is called internally when the generated cells are selected
-
– willDeselectCellAtIndexPath:
Method is called internally when the generated cells will deselect
-
– commitEditingStyle:forCellAtIndexPath:
Subclasses should override this method to handle when generated cells are deleted
-
– targetIndexPathForMoveFromCellAtIndexPath:toProposedIndexPath:
Subclasses should override this method to handle when generated cells are about to move.
-
– moveCellAtIndexPath:toIndexPath:
Subclasses should override this method to handle when generated cells are moved
-
– didTapAddButtonItem
Subclasses should override this method to handle when addButtonItem is tapped
-
– createNewItem
Subclasses should override this method to handle creating a new item
-
– buildDetailTableModel:forItem:
Subclasses must override this method to build a model for the generated detail view.
-
– getDetailViewNavigationBarTypeForItem:newItem:
Subclasses must override this method to determine the navigation bar type of the detail view for the given item.
-
– commitNewItem:detailModel:
Commits the newly created item.
-
– addCellForNewItem:
Subclasses should override this method to handle adding a cell for newItem (method called internally by framework)
-
– itemModified:
Subclasses should override this method to handle adding an item getting modified (method called internally by framework)
-
– commitAndProcessChangesForDetailModel:
Method gets called internally by framework.
-
– commitDetailModelChanges:
Method gets called internally by framework.
Properties
addButtonItem
Set this property to a valid UIBarButtonItem. When addButtonItem is tapped and allowAddingItems is TRUE, a detail view is automatically generated for the user to enter the new items properties. If the properties are commited, a new item is added to the array.
@property (nonatomic, strong) UIBarButtonItem *addButtonItem
See Also
Declared In
SCTableViewSection.h
addNewItemCell
When set to a valid cell object, ‘addNewItemCell’ will be displayed as the last cell of the section, and will add a new item to the section whenever it gets tapped by the user. This cell can be used as an alternative to addButtonItem. Default: nil.
@property (nonatomic, strong) SCTableViewCell *addNewItemCell
See Also
Declared In
SCTableViewSection.h
addNewItemCellExistsInEditingMode
When TRUE, addNewItemCell will be displayed in Editing Mode. Default: TRUE.
@property (nonatomic, readwrite) BOOL addNewItemCellExistsInEditingMode
Declared In
SCTableViewSection.h
addNewItemCellExistsInNormalMode
When TRUE, addNewItemCell will be displayed in Normal Mode. Default: TRUE.
@property (nonatomic, readwrite) BOOL addNewItemCellExistsInNormalMode
Declared In
SCTableViewSection.h
allowAddingItems
@property (nonatomic, readwrite) BOOL allowAddingItems
Declared In
SCTableViewSection.h
allowDeletingItems
@property (nonatomic, readwrite) BOOL allowDeletingItems
Declared In
SCTableViewSection.h
allowEditDetailView
Allows/disables a detail view for editing items' values. Default: TRUE.
@property (nonatomic, readwrite) BOOL allowEditDetailView
Discussion
Detail views are automatically generated for editing new items. You can control wether the view appears as a modal view or gets pushed to the navigation stack using the detailViewModal property. Modal views have the added feature of giving the end user a Cancel and Done buttons. The Cancel button cancels all user’s actions, while the Done button commits them. Also, if the cell’s validation is enabled, the Done button will remain disabled until all cells' values are valid.
Declared In
SCTableViewSection.h
allowMovingItems
Allows/disables moving cells/items from one row to another. Default: TRUE.
@property (nonatomic, readwrite) BOOL allowMovingItems
Declared In
SCTableViewSection.h
allowRowSelection
Allows/disables row selection. Default: TRUE.
@property (nonatomic, readwrite) BOOL allowRowSelection
Declared In
SCTableViewSection.h
autoFetchItems
Set to FALSE to disable the section from automatically fetching its items from dataStore. Default: TRUE.
@property (nonatomic, readwrite) BOOL autoFetchItems
Declared In
SCTableViewSection.h
autoSelectNewItemCell
Allows/disables automatic cell selection of newly created items. Default: TRUE.
@property (nonatomic, readwrite) BOOL autoSelectNewItemCell
Declared In
SCTableViewSection.h
cellCountLimitForAutoHeight
When the cell count of ‘SCArrayOfItemsSection’ reaches this limit, it will automatically calculate the first cell height and use it for all remaining cells, instead of calculating the height for each cell separately. This dratically improves performance for sections with a huge number of cells. Default: 100.
@property (nonatomic, readwrite) NSUInteger cellCountLimitForAutoHeight
Discussion
Note: In case the section has a huge number of cells, but their heights are not identical, consider implementing the sectionAction called customHeightForRowAtIndexPath.
See Also
SCSectionActions.customHeightForRowAtIndexPath
Declared In
SCTableViewSection.h
cellIdentifier
Subclasses should use this property when creating new dequeable cells
@property (nonatomic, readonly) NSString *cellIdentifier
Declared In
SCTableViewSection.h
dataFetchOptions
@property (nonatomic, strong) SCDataFetchOptions *dataFetchOptions
Declared In
SCTableViewSection.h
dataStore
The data store that’s used to store and fetch the section’s items.
@property (nonatomic, strong) SCDataStore *dataStore
Declared In
SCTableViewSection.h
fetchItemsCell
This cell is automatically displayed when more section items need to be fetched. This is typically the case when the section’s dataFetchOptions has specified a batchSize.
@property (nonatomic, strong) SCFetchItemsCell *fetchItemsCell
Declared In
SCTableViewSection.h
isFetchingItems
@property (nonatomic, readonly) BOOL isFetchingItems
Declared In
SCTableViewSection.h
items
The items fetched from dataStore.
@property (nonatomic, readonly) NSArray *items
Declared In
SCTableViewSection.h
itemsAccessoryType
The accessory type of the generated cells.
@property (nonatomic, readwrite) UITableViewCellAccessoryType itemsAccessoryType
Declared In
SCTableViewSection.h
placeholderCell
When set to a valid cell object, ‘placeholderCell’ will be displayed when no items exist in the section. As soon as any items are added, this cell automatically disappears. Default: nil.
@property (nonatomic, strong) SCTableViewCell *placeholderCell
Declared In
SCTableViewSection.h
selectedCellIndexPath
Called internally by framework to store the currently selected cell index path.
@property (nonatomic, strong) NSIndexPath *selectedCellIndexPath
Declared In
SCTableViewSection.h
skipNewItemDetailView
Set to TRUE to directly add the new item without displaying a detail view. This is useful in situations where the item details will be filled in programmatically by implementing the SCTableViewModelDelegate ‘tableViewModel:itemAddedForSectionAtIndexPath:item:’ method. Default: FALSE.
@property (nonatomic, readwrite) BOOL skipNewItemDetailView
Declared In
SCTableViewSection.h
Class Methods
sectionWithHeaderTitle:dataStore:
Allocates and returns an initialized ‘SCArrayOfItemsSection’ given a data store.
+ (id)sectionWithHeaderTitle:(NSString *)sectionHeaderTitle dataStore:(SCDataStore *)store
Parameters
- sectionHeaderTitle
A header title for the section.
- store
The data store containing the section’s items.
Declared In
SCTableViewSection.h
Instance Methods
addCellForNewItem:
Subclasses should override this method to handle adding a cell for newItem (method called internally by framework)
- (void)addCellForNewItem:(NSObject *)newItem
Declared In
SCTableViewSection.h
addSpecialCellsToItems
Used internally by the framework.
- (void)addSpecialCellsToItems
Declared In
SCTableViewSection.h
buildDetailTableModel:forItem:
Subclasses must override this method to build a model for the generated detail view.
- (void)buildDetailTableModel:(SCTableViewModel *)detailTableModel forItem:(NSObject *)item
Parameters
- detailTableModel
This is an empty model. Method should add sections and cells to this model.
- item
The item that the model should be built for. If item is nil, a model should be buil for a new item.
Declared In
SCTableViewSection.h
commitAndProcessChangesForDetailModel:
Method gets called internally by framework.
- (void)commitAndProcessChangesForDetailModel:(SCTableViewModel *)detailModel
Declared In
SCTableViewSection.h
commitDetailModelChanges:
Method gets called internally by framework.
- (void)commitDetailModelChanges:(SCTableViewModel *)detailModel
Declared In
SCTableViewSection.h
commitEditingStyle:forCellAtIndexPath:
Subclasses should override this method to handle when generated cells are deleted
- (void)commitEditingStyle:(UITableViewCellEditingStyle)editingStyle forCellAtIndexPath:(NSIndexPath *)indexPath
Declared In
SCTableViewSection.h
commitNewItem:detailModel:
Commits the newly created item.
- (void)commitNewItem:(NSObject *)newItem detailModel:(SCTableViewModel *)detailModel
Declared In
SCTableViewSection.h
createCellAtIndex:
Subclasses should override this method to handle the creation of section cells
- (SCTableViewCell *)createCellAtIndex:(NSUInteger)index
Declared In
SCTableViewSection.h
createNewItem
Subclasses should override this method to handle creating a new item
- (NSObject *)createNewItem
Declared In
SCTableViewSection.h
detailTextForCellAtIndex:
Subclasses should override this method to set the detail text for each generated cell
- (NSString *)detailTextForCellAtIndex:(NSUInteger)index
Declared In
SCTableViewSection.h
didFetchItems:sender:
Used internally by the framework.
- (void)didFetchItems:(NSArray *)fetchedItems sender:(id)sender
Declared In
SCTableViewSection.h
didSelectCellAtIndexPath:
Method is called internally when the generated cells are selected
- (void)didSelectCellAtIndexPath:(NSIndexPath *)indexPath
Declared In
SCTableViewSection.h
didTapAddButtonItem
Subclasses should override this method to handle when addButtonItem is tapped
- (void)didTapAddButtonItem
Declared In
SCTableViewSection.h
dispatchEventAddNewItem
User can call this method to dispatch an AddNewItem event, the same event dispached when the end-user taps addButtonItem.
- (void)dispatchEventAddNewItem
Declared In
SCTableViewSection.h
dispatchEventRemoveRowAtIndexPath:
User can call this method to dispatch a RemoveRow event, the same event dispached when the end-user taps the delete button on a cell.
- (void)dispatchEventRemoveRowAtIndexPath:(NSIndexPath *)indexPath
Declared In
SCTableViewSection.h
dispatchEventSelectRowAtIndexPath:
User can call this method to dispatch a SelectRow event, the same event dispached when the end-user selects a cell.
- (void)dispatchEventSelectRowAtIndexPath:(NSIndexPath *)indexPath
Declared In
SCTableViewSection.h
fetchItems:
Used internally by the framework.
- (void)fetchItems:(id)sender
Declared In
SCTableViewSection.h
getDetailViewNavigationBarTypeForItem:newItem:
Subclasses must override this method to determine the navigation bar type of the detail view for the given item.
- (SCNavigationBarType)getDetailViewNavigationBarTypeForItem:(NSObject *)item newItem:(BOOL)newItem
Declared In
SCTableViewSection.h
initWithHeaderTitle:dataStore:
Returns an initialized ‘SCArrayOfItemsSection’ given a data store.
- (id)initWithHeaderTitle:(NSString *)sectionHeaderTitle dataStore:(SCDataStore *)store
Parameters
- sectionHeaderTitle
A header title for the section.
- store
The data store containing the section’s items.
Declared In
SCTableViewSection.h
itemModified:
Subclasses should override this method to handle adding an item getting modified (method called internally by framework)
- (void)itemModified:(NSObject *)item
Declared In
SCTableViewSection.h
moveCellAtIndexPath:toIndexPath:
Subclasses should override this method to handle when generated cells are moved
- (void)moveCellAtIndexPath:(NSIndexPath *)fromIndexPath toIndexPath:(NSIndexPath *)toIndexPath
Declared In
SCTableViewSection.h
mutableItems
Used internally by the framework.
- (NSMutableArray *)mutableItems
Declared In
SCTableViewSection.h
removeSpecialCellsFromItems
Used internally by the framework.
- (void)removeSpecialCellsFromItems
Declared In
SCTableViewSection.h
setMutableItems:
Used internally by the framework.
- (void)setMutableItems:(NSMutableArray *)mutableItems
Declared In
SCTableViewSection.h
setPropertiesForCell:withIndex:
Subclasses should override this method to manage setting the properties cells after being dequed from the table view
- (void)setPropertiesForCell:(SCTableViewCell *)cell withIndex:(NSUInteger)index
Declared In
SCTableViewSection.h
targetIndexPathForMoveFromCellAtIndexPath:toProposedIndexPath:
Subclasses should override this method to handle when generated cells are about to move.
- (NSIndexPath *)targetIndexPathForMoveFromCellAtIndexPath:(NSIndexPath *)sourceIndexPath toProposedIndexPath:(NSIndexPath *)proposedIndexPath
Declared In
SCTableViewSection.h