SCTableViewModel

@interface SCTableViewModel
    : NSObject <UITableViewDataSource, UITableViewDelegate,
                UIScrollViewDelegate, SCInputAccessoryViewDelegate> {
  NSIndexPath *lastReturnedCellIndexPath;
  SCTableViewCell *lastReturnedCell;
  NSIndexPath *lastVisibleCellIndexPath;
  id target;
  SEL action;
  SCTableViewModel *masterModel;
  SCTableViewModel *activeDetailModel;
  UITableView *_tableView;
  UIBarButtonItem *editButtonItem;
  BOOL autoResizeForKeyboard;
  BOOL keyboardShown;
  CGFloat keyboardOverlap;
  SCInputAccessoryView *_inputAccessoryView;
  NSMutableArray *sections;
  NSArray *sectionIndexTitles;
  BOOL autoGenerateSectionIndexTitles;
  BOOL autoSortSections;
  BOOL hideSectionHeaderTitles;
  BOOL lockCellSelection;
  NSInteger tag;
  BOOL enablePullToRefresh;
  SCTableViewCell *activeCell;
  NSIndexPath *activeCellIndexPath;
  UIResponder *activeCellControl;
  UIBarButtonItem *commitButton;
  BOOL swipeToDeleteActive;
  SCModelActions *_modelActions;
  SCSectionActions *_sectionActions;
  SCCellActions *_cellActions;
  SCTheme *_theme;
}

This class is the master mind behind all of Sensible TableView’s functionality.

Sensible TableView provides an alternative easy way to create sophisticated table views very quickly. The sophistication of these table views can range from simple text cells, to cells with controls, to custom cells that get automatically generated from your own classes. SCTableViewModel also automatically generates detail views for common tasks such as selecting cell values or creating new objects. Using SCTableViewModel, you can easily create full functioning applications in a matter of minutes.

SCTableViewModel is designed to be loosely coupled with your user interface elements. What this means is that you can use SCTableViewModel with Apple’s default UITableView or with any of your custom UITableView subclasses. Similarly, you can use SCTableViewModel with any UIViewController, or any of its subclasses, including UITableViewController or your own subclasses.

Architecture:

An SCTableViewModel defines a table view model with several sections, each section being of type SCTableViewSection. Each SCTableViewSection can contain several cells, each cell being of type SCTableViewCell.

Show on GitHub

Creation and Initialization

  • Allocates and returns an initialized SCTableViewModel bound to a UITableView. *

    • Upon the model’s initialization, the model sets itself as the table view’s dataSource and delegate, and starts providing it with its sections and cells. *
    • - parameter: tableView The UITableView to be bound to the model. It’s ok for this value to be nil if the table view is not yet available when the model is created.

    Declaration

    Objective-C

    + (instancetype)modelWithTableView:(UITableView *)tableView;
    Show on GitHub

  • Returns an initialized ‘SCTableViewModel’ bound to a UITableView.
    *

    • Upon the model’s initialization, the model sets itself as the table view’s dataSource and delegate, and starts providing it with its sections and cells. *
    • - parameter: tableView The UITableView to be bound to the model. It’s ok for this value to be nil if the table view is not yet available when the model is created.

    Declaration

    Objective-C

    - (instancetype)initWithTableView:(UITableView *)tableView;
    Show on GitHub

