search

chrismiles / EZForm

iOS form handling and validation library.
MIT License
284 stars 64 forks source link

readme

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

Features

Quick Start

Git clone the source.

Add EZForm/EZForm.xcodeproj to your project (or workspace).

Add libEZForm.a to the Linked Frameworks and Libraries for your project.

Add -ObjC to "Other Linker Flags" in your target's build settings.

Import the main header:

#import <EZForm/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"];
    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 "x@y.z"
     * 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"];
    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 = [_myForm formFieldForKey:@"name"];
    [nameField useTextField:self.nameTextField];

    EZFormTextField *emailField = [_myForm formFieldForKey:@"email"];
    [emailField 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.

Simple Login Form Demo Registration Form Demo Registration Form Demo

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 6 and upwards. EZForm uses automatic reference counting (ARC).

The demo app included with the source requires iOS 6.

ARC

EZForm uses automatic reference counting (ARC).

Support

EZForm is provided open source with no warranty and no guarantee of support. However, best effort is made to address issues raised on Github.

If you would like assistance with integrating EZForm or modifying it for your needs, contact the author Chris Miles miles.chris@gmail.com for consulting opportunities.

Used In

EZForm has been used in these iOS projects:

License

EZForm is Copyright (c) 2011-2013 Chris Miles and released open source under a MIT license:

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.