FUEL CMS User Guide : Version 1.5.2


Fuel Forms Class

This class extends the Fuel_advanced_module class.

Properties Reference

Property Default Value Description
public
name forms The folder name of the module

Function Reference [+]

$this->fuel->forms->initialize([$params=array()])

Initialize the backup object. Accepts an associative array as input, containing preferences. Also will set the values in the config as properties of this object.

Returns

void

Parameters

(array) $params config preferences

$this->fuel->forms->create('$name', [$params=array()])

Creates and returns a single Fuel_form object.

Returns

object

Parameters

(string) $name Name of the form
(array) $params Initialization parameters

Example

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

$this->fuel->forms->get('$name', ['$check_db'=TRUE])

Returns a single Fuel_form object.

Returns

object

Parameters

(string) $name Name of the form to retrieve. Will first look in the database and then in the config file
(boolean) $check_db Determines whether to check the database or not

Example

$form = $this->fuel->forms->get('myform');

$this->fuel->forms->field_layout('$layout')

Returns a Fuel_block_layout object used in the CMS for creating fields in association with different field types (e.g. text, email, select... etc).

Returns

object

Parameters

(string) $layout Name of the block layout to retrieve

Example

$block_layout = $this->fuel->forms->field_layout('email');

$this->fuel->forms->all_entries_by_date('$start_date', '$end_date')

Returns all the entries for a given form.

Returns

array

Parameters

(string) $start_date start date
(string) $end_date end date

$this->fuel->forms->options_list(['$type'=NULL])

Returns a key value list of all the forms (used for dropdwons).

Returns

array

Parameters

(string) $type The type of form either "db" (found in the database) or "config" (found in the config)

$this->fuel->forms->__call('$method', $args)

Magic method which allows you to make calls like $this->fuel->forms->render('test');.

Returns

mixed

Parameters

(string) $method Method name
(array) $args An array of arguments to pass to the method


Fuel Form Class

This class extends the Fuel_base_library class.

Properties Reference

Property Default Value Description
protected
name N/A Name of the form (must be unique and is required)
slug N/A A slug value which can be passed to forms/{slug} for processing the form
save_entries N/A Determines whether to save the entries into the database
form_action N/A The URL in which to submit the form. If none is provided, one will be automatically created
anti_spam_method N/A The method to use to combat SPAM. Options are 'honeypot', 'equation', 'recaptcha', 'stopforumspam' or 'akismet'.
submit_button_text N/A The text to display for the submit button
submit_button_value N/A The value used to check that the form was actually submitted. Can't rely on just $_POST not being empty
reset_button_text N/A The text to display for the reset button
form_display N/A The method in which to options are 'auto', 'block', 'html'
block_view N/A The name of the block view file (only necessary if form_display is set to "block")
block_view_module N/A The name of the module the block view belongs to (only necessary if form_display is set to "block")
form_html N/A The HTML to display (only necessary if form_display is set to "html")
javascript_submit N/A Determines whether to submit the form via AJAX
javascript_validate N/A Determines whether to use javascript to do front end validation before sending to the backend
javascript_waiting_message N/A The message to display during the AJAX process
email_recipients N/A The recipients to recieve the email after form submission
email_cc N/A The CC recipients to recieve the email after form submission
email_bcc N/A The BCC recipients to recieve the email after form submission
email_subject N/A The subject line of the email being sent
email_from N/A The email from address <name>
email_message N/A The email message to send
mail_type N/A Sets the mail type to be either "text" or "html"
after_submit_text N/A The text/HTML to display after the submission process
attach_files N/A Will automatically attach files to the email sent out
attach_file_params N/A An array of parameters used for the CI File Upload class when uploading and attaching files to an email.
cleanup_attached N/A Will remove attached files from the file system after being attached
upload_data N/A An array of uploaded file information
attachments N/A An array of files to attach to the recipient email
return_url N/A The return URL to use after the submission process. It will default to returning back to the page that submitted the form
validation N/A An array of extra validation rules to run during the submission process beyond 'required' and the rules setup by default for a field type (e.g. valid_email, valid_phone)
js N/A Additional javascript files to include for the rendering of the form
fields N/A The fields for the form. This is not required if you are using your own HTML in a block or HTML form_display view
form_builder N/A Initialization parameters for the Form_builder class used if a form is being auto-generated
hooks N/A 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')
vars N/A An array of additional variables to send to the rendered output

