FormBuilder Installation

Important: This is a Beta version of the new FormBuilder. The code has not been fully tested so you may encounter some problems.

You will also need to install this extension manually via FTP.

FormBuilder requires an updated version of the Fragments Plugin. You will need to upgrade your existing Fragments Plugin with the version included in this package.

  1. Install the 'forms' Manager in /skyblue_root/managers/
  2. Install the 'forms' Fragment in /skyblue_root/data/skins/your_skin/fragments/
  3. Install the 'plugin.formbuilder.php' in /skyblue_root/data/skins/plugins/
  4. Install the 'plugin.fragments.php' in /skyblue_root/data/skins/plugins/

About FormBuilder

Forms Editor

Title

The 'title' the name of the form.

Show Title?

If set to 'Yes', the name entered in the Title field will display above the form on your web page.

Blurb

You can enter a paragraph of text here to display above your form.

Plugin Callback Event

The new FormBuilder uses a standard SkyBlueCanvas plugin to process the submitted form. The value that is automatically generated here is the 'event' on which the plugin is fired. For more details see FormBuilder Plugin in this document.

Note: If you are using the Mailer plugin (included with FormBuilder), your form must contain a field named 'email'.

Recepients

If your plugin uses the Mailer plugin (included with FormBuilder), you specify the recepient(s) in this field. To specify multiple recepients, enter the email addresses separated by a comma.

Auto Response

If you are using the Mailer plugin (included with FormBuilder), and you want an auto-response to be sent to anyone who submits your form, enter the message here.

If you want to personalize the response, you can bind fields from your form to the response by using a token formatted as { field_name }. FormBuilder will automatically replace the tokens with the values entered by the user. For instance, if your form is a contact form that includes a field named 'name', you can insert the responder's name with the token {name}.

You can also use SiteVars and MyVars in your Auto Response (plugins required). Simply add the SiteVars or MyVars tokens to the response text and FormBuilder will replace them before sending the response. FormBuilder can detect whether SiteVars or MyVars are or are not installed so if they are not present, no error will occur.

CSS ID

CSS ID is a unique CSS ID selector created for your form. Each form has a unique CSS ID.

Fragment Tokens

Fragment Body Token

FormBuilder will create the Fragment token needed to add a form to your web page. Simply copy this token and paste it into your page text or template.

Fragment Head Tokean

FormBuilder may need to load some dynamically generated JavaScript for each form. This Fragment View will autmatically load the script links in the HEAD element of your web page so you don't have in-line JavaScript code. Simply copy this token and paste it between the <head> and </head> tags in your template.

Fields Editor

Form

This field simply displays the name & ID of the form to which this field belongs.

Name

This is the 'name' attribute of the field. When your form is posted, name will be the key in the _POST array.

Label

This is the label corresponding to this field.

Field Type

This indicates the type of field to create.

Supported Field Types
Text field

This is a standard text input. This field has no configurtion options.

Textarea

This is a standard textarea element. When selected, this field type allows you to specify the number of rows and columns to set for the field.

Password

This type creates a password field that masks the keys entered.

When this type is selected, you can specify 4 options to set guidelines for passwords. These include minimum characters, whether or not to require a digit, whether or not to require an Upper Case letter, and special characters that you define (e.g., punctuation characters).

If any of the above options are specified for the password field, FormBuidler will auto-generate a Regular Expression to perform the field validation.

Checkbox
Radio

Checkbox and Radio Button create checkboxes and radio buttons (respectively) for the options that you enter. Options are entered in the format:

	option1_value : Option 1 Text ; 
	option2_value : Option 2 Text ;
	option3_value : Option 3 Text ;
	
Select List

The Select List type creates an HTML select list. The options for Select List are specified in the same format as Checkbox and Radio button. Select list, however, allows you to specify additional paramters for your select list. They are 'size' and 'Allow Multiple Selections'.

File Upload

This field type will create a 'file' input to allow users to upload a file to your site. For security, this field type allows you to specify a list of accepted MIME types. This feature is not implemented in the FormBuilder test version

Button

You can add custom buttons to your form with this type.

Custom JavaScript Handlers (Requires jQuery)

Also with the Button type, you can enter a custom JavaScript callback (function) that will be triggered when the button is clicked by a site user. FormBuilder will handle the creation of the jQuery code needed to attach your callback to the button's 'onclick' event. FormBuilder will also create a custom JavaScript file for your form and place it in the 'js' directory of your active skin. This file is dynamically generated and contains special markup to allow FormBuilder to parse and edit the file. You should not manually edit this file.

Validations

FormBuilder allows you to specify server-side field validations. The supported validations are:

The new FormBuilder also allows you to specify a custom field validation message for each field.

CSS Class

This is a CSS class selector you specify for your field.

Field Order

This field allows you to set/change the order in which the fields appear.

FormBuilder Fragment

FormBuilder uses a Fragment to display and validate forms created with the FormBuilder Manager. The Fragment View(s) are templates for customizing the display of your form. FormBuilder Fragment is more advanced than most SkyBlueCanvas Fragments and may require a higher skill level in PHP in order to modify the fragment code.

FormBuilder Plugin

When a site visitor completes and submits a form, the form is processed using a SkyBlueCanvas plugin (plugin.formbuilder.php).

When a new form is created in the FormBuilder Manager, a unique callback event is automatically created for the form. The callback event will be in the format:

callback_form_id_{id}

where {id} is the unique ID of the form object.

Note: When you create your first form, you will need to modify FormBuilder Plugin by copying the unique Callback Event ID created for the form. You will find this Event ID in the FormBuilder Form Editor. Copy the Event ID and open /skyblue_root/data/plugins/plugin.formbuilder.php, and replace the Event ID you see at the top of the file.

The FormBuilder plugin includes a simple Mailer to email form responses to the 'recepients' value entered for the Form in the FormBuilder Manager. If no recepients email address is entered, the form response will be sent to the Default Contact for the web site as set in Admin > Settings > Default Info.

You can add custom form handlers by creating a new callback in the FormBuilder plugin or by creating your own plugin. To register your callback to be triggered when the form is successfully validated, use the following format:

$Core->register('callback_form_id_{id}', 'MyCustomFormHandler');

function MyCustomFormHandler($data) {
	global $Filter;
	
	$Request = $Filter->get($data, 'request');
	$Form    = $Filter->get($data, 'form');
	$Fields  = $Filter->get($data, 'fields');
	
	// Your form processing code goes here.
	
}

When a site visitor submits the form, FormBuilder will automatically validate the form based on the validation rules you set in FormBuilder Manager. The callback handler (plugin) will only be called if the form validates successfully. Otherwise, the appropriate error messages will be displayed along with the values previously entered by the site visitor.