Configuration

  • Set to TRUE to enable pull-to-refresh functionality on the table view. Default: FALSE.

    See

    refreshControl

    Declaration

    Objective-C

    @property (nonatomic) BOOL enablePullToRefresh;
    Show on GitHub

  • Contains a UIRefreshControl that automatically provides pull-to-refresh functionality to the table view.

    Note

    enablePullToRefresh must be set to TRUE for this view to take effect.

    Declaration

    Objective-C

    @property (nonatomic, strong) UIRefreshControl *refreshControl;
    Show on GitHub

  • When set to a valid UIBarButtonItem, SCTableViewModel automatically puts its table view in edit mode when the button is tapped. Note: Must be set if the model is to automatically show/hide editing mode sections.

    Declaration

    Objective-C

    @property (nonatomic, strong) UIBarButtonItem *editButtonItem;
    Show on GitHub

  • If TRUE, SCTableViewModel will automatically resize its tableView when the keyboard appears. Property defualts to FALSE if viewController is a UITableViewController subclass, as UITableViewController will automatically handle the resizing. Otherwise, it defaults to TRUE.

    Declaration

    Objective-C

    @property (nonatomic) BOOL autoResizeForKeyboard;
    Show on GitHub

  • An array of strings that serve as the title of sections in the tableView and appear in the index list on the right side of the tableView. tableView must be in plain style for the index to appear.

    Declaration

    Objective-C

    @property (nonatomic, strong) NSArray *sectionIndexTitles;
    Show on GitHub

  • If TRUE, SCTableViewModel will automatically generate the sectionIndexTitles array from the first letter of each section’s header title. Default: FALSE.

    Declaration

    Objective-C

    @property (nonatomic) BOOL autoGenerateSectionIndexTitles;
    Show on GitHub

  • If TRUE, SCTableViewModel will automatically sort its sections alphabetically according to their header title value. Default: FALSE.

    Declaration

    Objective-C

    @property (nonatomic) BOOL autoSortSections;
    Show on GitHub

  • If TRUE, all section header titles will be hidden. Default: FALSE.

    Declaration

    Objective-C

    @property (nonatomic) BOOL hideSectionHeaderTitles;
    Show on GitHub

  • If TRUE, SCTableViewModel will prevent any cell from being selected. Default: FALSE.

    • - note: for preventing individual cells from being selected, use SCTableViewCell “selectable” property.

    Declaration

    Objective-C

    @property (nonatomic) BOOL lockCellSelection;
    Show on GitHub
  • tag

    An integer that you can use to identify different table view models in your application. Any detail model automatically gets its tag set to be the value of its parent model’s tag plus one. Default: 0.

    Declaration

    Objective-C

    @property (nonatomic) NSInteger tag;
    Show on GitHub

  • The detail view controller used to display all of the model’s automatically generated detail views. This property is typically used in iPad applications where the model and its detailViewController co-exist in a UISplitViewController.

    Note

    STV automatically attempts to set this property when the model is the master view controller of a UISplitViewController.

    Warning

    detailViewController must be of type SCViewController or SCTableViewController only.

    Declaration

    Objective-C

    @property (nonatomic, strong) UIViewController *detailViewController;
    Show on GitHub

  • The set of model action blocks.

    Declaration

    Objective-C

    @property (nonatomic, readonly) SCModelActions *modelActions;
    Show on GitHub

  • The set of section action blocks that get applied to all the model’s sections.

    Note

    Section actions defined in the model’s individual sections will override any actions set here.

    Declaration

    Objective-C

    @property (nonatomic, readonly) SCSectionActions *sectionActions;
    Show on GitHub

  • The set of cell action blocks that get applied to all the model’s cells.

    Note

    Cell actions defined in the model’s individual cells will override any actions set here.

    Declaration

    Objective-C

    @property (nonatomic, readonly) SCCellActions *cellActions;
    Show on GitHub

  • The theme used to style the model’s views. Default: nil.

    Declaration

    Objective-C

    @property (nonatomic, strong) SCTheme *theme;
    Show on GitHub

