FUEL CMS User Guide : Version 1.5.2


Forms

One of the biggest features of FUEL CMS is it's ability to create simple to complicated form interfaces for your models and layouts. The main engine behind this feature is the Form_builder class.

Examples


// load Form_builder;
$this->load->library('form_builder');

// load the custom form fields
$this->form_builder->load_custom_fields(APPPATH.'config/custom_fields.php');

// create fields
$fields['linked'] = array('type' => 'linked', 'linked_to' => array('name' => 'url_title'));
$fields['datetime'] = array('type' => 'datetime', 'first_day' => 2, 'date_format' => 'dd-mm-yyyy', 'min_date' => '01-01-2012', 'max_date' => '31-12-2012');
$fields['test_image'] = array('upload' => TRUE);
$fields['number'] = array('type' => 'number', 'represents' => 'int|smallint|mediumint|bigint', 'negative' => TRUE, 'decimal' => TRUE);
$fields['currency'] = array('type' => 'currency', 'negative' => TRUE, 'decimal' => '.');
$fields['phone'] = array('type' => 'phone', 'required' => TRUE);
$fields['file_example'] = array('type' => 'file', 'overwrite' => TRUE, 'display_overwrite' => TRUE, 'multiple' => FALSE);
$fields['state'] = array('type' => 'state');
$fields['list_items'] = array('type' => 'list_items');
$fields['sections'] = array(
				'display_label' => FALSE,
				'type' => 'template', 
				'label' => 'Page sections', 
				'fields' => array(
						'layout' => array('type' => 'select', 'options' => array('img_right' => 'Image Right', 'img_left' => 'Image Left', 'img_right_50' => 'Image Right 50%', 'img_left_50' => 'Image Left 50%')),
						'title' => '',
						'action' => '',
						'content' => array('type' => 'textarea'),
						'image' => array('type' => 'asset', 'multiple' => FALSE, 'img_styles' => 'float: left; width: 100px;'),
						'images' => array('type' => 'template', 'repeatable' => TRUE, 'view' => '_admin/fields/images', 'limit' => 3, 'fields' => 
																array('image' => array('type' => 'asset', 'multiple' => TRUE))
																),
					),
				'view' => '_admin/fields/section', 
				'add_extra' => FALSE,
				'repeatable' => TRUE,
				);
// set the fields
$this->form_builder->set_fields($fields);

// render the page
$vars['form'] = $this->form_builder->render();
$this->load->view('page', $vars);

Many of the custom field types may throw javascript errors if used outside of the CMS because they rely on javascript configuration values which are set by jQX. These config values would need to be created on the frontend (e.g. jqx.config.fuelPath, jqx.config.imgPath, ...etc), otherwise, you may see errors in the console like "jqx is not defined".

Universal Field Attributes

The following are field parameters that can be used with any field type:

Form Field Types

FUEL CMS 1.0 has added several new field types as well as made it easier to create custom form fields. In previous versions, to create a custom field type, you needed to create a custom function or class method and use the 'custom' field type to render it. In FUEL CMS 1.0, you can register those custom field types which means you don't need to make those associations for every form. It also allows you to associate them with their own javavascript files and functions to execute upon rendering. In addition, you can overwrite or augment existing field types, by adding field type associations in the fuel/application/config/custom_fields.php. For example, we use this method to associate the the datetime field type with the jQuery UI datepicker.

Custom fields require a function or class method to render the field and an association to be made in the fuel/application/config/custom_fields.php file (this file is explained below). Custom field types are not automatically load but can be done so by one of the following ways:

// loads from a config file
$this->form_builder->load_custom_fields(APPPATH.'config/custom_fields.php');

// registers a single custom field
$this->form_builder->register_custom_field($key, $custom_field);

By default, FUEL CMS 1.0 provides several custom field types which are defined in the fuel/modules/fuel/libraries/Fuel_custom_fields.php class.

Built-in Form_builder Field Types

FUEL Custom Field Types

text

This field type is the standard text field and the "type" parameter should be left blank or don't include it all together (it is the default field type if no representatives are used).

Note that the type being specified is empty. This is because using 'text' will create a textarea. The reason for this originally had to do with having a table field type of text would map better to a textarea then to a input text field.

Example

	$fields['text_example'] = array('type' => '');
	

The default field type if no "type" parameter is passed is a text input field.

password

This field type creates a standard password field.

Representations

	'name' => array('pwd', 'passwd') // targets any field with the name of pwd, passwd
	

