back to Modules

Formbuilder

About

This is the next generation of Feedback Forms, which will include an API for modules to use, as well as a general structured data system.

• Project homepage

What Does This Do?

The Form Builder Module allows you to create feedback forms (in fact, it's a replacement of the original Feedback Form module), with the added power of database storage. With its companion module Form Browser, you can use it to create simple database applications.

The forms created using the Form Builder may be inserted into templates and/or content pages. Forms may contain many kinds of inputs, and may have validation applied to these inputs. The results of these forms may be handled in a variety of ways.

How Do I Use it?

Install it, and poke around the menus. Play with it. Try creating forms, and adding them to your content. If you get stuck, chat with me on the #cms IRC channel, post to the forum, send me email, or, if you're really desperate, read the rest of this page.

How Do I Create a Form

In the CMS Admin Menu, you should get a new menu item called FormBuilder. Click on this. On the page that gets shown, there are options (at the bottom of the list of Forms) to Add a New Form or Modify Configuration. Adding a Form to a Page

In the main FormBuilder admin page, you can see an example of the tag used to display each form. It looks something like {cms_module module='FormBuilder' form='sample_form'}

By copying this tag into the content of a page, or into a template, will cause that form to be displayed. In theory, you can have multiple forms on a page if you really want to. Be careful when pasting the tag into a page's content if you use a WYSIWYG editor such as TinyMCE or HTMLArea. These editors may stealthily change the quote marks (") into HTML entities ("), and the forms will not show up. Try using single quotes (') or editing the HTML directly.

Working with Forms

By clicking on a Form's name, you enter the Form Edit page. There are several tabs, which are described below:

Main

This is the main place you'll work on your form. Here, you give it a name, an alias (which is used to identify it for placing it in a page or template), and, optionally, a CSS class with which to wrap the whole thing. You also select the display type. Your choices are:

• Table/CSS. The form is created using HTML tables. If you don't know what to choose, this is the easiest option, and will probably do most of what you want. You can still use CSS to style the form if you want.
• Pure CSS. The form is created, with all the fields wrapped in
  tags. You can then style the form as you see fit.
• Custom Template. Basically, you get a smarty template, a bunch of variables, and you're on your own. You have the power to create whatever you want.

Below this, if you have it enabled, is the "fast field adder" pulldown, that lets you quickly add a field to the end of your form by selecting the field type.

Below this is the list of fields that make up your form. More detail on this is described below.

Form Settings

Form Settings allows you to customize a lot of the messages and text in the controls for your form. It also allows you to pick a page to redirect users to after a successful form submission.

Table-based Layout Options

Table-layouts have gotten simpler, so your only option here is the position of the field names relative to the inputs. If you're using a Table/CSS layout, you can use this tab to select the field name positions.

Template Layout Options

This is where you do your customization work if your form uses a Custom Template.

The form should default to a a Custom template that documents the smarty tags available to you. Unless you're a smarty expert, you probably don't want to mess around with this. If you are a smarty expert, this is where you can unleash your magic.

Adding Fields to your Form

The types of fields that are currently supported fit into four groups: standard input fields, display control fields, email-specific fields, and form result handling fields (also called Form Dispositions in places):

• Standard Input Fields - these are inputs that allow entry of typical form elements; text inputs, radio buttons, etc.
• Display Control Fields - these input control how the user will see the display of the form; page breaks, static text, etc.
• Email-specific Fields - some forms generate email, and email-specific fields can alter attributes of the emails sent.
• Form Dispositions - These determine what happens when the user submits the form; for each result handling field, some method of transmitting, saving, or emailing the form contents takes place. A form may have multiple form dispositions.

Form fields are assigned names. These names identify the field, not only on the screen as labels for the user, but in the data when it's submitted so you know what the user is responding to. Phrasing the name like a question is a handy way of making it clear to the user what is expected. Similarly, many fields have both Names and Values. The Names are what gets shown to the user; the Value is what gets saved or transmitted when the user submits the form. The Values are never seen by the user, nor are they visible in the HTML, so it's safe to use for email addresses and such.

Some fields can have multiple values, or multiple name/value pairs. When you first create such a field, there may not be sufficient inputs for you to specify all the values you want. To get more space for inputting these values, use the buttons at the bottom of the page for adding options.

Fields can be assigned validation rules, which vary according to the type of the field. These rules help ensure that the user enters valid data. They may also be separately marked "Required", which will force the user to enter a response.

Fields also may be assigned a CSS class. This simply wraps the input in a div with that class, so as to allow customized layouts. To use this effectively, you may need to "view source" on the generated form, and then write your CSS.

• Standard Inputs
  • Text Input. This is a standard text field. You can limit the length, and apply various validation functions to the field.
  • Text Area. This is a big, free-form text input field.
  • Checkbox. This is a standard check box.
  • Checkbox Group. This is a collection of checkboxes. The only difference between this input and a collection of Checkbox inputs is that they are presented as a group, with one name, and can have a validation function requiring that you check one or more of the boxes in the group.
  • Radio Group. This is a collection of radio buttons. Only one of the group may be selected by the user.
  • Pulldown. This is a standard pulldown menu. It's really conceptually the same thing as a radio button group, but is better when there are a large number of options.
  • Multiselect. This is a multi-select field. It's really conceptually the same thing as a checkbox button group, but is better when there are a large number of options, as you can limit the number displayed on the screen at any one time.
  • State. This is a pulldown listing the States of the U.S.
  • Countries. This is a pulldown listing the Countries of the world (as of July 2005).
  • Date Picker. This is a triple pulldown allowing the user to select a date.