Managing Sections

  • The number of sections in the model.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSUInteger sectionCount;
    Show on GitHub

  • Adds a new section to the model.

    • - parameter: section Must be a valid non nil SCTableViewSection.

    Declaration

    Objective-C

    - (void)addSection:(SCTableViewSection *)section;
    Show on GitHub

  • Inserts a new section at the specified index.

    • - parameter: section Must be a valid non nil SCTableViewSection.
    • - parameter: index Must be less than the total number of sections.

    Declaration

    Objective-C

    - (void)insertSection:(SCTableViewSection *)section atIndex:(NSUInteger)index;
    Show on GitHub

  • Returns the section at the specified index.

    • - parameter: index Must be less than the total number of sections.

    Declaration

    Objective-C

    - (SCTableViewSection *)sectionAtIndex:(NSUInteger)index;
    Show on GitHub

  • Returns the first section with the specified header title.

    • - parameter: title The header title.

    Declaration

    Objective-C

    - (SCTableViewSection *)sectionWithHeaderTitle:(NSString *)title;
    Show on GitHub

  • Returns the index of the specified section.

    • - parameter: section Must be a valid non nil SCTableViewSection.
    • - returns: If section is not found, method returns NSNotFound.

    Declaration

    Objective-C

    - (NSUInteger)indexForSection:(SCTableViewSection *)section;
    Show on GitHub

  • Removes the section at the specified index from the model.

    • - parameter: index Must be less than the total number of section.

    Declaration

    Objective-C

    - (void)removeSectionAtIndex:(NSUInteger)index;
    Show on GitHub

  • Removes all sections from the model.

    Declaration

    Objective-C

    - (void)removeAllSections;
    Show on GitHub

  • Generates sections using the given object and its data definition. The method fully utilizes the definition’s groups feature by generating a section for each group.

    • - parameter: object The object that the sections will be generated for.
    • - parameter: definition The object’s definition.
    • - warning: Important: definition must be the data definition representing the given object.

    Declaration

    Objective-C

    - (void)generateSectionsForObject:(NSObject *)object
                   withDefinition:(SCDataDefinition *)definition;
    Show on GitHub

  • Generates sections using the given object and its data definition. The method fully utilizes the definition’s groups feature by generating a section for each group.

    • - parameter: object The object that the sections will be generated for.
    • - parameter: definition The object’s definition.
    • - parameter: newObject Set to TRUE if the generated sections are used represent a newly created fresh object, otherwise set to FALSE.
    • - warning: Important: definition must be the data definition representing the given object.

    Declaration

    Objective-C

    - (void)generateSectionsForObject:(NSObject *)object
                   withDefinition:(SCDataDefinition *)definition
                        newObject:(BOOL)newObject;
    Show on GitHub

  • Generates sections using the given object and its data store.

    • - parameter: object The object that the sections will be generated for.
    • - parameter: store The object’s data store.

    Declaration

    Objective-C

    - (void)generateSectionsForObject:(NSObject *)object
                    withDataStore:(SCDataStore *)store;
    Show on GitHub

  • Generates sections using the given object and its data store.

    • - parameter: object The object that the sections will be generated for.
    • - parameter: store The object’s data store.
    • - parameter: newObject Set to TRUE if the generated sections are used represent a newly created fresh object, otherwise set to FALSE.

    Declaration

    Objective-C

    - (void)generateSectionsForObject:(NSObject *)object
                    withDataStore:(SCDataStore *)store
                        newObject:(BOOL)newObject;
    Show on GitHub

  • Generates sections using a user defaults definition.

    Declaration

    Objective-C

    - (void)generateSectionsForUserDefaultsDefinition:
    (SCUserDefaultsDefinition *)userDefaultsDefinition;
    Show on GitHub