Function Reference [+]

$this->fuel->form->initialize([$params=array()])

Initialize the object. Accepts an associative array as input, containing preferences. Also will set the values in the config as properties of this object.

Returns

void

Parameters

(array) $params config preferences

$this->fuel->form->render([$params=array()])

Renders the form for the front end.

Returns

string  Returns the rendered form

Parameters

(array) $params An array to modify object properties. If none are provided, it will use the current properties on the object (optional)

Example


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

	 // OR, pass parameters directly to the "render" method
	 $form = $this->fuel->forms->create('myform');
	 echo $form->render(array('fields' => array('name' => array('required' => TRUE))));

$this->fuel->form->get_vars()

Returns an array of additional variables to be sent to the view.

Returns

array

$this->fuel->form->set_vars('$vars')

Sets additional variables to be sent to the view.

Returns

$this

$this->fuel->form->add_field($name, [$params=array([type]=>text)])

Adds a field to the form. This can also be done by passing the "fields" parameter when creating a form.

Returns

object  Returns itself for method chaining

Parameters

(array) $name The name of the field to add
(array) $params Form field parameters

Example

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

$this->fuel->form->remove_field('$key')

Removes a field from the form.

Returns

object  Returns itself for method chaining

Parameters

(mixed) $key The name or array of field names of the field to remove

$this->fuel->form->add_validation('$name', ['$func'=NULL], ['$msg'=NULL], [$params=array()])

Adds validation to a form. Note that you can pass {...} placeholders that represent $_POST values.

Returns

object  Returns itself for method chaining

Parameters

(mixed) $name Can be a string, an array like array('start_date', 'check_date', 'Please enter in a valid date.'), or an array of arrays
(mixed) $func The function to validate with which must return either TRUE or FALSE. You can use the array($object, 'method') syntax for methods on object instances
(string) $msg The error message to display when the function returns FALSE
(mixed) $params Can be a string or an array. You can use place holder to represent post data (e.g. {email});

Example


	 $validation = array('name', 'is_equal_to', 'Please make sure the passwords match', array('{password}', '{password2'));
	 $form = $this->fuel->forms->create('myform', array('fields' => array('name' => array('required' => TRUE))));
	 $form->add_validation($validation);
	 if ($form->validate())
	 {
		echo 'Is Valid!!!';
	 }
	 else
	 {
		echo 'Not Valid :-(';
	 }

$this->fuel->form->remove_validation('$key', ['$func'=NULL])

Removes a validation rule from a form.

Returns

object  Returns itself for method chaining

Parameters

(string) $key Field to remove
(string) $func Key for rule (can have more then one rule for a field) (optional)

Example


	 $_POST['password'] = 'xx';
	 $_POST['password2'] = 'xxx';

	 $validation = array('name', 'is_equal_to', 'Please make sure the passwords match', array('{password}', '{password2'));
 	 $fields['password'] = array('type' => 'password', 'validation' => array($validation));
	 $fields['password2'] = array('type' => 'password', 'label' => 'Password verfied');

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

	 $form->add_validation($validation);
	 $validated = $form->validate(); // FALSE
	 $form->remove_validation('name');
	 $validated = $form->validate(); // TRUE

$this->fuel->form->process()

