EZForm

https://github.com/chrismiles/EZForm

EZForm is a form handling and validation library for iOS. It is designed to be decoupled from your user interface layout, leaving you free to present your form UI any way you like. That doesn't mean EZForm won't integrate with your UI. You tell EZForm which of your controls and views you want to handle each form field, and EZForm will take care of input validation, input filtering and updating views when field values change.

Goals of EZForm

• To simplify form handling and validation while staying out of your way.

• To be decoupled from the user interface layout of the form. Design your form's interface any way you like: with Interface Builder, with code, or any way you choose.

• To assist managing form input and display by working with any user interface controls and views that you tell it about.

• To provide common input conveniences, if requested, such as: keyboard input accessories with navigation between text fields; automatic scrolling or repositioning of views to keep input fields visible; and invalid field indicator management.

Features

• Form field types including: text, boolean, radio.

• Text fields can integrate with views of type: UITextField, UITextView, UILabel.

• Boolean fields can integrate with views of type: UISwitch, UIButton, UITableViewCell.

• Radio fields can integrate with views of type: UILabel.

• Block based validators. User-defined input validation rules can be added to fields as block objects.

• Some common validators are included with EZForm.

• Block based input filters. Input filters control what can be entered by the user. For example, an input filter could be added to a text field to allow only numeric characters to be typed.

• Some common input filters are included with EZForm.

• Standard input accessory and field navigation. A standard input accessory can be added to text fields by EZForm with one method call. It adds a bar to the keyboard with field navigation and done buttons, similar to Mobile Safari's input accessory. Navigation between fields is handled automatically by EZForm.

• Automatic view scrolling to keep active text fields visible. With the option enabled, EZForm will adjust a scroll view, table view or arbitrary view to keep the text field being edited on screen and not covered by a keyboard.

• Invalid field indicators. EZForm can automatically show invalid indicator views on text fields that fail validation. Invalid indicator views can be user-supplied or supplied by EZForm.

Quick Start

Git clone the source.

Copy the EZForm directory to your project and add the contained files to your target.

Import the main header:

#import "EZForm.h"

Create an EZForm instance and add some EZFormField subclass instances to it. For example:

- (void)initializeForm
{
    /*
     * Create EZForm instance to manage the form.
     */
    _myForm = [[EZForm alloc] init];
    _myForm.inputAccessoryType = EZFormInputAccessoryTypeStandard;
    _myForm.delegate = self;

    /*
     * Add an EZFormTextField instance to handle the name field.
     * Enables a validation rule of 1 character minimum.
     * Limits the input text field to 32 characters maximum (when hooked up to a control).
     */
    EZFormTextField *nameField = [[[EZFormTextField alloc] initWithKey:@"name"] autorelease];
    nameField.validationMinCharacters = 1;
    nameField.inputMaxCharacters = 32;
    [_myForm addFormField:nameField];
    
    /*
     * Add an EZFormTextField instance to handle the email address field.
     * Enables a validation rule that requires an email address format "[email protected]"
     * Limits the input text field to 128 characters maximum and filters input
     * to assist with entering a valid email address (when hooked up to a control).
     */
    EZFormTextField *emailField = [[[EZFormTextField alloc] initWithKey:@"email"] autorelease];
    emailField.inputMaxCharacters = 128;
    [emailField addValidator:EZFormEmailAddressValidator];
    [emailField addInputFilter:EZFormEmailAddressInputFilter];
    [_myForm addFormField:emailField];
}

You can update the form fields directly based on user input. But, more commonly, you will wire up your input controls directly to EZForm so it will handle input, validation, field navigation, etc, automatically. For example:

- (void)viewDidLoad
{
    [super viewDidLoad];

    /* Wire up form fields to user interface elements.
     * This needs to be done after the views are loaded (e.g. in viewDidLoad).
     */
    EZFormTextField *nameField = (EZFormTextField *)[_myForm formFieldForKey:@"name"];
    [nameField useTextField:self.nameTextField];
    
    EZFormTextField *emailField = (EZFormTextField *)[_myForm formFieldForKey:@"email"];
    [_myForm useTextField:self.emailTextField];
    
    /* Automatically scroll (or move) the given view if needed to
     * keep the active form field control visible.
     */
    [_myForm autoScrollViewForKeyboardInput:self.tableView];
}

If you wire up any of your views to EZForm you should unwire them in viewDidUnload, which you can do with one method call:

- (void)viewDidUnload
{
    [super viewDidUnload];
    [_myForm unwireUserViews];
}

See the demo app source for more examples of how to work with EZForm.

Demo

A demo universal iOS app is included with the source, containing some example form implementations. The demo app requires iOS 5 (it uses Storyboards).

Documentation

EZForm comes with full API documentation, which is Xcode Document Set ready. Use appledoc to generate and install the document set into Xcode - http://gentlebytes.com/appledoc/

To generate the document set using appledoc from the command-line, cd to the root of the source directory and enter:

./gen-apple-doc-set

Requirements

EZForm is compatible with iOS 4 and upwards.

The demo app included with the source requires iOS 5 (it uses Storyboards).

ARC

The EZForm Master branch is non-ARC. However, producing an ARC version is easy as EZForm memory management is kept clean and ARC-conversion ready.

To generate an ARC version simply open the demo app project in Xcode and select: Edit / Refactor / Convert to Objective-C ARC... The project should convert cleanly and the ARC-ready EZForm source can then be copied to your project. If any ARC problems, please raise an issue.

License

EZForm is released open source with a MIT license. See LICENSE file in the source.

Use it freely for private or commercial use. Attribution is appreciated.