XLForm

If you are working in Swift then you should have a look at [Eureka], a complete re-design of XLForm in Swift and with more features.

We are not implementing any new features for XLForm anymore. However, if a critical issue arises we will fix it.

Purpose

XLForm is the most flexible and powerful iOS library to create dynamic table-view forms. The goal of the library is to get the same power of hand-made forms but spending 1/10 of the time.

XLForm provides a very powerful DSL (Domain Specific Language) used to create a form. It keeps track of this specification on runtime, updating the UI on the fly.

Let's see the iOS Calendar Event Form created using XLForm

Screenshot of native Calendar Event Example

What XLForm does

Loads a form based on a declarative form definition.
Keeps track of definition changes on runtime to update the form interface accordingly. Further information on Dynamic Forms section of this readme.
Supports multivalued sections allowing us to create, delete or reorder rows. For further details see Multivalued Sections section bellow.
Supports custom rows definition.
Supports custom selectors. For further details of how to define your own selectors check Custom selectors section out.
Provides several inline selectors such as date picker and picker inline selectors and brings a way to create custom inline selectors.
Form data validation based on form definition.
Ability to easily navigate among rows, fully customizable.
Ability to show inputAccessoryView if needed. By default a navigation input accessory view is shown.
Read only mode for a particular row or the entire form.
Rows can be hidden or shown depending on other rows values. This can be done declaratively using NSPredicates. (see Make a row or section invisible depending on other rows values)

How to create a form

Create an instance of XLFormViewController

Swift

class CalendarEventFormViewController : XLFormViewController {

  required init(coder aDecoder: NSCoder) {
    super.init(coder: aDecoder)
    self.initializeForm()
  }


  override init(nibName nibNameOrNil: String?, bundle nibBundleOrNil: NSBundle?) {
    super.init(nibName: nibNameOrNil, bundle: nibBundleOrNil)
    self.initializeForm()
  }

  func initializeForm() {
    // Implementation details covered in the next section.
  }

}

Objective-C

#import "XLFormViewController.h"

@interface CalendarEventFormViewController: XLFormViewController

@end

@interface ExamplesFormViewController ()

@end

@implementation ExamplesFormViewController

- (instancetype)initWithNibName:(NSString *)nibNameOrNil bundle:(NSBundle *)nibBundleOrNil {
    self = [super initWithNibName:nibNameOrNil bundle:nibBundleOrNil];
    if (self){
        [self initializeForm];
    }
    return self;
}

- (id)initWithCoder:(NSCoder *)aDecoder {
    self = [super initWithCoder:aDecoder];
    if (self){
        [self initializeForm];
    }
    return self;
}

- (void)initializeForm {
  // Implementation details covered in the next section.
}

@end

Implementing the initializeForm method

To create a form we should declare it through a XLFormDescriptor instance and assign it to a XLFormViewController instance. As we said XLForm works based on a DSL that hides complex and boilerplate stuff without losing the power and flexibility of hand-made forms.

To define a form we use 3 classes:

XLFormDescriptor
XLFormSectionDescriptor
XLFormRowDescriptor

A form definition is a XLFormDescriptor instance that contains one or more sections (XLFormSectionDescriptor instances) and each section contains several rows (XLFormRowDescriptor instance). As you may have noticed the DSL structure is analog to the structure of a UITableView (Table -->> Sections -- >> Rows). The resulting table-view form's structure (sections and rows order) mirrors the definition's structure.

Let's see an example implementation of initializeForm to define the iOS Calendar Event Form