Example

	$fields['pwd_example'] = array('type' => 'password', 'label' => 'Password');
	// OR with the representative
	$fields['pwd'] = array('label' => 'Password');
	

select

This field type creates a standard select dropdown box. The following additional parameters can be passed to this field type:

Example

	$options = array('a' => 'option A', 'b' => 'option B', 'c' => 'option C');
	$fields['select_example'] = array('type' => 'select', 'options' => $options, 'model' => 'people', 'first_option' => 'Select one...'); // will use the options_list method from the people_model
	$fields['select_example'] = array('type' => 'select', 'options' => $options, 'model' => array('my_module' => array('people' => 'people_options')), 'first_option' => 'Select one...'); // will use the people_options method from modules/my_module/people_model
	

checkbox

This field type creates a standard checkbox field. The following additional parameter can be passed to this field type:

Example

	$fields['checkbox_example'] = array('type' => 'checkbox', 'checked' => TRUE);
	

textarea

This field type creates a textarea field. Passing the 'class' parameter with a value of no_editor will render the field without the text editor (e.g. markitUp! or CKEditor depending on your settings).

Representations

This field is represented by wysiwyg by default.

Example

	$fields['textarea_example1'] = array('type' => 'textarea', 'cols' => 40, 'rows' => 5, 'class' => 'no_editor');
	$fields['textarea_example2'] = array('type' => 'textarea', 'cols' => 40, 'rows' => 5, 'class' => 'markitup');
	$fields['textarea_example3'] = array('type' => 'textarea', 'cols' => 40, 'rows' => 5, 'class' => 'wysiwyg'); //ckeditor
	

hidden

This field type creates a standard hidden field.

submit

This field type creates a standard submit button.

Example

	$fields['submit_example'] = array('type' => 'submit', 'value' => 'Save');
	

button

This field type creates a standard form button. The following additional parameter can be passed to this field type:

Example

	$fields['my_button'] = array('type' => 'button', 'value' => 'My Button');
	

enum

This field type creates a standard checkbox field. The following additional parameters can be passed to this field type:

Example

	$options = array('yes' => 'yes', 'no' => 'no');
 	$fields['enum_example'] = array('type' => 'enum', 'mode' => 'radios', 'options' => $options);
 	$fields['enum_example'] = array('type' => 'enum', 'mode' => 'select', 'options' => $options);
	
Enum example        

multi

This field type creates either a series of checkboxes or a multiple select field. The following additional parameters can be passed to this field type:

Representations

	'type' => array('array') // targets any field with the type of array
	

Example

	$options = array('a' => 'option A', 'b' => 'option B', 'c' => 'option C');
	$fields['multi_example'] = array('type' => 'multi', 'options' => $options, 'value' => 'a');
	
           

file

This field type creates a standard file upload field. The following additional parameters can be passed to this field type:

Image Specific

Representations

	'type' => 'blob' // targets any field with the type of blog
	

Example

	$fields['file_example'] = array('type' => 'file', 'overwrite' => TRUE, 'display_overwrite' => TRUE, 'multiple' => FALSE, 'file_name' => 'my_file_{id}');
	

Note the use of "{id}" in the file_name parameter. This will automatically merge in form field values for the name of the file.

 

date

This field type creates a text field with a date picker. The following additional parameters can be passed to this field type:

Example

	$fields['date_example'] = array('type' => 'date', 'first_day' => 2, 'date_format' => 'd-m-Y', 'min_date' => '01-01-2012', 'max_date' => '31-12-2012');
	

time

This field type creates a hour and minute fields.

Example

	$fields['time_example'] = array('type' => 'time');
	
:        

datetime

This field type combines the date and time fields and has the same additional parameters as the date field.

This field type creates a text field with a date picker. The following additional parameters can be passed to this field type:

Representations

	'type' => 'datetime|timestamp' // targets any field with the type of datetime or timestampe (equivalent to array('datetime', 'timestamp'))
	

Example

	$fields['datetime_example'] = array('type' => 'datetime', 'first_day' => 2, 'date_format' => 'd-m-Y', 'min_date' => '01-01-2012', 'max_date' => '31-12-2012', 'ampm' => TRUE);
	
:        

number

This field type creates a number field which is supported by some modern browsers checkbox field. The following additional parameter can be passed to this field type:

Representations

	'type' => array('int', 'smallint', 'mediumint', 'bigint') // targets any field with the type of int, smallint, mediumint or bigint
	

