FUEL CMS User Guide : Version 1.5.2

Forms Module Documentation

This Forms module documentation is for version 1.1.3.

The Forms module provides a flexible way to create simple to complex forms. This is what you can do with it:

• Create forms in the CMS, as static views or a combination of the two
• Use one of the additional custom field types to combat SPAM including a honeypot, a simple equation, reCAPTCHA, stopforumspam or Akismet
• Email specified recipients upon form submission
• Save entries into the database which can be exported as a CSV file
• Validate required and common field types like email as well as setup your own custom validation
• Submit and validate forms via javascript as well as server side
• Specify a return URL
• Automatically will attach uploaded files to the recipient email
• Hook into various parts of the processing of the email that gets sent

Hooks

There are a number of hooks you can use to add additional processing functionality during the form submission process. You can pass it a callable function or an array with the first index being the object and the second being the method to execute on the object. Additionally, you can specify an array of CodeIgniter hook parameters. The hooks must be specified in the config file to be run upon processing and not on the object during rendering unless the form is submitting to the same page in which it is rendered. A hook gets passed 2 parameters—the first is the form object instance, the second is the $_POST parameters as a convenience. The following hooks are:

• pre_render: executes before displaying the rendered form
• pre_process: executes before anything processes and the response email is compiled which means you can alter $_POST values if necessary
• pre_validate: excutes right before the validation of the form fields
• post_validate: executes after the validation of the form fields
• pre_save: executes right before saving (if saving is enabled for the form)
• post_save: executes right after saving (if saving is enabled for the form)
• post_process: executes after everything is processed and before the notifications are sent (if there are any)
• pre_notify: executes right before notifying a recipient
• notify: will replace the default email notification with your own custom callback
• success: executes upon successful submission
• error: executes on error

If the CodeIgniter hook parameters syntax is used, the actual hook name being used is 'form_{slug}_{hook}' (e.g. form_contact_pre_validate).

Below is an example of adding a hook in the configuration file of a form:

// you can add form configurations here which can then be referenced simply by one of the following methods form('test'), $this->fuel->forms->get('test')
$config['forms']['forms'] = array(
	'contact' => array(
				'anti_spam_method' => array('method' => 'honeypot'),
				'after_submit_text' => 'Your inquiry has been successfully sent.',
				'email_recipients' => array('superman@krypton.com'),
				'javascript_submit' => TRUE,
				'javascript_validate' => TRUE,
				'form_action' => 'forms/application',
				'submit_button_text' => 'Submit',
				'reset_button_text' => 'Reset',
				'form_display' => 'block',
				'block_view' => 'application_form',
				'fields' => array(
					'fullname' => array('required' => TRUE, 'label' => 'Full Name'),
					'phone' => array('type' => 'phone', 'required' => TRUE, 'label' => 'Phone'),
					'email' => array('type' => 'email', 'required' => TRUE),
					'comments' => array('type' => 'textarea', 'rows' => 5, 'label' => 'Comments & Questions'),
					),
				'hooks' => array(
					'post_validate' => 'my_post_validate_func'
					)
	)
);

Examples

There are several ways you can create forms. One is by using the CMS. The other is by specifying the parameters for the form in the forms configuration file under the "forms" configuration are.

Below are some examples of how to use the module:

Using the 'form' helper function

// load the helper ... $CI is CI object obtained from the get_instance(); and automatically passed to blocks
$CI->load->module_helper(FORMS_FOLDER, 'forms');

