FUEL CMS User Guide : Version 1.3.2


Forms Module Documentation

This Forms module documentation is for version 0.9.

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

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:

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_php_functions'] configuration in the fuel/application/config/parser.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', '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_subject'] = 'Website Submission';
$params['email_message'] = '{name} Just signed up!';
$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')


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

Property Default Value Description
forms
array(
/*'test' => array('javascript_validate' => FALSE, 'javascript_submit' => FALSE,
'fields' => array(
'name' => array('required' => TRUE),
'email' => array('required' => TRUE),
),
)*/
)
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')
custom_fields
array()
Custom fields you want to use with forms (http:docs.getfuelcms.com/general/forms#association_parameters)
test_email
array()
The default testing email address for when then application is not in production
email_from
'Website Form Submission <website@'.$_SERVER['SERVER_NAME'].'.com>'
The default from address to use when sending email notifications
email_subject
'Website Form'
The testing email address for when then application is not in production
blacklist
array()
A list of IP addresses to block
js
array()
Javascript files to include with each form

Libraries

Helpers