Preference Form Class

This class can be used to create forms to manage website settings stored in the database with only a few lines of code.

Note: For an example of a controller implementing a preference form please take a look at the file system/application/controllers/admin/settings.php

Using the Class

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.

There are two ways to setup the preference form. The first is with groups. 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 settings.php file metioned earlier. This allows you to have multiple sub-categories of settings, making it easyier for the user to find the setting they want.

The other way is to have all the settings on a single page. Now this is fine if you only have a couple of settings.

Setting up a form

To setup a form you pass a config array into the class when loading it. This config array must have form_name and form_link entries. Where uri_string is the uri string corrosponding to the controller and method from which the user will visit to display the settings form. If the form is being created when the user visits an index() method of a controller you must put /index on the end of the uri string.
$config['form_name'] = 'My Form'; $config['form_link'] = 'uri_string';
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.
$config['groups'] = array) 'group_id' => array('name' => 'name', fields => 'fields'), .. .. 'group_id' => array('name' => 'name', fields => 'fields'), );
From the code above you can see each row of the array defines a new group to split the form into.
- group_id should be a unqiue string for that group which can be passed in the url. So stick to alpha, numeric & underscore strings only.
- name is the form title. So 'General Settings' or something.
- fields is a comma seperated string of all the preference names to include in the group.
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.
$config['fields']['setting_name'] = array('type'=>'type','rules'=>'rules', 'params'=>params); .. .. $config['fields']['setting_name'] = array('type'=>'type','rules'=>'rules', 'params'=> params);
Now I'm affraid explaining this can be quite tricky.
- setting_name is the name you have called the preference in the database.
- type is the type of input you want, please see here for the possible types.
- rules is a validation string you want to run the input through on submittion. E.g. 'trim|required|valid_email'
- params is an array of extra parameters you want assigned to the input E.g. array('size'=>'20','onClick'=>'..').
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.
// This is perfectly OK, not entering anything will default to using a text input // with no validation $fields['fields']['setting'] = array(); // Here we only specify a type, so it will go and fetch the default validation rule // for this type and use it. $fields['fields']['setting'] = array('type'=>'boolean');
Now we have the config values setup we need to output the form created.
$this->load->module_library('preferences','preference_form');<br /> $this->preference_form->initalize($config); // Get the form output and assign to a variable ready to display $form_output = $this->preference_form->display();

Form Input Types

As said in the section above, you can select from many different pre-created input types.

Type	Default Rule	Description
text	trim	Creates a basic textbox input for entering a string.
textarea	trim	Creates a basic textarea input. You may need to specify rows and cols in the 'params' array, E.g. 'params' => array('rows'=>'15','cols'=>'15')
boolean		Creates yes/no radio buttons for boolean input
dropdown		Creates a dropdown select box. To specify the possible options pass an 'options' array in the 'params' array. E.g 'params' => array('options' => array('1'=>'Option 1','2'=>'Option 2'))

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 modules/preferences/libraires/Preferences_form.php and scroll down until you see functions with the name function _field_*. Below is the basic code needed to create your own form input function.


function _field_fieldname($key)

{

    $params = $this->field[$key]['params'];

    $params['name'] = $key;

    $params['id'] = $key;

    $params['value'] = $this->CI->validation->{$key};

    

    // Extra code needed to process the input
     
    
   
    // E.g. return form_input($params);

    return form_html;

}

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 modules/preferences/libraires/Preferences_form.php.

Preference Form Function Reference

$this->preference_form->initalize()

Initalize Form:

$this->preference_form->initalize($config);

Set up a form using the settings defined in the array $config

$this->preference_form->display()

Output Form:

$this->preference_form->display(TRUE/FALSE);

Process the form setup using initalize and return the output.

The first optional parameter defines whether the output should be returned or printed, if TRUE the form will be printed, otherwise it will be returned.