echo form('myform', array('fields' => array('name' => array('required' => TRUE)));

To add the form to a page in the CMS, you will need to add the "form" function to the $config['parser_allowed_functions'] configuration in the fuel/application/config/MY_fuel.php file. Then you can use the templating syntax like so:

{form('myform')}

Using the 'forms' fuel object

$form = $this->fuel->forms->create('myform', array('fields' => array('name' => array('required' => TRUE))));
echo $form->render();

Adding additional validation

$validation = array('name', 'is_equal_to', 'Please make sure the passwords match', array('{password}', '{password2}'));

$fields['name'] = array();
$fields['password'] = array('type' => 'password');
$fields['password2'] = array('type' => 'password', 'label' => 'Password verfied');

$form = $this->fuel->forms->create('myform', array('fields' => $fields, 'validation' => $validation));
echo $form->render();

Customizing the HTML

There are several ways to generate the HTML for the form. The first option is to use "auto" which will use the Form_builder class to generate the form based on the fields you've specified. Fields can be specified in the CMS or passed in under the 'fields' parameter as demonstrated in the above example. The second option is to use a block view and the third is to simply use an HTML string. In both cases, you will automatically have several variables passed to it included a $fields array which contains an array of all the the rendered fields, their labels, and their "key" values. It also will pass variables of email_field and email_label where "email" is the name of the field. You can then use the following in your block view or HTML:

Block View

<?php foreach($fields as $field) : ?>

	<?=$field['label']?>
	
<?=$field['field']?>

<?php endforeach; ?>



	<?=$name_label?>
	
<?=$name_field?>


	<?=$email_label?>
	
<?=$email_field?>

Template Syntax

	{name_label}

	
{name_field}



	{email_label}

	
{email_field}

Special Hidden Fields

If you are using your own HTML code, you may need to include 2 additional hidden fields with values—return_url and form_url. There is also an "__antispam__" field that automatically gets generated and can be outputted automatically. Below is an example of what you can include in your own blocks.

...


<?=$__antispam___field?>

Kitchen Sink

$fields['name'] = array();
$fields['password'] = array('type' => 'password');
$fields['password2'] = array('type' => 'password', 'label' => 'Password verfied');

$params['name'] = 'My Form';
$params['slug'] = 'my_form';
$params['fields'] = $fields;
$params['validation'] = array('name', 'is_equal_to', 'Please make sure the passwords match', array('{password}', '{password2}')); // validation rules
$params['slug'] = 'myform'; // used for form action if none is provided to submit to forms/{slug}
$params['save_entries'] = FALSE; // saves to the form_entries table
$params['form_action'] = 'http://mysite.com/signup'; // if left blank it will be submitted automatically to forms/{slug} to be processed
$params['anti_spam_method'] = array('method' => 'recaptcha', 'recaptcha_public_key' => 'xxx', 'recaptcha_private_key' => 'xxxxx', 'recaptcha_theme' => 'white');
$params['submit_button_text'] = 'Submit Form';
$params['submit_button_value'] = 'Submit'; // used to determine that the form was actually submitted
$params['reset_button_text'] = 'Reset Form';
$params['form_display'] = 'auto'; // can be 'auto', 'block', 'html'
$params['block_view'] = 'form'; // fuel/application/views/_blocks/form.php
$params['block_view_module'] = 'application'; // the name of the module the block exists (default is the main application folder)
$params['javascript_submit'] = FALSE;
$params['javascript_validate'] = TRUE;
$params['javascript_waiting_message'] = 'Submitting Information...';
$params['email_recipients'] = 'superman@krypton.com';
$params['email_cc'] = 'batman@gotham.com';
$params['email_bcc'] = 'wonderwoman@paradiseisland.com';
$params['email_reply_to'] = 'noreply@paradiseisland.com';
$params['email_subject'] = 'Website Submission';
$params['email_message'] = '{name} Just signed up!';
$params['mail_type'] = 'text';
$params['after_submit_text'] = 'You have successfully signed up.';
$params['attach_files'] = TRUE; // Will automatically attach files to the email sent out
$params['attach_file_params'] = array('upload_path' => APPPATH.'cache/', 'allowed_types' => 'pdf|doc|docx',	'max_size' => '1000'); 
$params['cleanup_attached'] = TRUE;
$params['return_url'] = 'http://mysite.com/signup'; // only works if javascript_submit = FALSE
$params['js'] = 'myvalidation.js'; // extra javascript validation can be included
$params['form_builder'] = array(); // Initialization parameters for the Form_builder class used if a form is being auto-generated
$params['hooks'] = array(); // An array of different callable functions associated with one of the predefined hooks "pre_validate", "post_validate", "pre_save", "post_save", "pre_notify", "success", "error" (e.g. 'pre_validate' => 'My_func')
$params['vars'] = array(); // An array of additional variables to send to the rendered output

$form = $this->fuel->forms->create('myform', $params);
echo $form->render();

Use Without Database Tables

If you don't want to create your forms in the CMS and/or want to capture the entries in the CMS database, you can use configure the module to work without using the tables that are automaticaly installed by the installer. To do this, add the following to your fuel/application/MY_fuel_modules.php file:

$config['module_overwrites']['forms']['disabled'] = TRUE;
$config['module_overwrites']['form_entries']['disabled'] = TRUE;

Forms Configuration

The following configuration parameters can be found in the modules/forms/config/forms.php configuration file. It is recommended that you copy the config file and place it in your fuel/application/config directory which will override the defaults and make it easier for future updates.

array(
/*'test' => array('javascript_validate' => FALSE, 'javascript_submit' => FALSE,
'fields' => array(
'name' => array('required' => TRUE),
'email' => array('required' => TRUE),
),
)*/
)

array()

array()

'Website Form Submission <website@'.$_SERVER['SERVER_NAME'].'>'

'Website Form'

array()

array()

''

array(
'ip_threshold_flag'      => 5,
'email_threshold_flag'   => 20,
'name_threshold_flag'    => 50,
'ip_threshold_ignore'    => 20,
'email_threshold_ignore' => 50,
'name_threshold_ignore'  => 60,
)

array(
'email_post_field'       => 'email',
'name_post_field'        => 'name',
'comment_post_field'     => 'comment',
)

TRUE

FALSE

TRUE

array(
'upload_path'            => APPPATH.'cache/',
'allowed_types'          => 'pdf|doc|docx',
'max_size'               => '1000',
)

TRUE

Libraries

• Fuel Forms Class
• Forms Custom Fields Class

Helpers

• Forms Helper