Example

	$fields['number_example'] = array('type' => 'number', 'represents' => 'int|smallint|mediumint|bigint', 'negative' => TRUE, 'decimal' => TRUE);
	

email

This field type creates an input field of type "email" which is supported by some modern browsers and will automatically validate the email address.

Example

	$fields['email_example'] = array('type' => 'email');
	

range

This field type creates an input field of type "range" which is supported by some modern browsers and creates a slider. The following additional parameters can be passed to this field type:

Example

	$fields['range_example'] = array('type' => 'range', 'min' => 1, 'max' => 10);
	

boolean

This field type creates either a checkbox or an enum type field (e.g. published with a "yes" and "no" radio OR simply a "yes" checkbox). The following additional parameters can be passed to this field type:

Example

	$options = array('a' => 'option A', 'b' => 'option B', 'c' => 'option C');
 	$fields['boolean_example'] = array('type' => 'boolean', 'mode' => 'radios', 'options' => $options);
	

nested

This field type creates a nested Form_builder object. The following additional parameters can be passed to this field type:

Example

	$f['nested_textarea'] = array('type' => 'textarea');
	$f['nested_boolean'] = array('type' => 'boolean');
	$fields['nested_example'] = array('type' => 'nested', 'fields' => $f, 'display_label' => FALSE);
	

fieldset

This field type groups fields together. If the form is rendered in the CMS, you can assign the 'class' parameter the value of 'tab' or "collapsible" and the fields will grouped under tabs or collapsible headers respectively.

section

This field type creates heading in the form. You can can pass a 'value', 'label' or 'name' with the value of the what you want to display for the section. The following additional parameter can be passed to this field type:

Example

	$fields['section_example'] = array('type' => 'section', 'tag' => 'h3', 'value' => 'This is a section header example');
	

This is a section header

copy

This field type creates copy block in the form. You can can pass a 'value', 'label' or 'name' with the value of the what you want to display for the section. The following additional parameter can be passed to this field type:

Example

	$fields['copy_example'] = array('type' => 'copy', 'tag' => 'p', 'value' => 'This is the copy example');
	

This is the copy example

custom

This field type can be used to create custom field types. To create reusable custom field types, visit the next section. The following additional parameter can be passed to this field type:

Example

	function my_custom_field($params)
	{
		$form_builder =& $params['instance'];
		$str = $form_builder->create_checkbox($params).' ';
		return $str;
	}
	$fields['custom_example'] = array('type' => 'custom', 'func' => 'my_custom_field', 'display_label' => FALSE);
	

template

This field type can provide you a lot of flexibility in how you setup your forms by allowing you to nest sub forms and make them repeatable and draggable for reordering. This field type can work well for layout sections that have repeatable fields you may want to reorder (e.g. a title, body, image section).

Example

	$fields['template_example'] = array('display_label' => FALSE, 
								'add_extra' => FALSE, 
								'init_display' => 'none', 
								'dblclick' => 'accordion', 
								'repeatable' => TRUE, 
								'style' => 'width: 900px;', 
								'type' => 'template', 
								'label' => 'Page sections', 
								'title_field' => 'title',
								'fields' => array(
													'sections' => array('type' => 'section', 'label' => '{__title__}'),
													'title' => array('style' => 'width: 800px'),
													'content' => array('type' => 'textarea', 'style' => 'width: 800px; height: 500px;'),
												)
											);
	

You can nest a template field in the fields parameter but only one level deep.

You can use the {__num__}, {__index__} and {__title__} as placeholders in your view or template files.

block

This field type is used for dynamically pulling in block layout fields:

Example

	$fields['block_example'] = array('type' => 'block', 'folder' => 'sections');
	

asset

This field type is used for uploading and assigning asset values to fields. It can provide two buttons next to the field. One to select an asset and the other to upload. The following additional parameter can be passed to this field type:

Upload Specific

Image Specific

Representations

	'name' => '.*image$|.*img$' // targets any field with the name ending with "image" or "img"
	

Example

	$fields['image'] = array('type' => 'asset', 'folder' => 'images/my_folder', 'hide_options' => TRUE);
	

url

This field type is used for links/URLs. The following additional parameters can be passed to this field type:

Representations

	'name' => 'url|link' // targets any field with the name of "url" or "link"
	

Example

	$fields['url'] = array();
	

wysiwyg

