Evénement déclenché lorsqu'un formulaire FormBuilder est envoyé.

Paramètres

• form_name - The form name (string)
• form_id - The internal form id (int)
• value_ - Supply a default value to a field with the specified name.

Evénement déclenché s'il y a une erreur lorsqu'un formulaire FormBuilder est envoyé

Paramètres

• form_name - The form name (string)
• form_id - The internal form id (int)
• error - A list of all known errors (string)

Evénement déclenché lorsqu'un formulaire FormBuilder est affiché

Paramètres

• form_name - The form name (string)
• form_id - The internal form id (int)

Variables du Gabarit de Formulaire

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} )

Voici les différentes valeurs applicables aux champs :

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.

Voici les variables smarty complémentaires que vous pouvez utiliser :

Dunno why you'd want some of those, but there you go...

Make sure to set the "Modify Forms" permissions on users who will be administering feedback forms. Also, if you'll be emailing form results, be sure to update the Configuration appropriately.

Please be aware that a feedback form should not be active (e.g., usable by the public) while you are still editing the form. You should create the form, and place the tag into an active content page only when you have finished editing. Otherwise, erroneous results could be returned.

Additionally, this version does not support parallel editing of forms. Please take care that only one admin is editing a given form at a given time.

Que fait ce module ?

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.

Comment l'utiliser ?

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.

Comment créer un formulaire ?

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.

Ajouter un formulaire à une 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, 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.

Travailler avec les formulaires

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.

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.

Soumission des formulaires

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).

Option d'affichage du formulaire

This tab allows for other form customizations, like the symbol to show for required fields.

Captcha Settings

If you have installed the Captcha module, this tab lets you configure the Captcha settings for your form.

Gabarit de formulaire

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.

Soumission du gabarit

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.

Ajouter des champs dans votre formulaire

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.
  • Canadian Province. This is a pulldown listing the Canadian Provinces (Contributed by Noel McGran. Thanks!)
  • 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.
  • Time Picker. This is a set of pulldowns allowing the user to select a time (using 12 or 24 hour clock).
  • File Upload. This is a file upload field.
  • Link (User Entered). This creates a double input field for getting a link URL and link title.
  • Text Field (Multiple). This field creates one or more text inputs with add and delete buttons, effectively giving the end user a way of creating variable-length lists.
• 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.
  • Email Subject Field. This allows users to provide a subject for their email. The email generated when the form gets handled will use this in the "Subject" field. This may cause trouble with certain dispositions that want to control the Email Subject, so use it with caution.