Managing Cells

  • The current active cell. A cell becomes active if it is selected or if its value changes.

    Declaration

    Objective-C

    @property (nonatomic, readonly) SCTableViewCell *activeCell;
    Show on GitHub

  • The indexPath of activeCell.

    Declaration

    Objective-C

    @property (nonatomic, readonly) NSIndexPath *activeCellIndexPath;
    Show on GitHub

  • The current active input control.

    Declaration

    Objective-C

    @property (nonatomic, readonly) UIResponder *activeCellControl;
    Show on GitHub

  • Assigns the given object (given it’s data definition) to be the bound object in all of the model’s cells. *

    Declaration

    Objective-C

    - (void)setBoundObjectForAllCells:(NSObject *)boundObject
                   dataDefinition:(SCDataDefinition *)dataDefinition;
    Show on GitHub

  • Assigns the given object (given it’s data store) to be the bound object in all of the model’s cells. *

    Declaration

    Objective-C

    - (void)setBoundObjectForAllCells:(NSObject *)boundObject
                 boundObjectStore:(SCDataStore *)boundObjectStore;
    Show on GitHub

  • Returns the cell at the specified indexPath.

    • - parameter: indexPath Must be a valid non nil NSIndexPath.

    Declaration

    Objective-C

    - (SCTableViewCell *)cellAtIndexPath:(NSIndexPath *)indexPath;
    Show on GitHub

  • Returns the index path for the specified cell.

    • - parameter: cell Must be a valid non nil SCTableViewCell.
    • - returns: If cell is not found, method returns NSNotFound.

    Declaration

    Objective-C

    - (NSIndexPath *)indexPathForCell:(SCTableViewCell *)cell;
    Show on GitHub

  • Returns the first cell with the given bound property name. *

    Declaration

    Objective-C

    - (SCTableViewCell *)cellWithBoundPropertyName:(NSString *)boundPropertyName;
    Show on GitHub

  • Returns the indexPath of the cell that comes after the specified cell in the model.

    • - parameter: indexPath The indexPath of the current cell.
    • - parameter: rewind If TRUE and cell is the very last cell in the model, method returns the indexPath of the cell at the very top.
    • - returns: Returns nil if cell is the last cell in the model and rewind is FALSE, or if cell does not exist in the model.

    Declaration

    Objective-C

    - (NSIndexPath *)indexPathForCellAfterCellAtIndexPath:(NSIndexPath *)indexPath
                                               rewind:(BOOL)rewind;
    Show on GitHub

  • Returns the indexPath of the cell that comes after the specified cell in the model.

    • - parameter: cell Must be a valid non nil SCTableViewCell.
    • - parameter: rewind If TRUE and cell is the very last cell in the model, method returns the indexPath of the cell at the very top.
    • - returns: Returns nil if cell is the last cell in the model and rewind is FALSE, or if cell does not exist in the model.

    Declaration

    Objective-C

    - (NSIndexPath *)indexPathForCellAfterCell:(SCTableViewCell *)cell
                                    rewind:(BOOL)rewind;
    Show on GitHub

  • Returns the cell that comes after the specified cell in the model.

    • - parameter: cell Must be a valid non nil SCTableViewCell.
    • - parameter: rewind If TRUE and cell is the very last cell in the model, method returns the cell at the very top.
    • - returns: Returns nil if cell is the last cell in the model and rewind is FALSE, or if cell does not exist in the model.

    Declaration

    Objective-C

    - (SCTableViewCell *)cellAfterCell:(SCTableViewCell *)cell rewind:(BOOL)rewind;
    Show on GitHub

  • Returns the indexPath of the cell that comes before the specified cell in the model.

    • - parameter: indexPath The indexPath of the current cell.
    • - parameter: rewind If TRUE and cell is the very first cell in the model, method returns the indexPath of the last cell.
    • - returns: Returns nil if cell is the last cell in the model and rewind is FALSE, or if cell does not exist in the model.

    Declaration

    Objective-C

    - (NSIndexPath *)indexPathForCellBeforeCellAtIndexPath:(NSIndexPath *)indexPath
                                                rewind:(BOOL)rewind;
    Show on GitHub

  • Returns the indexPath of the cell that comes before the specified cell in the model.

    • - parameter: cell Must be a valid non nil SCTableViewCell.
    • - parameter: rewind If TRUE and cell is the very first cell in the model, method returns the indexPath of the last cell.
    • - returns: Returns nil if cell is the last cell in the model and rewind is FALSE, or if cell does not exist in the model.
    • - see: moveToNextCellControl:

    Declaration

    Objective-C

    - (NSIndexPath *)indexPathForCellBeforeCell:(SCTableViewCell *)cell
                                     rewind:(BOOL)rewind;
    Show on GitHub

  • Returns the cell that comes before the specified cell in the model.

    • - parameter: cell Must be a valid non nil SCTableViewCell.
    • - parameter: rewind If TRUE and cell is the very first cell in the model, method returns the last cell.
    • - returns: Returns nil if cell is the last cell in the model and rewind is FALSE, or if cell does not exist in the model.
    • - see: moveToPreviousCellControl:

    Declaration

    Objective-C

    - (SCTableViewCell *)cellBeforeCell:(SCTableViewCell *)cell rewind:(BOOL)rewind;
    Show on GitHub

  • Moves the first responder to the next cell control, automatically scrolling the table view as needed. If rewind is TRUE, the first responder is moved to the very first cell after the last cell has been reached.

    Note

    This method is typically used when you’re overriding the framework’s automatic handling of the keyboard’s ‘Return’ button.

    Declaration

    Objective-C

    - (void)moveToNextCellControl:(BOOL)rewind;
    Show on GitHub

  • Moves the first responder to the previous cell control, automatically scrolling the table view as needed. If rewind is TRUE, the first responder is moved to the very last cell after the first cell has been reached.

    Declaration

    Objective-C

    - (void)moveToPreviousCellControl:(BOOL)rewind;
    Show on GitHub

