<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>BackendPro User Guide : Preference Form Class</title>
<style type='text/css' media='all'>@import url('../userguide.css');</style>
<link rel='stylesheet' type='text/css' media='all' href='../userguide.css' />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='robots' content='all' />
</head>
<body>
<!-- START NAVIGATION -->
<div id="nav"><div id="nav_inner"></div></div>
<div id="nav2"><a name="top"> </a></div>
<div id="masthead">
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td><h1>BackendPro User Guide Version 0.6.1</h1></td>
<td id="breadcrumb_right"><a href="../contents.html">Table of Contents</a></td>
</tr>
</table>
</div>
<!-- END NAVIGATION -->
<!-- START BREADCRUMB -->
<table cellpadding="0" cellspacing="0" border="0" style="width:100%">
<tr>
<td id="breadcrumb">
<a href="http://www.kaydoo.co.uk/projects/backendpro">BackendPro Home</a> ›
<a href="../index.html">User Guide Home</a> ›
Preference Form Class
</td>
<td id="searchbox"><form method="get" action="http://www.google.com/search"><input type="hidden" name="as_sitesearch" id="as_sitesearch" value="http://www.kaydoo.co.uk/backendpro/user_guide/" />Search User Guide <input type="text" class="input" style="width:200px;" name="q" id="q" size="31" maxlength="255" value="" /> <input type="submit" class="submit" name="sa" value="Go" /></form></td>
</tr>
</table>
<!-- END BREADCRUMB -->
<br clear="all" />
<!-- START CONTENT -->
<div id="content">
<h1>Preference Form Class</h1>
<p>This class can be used to create forms to manage website settings stored in the database with only a few lines of code.</p>
<p class="important"><strong>Note:</strong> For an example of a controller implementing a preference form please take a look at the file
<var>system/application/controllers/admin/settings.php</var></p>
<h2>Using the Class</h2>
<p>Creating a preference form couldn't be simpler. It only takes a few lines of code instructing the class
what preferences you want to manage and how they should be managed and the rest is done for you.</p>
<p>There are two ways to setup the preference form. The first is with <strong>groups</strong>. This
method is good if you have a lot of settings you want to manage on the same page. An example of a grouped
form is that in the <var>settings.php</var> file mentioned earlier. This allows you to have multiple sub-categories
of settings, making it easier for the user to find the setting they want.</p>
<p>The other way is to have all the settings on a <strong>single page</strong>. Now this is fine if you only
have a couple of settings.</p>
<h3>Setting up a form</h3>
<ol>
<li>
<p>To setup a form you pass a <kbd>config</kbd> array into the class when loading it. This config
array must have <kbd>form_name</kbd> and <kbd>form_link</kbd> entries. Where <var>uri_string</var>
is the uri string corresponding to the controller and method from which the user will visit to display
the settings form. <strong>If the form is being created when the user visits an <dfn>index()</dfn> method
of a controller you must put <var>/index</var> on the end of the uri string.</strong></p>
<code>
$config['<kbd>form_name</kbd>'] = 'My Form';<br />
$config['<kbd>form_link</kbd>'] = '<var>uri_string</var>';
</code>
</li>
<li>
<p>The next data you need to pass in is what groups you want to assign settings to. If you do not want
to use groups then skip this bit.</p>
<code>
$config['groups'] = array)<br />
'<var>group_id</var>' => array('name' => '<var>name</var>', fields => '<var>fields</var>'),<br />
..<br />
..<br />
'<var>group_id</var>' => array('name' => '<var>name</var>', fields => '<var>fields</var>'),<br />
);
</code>
<p>From the code above you can see each row of the array defines a new group to split the form into.</p>
<ul>
<li><var>group_id</var> should be a unique string for that group which can be passed in the url. So stick to alpha, numeric & underscore strings only.</li>
<li><var>name</var> is the form title. So 'General Settings' or something.</li>
<li><var>fields</var> is a comma separated string of all the preference names to include in the group.</li>
</ul>
</li>
<li>
<p>The last part of the configuration is how to handle each preference, e.g. what type of form input and what
validation should be used. Only by defining a preference in the following way will it be included in the form,
just assigning it to a group will not display the preference.</p>
<code>
$config['fields']['<var>setting_name</var>'] = array('type'=>'<var>type</var>','rules'=>'<var>rules</var>', 'params'=><kbd>params</kbd>);<br />
..<br />
..<br />
$config['fields']['<var>setting_name</var>'] = array('type'=>'<var>type</var>','rules'=>'<var>rules</var>', 'params'=> <kbd>params</kbd>);
</code>
<p>Now I'm afraid explaining this can be quite tricky.</p>
<ul>
<li><var>setting_name</var> is the name you have called the preference in the database.</li>
<li><var>type</var> is the type of input you want, please see <a href="#form_input_types">here</a> for the possible types.</li>
<li><var>rules</var> is a validation string you want to run the input through on submission. E.g. <dfn>'trim|required|valid_email'</dfn></li>
<li><kbd>params</kbd> is an array of extra parameters you want assigned to the input E.g. <dfn>array('size'=>'20','onClick'=>'..')</dfn>.</li>
</ul>
<p>Now as said it is a bit complex and this is why. The preference form class has defaults. What I mean by this if you don't
specify a field value it will use a default, lets look at some examples.</p>
<code>
// This is perfectly OK, not entering anything will default to using a <kbd>text</kbd> input<br />
// with no validation<br />
$fields['fields']['setting'] = array(); <br />
<br />
// Here we only specify a type, so it will go and fetch the default validation rule <br />
// for this type and use it.<br />
$fields['fields']['setting'] = array('type'=>'boolean');
</code>
</li>
<li>
<p>Now we have the config values setup we need to output the form created.</p>
<code>
$this->load->module_library('preferences','preference_form');<br /><br />
$this->preference_form->initalize($config);<br />
<br />
// Get the form output and assign to a variable ready to display<br />
$form_output = $this->preference_form->display();
</code>
</li>
</ol>
<a name="form_input_types"></a>
<h2>Form Input Types</h2>
<p>As said in the section above, you can select from many different pre-created input types.
</p>
<table cellpadding="0" cellspacing="1" border="0" style="width:100%" class="tableborder">
<tr>
<th>Type</th>
<th>Default Rule</th>
<th>Description</th>
</tr>
<tr>
<td class="td"><strong>text</strong></td>
<td class="td">trim</td>
<td class="td">Creates a basic textbox input for entering a string.</td>
</tr>
<tr>
<td class="td"><strong>textarea</strong></td>
<td class="td">trim</td>
<td class="td">Creates a basic textarea input. You may need to specify rows and cols in the 'params' array, E.g. <dfn> 'params' => array('rows'=>'15','cols'=>'15')</dfn></td>
</tr>
<tr>
<td class="td"><strong>boolean</strong></td>
<td class="td"></td>
<td class="td">Creates yes/no radio buttons for boolean input</td>
</tr>
<tr>
<td class="td"><strong>dropdown</strong></td>
<td class="td"></td>
<td class="td">Creates a dropdown select box. To specify the possible options pass an 'options' array in the 'params' array. E.g <dfn>'params' => array('options' => array('1'=>'Option 1','2'=>'Option 2'))</dfn></td>
</tr>
</table>
<p>If you require a form input which is not provided by default you can add your own inputs to the class.
To do this open the file <var>modules/preferences/libraires/Preferences_form.php</var> and scroll down
until you see functions with the name <dfn>function _field_*</dfn>. Below is the basic code needed to create your
own form input function.</p>
<code>
function _field_<var>fieldname</var>($key)<br />
{<br />
$params = $this->field[$key]['params'];<br />
$params['name'] = $key;<br />
$params['id'] = $key;<br />
$params['value'] = $this->CI->validation->{$key};<br />
<br />
// Extra code needed to process the input<br />
<br />
// E.g. return form_input($params);<br />
return <var>form_html</var>;<br />
}
</code>
<p>If your stuck on what this code does I would advice you take a look at the way I have declared the basic types
in <var>modules/preferences/libraires/Preferences_form.php</var>.</p>
<h2>Preference Form Function Reference</h2>
<a name="initalize"></a>
<h3>$this->preference_form->initalize()</h3>
<p>Initalize Form:</p>
<code>$this->preference_form->initalize(<var>$config</var>);</code>
<p>Set up a form using the settings defined in the array <var>$config</var></p>
<a name="display"></a>
<h3>$this->preference_form->display()</h3>
<p>Output Form:</p>
<code>$this->preference_form->display(<var>TRUE/FALSE</var>);</code>
<p>Process the form setup using <strong>initalize</strong> and return the output.</p>
<p>The first <strong>optional</strong> parameter defines whether the output should
be returned or <strong>printed</strong>, if <strong>TRUE</strong> the form will be printed, otherwise
it will be returned.</p>
<p class="important"><strong>Note:</strong> For an example of a controller implementing a preference form please take a look at the file
<var>system/application/controllers/admin/settings.php</var></p>
</div>
<!-- END CONTENT -->
<div id="footer">
<p>
<a href="#top">Top of Page</a> ·
<a href="../index.html">User Guide Home</a>
</p>
<p><a href="http://www.kaydoo.co.uk/projects/backendpro">BackendPro</a> · Copyright © 2009 · <a href="http://www.kaydoo.co.uk">Adam Price</a></p>
</div>
</body>
</html>