- (void)initializeForm {
  XLFormDescriptor * form;
  XLFormSectionDescriptor * section;
  XLFormRowDescriptor * row;

  form = [XLFormDescriptor formDescriptorWithTitle:@"Add Event"];

  // First section
  section = [XLFormSectionDescriptor formSection];
  [form addFormSection:section];

  // Title
  row = [XLFormRowDescriptor formRowDescriptorWithTag:@"title" rowType:XLFormRowDescriptorTypeText];
  [row.cellConfigAtConfigure setObject:@"Title" forKey:@"textField.placeholder"];
  [section addFormRow:row];

  // Location
  row = [XLFormRowDescriptor formRowDescriptorWithTag:@"location" rowType:XLFormRowDescriptorTypeText];
  [row.cellConfigAtConfigure setObject:@"Location" forKey:@"textField.placeholder"];
  [section addFormRow:row];

  // Second Section
  section = [XLFormSectionDescriptor formSection];
  [form addFormSection:section];

  // All-day
  row = [XLFormRowDescriptor formRowDescriptorWithTag:@"all-day" rowType:XLFormRowDescriptorTypeBooleanSwitch title:@"All-day"];
  [section addFormRow:row];

  // Starts
  row = [XLFormRowDescriptor formRowDescriptorWithTag:@"starts" rowType:XLFormRowDescriptorTypeDateTimeInline title:@"Starts"];
  row.value = [NSDate dateWithTimeIntervalSinceNow:60*60*24];
  [section addFormRow:row];

  self.form = form;
}

XLForm will load the table-view form from the previously explained definition. The most interesting part is that it will update the table-view form based on the form definition modifications. That means that we are able to make changes on the table-view form adding or removing section definitions or row definitions to the form definition on runtime and you will never need to care again about NSIndexPath, UITableViewDelegate, UITableViewDataSource or other complexities.

To see more complex form definitions take a look at the example application in the Examples folder of this repository. You can also run the examples on your own device if you wish. XLForm has no dependencies over other pods, anyway the examples project makes use of some cocoapods to show advanced XLForm features.

Using XLForm with Storyboards

Perform the steps from How to create a form
In Interface Builder (IB), drag-and-drop a UIViewController onto the Storyboard
Associate your custom form class to the UIViewController using the Identity Inspector

How to run XLForm examples

Clone the repository git@github.com:xmartlabs/XLForm.git. Optionally you can fork the repository and clone it from your own github account, this approach would be better in case you want to contribute.
Move to either the Objective-c or Swift example folder.
Install example project cocoapod dependencies. From inside Objective-c or Swift example folder run pod install.
Open XLForm or SwiftExample workspace using XCode and run the project. Enjoy!

Rows

Input Rows

Screenshot of Input Examples

Input rows allows the user to enter text values. Basically they use UITextField or UITextView controls. The main differences among the input row types is the keyboardType, autocorrectionType and autocapitalizationType configuration.

static NSString *const XLFormRowDescriptorTypeText = @"text";

Will be represented by a UITextField with UITextAutocorrectionTypeDefault, UITextAutocapitalizationTypeSentences and UIKeyboardTypeDefault.

static NSString *const XLFormRowDescriptorTypeName = @"name";

Will be represented by a UITextField with UITextAutocorrectionTypeNo, UITextAutocapitalizationTypeWords and UIKeyboardTypeDefault.

static NSString *const XLFormRowDescriptorTypeURL = @"url";

Will be represented by a UITextField with UITextAutocorrectionTypeNo, UITextAutocapitalizationTypeNone and UIKeyboardTypeURL.

static NSString *const XLFormRowDescriptorTypeEmail = @"email";

Will be represented by a UITextField with UITextAutocorrectionTypeNo, UITextAutocapitalizationTypeNone and UIKeyboardTypeEmailAddress.

static NSString *const XLFormRowDescriptorTypePassword = @"password";

Will be represented by a UITextField with UITextAutocorrectionTypeNo, UITextAutocapitalizationTypeNone and UIKeyboardTypeASCIICapable. This row type also set the secureTextEntry to YES in order to hide what the user types.

static NSString *const XLFormRowDescriptorTypeNumber = @"number";

Will be represented by a UITextField with UITextAutocorrectionTypeNo, UITextAutocapitalizationTypeNone and UIKeyboardTypeNumbersAndPunctuation.

static NSString *const XLFormRowDescriptorTypePhone = @"phone";

Will be represented by a UITextField with UIKeyboardTypePhonePad.

static NSString *const XLFormRowDescriptorTypeTwitter = @"twitter";

Will be represented by a UITextField with UITextAutocorrectionTypeNo, UITextAutocapitalizationTypeNone and UIKeyboardTypeTwitter.

static NSString