• 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.
  • -Fieldset Start. Combined with Fieldset End, this allows you to group various fields within your form. Use this to start a given grouping.
  • -Fieldset End. Combined with Fieldset Start, this allows you to group various fields within your form. Use this to end a given grouping.
  • -Hidden Field. This allows you to embed a hidden field in your form.
  • -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.
  • -Static Link. This allows you to put a link to a given page into your form. Optionally, you can have it autopopulate with the page where the form is embedded (useful if you're sending results via email).
  • -Computed Field. This allows you to embed a computed field in your form. It is not visible to the user until after the form is submitted. It allows you to do simple arithmetic or string concatenation.
  • -Unique Integer (Serial). This is an integer that increases every time someone hits your form. Your results may not be sequential, but they will increase monotonically.
• Form Handling Inputs (Dispositions)
  • *Call a User Defined Tag With the Form Results. This submits all the form results to the User-Defined Tag you specify. The UDT can handle the results however it wants. Values are passed as $param['field_name'].
  • *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.
  • *Email to User-Supplied Address. This puts an input field in the form for the user to populate with an email address. The form results get sent to that address. Beware of Spam abuse! Active the primitive anti-spam features in the FormBuilder configuration screen.
  • *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.
  • *Redirect to Page Based on Pulldown. This allows you to redirect the form to a different site page depending on its value. If you have multiple dispositions, make sure this is used last.
  • *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.
  • *Save Results to File Based on Pulldown. Like the Flat File disposition, except the value of a pull-down determines which file results get written to.
  • *Save Results to File(s) Based on Multiple Selections. Like the Flat File disposition, except the value(s) of checkboxes determines which file(s) results get written to.
  • *Email to CMS Admin User. Provides a pull-down of CMS Admin users, and directs the results as an email to the selected admin.
  • *Store Results for FormBrowser Module v.3. Stores the form results in an XML structure as a single database record. This will become the interface to Form Browser in the next release.

Passing Default Values to Forms

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:

{cms_module module='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 unweildy or contain characters that don't work well with Smarty. So there is an alternative like this:

{cms_module module='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"

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.

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.

Configuration

There are some global configuration options for FormBuilder:

• Enable fast field add pulldown. This enables the pulldown on the Form Edit page which saves a step in the creation of new fields.
• Hide Errors. This is set by default. Unchecking it will cause more detailed errors to be displayed if there are problems when you submit your form.
• Require Field Names. Typically, you will want form fields to be named so you can tell which is which. However, in some cases, you might want to have nameless fields. Uncheck this if you want to allow nameless fields.
• Unique Field Names. Typically, you will want form fields to have unique names so you can tell which is which. Uncheck this if you want to allow fields to share names.
• Use relaxed email validation. This uses a less restrictive regular expression for validating email; e.g., x@y will be allowed, where typically x@y.tld is required.
• Show Form Builder Version. Displays the version of FormBuilder you're using in a comment when the form is generated. Typically only useful when debugging.
• Enable primitive anti-spam features. When turned on, this allows any given IP address to only generate 10 emails per hour.
• Show Field IDs. When turned on, FormBuilder will display field ids when adding or editing a form.

Styling and CSS

Paul Noone graciously provides us all with a pretty good standard CSS that you can use for forms:

	/* Sample FormBuilder CSS base */
	form {margin-top:0}
	form, td, th, li { font-size: 100%}
	form div {margin-bottom:0}
	fieldset div {
		margin-bottom:0.5em;
		margin-left:1em;
	}
	fieldset div div {
		margin-top:0.5em;
		margin-left:1em
	}
	fieldset {
		margin-bottom:1em;
		border:1px solid #F60;
		padding:0.5em
	}
	fieldset label {
		width:auto;
	}
	legend {
		color:#FFF;
		background:#F60;
		font-style:italic;
		font-size:1.2em;
		margin-bottom:0.5em;
		padding:0.2em;
		width:auto;
		border:1px solid #CCC
	}
	textarea {
		margin: 0.5em 0;
		width:98%;
		height: 6em
	}

	/* Apply this class to text/select input fields with shorter labels
		to help alignment */
	.short-label label {float:left; width:10em}
	.short-label fieldset div input,
	.short-label fieldset div select {width:16em}

	/* Pretty up your Captcha image output */
	.captcha {
		margin:0.5em 0;
		width:200px;
		text-align:center
	}
	.captcha img {border:1px solid #F60; margin-bottom:0.5em}
	.captcha input {width:196px; margin-top:0.5em}

	/* Just a bit more room for the Submit button */
	.submit {margin-top:0.5em}

Form Template Variables

Form Template Variables

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 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...

Known Issues

• FormBuilder is not yet integrated with FrontEnd Users. It will be.
• FormBuilder does not yet support pretty urls, although that shouldn't matter since the user side is pretty simple.
• FileUpload Fields may not work correctly with multipage forms.

Troubleshooting

1. First step is to check you're running CMS 1.1 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. Uncheck the "Hide Errors" checkbox in the global options, and see what message gets displayed when you submit your form.
5. Just mess around and try clicking on links and icons and stuff. See what happens.
6. Last resport is to email me or catch me on IRC and we can go from there.

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.

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 .
• 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.

Keep in mind that the author has put hundreds of hours into the development of this module. Please take the time to read the documentation before sending questions. Either that, or write your questions on financially negotiable instruments (i.e., cash).

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 © 2008, 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.

• Version 0.5.3. 26 May 08. Bugfixes to previous set of bugfixes. Now ready for major upgrades for 0.6.
• Version 0.5.2. 25 May 08. Bugfixes. Release in preparation for substantial reworking for 0.6
• Version 0.5.1. 30 April 08. Bugfixes, rewrote some of the File Upload code to prevent white screen of annoyance.
• Version 0.5. 19 April 08. Bugfixes, support for FormBrowser fixes and features, disposition type for upcoming FormBrowser version.
• Version 0.4.4. 26 Sept 07. Bugfixes for radio button groups, fix for validation of DispositionDeliverToEmailAddressField.
• Version 0.4.3. 18 Sept 07. Bugfixes for pulldowns using numbers, option to inline form, fixes for table-layouts provided by Ap Muthu, fix for requirability of Dispositions.
• Version 0.4.2. 14 Sept 07. Bugfixes for XML export, RadioButton Group submission, and HTML labels.
• Version 0.4.1. Bugfixes for File Disposition Types.
• Version 0.4
  • Upped minimum CMS version to 1.1
  • Numerous Bug fixes; too many to enumerate here
  • Massive rejiggering of code to work with CMS MS 1.1 parameter sanitizing regime
  • Added field types: "TextField (Multiple)" and "Computed Field"
  • Added dispositions: "Save Results to File Based on Pulldown" and "Save Results to File(s) Based on Multiple Selections"(Calguy)
  • Added neat-o AJAX-y template-copying for Form Templates, gave versions of old table-based templates to soothe the raging masses.
  • Added ability to pass default values to form elements from module tag using value_FIELDNAME="value" syntax (Calguy)
  • Added option to display field ids in admin (Calguy)
• Version 0.3
  • Added Captcha module support.
  • Reworked labeling of form elements to be XHTML compliant
  • Added Paul Noone's new, improved contact form templates
  • Implementation of Email Subject Field
  • Added admin-specifiable values to hidden field type, which may contain parsable smarty tags
  • Text Area Field now allows specification of rows and cols in the admin, instead of CSS
  • Added Drag'n'Drop reordering of form fields.
  • Added non-blank field name and unique field name global configuration options and validation
  • Implemented templated display of form results upon submission in addition to page redirecting
• Version 0.2.4 - 09 May 2007

  Big release:

  • Added "Email Form to User-Supplied Address" disposition.
  • Added "TimePicker" field type. Split "Link" field into a "User-supplied Link" field and a "Static Link" field.
  • Added HTML email option and auto-templates for all email dispositions.
  • Added primitive anti-spam features.
  • Added XML-based import and export of forms.

• Version 0.2.3

  Add the ability to call a selectable user defined tag upon disposition of the form.

• Version 0.2.2

  Many thanks to Utter Design for sponsoring some changes and bugfixes, which include:

  • Added file upload capabilities to the email disposition
  • Add PageSetStart and PageSetEnd field types

    These field types allow you to create fieldsets in your form, and organise your fields logically for the user. You can even nest fieldsets, and associate a style with them appropriately. The default template was changed to prevent it from wrapping a div around these types of fields.

  • Fixed a problem with DATETIME fields on install

    This solves a problem when on install the response table would sometimes not get created when using adodb lite

• Version 0.2 - 14 November 2006. Calguy & tsw's bug fixes for field re-ordering and custom templates. Additional bug fixes for field labels.
• Version 0.1 - 8 July 2006. Initial Release