reformed Form Builder Documentation

(A printable version of this help file is available here.)

Documentation by Paul Pullen, reformed Creator

Table of Contents

  1. Overview -- What is reformed?
  2. Installation
  3. Create a Form
  4. The Form Editor
  5. Form Controls
  6. Form Validation
  7. Editing a Form
  8. Testing Your Form
  9. Saving Your Form
  10. Changing Your Form's Theme
  11. Creating Your Own Theme
  12. Adding the Form to Your Website
  13. Processing Your Form
  14. Support and Feedback
  15. Credits

Overview -- What is reformed?

Welcome to reformed--the easiest way to create robust, great-looking forms for your website.

reformed forms are easy to build using the intuitive form editor, and can be styled in a single-click using the built-in theme switcher. Forms created with reformed are styled using the jQuery UI Themeroller, so it's easy to create your own custom theme as well. And if your site already uses jQuery UI, your form will automatically pick up your site's theme styling (or, you can mix-and-match, as reformed CSS files are scoped only to affect reformed forms so as to not interfere with your site's current styling).

Recommended requirements: Browsers: IE8+, Firefox 3.6+, Google Chrome, Safari; jQuery 1.4.4+, jQuery UI 1.8.7+, Uniform jQuery plugin (included), jQuery Validation Library (included).

IMPORTANT: reformed uses HTML5 localStorage to store saved forms, and this requires that reformed be run from a web server, rather than just as a local file. This is because localStorage uses the app's domain name to attach the storage area, and this is unavailable when opening reformed as a local file. A local web server (e.g., WampServer or XAMPP or similar setup) is recommended if you wish to save your forms for later use/editing. reformed will work when opened as a local file in Firefox and Chrome, but not in IE. However, saved data will be lost when your browser is closed when run as a local file, instead of from a local web server.

Back to Top

Installation

Installation is simple: just unzip the reformed bundle and upload to a local web server. Using on a live, online web server is not recommended, as there are no access controls or other protections built-in, and reformed is meant to be run via localhost or as a local app.

reformed will work locally without a web server in Firefox and Chrome, but data will lost upon browser close. Saved data requires HTML5 localStorage, and this requires that reformed be run from a domain.

Back to Top

Creating a Form

Creating a new form is easy: Simply click on "Create a New Form" from the home screen to get started. Next, you'll choose a name for your form, enter a brief description, and decide if you'd like to include a reset button with the submit button. Submit buttons are automatically added to the form upon creation, while reset buttons are optional. Reset buttons allow users to clear the entire form with a single button press, but if a user accidentally clicks one, it can lead to a frustrating experience. It's up to you to decide if your form users will benefit from a reset button or not.

You'll also need to select your form's "action", or, the relative path to the script that will handle the processing of your form on the server. This field defaults to the generic processor script included with reformed (reformed/formmail/formmail.php).

Click the "Open Form Editor" button to proceed to the Form Editor.

Back to Top

The Form Editor

The Form Editor is where you'll build, style, and test your form. It's comprised of two main sections: the Sidebar (where the form controls and other form options) are located, and the Form Preview Area, where you'll see a live preview of your form as you create it. Beneath the Form Preview Area, you'll notice buttons that will allow you to easily change your form's theme, edit your form by adding/rearranging/deleting form elements, test your form's validations and submission variables, and save your form for reuse or editing at a later time.

Next we'll explore the various form elements/controls available to your form.

Back to Top

Form Controls

There are 9 basic and 4 helper form controls that you may add to your form. Each control has several configuration and validation options available. We'll discuss each in turn.

Basic Controls:

  1. Fieldsets

    Fieldsets allow you to visually group related form elements. You may choose to wrap a simple form in a single fieldset, or use several fieldsets to separate groups of form elements for more complex forms. Fieldsets can even be nested within one another.

    To add a fieldset to your form, you'll first need to have added some form controls to your form. When the fieldset controls are opened, you'll be able to click-and-drag a selection box around the elements you wish to group within a fieldset. You may also CTRL-click to add or remove elements from your selection. When finished selecting elements, click the "OK" button beneath the fieldset control button in the Sidebar. You'll be prompted for the fieldset's legend (this is the text that appears in the top left corner of the fieldset, and describes the group of controls), and given the opportunity to assign an optional id or class to the fieldset.

    NOTE: When editing your form (using the "Edit Form" button beneath the Form Preview Area window), if you delete a fieldset, ALL ITEMS WITHIN THAT FIELDSET WILL BE DELETED FROM YOUR FORM AS WELL. Keep this in mind during editing.

  2. Text Fields

    Text fields are appropriate when you require a brief amount of information, such as a name, date, e-mail address, url, or street address, as just a few examples.

    To add a text field to your form, click the (+) button to the right of the text field in the Sidebar. You'll need to provide a name (this is the name that will be sent to your form processor script) and a label for this field. Optionally, you may provide a default value, class, and/or id for this field as well. Several validation options are available for text fields; please see the Form Validation section for a detailed description of these options.

  3. Password Fields

    Password fields are used to enable users to enter private information (e.g., passwords, credit-card numbers, etc.) into forms while concealing it on-screen from others who may have a view of your screen.

    To add a password field to your form, click the (+) button to the right of the password field in the Sidebar. You'll need to provide a name (this is the name that will be sent to your form processor script) and a label for this field. Optionally, you may provide a default value, class, and/or id for this field as well. Several validation options are available for password fields; please see the Form Validation section for a detailed description of these options.

  4. Textareas

    Textareas allow your users to input a lengthier amount of text, such as may be necessary for a feedback form, for example.

    To add a textarea to your form, click the (+) button to the right of the textarea field in the Sidebar. You'll need to provide a name (this is the name that will be sent to your form processor script) and a label for this field. Optionally, you may provide a default value, class, and/or id for this field as well. The number of rows and columns of the textarea may also be adjusted here; default styling is 5 rows and 50 columns. Several validation options are available for textarea fields; please see the Form Validation section for a detailed description of these options.

  5. File Inputs

    File Inputs allow your users to upload files, such as pictures, documents, or videos, to your website.

    To add a file input to your form, click the (+) button to the right of the file input field in the Sidebar. You'll need to provide a name (this is the name that will be sent to your form processor script) and a label for this field. Optionally, you may provide a class or id for this field as well. Several validation options are available for file inputs; please see the Form Validation section for a detailed description of these options.

    Other notes:

    If you add more than one file input to your form and give each of these fields the same name, a "[]" is automatically appended to each of these file inputs names in the form HTML, and these files will be available in a single array to your form processor script. For example, if you have 3 file inputs each named "images", and you have a php form processor script, these files would be available to that script within the $_FILES['images'] array, which could then be looped over to retrieve your desired upload information (see http://www.php.net/manual/en/features.file-upload.post-method.php for more information about PHP file uploads).

    If your form contains a file input, the appropriate enctype attribute (enctype="multipart/form-data") is automatically added to your form.

    The simple form processor included with reformed CANNOT PROCESS FILE UPLOADS! Instead, look into a full-featured form processor such as the FREE Form Tools.

  6. Select Dropdowns/Multiple Select Boxes

    Select Dropdowns and Multiple Select Boxes allow users to select one or more values from a predetermined list of options.

    To add a select dropdown or multiple select box to your form, click the (+) button to the right of the select dropdown in the Sidebar. You'll need to provide a name (this is the name that will be sent to your form processor script) and a label for this field. You'll next need to provide one or more options for the select list.

    For each select option, you'll need to provide that option's submitted value (this is the value sent to the server when this option is selected), as well as the displayed value (this is what the user will see/select in your form). Optionally, you may group options by providing an Option Group heading--each option with the same option group heading will be listed beneath this heading. (NOTE: option groups and their subsequent options are listed in the order they are provided--it's possible to have the same group listed twice unless you keep similar groups contiguous when creating the option list; that is, you should list your options and groups as you wish for them to be presented on the site--no other ordering or automatic grouping is done on select lists.)

    As with other inputs, you may provide an optional class and/or id for your select input. You may also specifiy the size of the select (default is one) and whether or not you will allow users to select multiple options. If the size is more than 1, a select box will be created, instead of a select dropdown. Further, if the multiple selections option is checked, even if the size is listed as 1, a select box with a size of 5 will be created. Several validation options are available for select inputs; please see the Form Validation section for a detailed description of these options.

    Other Notes:

    If your form contains a multiple selection input, the 'multiple="multiple" attribute will be added to your select input, and a "[]" will automatically be appended to the select input's name in the form's HTML, thereby making multiple selections available as an array to your form processor script. For example, if you have a multiple select field named "interests", and a user chooses both "hiking" and "biking", these values will be passed to your form processor script within an array named "interests" ($interests_array = $_POST['interests']; see http://www.php.net/manual/en/faq.html.php for more information about processing form information with PHP.)

  7. Radio Button Groups

    Radio Button Groups are the appropriate choice when there can be one, and only one, valid selection from a group of options.

    To add a radio button group to your form, click the (+) button to the right of the radio button group in the Sidebar. You'll need to provide a name (this is the name that will be sent to your form processor script) and a label for this field. Optionally, you may provide an id and/or class for this field.

    Next, you'll add your radio group's options. Each radio option is comprised of a submitted value (this is the value sent to the form processor script if this particular option is the one selected), and a displayed value (this is what's shown to your form users as the selection). Additionally, you may select the radio button after which option you'd like to be the default selection (if any).

    Several validation options are available for radio buttons; please see the Form Validation section for a detailed description of these options.

  8. Checkbox Groups

    Checkbox Groups allow your users to make one or multiple selections from a group of options.

    To add a checkbox button group to your form, click the (+) button to the right of the checkbox button group in the Sidebar. You'll need to provide a name (this is the name that will be sent to your form processor script) and a label for this field. Optionally, you may provide an id and/or class for this field.

    Next, you'll add your checkbox group's options. Each checkbox option is comprised of a submitted value (this is the value sent to the form processor script if this particular option is one of the one selected), and a displayed value (this is what's shown to your form users as the selection). Additionally, you may select which, if any, options should be selected by default upon page load, by checking the checkbox beside each such option.

    Several validation options are available for checkboxes; please see the Form Validation section for a detailed description of these options.

    Other Notes:

    Checkbox names will automatically have a "[]" appended to them so that these values will be available in an array to your form processor script (see http://www.php.net/manual/en/faq.html.php for more information about processing form information with PHP).

  9. Hidden Inputs

    Hidden Inputs allow you to pass hidden information (e.g., a user ID, submission flag, etc.) to your form processor script along with the rest of your form information when submitted. This infomation is not visible on the form itself (however, be careful, because the information is viewable within the form's HTML code, so don't rely on this mechanism as a means to hide sensitive data).

    To add a hidden input to your form, click the (+) button to the right of the hidden input in the Sidebar. You'll need to provide a name (this is the name that will be sent to your form processor script) and the value of the hidden input. No other options are available or necessary.

    Other Notes:

    Hidden inputs WILL be visible in the Form Preview Area as visual reminders that these have been added to your form. These visual reminders WILL NOT be in the final form code.

Helper Controls:

There are 4 helper controls that allow you to include functionality into your form that would otherwise be complex to code yourself and/or very tedious or time-consuming to include otherwise. These are accessed by clicking the "Helpers" tab at the top of the form controls box.

  1. Datepicker

    The Datepicker allows you to include a pop-up jQuery UI datepicker in your form. Datepickers allow people to enter dates into your form by selecting from a pop-up calendar.

    To include a datepicker in your form, click the (+) button to the right of the datepicker in the Sidebar. Datepicker attributes are the same as an ordinary text field. However, a class of "datepicker" is automatically included with the datepicker text field, allowing reformed to automatically attach the datepicker script to this form element.

    There are several validation options available for the datepicker. Please see the Form Validation section for a detailed description of these options.

  2. State Select Dropdown

    The State Select Dropdown allows you to easily add a state selection dropdown to your form, without the tedious typing of every option by hand.

    To add a state select dropdown to your form, click the (+) to the right of the state select dropdown in the Sidebar. State select attributes are the same regular select dropdowns, except that you do not enter any options.

    Several validation options are available for state select dropdowns; please see the Form Validation section for a detailed description of these options.

  3. Country Select Dropdown

    The Country Select Dropdown allows you to easily add a country selection dropdown to your form, without the tedious typing of every option by hand.

    To add a country select dropdown to your form, click the (+) to the right of the country select dropdown in the Sidebar. Country select attributes are the same regular select dropdowns, except that you do not enter any options.

    Several validation options are available for country select dropdowns; please see the Form Validation section for a detailed description of these options.

  4. Simple Human Verification

    The Simple Human Verification (SHV) control allows you to add a simple verification question to your form to help prevent automated form submissions, similar to CAPTCHAs. Although certainly not bulletproof, this control can help prevent abuse of your form, and it is much less tedious to end users than most other CAPTCHA methods.

    The SHV works by first disabling the form's submit button, then requiring the user to answer a simple question, requiring only a single keystroke to answer, such as "What is 1 + 7?". When answered correctly, the form's submit button is re-enabled, and the user may then submit the form. If answered incorrectly, an error message is shown, and the user is prompted to try again.

    To add an SHV to your form, click the (+) button to the right of the "Human Test" control in the Sidebar. If added to your form, the SHV will always be required to be answered before the form can be successfully submitted. You may enter a name for this input, along with an id and/or class but the label will automatically be replaced with a Verification Question. Validation is handled via a separate script, and although you may add validation options to this field, they are unnecessary.

Back to Top

Form Validation

In every form element configuration dialog, except for fieldsets and SHVs, a set of validation options are available. For client-side validation of forms, reformed uses the wonderful jQuery Validation plugin by Jörn Zaefferer. This allows you to validate fields by adding special classes to the element, such as "required" or "email". If you select validations from the validation menu, these classes will be automatically added to the specific element you're creating. Extra validation rules (not included with the default jQuery validation download) are included with reformed to cover nearly any validation task. Below is a listing of the validation options built-in to the reformed Form Builder, but note that reformed does not use every available validation. This doesn't mean that you can't, however. Please see the above link and download the source from Github for a comprehensive listing of all rules.

It's also worth noting that validation options can be combined; for example, you can require that a text field be both required and contain a valid URL.

Back to Top

Basic Validation Rules

Note about min/max and minimum/maximum validation error messages: if you enter values in both the min and max or minimum and maximum validation boxes, the error message will reflect this range, rather than two separate error messages being applied. For example, a message similar to "Please select between MIN and MAX options" will be generated, with MIN and MAX replaced with the actual valid amounts. This applies for subsequent validation options as well.

Text-based Validations

Numeric-based Validations

File-based Validations

Date-based Validations

Important Note:

Client-side validation should be used as a convenience, and NOT as the ONLY input validation check you do. Javascript validation is easy to circumvent and should be complimented with appropriate Server-side validation checks; NEVER RELY SOLELY ON CLIENT-SIDE VALIDATION, ESPECIALLY IF YOU ALLOW UPLOADS VIA YOUR FORMS!!!

Back to Top

Editing a Form

Once you have added various elements to your form, you might wish to rearrange or even delete one or more of these elements. To do so, simply click the "Edit Form" button beneath the Form Preview Area on the Form Editor page to enter edit mode.

Every editable element will become draggable, and you may rearrange form elements as you desire. Each editable element will also be given an (X) button, that when clicked, will delete the element(s) to which its attached. NOTE: if you delete a fieldset, ALL ELEMENTS WITHIN THAT FIELDSET WILL BE DELETED AS WELL. If you need to edit a fieldset, it's probably best to just edit the form's HTML (see below).

If you wish to add other HTML to your form, or wish to do more complex editing, such as adding/removing fieldsets, classes, and ids, styles, etc., you may click the "Edit HTML" button in the Sidebar. This will bring up the raw HTML inside an editor box for you to manipulate as you wish. If you are unfamiliar with HTML or form code in general, it's likely best to avoid this feature if possible. Also note that the form's basic markup structure (a series of definition lists (dl tags) ), should remain intact to ensure proper styling.

When finished editing your form, click the "Edit Form" button again to restore the Form Controls Sidebar.

Back to Top

Testing Your Form

While in the Form Editor, your form will not be submitted to a processor script if you happen to click the Submit button. However, you may test your validations and see what names and values would have been submitted to a processor script by clicking the "Test Form" button (or the Submit button of your form).

Note: Values passed to your form processor script as arrays, such as a series of checkbox values, are presented as a comma-delimited list in the test form results window. Further, file inputs' values are NOT listed in the test results.

Back to Top

Saving Your Form

Once you have created your form, you'll naturally want to save it. This is easily accomplished by clicking the "Save Form" button in the Form Editor. reformed uses new HTML5 technology to save your forms to your browser's internal storage (localStorage). As such, to successfully save your form, you will need a browser that supports localStorage. IE8+, Firefox 3.5+, Google Chrome, and Safari are all acceptable choices.

To view, edit, and get your form's HTML code to add it to your site, simple click on "View/Edit Saved Forms" from the home screen. You'll see a list of all the forms saved to that particular browser. Please note that each browser maintains its own storage area; therefore, forms saved using Firefox will not be available from IE or Chrome, for example.

Back to Top

Changing Your Form's Theme

One of the coolest features of reformed is that it uses jQuery UI themes to style form elements*, making it easy to change the entire look and feel of your form with just a few button clicks. Using the jQuery UI Themeroller tool, you can even create your own theme to custom match your current site (see Creating Your Own Theme for instructions).

reformed comes with all the built-in themes found on the jQuery UI site. Changing themes is as easy as clicking the "Change Theme" button, and selecting you new theme. You'll be instructed on how to add the themed form to your site when you click the "Get Code" link from the Saved Forms screen. Another neat feature is that all form style code is scoped to affect only the reformed-generated form, so it shouldn't affect your current site if you're using a different jQuery UI theme with your site. Detailed instructions about adding the form to your site can be found in the Adding the Form to Your Website section below.

*Note: file inputs, select dropdowns, radio buttons, and checkboxes are styled separately using the wonderful Uniform jQuery plugin.

Back to Top

Creating Your Own Theme

If you'd like to create your own custom theme using the jQuery UI Themeroller tool, simply style your theme as you normally would, and then proceed to the Themeroller download page. In the middle-top right of the download page, in the "Theme" box, there is an "Advanced Theme Settings" link--click this link and you will be given options to set the CSS scope and name of the custom theme.

CSS scoping limits the effects of the theme's styling to a particular set of elements on your site. If you plan to use the custom theme sitewide to style all elements on your site, you do not have to scope your CSS--just download and use it as you normally would on your site, and remove the link to any reformed-form theme CSS in your document head. However, if you want the theme to apply only to the reformed-forms on your site, in the CSS scope box, enter ".reformed-form" (note the leading "."). Since reformed forms are wrapped in a div with a class of .reformed-form, the theme settings will only apply to the form (or any other elements you wrap in such a div). You'll also need to give the theme a name, and include a link to the theme's CSS file in your document head.

Back to Top

Adding the Form to Your Website

reformed requires that your site have jQuery 1.4+ (1.4.4 recommended) and jQuery UI 1.8.7+ available. Without these two scripts, reformed will not work.

You may download these from the jQuery site.

The following are instructions for adding your reformed form to your website:

  1. On the "Saved Forms" screen, find the form you'd like to add to your site and click the "Get Code" link for that form.

  2. Copy-and-paste the form code into your site where you'd like to display your form.

  3. You'll need to download the 2 packages listed on the "Get Code" pop-up containing the necessary code and styles to transform your forms:

    • reformed.zip -- This contains all the base and auxiliary reformed code and css, along with the generic php form processor script. Unzip this and copy the entire folder to your server. The only file you'll ever need to edit in this bundle may be the ui.reformed.css file, which defines the basic structural style of the HTML form (e.g., input widths, label widths, etc.).
    • reformed-form-(your-chosen-theme).zip -- This contains the specific jQuery UI styles for your chosen form theme. Unzip this and upload the entire folder to your server (typically to your CSS folder, but this is not a requirement.) NOTE: if your site is already themed by jQuery UI, and you wish for your form to inherit these existing styles, you only need to include the base reformed files into your site, and may ignore the reformed-form-theme folder.
  4. In the head of your HTML page, include references to the following reformed CSS and js files (taking care to ensure correct paths depending upon where you uploaded these files on your server):

    Be sure to replace the "YOUR-THEME" reference in the last CSS include above with the name of your theme's CSS files! Also, you may wish to combine the reformed javascript files and css files into respective single files for convenience; they are submitted with reformed as separate files to offer as modular an experience as possible.

  5. Now you're ready to setup the default validation options for your form, and add the call to the included jQuery UI reformed plugin, which does all the magic of styling your form.

    Simply add the following validation code, and then call reformed() on any jQuery form object, like so:

    The reformed plugin has various options that may be set when called to control certain aspects of the form's styling. All options are displayed below, with their default values:

    Note: calling these after reformed has already been called using the $(selector).reformed("option", "name" , "newValue") format may result in some unexpected behavior (we're working on it). It's best to set any desired options during the initial call to reformed.

  6. That's it! Your form should be displayed in all its reformed glory now!
Back to Top

Processing Your Form

reformed ships with a basic form processor that e-mails form submissions to a specified address, and that doesn't handle file uploads. You'll likely require a more robust server-side form processor script. There are many free examples online that you may use, but remember that these may not include validation checks or other necessary form handling code, so use them with caution.

Instructions for the included php FormMail form processor script (© Matt Brown -- see license or Credits for a link) can be found here. If you use this script to process your form, you must include a hidden input in your form with a name of "recipient" and a value of the e-mail address to which the form results will be mailed, like so:

<input type="hidden" name="recipient" value="email@example.com">

There are several configuration options you may setup, such as redirects upon successful submission, or customization of "Thank You" messages. Please see the FormMail documentation for full configuraiton options.

For a FREE, robust, and complete form handling solution, check out Form Tools.

Back to Top

Support and Feedback

I'd love to hear your ideas and feedback about reformed! Visit ReformedApp.com to share your feedback, or if you need help with a specific problem and you couldn't find the answer in this help file.

Back to Top

Credits

reformed would like to give a "shout out" to these awesome scripts/libraries:

For a robust, FREE, and complete form processing solution, check out Form Tools.

Back to Top