Developers Documentation

×

Warning

301 error for file:https://clearos.com/dokuwiki2/lib/exe/css.php?t=dokuwiki&tseed=82873f9c9a1f5784b951644363f20ef8

User Tools

Site Tools


Form Controller

There are three main styles of forms/controllers found in ClearOS. This document provides information on the basic structure of a simple form controller. You can find more information about the other two styles of controllers here:

Please make sure you have a license notice at the top of your source code file.

Class Declaration

All controller classes must extend the ClearOS_Controller class. Also, don't forget to add the documentation block that describes your controller class!

/**
 * Date controller.
 *
 * @category   Apps
 * @package    Date
 * @subpackage Controllers
 * @author     ClearFoundation 
 * @copyright  2011 ClearFoundation
 * @license    http://www.gnu.org/copyleft/gpl.html GNU General Public License version 3 or later
 * @link       http://www.clearfoundation.com/docs/developer/apps/date/
 */
 
class Date extends ClearOS_Controller
{
    ...

Kudo moment. The ClearOS_Controller is really just MX_Controller from wiredesignz. Vanity over the name of a controller - a bit geeky, we know.

Index Method

Load Libraries

In order to keep the ClearOS development framework lightweight, libraries must be explicitly loaded in the controller.

// Load dependencies
//------------------
 
$this->load->library('date/Time');
$this->lang->load('date');

Validate

Every piece of data that can be posted to a form must be properly validated. This is one of the most critical elements in creating a secure web application. Improper validation can quickly lead to a security vulnerability. To help with implementing security best practices, the ClearOS framework has extended the base CodeIgniter system to simplify (and secure) your code. In the form_validation→set_policy function, you can use the validation routines from your libraries. The format is:

set_policy(form_variable, library, method, is_required);

For example:

set_policy('timezone', 'date/Time', 'validate_time_zone', TRUE);

// Set validation rules
//---------------------
 
$this->form_validation->set_policy('timezone', 'date/Time', 'validate_time_zone', TRUE);
$form_ok = $this->form_validation->run();

Handle Update

Before displaying a view, you may need to handle an update provided by an end users. If the form data has successfully passed through the validation routines ($form_ok === TRUE), then we simply pass the data to the library.

// Handle form submit
//-------------------
 
if (($this->input->post('submit') && $form_ok)) {
    try {
        $this->time->set_time_zone($this->input->post('timezone'));
        $this->page->set_status_updated();
    } catch (Exception $e) {
        $this->page->view_exception($e);
        return;
    }
}

Load View Data

No different than CodeIgniter, the $data array is populated in the controller and then passed on to the view. For the most part, this data comes from method calls in the underlying library.

// Load view data
//---------------
 
try {
    $data['timezone'] = $this->time->get_time_zone();
    $data['timezones'] = $this->time->get_time_zone_list();
} catch (Exception $e) {
    $this->page->view_exception($e);
    return;
}

Load Views

The last step in the controller is to load the view. Instead of using the standard $this→page→view() function in CodeIgniter, we use a slightly different method call: view_form(). In case you are wondering, this approach simplifies header/footer management, as well as mobile support.

// Load views
//-----------
 
$this->page->view_form('date', $data);

Exception Handling

Any interaction with the underlying libraries should be handled via the old try/catch exception handler. Most of the underlying exceptions are simply passed straight to a standard warning message in the view. In some circumstances, you may want to catch a particular exception and do something different. That's fine, go right ahead.

try {
    $data['timezone'] = $this->ntptime->get_time_zone();
} catch (Timezone_Not_Set_Exception $e) {
    // An unconfigured time zone is not fatal, but warn the user.
    $data['my_warning'] = lang('time_time_zone_not_set_warning');
} catch (Exception $e) {
    $this->page->view_exception($e);
}
content/en_us/dev_framework_reference_guide_form_controller.txt · Last modified: 2015/03/02 09:48 by dloper

https://clearos.com/dokuwiki2/lib/exe/indexer.php?id=content%3Aen_us%3Adev_framework_reference_guide_form_controller&1710848568