Managing Detail Views

  • Dismisses all detail views, commiting all changes when commit is TRUE, otherwise it will ignore all changes.

    Declaration

    Objective-C

    - (void)dismissAllDetailViewsWithCommit:(BOOL)commit;
    Show on GitHub

Managing Model Values

  • TRUE if all the model’s section and cell values are valid.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL valuesAreValid;
    Show on GitHub

  • This property is TRUE if any of the model’s cells or sections needs to be commited, otherwise it’s FALSE.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL needsCommit;
    Show on GitHub

  • ‘SCTableViewModel’ will automatically enable/disable the commitButton based on the valuesAreValid property, where commitButton is enabled if valuesAreValid is TRUE.

    Declaration

    Objective-C

    @property (nonatomic, strong) UIBarButtonItem *commitButton;
    Show on GitHub

  • Forces the commit of all section and cell values into their respective bound objects. There is usually no need to call this method manually as it’s typically called by the framework when the user is ready to commit changes.

    Declaration

    Objective-C

    - (void)commitChanges;
    Show on GitHub

  • Reload’s the model’s bound values in case the associated bound objects or keys valuea has changed by means other than the cells themselves (e.g. external custom code).

    Declaration

    Objective-C

    - (void)reloadBoundValues;
    Show on GitHub

Miscellaneous

  • The UITableView bound to ‘SCTableViewModel’.

    Declaration

    Objective-C

    @property (nonatomic, weak) UITableView *tableView;
    Show on GitHub

  • The UIViewController of tableView.

    Declaration

    Objective-C

    @property (nonatomic, readonly) UIViewController *viewController;
    Show on GitHub

  • The keyboard input accessory view responsible for providing keyboard navigation between the different responders. Set to a valid SCInputAccessoryView to enable the accessory view functionality.

    Declaration

    Objective-C

    @property (nonatomic, strong) SCInputAccessoryView *inputAccessoryView;
    Show on GitHub

  • Clears all contents of the model.

    Declaration

    Objective-C

    - (void)clear;
    Show on GitHub

  • Sets the editing mode for tableView.

    Declaration

    Objective-C

    - (void)setTableViewEditing:(BOOL)editing animated:(BOOL)animate;
    Show on GitHub

  • Returns the detail view controller that would normally be generated for the given cell.

    Note

    This method is typically used to implement 3D Touch Peek and Pop.

    Declaration

    Objective-C

    - (UIViewController *)detailViewControllerForCellAtIndexPath:
    (NSIndexPath *)indexPath;
    Show on GitHub

