tomthorogood / tl-forms Goto Github PK

TL Forms is a javaScript library which assists in easy creation and
implementation of forms in a jQuery powered application.
    
Copyright (C) 2012 Tom Thorogood (Turn Left, LLC)
[email protected] | http://www.turnleftllc.com

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
===============================
REQUIREMENTS

In order to use TL Forms, you must have the following:
    jQuery (jquery.com)
    jQuery UI (for the slide animation, and some color animations) (jqueryui.com)

Certain implementations also require other libraries:
    The jQuery form plugin (for ajaxSubmit): http://jquery.malsup.com/form/
    The TL Overlay class (http://www.turnleftllc.com/api/tl_overlay.js)

================================
SETUP:

If you're on linux, run build.sh in the tools/ directory. You must have Java 6 in order to do so.
This will combine all the necessary files and minimize them, placing the dev version in dev/ and the minified version in min/.

If you're on windows, run concat.py, and then minify.py. Concat combines all the files in src, and minify minifies that output.
Most likely, this won't even be necessary, as this utility should be run before each push into the repository, but just in case...

The base use is fairly straightforward. The following must be included in your HTML code:
<script type="text/javascript" src="[[path to jquery]]"></script>
<script type="text/javascript" src="[[path to jquery ui]]"></script>
<!--optional, but recommended
<script type="text/javascript" src="tl_overlay.js"></script>
<script type="text/javascript" src="jquery.form.js"></script>
-->
<script type="text/javascript" path/to/min/="tl_forms.js"></script>

===============================
USE:

Creating a form widget with TL-Forms is super easy.
To start, instantiate your widget:
var widget = new Form_Widget(
    "POST", "handler_url.php", 
    /* disable overlay */ true, 
    /* div where your form should appear */ document.getElementById('my_form_goes_here'
    );

Then, add stuff in!

widget.add_field({
    name    :   "email_address",
    type    :   "text",
    valid_as:   "email",
    required:   true,
    value   :   "Enter Your Email Address
});

Want to break your form into chunks! Split the fields into groups:

widget.grouping("Contact Info", ["email_address", "phone_number"]);
widget.grouping("Favorite Things", ["color", "food", "dog breed"]);

Want a progress bar?

widget.enable_progress_bar("parent_div", "progress_bar_div");
widget.progress_button("my_progress_button");

Ajax submission?
widget.set_ajax(true, "handler_url.php", function() { ...your callback ... });

Instructions to your user?
widget.add_instructions("email_address", "Please eneter your email address so that we can send you spam!");
widget.set_instructions("div_where_instructions_should_go");
================================

TOOLS:
    Within the tools folder, there is a shell command called "build". This runs concat.py, and subsequently minify.py.
    concat.py will take everything src/ and make one big file in dev/ called tl_forms.js.
    minify.py will use the YUI Compressor to minify that giant file and place it in min/
    As a general convention, before committing, please use these tools.

    If you are on Windows, please create a version of these that works on Windows!  The YUI Compressor
    is included in tools/ as well. No need to have that already installed, but you will need Java. 
===============================

DEVELOPMENT:
    To keep things organized, each individual "class" (Constructor & prototypes) is stored separate in src/
    as is Java's convention. I'm not a fabulous Java developer by trade, but I rather love the 
    one class per file requirement. 

    The good news is that it's organized. The bad news is that debugging can be a little bit of a pain.
    It is easiest if the unit testing html file includes each individual src/ class. However before moving
    to production, you'll want to use the giant concatenated version in dev/ so that when you're ready to deploy,
    the only thing you'll have to change is dev/ -> min/. if you start running into problems, change it back.
    
    Never edit the file in dev/. If you edit that, and then reuse the build tool, you'll erase your changes. 
    Never edit the file in dev/. If you edit that, and then reuse the build tool, you'll erase your changes.
    Never--you get this, right?