Powerful data driven content manager for UITableView.
RETableViewManager
allows to manage the content of any UITableView
with ease, both forms and lists. RETableViewManager
is built on top of reusable cells technique and provides APIs for mapping any object class to any custom cell subclass.
The general idea is to allow developers to use their own UITableView
and UITableViewController
instances (and even subclasses), providing a layer that synchronizes data with the cell appereance.
It fully implements UITableViewDelegate
and UITableViewDataSource
protocols so you don't have to.
Get your UITableView
up and running in several lines of code:
- (void)viewDidLoad
{
[super viewDidLoad];
// Create the manager and assign a UITableView
//
self.manager = [[RETableViewManager alloc] initWithTableView:self.tableView];
// Add a section
//
RETableViewSection *section = [RETableViewSection sectionWithHeaderTitle:@"Test"];
[manager addSection:section];
// Add a string
//
[section addItem:@"Just a simple NSString"];
// Add a basic cell with disclosure indicator
//
[section addItem:[RETableViewItem itemWithTitle:"String cell" accessoryType:UITableViewCellAccessoryDisclosureIndicator selectionHandler:^(RETableViewItem *item) {
NSLog(@"Test: %@", item);
}]];
// Custom items / cells
//
self.manager[@"CustomItem"] = @"CustomCell";
[section addItem:[CustomItem item]];
}
RETableViewManager comes pre-packaged with extensible and ready-to-use in production components:
- Text
- Bool
- Number
- Float
- Date/Time
- Long Text
- Radio option selector
- Multiple option selector
- Credit card and expiration date
Also RETableViewManager
provides APIs for super easy cell styling.
- Xcode 5 or higher
- Apple LLVM compiler
- iOS 6.0 or higher
- ARC
Build and run the RETableViewManagerExample.xcworkspace
in Xcode to see RETableViewManager
in action.
The recommended approach for installating RETableViewManager
is via the CocoaPods package manager, as it provides flexible dependency management and dead simple installation.
For best results, it is recommended that you install via CocoaPods >= 0.26.2 using Git >= 1.8.0 installed via Homebrew.
Install CocoaPods if not already available:
$ [sudo] gem install cocoapods
$ pod setup
Change to the directory of your Xcode project:
$ cd /path/to/MyProject
$ touch Podfile
$ edit Podfile
Edit your Podfile and add RETableViewManager:
platform :ios, '6.0'
pod 'RETableViewManager', '~> 1.5.2'
Install into your Xcode project:
$ pod install
Open your project in Xcode from the .xcworkspace file (not the usual project file)
$ open MyProject.xcworkspace
Please note that if your installation fails, it may be because you are installing with a version of Git lower than CocoaPods is expecting. Please ensure that you are running Git >= 1.8.0 by executing git --version
. You can get a full picture of the installation details by executing pod install --verbose
.
Key Classes | |
---|---|
RETableViewManager | The manager class. Each manager has multiple RETableViewSection sections. |
RETableViewSection | Represents sections in RETableViewManager, each section has multiple RETableViewItem items. |
RETableViewItem | RETableViewItem is the root class of most RETableViewManager item hierarchies. Through RETableViewItem, items inherit a basic interface that communicates with RETableViewCell and RETableViewManager. |
RETableViewCell | The RETableViewCell class defines the attributes and behavior of the cells that appear in UITableView objects. You should subclass RETableViewCell to obtain cell characteristics and behavior specific to your application's needs. By default, RETableViewCell is being mapped with RETableViewItem. |
Styling | |
RETableViewCellStyle | Provides style for RETableViewCell subclasses. You can define such properties as backgroundImageMargin, cellHeight, contentViewMargin and more. |
Helper Controllers | |
RETableViewOptionsController | Performs selection based on user input and provides result on completion. Should be used with RERadioItem. |
RETableViewManager
includes a number of built-in items and cells that perform common tasks (text input, date input and so on).
Built-in Items and Cells | ||
---|---|---|
Item Class | Cell Class | Description |
RETextItem | RETableViewTextCell | Provides convenience for a user text input. You can set a bunch of properties through RETextItem that you would normally find in UITextField. |
RELongTextItem | RETableViewLongTextCell | Provides convenience for a multiline user text input. You can set a bunch of properties through RELongTextItem that you would normally find in UITextView. |
RENumberItem | RETableViewNumberCell | Provides convenience for a user number input using REFormattedNumberField. |
REBoolItem | RETableViewBoolCell | Provides convenience for a user boolean input using UISwitch. |
RERadioItem | RETableViewCell | Provides convenience for selecting a single option using RETableViewOptionsController. |
REMultipleChoiceItem | RETableViewCell | Provides convenience for selecting multiple options using RETableViewOptionsController. |
REFloatItem | RETableViewFloatCell | Provides convenience for adjusting float values ranging from 0.0 to 1.0. |
REDateTimeItem | RETableViewDateTimeCell | Provides convenience for modifying date in NSDate objects. |
REPickerItem | RETableViewPickerCell | Provides convenience for selecting multiple options using UIPickerView. |
RESegmentedItem | RETableViewSegmentedCell | Provides convenience for working with UISegmentedControl. |
RECreditCardItem | RETableViewCreditCardCell | Provides convenience for a user credit card input. Allows to enter a credit card number, expiration date and security code, all in a single table view cell. |
Section without a title:
RETableViewSection *section = [RETableViewSection section];
[self.manager addSection:section];
Section with a title:
RETableViewSection *section = [RETableViewSection sectionWithHeaderTitle:@"Header"];
[self.manager addSection:section];
Section with a title and a footer:
RETableViewSection *section = [RETableViewSection sectionWithHeaderTitle:@"Header" footerTitle:@"Footer"];
[self.manager addSection:section];
Section with a custom header view:
RETableViewSection *section = [RETableViewSection sectionWithHeaderView:myCustomSectionHeaderView];
[self.manager addSection:section];
Section with a custom header and footer view:
RETableViewSection *section = [RETableViewSection sectionWithHeaderView:myCustomSectionHeaderView footerView:myCustomSectionFooterView];
[self.manager addSection:section];
// Create the manager
//
self.manager = [[RETableViewManager alloc] initWithTableView:self.tableView];
// Add a section
//
RETableViewSection *section = [RETableViewSection sectionWithHeaderTitle:@"Test"];
[self.manager addSection:section];
// Add items to the section
//
self.textItem = [RETextItem itemWithTitle:@"Enter text" value:@""];
[section addItem:self.textItem];
self.numberItem = [RENumberItem itemWithTitle:@"Enter text" value:@"" placeholder:@"(123) 456-7890" format:@"(XXX) XXX-XXXX"];
[section addItem:self.numberItem];
You can read self.textItem.value
and self.numberItem.value
later whenever you need them.
// Create the manager
//
self.manager = [[RETableViewManager alloc] initWithTableView:self.tableView];
// Add a section
//
RETableViewSection *section = [RETableViewSection sectionWithHeaderTitle:@"Test"];
[self.manager addSection:section];
// Add a bool value cell (using UISwitch)
//
[section addItem:[REBoolItem itemWithTitle:@"Switch test" value:YES switchValueChangeHandler:^(REBoolItem *item) {
NSLog(@"Value: %i", item.value);
}]];
// Create the manager
//
self.manager = [[RETableViewManager alloc] initWithTableView:self.tableView];
// Add a section
//
RETableViewSection *section = [RETableViewSection sectionWithHeaderTitle:@"Test"];
[self.manager addSection:section];
// Add radio cell (options)
//
__typeof (&*self) __weak weakSelf = self;
RERadioItem *optionItem = [RERadioItem itemWithTitle:@"Radio" value:@"Option 4" selectionHandler:^(RERadioItem *item) {
[weakSelf.tableView deselectRowAtIndexPath:item.indexPath animated:YES];
// Generate sample options
//
NSMutableArray *options = [[NSMutableArray alloc] init];
for (NSInteger i = 1; i < 40; i++)
[options addObject:[NSString stringWithFormat:@"Option %i", i]];
// Present options controller
//
RETableViewOptionsController *optionsController = [[RETableViewOptionsController alloc] initWithItem:item options:options completionHandler:^(RETableViewItem *selectedItem) {
item.value = selectedItem.title;
[weakSelf.tableView reloadRowsAtIndexPaths:@[item.indexPath] withRowAnimation:UITableViewRowAnimationNone];
}];
[weakSelf.navigationController pushViewController:optionsController animated:YES];
}];
[section addItem:optionItem];
// Create the manager
//
self.manager = [[RETableViewManager alloc] initWithTableView:self.tableView];
// Add a section
//
RETableViewSection *section = [RETableViewSection sectionWithHeaderTitle:@"Test"];
[self.manager addSection:section];
// Add a float item
//
[section addItem:[REFloatItem itemWithTitle:@"Float item" value:0.3 sliderValueChangeHandler:^(REFloatItem *item) {
NSLog(@"Value: %f", item.value);
}]];
// Create the manager
//
self.manager = [[RETableViewManager alloc] initWithTableView:self.tableView];
// Add a section
//
RETableViewSection *section = [RETableViewSection sectionWithHeaderTitle:@"Test"];
[self.manager addSection:section];
// Add a date item
//
[section addItem:[REDateTimeItem itemWithTitle:@"Date / Time" value:[NSDate date] placeholder:nil format:@"MM/dd/yyyy hh:mm a" datePickerMode:UIDatePickerModeDateAndTime]];
// Create the manager
//
self.manager = [[RETableViewManager alloc] initWithTableView:self.tableView];
// Add a section
//
RETableViewSection *section = [RETableViewSection sectionWithHeaderTitle:@"Test"];
[self.manager addSection:section];
// Add a picker item
//
[section addItem:[REPickerItem itemWithTitle:@"Picker" value:@[@"Item 12", @"Item 23"] placeholder:nil options:@[@[@"Item 11", @"Item 12", @"Item 13"], @[@"Item 21", @"Item 22", @"Item 23", @"Item 24"]]]];
// Create the manager
//
self.manager = [[RETableViewManager alloc] initWithTableView:self.tableView];
// Add a section
//
RETableViewSection *section = [RETableViewSection sectionWithHeaderTitle:@"Test"];
[self.manager addSection:section];
// Add a segmented item
//
[section addItem:[RESegmentedItem itemWithTitles:@[@"One", @"Two"] value:1 switchValueChangeHandler:^(RESegmentedItem *item) {
NSLog(@"Value: %i", item.value);
}]];
Validations are performed using REValidation library.
Example:
self.textItem = [RETextItem itemWithTitle:@"Text" value:@"" placeholder:@"Text item"];
self.textItem.validators = @[@"presence", @"length(3, 10)"];
self.emailItem = [RETextItem itemWithTitle:@"Email" value:@"" placeholder:@"Email item"];
self.emailItem.name = @"Your email";
self.emailItem.validators = @[@"presence", @"email"];
Each item, each section and the manager have property errors
. This property is always up to date with errors on each level.
For example, an RETableViewItem
would only have its own validation errors, RETableViewSection
would have all errors that occured in that section (one per item).
RETableViewManager
's property errors
would reflect all errors.
RETableViewManager
allows to map custom objects to custom cells. In order to map your custom object (an item) to a cell,
simply write:
self.manager[@"CustomItem"] = @"CustomCell";
If you take a look at RETableViewManager Source Code you may find out how default mapping is being performed:
- (void)registerDefaultClasses
{
self[@"__NSCFConstantString"] = @"RETableViewCell";
self[@"__NSCFString"] = @"RETableViewCell";
self[@"NSString"] = @"RETableViewCell";
self[@"RETableViewItem"] = @"RETableViewCell";
self[@"RERadioItem"] = @"RETableViewOptionCell";
self[@"REBoolItem"] = @"RETableViewBoolCell";
self[@"RETextItem"] = @"RETableViewTextCell";
self[@"RELongTextItem"] = @"RETableViewLongTextCell";
self[@"RENumberItem"] = @"RETableViewNumberCell";
self[@"REFloatItem"] = @"RETableViewFloatCell";
self[@"REDateTimeItem"] = @"RETableViewDateTimeCell";
self[@"RECreditCardItem"] = @"RETableViewCreditCardCell";
self[@"REMultipleChoiceItem"] = @"RETableViewOptionCell";
}
Your custom items should be subclassed from RETableViewItem
. Custom cells should be subclassed from RETableViewCell
.
These are 2 base classes that provide all necessary logic to bound your subclasses together.
In your RETableViewCell
subclass you need to link an item
object with your item. This could be simply done by declaring
it:
#import <RETableViewManager/RETableViewManager.h>
#import "CustomItem.h"
@interface CustomCell : RETableViewCell
@property (strong, readwrite, nonatomic) CustomItem *item;
@end
After that your custom object (item) is ready to use within the cell.
There are 3 basic methods of RETableViewCell
that you need to implement:
- Class method to adjust cell size:
+ (CGFloat)heightWithItem:(RETableViewItem *)item tableViewManager:(RETableViewManager *)tableViewManager;
Your custom item will be passed to this method in order to determine cell size. You need to return the calculated size.
- Instance method that is being fired when the cell is being created.
- (void)cellDidLoad;
You might want to create cell subviews here. This method will be called only once, after that the cell will be reused.
- Instance method that is being fired each time the cell is being reused.
- (void)cellWillAppear;
cellWillAppear
is a great place to assign values to labels (from your custom item), adjust colors, etc.
Quick example:
- (void)cellDidLoad
{
[super cellDidLoad];
self.testLabel = [[UILabel alloc] initWithFrame:CGRectMake(0, 0, 200, 44)];
[self.contentView addSubview:self.testLabel];
}
- (void)cellWillAppear
{
[super cellWillAppear];
self.testLabel.text = self.item.someVariable;
}
Interface builder cells are supported out of the box, no special set up needed.
Cells and items are being automatically registered like any other custom cells in RETableViewManager
:
self.manager[@"XIBTestItem"] = @"XIBTestCell";
Here XIBTestItem
would be your cell identifier and you should have the XIBTestCell.xib
file in your bundle. That's it.
It's super easy to customize different offsets and cell background images of
the entire UITableView
(or any particular section) with RETableViewManager
.
RETableViewManager
and RETableViewSection
both have the style
property (an instance of the RETableViewCellStyle
class).
Here's the quick example of how the custom styling works:
// Set default cell height
//
self.manager.style.cellHeight = 42.0;
// Set cell background image
//
[self.manager.style setBackgroundImage:[[UIImage imageNamed:@"First"] resizableImageWithCapInsets:UIEdgeInsetsMake(10, 10, 10, 10)]
forCellType:RETableViewCellTypeFirst];
[self.manager.style setBackgroundImage:[[UIImage imageNamed:@"Middle"] resizableImageWithCapInsets:UIEdgeInsetsMake(10, 10, 10, 10)]
forCellType:RETableViewCellTypeMiddle];
[self.manager.style setBackgroundImage:[[UIImage imageNamed:@"Last"] resizableImageWithCapInsets:UIEdgeInsetsMake(10, 10, 10, 10)]
forCellType:RETableViewCellTypeLast];
[self.manager.style setBackgroundImage:[[UIImage imageNamed:@"Single"] resizableImageWithCapInsets:UIEdgeInsetsMake(10, 10, 10, 10)]
forCellType:RETableViewCellTypeSingle];
// Set selected cell background image
//
[self.manager.style setSelectedBackgroundImage:[[UIImage imageNamed:@"First_Selected"] resizableImageWithCapInsets:UIEdgeInsetsMake(10, 10, 10, 10)]
forCellType:RETableViewCellTypeFirst];
[self.manager.style setSelectedBackgroundImage:[[UIImage imageNamed:@"Middle_Selected"] resizableImageWithCapInsets:UIEdgeInsetsMake(10, 10, 10, 10)]
forCellType:RETableViewCellTypeMiddle];
[self.manager.style setSelectedBackgroundImage:[[UIImage imageNamed:@"Last_Selected"] resizableImageWithCapInsets:UIEdgeInsetsMake(10, 10, 10, 10)]
forCellType:RETableViewCellTypeLast];
[self.manager.style setSelectedBackgroundImage:[[UIImage imageNamed:@"Single_Selected"] resizableImageWithCapInsets:UIEdgeInsetsMake(10, 10, 10, 10)]
forCellType:RETableViewCellTypeSingle];
// Retain legacy grouped cell style in iOS 7
//
if (REDeviceIsUIKit7()) {
self.manager.style.contentViewMargin = 10.0;
self.manager.style.backgroundImageMargin = 10.0;
}
// Set a custom style for a particular section
//
self.accessoriesSection.style = [self.manager.style copy];
[self.accessoriesSection.style setBackgroundImage:[[UIImage imageNamed:@"First_Alt"] resizableImageWithCapInsets:UIEdgeInsetsMake(10, 10, 10, 10)]
forCellType:RETableViewCellTypeFirst];
[self.accessoriesSection.style setBackgroundImage:[[UIImage imageNamed:@"Middle_Alt"] resizableImageWithCapInsets:UIEdgeInsetsMake(10, 10, 10, 10)]
forCellType:RETableViewCellTypeMiddle];
[self.accessoriesSection.style setBackgroundImage:[[UIImage imageNamed:@"Last_Alt"] resizableImageWithCapInsets:UIEdgeInsetsMake(10, 10, 10, 10)]
forCellType:RETableViewCellTypeLast];
[self.accessoriesSection.style setBackgroundImage:[[UIImage imageNamed:@"Single_Alt"] resizableImageWithCapInsets:UIEdgeInsetsMake(10, 10, 10, 10)]
forCellType:RETableViewCellTypeSingle];
Roman Efimov
RETableViewManager is available under the MIT license.
Copyright © 2013 Roman Efimov.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.