Event triggered when a FormBuilder form is submitted.
Event triggered if there is an error when a FormBuilder form is submitted
Event triggered when a FormBuilder form is displayed
You can edit it to make your form layout look any way you'd like. To make the form work, you'll need to always include the {\$fb_hidden} and {\$submit} tags.
You can access your form fields either using the \$fields array or by directly accessing fields by their names (e.g., {\$myfield->input} )
Each field has the following attributes:
In the case of a multipage form, you will also have access to the value of previous fields. They are in the \$previous array, or accessible by their names (e.g., {\$myfield->value} ). You can use this in Static Text fields as well, which is a nice way to personalize forms!
In certain cases, field->input is actually an array of objects rather than an input. This happens, for example, in CheckBoxGroups or RadioButtonGroups. For them, you can iterate through field->input->name and field->input->inputs.
Additional smarty variables that you can use include:
Dunno why you'd want some of those, but there you go...
The Form Builder Module allows you to create 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.
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, try reading the instructions on the rest of this page.
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.
In the main FormBuilder admin page, you can see an example of the tag used to display each form. It looks something like {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, FCKEdit, 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.
By clicking on a Form's name, you enter the Form Edit page. There are several tabs, which are described below:
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.
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.
When the form is submitted, you can either redirect the user to another page of your site, or you can present the user some message (which can contain any of the user's form entries, or just static text). In this tab, you select which of these approaches you wish to use, and, if you chose redirection, it allows you to pick the page to redirect users to after a successful form submission.
Also on this page, you can specify the labels of various submission buttons (\"Previous\", \"next\", \"submit\"). You can also opt to have some Javascript added to the last page of a form that will prevent multiple submissions (useful on slow servers).
This tab allows for other form customizations, like the symbol to show for required fields.
If you have installed the Captcha module, this tab lets you configure the Captcha settings for your form.
This is where you do your customization work of your form's Smarty Template. See the section called Form Template Variables below.
The form should default to 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.
If, in the Form Submission tab, you selected 'Display \"Submission Template\", this is where you can create that template. There is a display of which smarty variables are available to you, and a button to generate a sample template.
If you're a Smarty expert, you can do all manner of creative and powerful things here. If you're not a Smarty expert, you might just want to use the default.
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):
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.
Calguy added a nice feature, which is that you can pass default field values to your form via the module tag. This allows you to have the same form in multiple places, but with different default values. It may not work for more exotic field types, but for fields that have a single value, you can specify like:
{FormBuilder form='my_form' value_FIELDNAME='default_value'}
This will set the field with FIELDNAME to 'default_value'.
This can be problematic, as sometimes field names are unwieldy or contain characters that don't work well with Smarty. So there is an alternative like this:
{FormBuilder form='my_form' value_fldNUMBER='default_value'}
That uses field NUMBER, where NUMBER is the internal FormBuilder field id. You might wonder how you know what that id is. Simply go into the FormBuilder configuration tab, and check \"Show Field IDs\"
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.
To the right, you'll find a legend which lists all of the variables that are available to you to use in your template. As of version 0.3, variables have two names, one based on the field name, the other based on the field ID. If you use field names that have characters outside of the ASCII 32-126 range, it will be safer to use the ID-based variables.
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.
As of version 0.2.4, you can opt to send any of these emails as HTML email. There should be a checkbox at the top of the template page for this. There is also a \"Create Sample HTML Template\" button over in the legend area. For HTML email, the email body will also provide the default text-only values.
There are some special features when using FormBuilder with FormBrowser. The new approach stores the form results in XML, so that far fewer queries are needed to retrieve records. This means you can use FormBrowser with hundreds or even thousands of records. It also means you will have to choose up front which fields you will want to be able to sort by. You can choose up to five.
In advanced options, you can tie a form to Frontend Users. That means each user gets one record for the form; they can create it a single time, subsequent times they will be editing their record. The record will not be visible to any other users (excluding admins). This form should be added to your page using the syntax {FormBuilder action='feuserform' form='form_name'}.
For greater data safety, you can encrypt the stored forms in the database. You can use the built-in mycrypt library or the OpenSSL module. In either case, for the passphrase, you can either enter text in the field or a file name. If you specify a file name, the contents of that file will be used as the passphrase for encrypting.
If you encrypt, be aware that the fields you use for sorting are not encrypted. You can choose to hash them; the cheat here is that the first four letters are left intact to allow for sorting. The sorting may not be perfect, and this weakens the security since it exposes some cleartext, but it is better than nothing.
DISCLAIMER. The encryption offered here should be considered just one more hurdle for a hacker, not as a guarantee that your information will be secure. A smart hacker who has found some exploit to view database records may well be smart enough to get at the module source code, and find their way to the passphrase. This will not protect you against an enemy who has full access to your server, some familiarity with PHP, and the time to poke around. Do not use this to protect high-value information such as financial data, sensitive political information, human rights data, or anything else that might be of value to a repressive government or organized crime cartel.
There are some global configuration options for FormBuilder:
After a bit of nagging on the part of people who actually respect standards, FormBuilder no longer encourages tricks like embedding CSS in static text fields. Instead, it creates a stylesheet called \"FormBuilder Default\" that you are encouraged to attach to the page template that you use for pages that contain your form.
This default CSS was graciously provided by Paul Noone.
This is no longer a particularly early version, but 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 early 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.
This module does not include commercial support. However, there are a number of resources available to help you with it:
Keep in mind that the author has put hundreds and hundreds of hours into the development of this module. Please take the time to read the documentation before sending questions. Either that, or send your questions written on financially negotiable instruments (i.e., checks or cash). Am I sounding like a broken record? Do you kids these days even know what a broken record is? I would say skipping CD, but you might not know what that is either. Like a sample that got stuck on loop? Damn, I am getting old. So is this paragraph. Time to move on, here.
As per the GPL, this software is provided as-is. Please read the text of the license for the full disclaimer.
Copyright © 2008, Samuel Goldstein <sjg@cmsmodules.com>. All Rights Are Reserved.
This module has been released under the GNU Public License. You must agree to this license before using the module.