This field type is used for textareas and will use FUEL's $config['text_editor'] configuration to determine which editor to display in the field by default. The following additional parameters can be passed to this field type:

Example

	$fields['wysiwyg_example1'] = array('type' => 'wysiwyg', 'editor' => 'markitup');
	$fields['wysiwyg_example2'] = array('type' => 'wysiwyg', 'editor' => 'wysiwyg'); //ckeditor
	

inline_edit

This field type is used for associating a separate module's data with your own. The following additional parameters can be passed to this field type:

Example

		$fields['inline_edit_example'] = array('type' => 'inline_edit', 'module' => 'projects');
	

linked

This field type will take the value from one field and apply it to another field after passing it through a function (e.g. a slug field being based on a title field). The default filter functions are mirror, url_title, strtolower, and strtoupper. The following additional parameter can be passed to this field type:

Example

		$fields['name'] = array(); // field to link to
		$fields['linked_example'] = array('type' => 'linked', 'linked_to' => array('name' => 'strtoupper'));
	

currency

This field type can be used for inputting currency values. The following additional parameters can be passed to this field type:

You must specify a default value for the field which is greater than or equal to the minimum value and less than or equal to the maximum value

Example

	$fields['currency'] = array('type' => 'currency', 'decimal' => '.', 'currency' => '€', 'min' => -1000, 'max' => 1000);
	
€

state

This field displays a dropdown of states to select from. It automatically pulls it's options from the fuel/application/config/states.php config file. The following additional parameters can be passed to this field type:

Representations

	'name' => 'state' // targets any field with the name of state
	

Example

	$fields['state'] = array('type' => 'state');
	

slug

This field type can be used for creating slug or permalink values for a field using the url_title function. The following additional parameter can be passed to this field type:

Representations

	'name' => 'slug|permalink' // targets any field with the name of slug or permalink (e.g. could also use array('slug', 'permalink'))
	

Example

	$fields['title'] = array(); // field to link to
	$fields['slug_example'] = array('type' => 'slug', 'linked_to' => 'title');
	

list_items

This field type allows you to create bulletted list items by separating each line by a return. The data saved in the database will be either an unordered or ordered HTML list. The following additional parameter can be passed to this field type:

Example

	$value = "line1\nline2\nline3";
	$fields['list_items'] = array('type' => 'list_items', 'value' => $value, 'list_type' => 'ol');
	

language

This field type generates a dropdown select with the language values specified in MY_fuel.php.

Representations

	'name' => 'language' // targets any field with the name of language
	

Example

	$fields['language_example'] = array('type' => 'language');
	

keyval

This field allows you go create a key / value array by separating keys and values with a delimiter. Each key/value goes on it's own line. The post-processed result is a JSON encoded string:

Example

	$fields['keyval_example'] = array('type' => 'keyval');
	

toggler

This field is essentially an enum field that toggles the display of specified fields. To make a field toggleable, you need to give it a class parameter with a value of "toggle" and an additional class value that correlates to the value selected from the toggle field. The following additional parameter can be passed to this field type:

Example

	$fields['toggler_example'] = array('type' => 'toggler', 'prefix' => 'toggle_', 'options' => array('1' => 'One', '2' => 'Two'));
	$fields['toggler_field1'] = array('class' => 'toggle toggle_1');
	$fields['toggler_field2'] = array('type' => 'select', 'class' => 'toggle toggle_2', 'options' => array('1' => 'One', '2' => 'Two'));
	

colorpicker

This field provides a hexidecimal color picker:

Example

	$fields['colorpicker_example'] = array('type' => 'colorpicker');
	
#

dependent

This field allows you to have one field determine the options of another field:

Example

	$fields['dependent_example'] = array('type' => 'dependent', 'depends_on' => 'language', 'url' => fuel_url('my_module/ajax/options'), 'multiple' => TRUE, 'replace_selector' => '.language_depends');
	

embedded list

This field creates an unsortable list view of another module's data using the Data_table class. Each row has an edit button that displays a modal window of the edit screen from that module. The base_module_model has 2 methods on it to help facilitate this class. The first is the get_embedded_list_items method which renders the HTML for the table. The second is the ajax_embedded_list method that is called via AJAX to refresh the table after editing data in the modal window.