• Email-specific Inputs
  • Email From Address Field. This allows users to provide their email address. The email generated when the form gets handled will use this address in the "From" field.
  • Email From Name Field. This allows users to provide their name. The email generated when the form gets handled will use this name in the "From" field.
• Display Control Fields
  • -Page Break. This allows you to split your feedback form into multiple pages. Each page is independently validated. This is good for applications like online surveys.
  • -Static Text. This allows you to put text or a label in the middle of your form. This is useful for giving additional help text, especially if you're not using a Custom Template to render your form.
• Form Handling Inputs (Dispositions)
  • *Email Results Based on Pulldown. This is useful for web sites where comments get routed based on their subject matter, e.g., bugs get sent to one person, marketing questions to another person, sales requests to someone else, etc. The pulldown is populated with the subjects, and each gets directed to a specific email address. You set up these mappings in the when you create or edit a field of this type. If you use one of these "Director" pulldowns, the user must make a selection in order to submit the form. This input is part of the form the user sees, although the email addresses are not made visible nor are they embedded in the HTML.
  • *Email Results to set Address(es). This simply sends the form results to one or more email addresses that you enter when you create or edit this type of field. This field and its name are not visible in the form that the user sees. The email addresses are not made visible nor are they embedded in the HTML.
  • *Store Results in Database. This will store the form contents in an internal database. You will always use this disposition if you use the form with FormBrowser.
  • *Validate via Email. This is a strange and powerful field. It provides the user a mandatory input for their email address. Once they submit their form, the standard form dispositions are not performed -- rather, it send the user an email with a special coded link. If they click on the link, the other form is considered "approved," and the other dispositions are all performed.
  • *Write Results to Flat File. This takes the form results and writes them into a text file. You may select the name of the file, and set its format. These files are written to the "output" directory under the module's installation directory, assuming the web server has permission to write there.

Email and Flat File Templates

Many disposition types allow you to create a template for the email that is generated, or for the way the results are written to a file. If you opt not to create a template, the FormBuilder will use it's own best guess, which may or may not work out to your liking. You can always click on the "Create Sample Template" and then customize the results.

Note that once you've changed a template, it will no longer automatically add new fields. For this reason, it's usually best to create your templates as the last step of creating your form.

Known Issues:

• Some field types from FeedbackForms are not implemented in FormBuilder. If there is demand for them, they will be added.
• FormBuilder is not yet integrated with FrontEnd Users. It will be.
• FormBuilder cannot yet be inlined. That should be a simple upgrade down the line.
• FormBuilder does not yet support pretty urls, although that shouldn't matter since the user side is pretty simple.

Troubleshooting

1. First step is to check you're running CMS 1.0-svn or later.
2. Second step is to read and understand the caveat about WYSIWYG editors up in the section Adding a Form to a Page.
3. If you're missing fields in an email that gets generated, check the disposition field's template, and make sure you're specifying the missing fields. Seems obvious, but it's an easy mistake to make.
4. Just mess around and try clicking on links and icons and stuff. See what happens.
5. Last resport is to email me or catch me on IRC and we can go from there.

This is a fairly early version, if not a rank beta release, and it is probably still buggy. While I've done all I can to make sure no egregious bugs have crept in, I have to admit that during testing, this program revealed seven cockroaches, two earwigs, a small family of aphids, and a walking-stick insect. It also ate the neighbor's nasty little yap dog, for which I was inappropriately grateful.

The final release will include bug fixes, documentation, and unconditional love.

Support

This module does not include commercial support. However, there are a number of resources available to help you with it:

• For the latest version of this module, FAQs, or to file a Bug Report, please visit the CMS Made Simple Developer Forge.
• To obtain commercial support, please send an email to the author at <sjg AT cmsmodules DOT com>.
• Additional discussion of this module may also be found in the CMS Made Simple Forums.
• The author can often be found in the CMS IRC Channel.
• Lastly, you may have some success emailing the author directly and grovelling for free support.

As per the GPL, this software is provided as-is. Please read the text of the license for the full disclaimer.

Copyright and License

Copyright © 2006, Samuel Goldstein. All Rights Are Reserved.

This module has been released under the GNU Public License. You must agree to this license before using the module.

Dependencies

• CMSMailer => 1.73

Parameters

• (optional) lang="en_US" - Parameter is used to specify what language to use for display on the frontend. Not all modules support or need this.

User questions

There aren't any forums for this extension, so... will this module be able to send html/multipart-alternative emails? If it already does, how do you set that up?

back to Modules

This page in: English - Deutsch - Español - Français - Italiano - Lietuvių - Nederlands - Norsk - Polski - Česky - Русский - Svenska - Tiếng Việt - عربي - 日本語 简体中文