Processes the field which includes validation, submission to database (if submit_entries = TRUE) and emailing to recipients (if email_recipients isn't blank).

Returns

boolean  Returns whether the processing was successfull without any errors

Example


	$form = $this->fuel->forms->get('myform');
	if ($form->process())
	{
		echo 'Success';
	}
	else
	{
		echo 'Failure';
	}

$this->fuel->form->is_spam($posted)

Checks if a form posting has SPAM characteristics.

Returns

boolean Returns TRUE/FALSE based on if either stopforumspam or AKISMET returns it as SPAM

Parameters

(array) $posted Posted form values

$this->fuel->form->validate()

Validates the form before submission.

Returns

boolean  Returns TRUE/FALSE based on if the form validates or not. Is called during the "process" method as well

Example


	$form = $this->fuel->forms->get('myform');
	if ($form->validate())
	{
		echo 'Is valid';
	}
	else
	{
		echo 'Invalid!!!';
	}
	// ... further processing

$this->fuel->form->upload_files([$files=array()], [$params=array()])

Sets a callback hook to be run via "pre" or "post" rendering of the page.

Returns

void

Parameters

(mixed) $files A string or an array of server file paths to attach. If no values are passed, then it will automatically look in the $_FILES array
(array) $params An array of configuration parameters to pass to the CI File Upload class.

$this->fuel->form->set_hook('$type', $hook)

Sets a callback hook to be run via "pre" or "post" rendering of the page.

Returns

void

Parameters

(key) $type The type of hook (e.g. "pre_render" or "pre_process")
(array) $hook An array of hook information including the class/callback function. More here

$this->fuel->form->call_hook('$hook', [$params=array()])

Calls a specified hook to be run.

Returns

void

Parameters

(hook) $hook The type of hook (e.g. "pre_validate" or "pre_save")
(array) $params An array of additional parameters to pass to the hook method/function

$this->fuel->form->notify(['$msg'=NULL])

Sends email notification to those specified in the email_recipients field. Is called within the process method as well.

Returns

boolean  Returns TRUE/FALSE based on if the form validates or not. Is called during the "process" method as well

Parameters

(string) $msg The message to send (optional)

Example


	$form = $this->fuel->forms->create('myform', array('email_recipients' => array('superman@krypton.com')));
	if ($form->notify())
	{
		echo 'Notified';
	}
	else
	{
		echo 'Failure in Notification';
	}

$this->fuel->form->js_output()

Returns the javascript files used for rendering the form. The render method will automatically call this method, however,. it's at your disposal if you wish to render it in your own block outside of that process.

Returns

string  Returns the javascript script files registered with the form including any the jquery.validate plugin if javascript_validate is set to TRUE

Example


	$form = $this->fuel->forms->create('myform', array('js' => array('myvalidation.js')));
	echo $form->js_output();

$this->fuel->form->rendered_vars('$form_fields', '$form_builder')

Returns the rendered form fields as variables which can be consumed by views/blocks and includes an array of rendered field output, labels, and the form object itself.

Returns

array  Returns an array of variables that can be used in views/block files

Example


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

$this->fuel->form->form_fields([$values=array()])

Returns an array of form fields that can be used with the Form_builder class.

Returns

array  Returns an array of form fields

Example


	$form = $this->fuel->forms->create('myform', array('fields' => array('name' => array('required' => TRUE), 'email' => array('required' => TRUE))));
	foreach($form->form_fields() as $name => $field)
	{
		echo $this->form_builder->create_field($field);
	}

$this->fuel->form->get_validator()

Returns the validator object used for validating the front end.

Returns

object

$this->fuel->form->add_attachment('$attachment')

Adds an attachment for the recipient email.

Returns

string

$this->fuel->form->__call('$method', $args)

Magic method for capturing method calls on the record object that don't exist. Allows for "get_{field}" to map to just "{field}" as well as "is_{field}"" and "has_{field}".

Returns

mixed

Parameters

(object) $method method name
(array) $args arguments

$this->fuel->form->__set('$var', '$val')

Magic method to set first property, method, then field values.

Returns

void

Parameters

(string) $var field name
(mixed) $val

$this->fuel->form->__get('$var')

Magic method to return first property, method, then field values.

Returns

mixed

Parameters

(string) $var field name


Form Field Class

This class extends the Fuel_base_library class.

Properties Reference

Property Default Value Description
protected
params N/A

Function Reference [+]

$this->form_field->set_params($params)

Set object parameters.

Returns

void

Parameters

(array) $params Config preferences

$this->form_field->values()

Returns the values of the form fields in an array.

Returns

array

$this->form_field->is_required()

Returns TRUE/FALSE depending on if the field is considered required.

Returns

boolean

$this->form_field->render(['$string'=TRUE])

Renders the form field.

Returns

string

$this->form_field->__set('$var', '$val')

Magic method to set first property, method, then field values.

Returns

void

Parameters

(string) $var field name
(mixed) $val

$this->form_field->__get('$var')

Magic method to return first property, method, then field values.

Returns

mixed

Parameters

(string) $var field name

$this->form_field->__isset('$var')

Magic method that returns TRUE/FALSE depending if the parameter is set.

Returns

boolean

Parameters

(string) $var field name