Internal Properties & Methods (should only be used by the framework or when subclassing)

  • Returns true if the modeled table view is live and displaying cells.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL live;
    Show on GitHub

  • Property is used internally by the framework to determine if the table view is in swipe-to-delete editing mode.

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL swipeToDeleteActive;
    Show on GitHub

  • Property is used internally by the framework to set the master model in a master-detail relationship.

    Declaration

    Objective-C

    @property (nonatomic, weak) SCTableViewModel *masterModel;
    Show on GitHub

  • Property is used internally by the framework to set the master boundObject in a master-detail relationship.

    Declaration

    Objective-C

    @property (nonatomic, weak) NSObject *masterBoundObject;
    Show on GitHub

  • Property is used internally by the framework to set the master boundObject store in a master-detail relationship.

    Declaration

    Objective-C

    @property (nonatomic, weak) SCDataStore *masterBoundObjectStore;
    Show on GitHub

  • Holds the currently active detail model.

    Warning

    Property must only be set internally by the framework.

    Declaration

    Objective-C

    @property (nonatomic, weak) SCTableViewModel *activeDetailModel;
    Show on GitHub

  • Called internally to rollback to initial cell bound values when their bound object was first assigned.

    Declaration

    Objective-C

    - (void)rollbackToInitialCellValues;
    Show on GitHub

  • Method called internally by framework to reload cells values, if needed.

    Declaration

    Objective-C

    - (void)reloadCellsIfNeeded;
    Show on GitHub

  • Warning: Method must only be called internally by the framework.

    Declaration

    Objective-C

    - (void)enterLoadingMode;
    Show on GitHub

  • Warning: Method must only be called internally by the framework.

    Declaration

    Objective-C

    - (void)exitLoadingMode;
    Show on GitHub

  • Warning: Method must only be called internally by the framework.

    Declaration

    Objective-C

    - (void)clearLastReturnedCellData;
    Show on GitHub

  • Warning: Method must only be called internally by the framework.

    Declaration

    Objective-C

    - (void)configureDetailModel:(SCTableViewModel *)detailModel;
    Show on GitHub

  • Warning: Method must only be called internally by the framework.

    Declaration

    Objective-C

    - (void)keyboardWillShow:(NSNotification *)aNotification;
    Show on GitHub

  • Warning: Method must only be called internally by the framework.

    Declaration

    Objective-C

    - (void)keyboardWillHide:(NSNotification *)aNotification;
    Show on GitHub

  • Method gets called internally whenever the value of a section changes. This method should only be used when subclassing ‘SCTableViewModel’. If what you want is to get notified when a section value changes, consider using SCTableViewModelDelegate methods.

    When subclassing ‘SCTableViewModel’, you can override this method to define custom behaviour when a section value changes. However, you should always call “[super valueChangedForSectionAtIndex:]” somewhere in your subclassed method.

    Declaration

    Objective-C

    - (void)valueChangedForSectionAtIndex:(NSUInteger)index;

    Parameters

    index

    Index of the section changed.
    Show on GitHub

  • Method gets called internally whenever the value of a cell changes. This method should only be used when subclassing ‘SCTableViewModel’. If what you want is to get notified when a cell value changes, consider using either SCTableViewModelDelegate or the cell’s actions.

    When subclassing ‘SCTableViewModel’, you can override this method to define custom behaviour when a cell value changes. However, you should always call “[super valueChangedForRowAtIndexPath:]” somewhere in your subclassed method.

    Declaration

    Objective-C

    - (void)valueChangedForRowAtIndexPath:(NSIndexPath *)indexPath;

    Parameters

    indexPath

    Index path of the cell changed.
    Show on GitHub

  • Method used internally by the framework to monitor model modification events.

    Declaration

    Objective-C

    - (void)setTargetForModelModifiedEvent:(id)_target action:(SEL)_action;
    Show on GitHub

  • Subclasses should override this method to handle when editButtonItem is tapped.

    Declaration

    Objective-C

    - (void)didTapEditButtonItem;
    Show on GitHub

  • Method called by refreshControl to initiate refresh.

    Declaration

    Objective-C

    - (void)pullToRefreshDidStartLoading;
    Show on GitHub

  • Method called internally.

    Declaration

    Objective-C

    - (void)styleSections;
    Show on GitHub

  • Method called internally.

    Declaration

    Objective-C

    - (void)styleViews;
    Show on GitHub

  • Method called internally.

    Declaration

    Objective-C

    - (void)styleCell:(SCTableViewCell *)cell
                    atIndexPath:(NSIndexPath *)indexPath
    onlyStylePropertyNamesInSet:(NSSet *)propertyNames;
    Show on GitHub

  • Method called internally.

    Declaration

    Objective-C

    - (void)configureCell:(SCTableViewCell *)cell
          atIndexPath:(NSIndexPath *)indexPath;
    Show on GitHub

  • Undocumented

    Declaration

    Objective-C

    @property (nonatomic, readonly) UITableView *trueTableView
    Show on GitHub