Example

	$fields['embedded_list_example'] = array('type' => 'embedded_list', 'module' => array(FUEL_FOLDER => 'fuel_tags_model'), 'cols' => '', method_params' => array('where' => array('context' => 'test')));
	

select2

This field type can be used with any select field and transforms it into a searchable list using the Select2 plugin.

Example

	$fields['select2_example'] = array('type' => 'select2');
	

Custom Field Type Association Parameters

Creating a custom field type requires an association be made in the fuel/application/config/custom_fields.php to the $config['custom_fields'] initialization parameter. The following parameters can be used in the association:

Example

'class'		=> array(FUEL_FOLDER => 'Fuel_custom_fields'), // key is the module, and the value is the class
'function'	=> 'template', // the method to execute. If no class is specified, then it will call it like a normal function
'filepath'	=> '', // if no file path is provided, it will look in libraries folder
'js'		=> array(
					FUEL_FOLDER => // the module in which assets/js folder to look in 
						'jquery/plugins/jquery.repeatable', // the path to the javascript file relative to the assets/js folder
						),
'js_function' => 'fuel.fields.template_field', // the name of the javascript function to execute upon rendering of the form
'js_exec_order' => 0, // the execution order of the javascript function
'css' => '', // the path to the css file relative to the assets/css folder

Representatives

Also new to the Form_builder class is the concept of representatives. Representatives allow you to assign a field with certain attributes (e.g. type, name, etc) to a specific field type. For example, FUEL will automatically set a field with a name of 'pwd' or 'passwd' to be the 'password' type field. Or, if you have a field of type 'int', 'smallint', 'mediumint', 'bigint', it will be assigned the 'number' field type. When assigning a representative, the key is the field type to be the representative and the value is either an array or string/regular expression to match for fields to represent.

There are several ways to assign representatives to a field type:

The first is to add them to the $config['representatives'] array in the fuel/application/config/custom_fields.php:

// will assign any field of type 'int', 'smallint', 'mediumint' or 'bigint' to be represented by the 'my_field' type
$config['representatives']['my_field'] =  => array('int', 'smallint', 'mediumint', 'bigint');

// will assign any field with the name of 'pwd' or 'passwd' to the type of 'my_field'. This method is using the name attribute as the key. 
// If no key then it will assume the attribute is 'type'
$config['representatives']['my_field'] =  => array('name' => array('pwd', 'passwd'));

The second way is to assign them using the 'represents' attribute when making a custom field type association. For example, both the datetime and wysiwyg use this method by default as shown below:

$config['custom_fields'] = array(
	'datetime' => array(
		'css_class' => 'datepicker',
		'js_function' => 'fuel.fields.datetime_field',
		// 'js_params' => array('format' => 'mm-dd-yyyy'),
		'represents' => 'datetime|timestamp',
	),

	'wysiwyg' => array(
		'class'		=> array(FUEL_FOLDER => 'Fuel_custom_fields'),
		'function'	=> 'wysiwyg',
		'filepath'	=> '',
		'css' 		=> array(FUEL_FOLDER => 'markitup'),
		'js'		=> array(
							FUEL_FOLDER => array(
								'editors/markitup/jquery.markitup',
								'editors/markitup/jquery.markitup.set',
								'editors/ckeditor/ckeditor.js',
								'editors/ckeditor/config.js',
							)
		),
		'css' => array(FUEL_FOLDER => 'markitup'),
		'js_function' => 'fuel.fields.wysiwyg_field',
		'represents' => array('text', 'textarea', 'longtext', 'mediumtext'),
	),


The third way is to assign it when creating a field like so:

$fields['my_field'] = array('type' => 'my_field', 'represents' => 'blob');

The fourth way of setting a representative is to simply use the set_representative method on the form_builder object like so:

$this->form_builder->set_representative('my_field', array('blob'));

Removing Representatives

Sometimes a field may be using a representative that you don't won't. For example, you may have a field that has "url" in the name and it is using the url field type which you don't want. To fix that you can use the ignore_representative parameter like so:

$fields['my_field'] = array('type' => 'my_field', 'ignore_representative' => TRUE);

If you'd like to remove a representative completely from the form_builder instance, you can use the remove_representative like so:

$this->form_builder->remove_representative('url');

Pre & Post Processing Fields

If you need a field that does additional processing before being set as the value of the field or after posting, you can create a pre-processing or post-processing function to handle it. To register that function with the field, you specify the pre_process or post_process parameter respectively. The value assigned to the the pre/post_process parameters is the name of the function (as a string), a lambda function, or an array with the first value being the instance of an object and the second value being the name of the method on that object. There are several custom functions that take advantage of this feature including the asset, slug template, currency and keyval field types.