ClearOS Documentation

×

Warning

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

User Tools

Site Tools


Controllers

A ClearOS controller is almost identical to a CodeIgniter controller. This document highlights the differences as well as some best practices.

  • Coding style
  • Integrated validation
  • Method naming convention

For a review of controllers, please visit the CodeIgniter documentation.

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.
 *
 * @package Frontend
 * @author {@link http://www.clearfoundation.com ClearFoundation}
 * @license http://www.gnu.org/copyleft/gpl.html GNU Public License
 * @copyright Copyright 2010, ClearFoundation
 * @link http://www.clearfoundation.com 
 */
 
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.

Methods

This section describes some of the common elements of a controller method. You can find more specific examples in the following documents.

Load Libraries

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

// Load libraries
//---------------
 
$this->load->library('date/NtpTime');

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_rules function, you can use the validation routines from your libraries. The format is:

api_{app name}_{library}_{validation method}

For example:

api_dns_DnsMasq_ValidateWins

// Set validation rules
//---------------------
 
$this->load->library('form_validation');
 
$this->form_validation->set_rules('gateway', lang('dhcp_gateway'), 'api_dns_DnsMasq_ValidateGateway');
$this->form_validation->set_rules('wins', lang('dhcp_wins'), 'api_dns_DnsMasq_ValidateWins');
 
$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 === TRUE)) {
    try {
        $this->time->SetTimeZone($this->input->post('timezone'));
    } catch (Exception $e) {
        $data['exceptions'][] = $e->GetMessage();
    }
}

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['subnets'] = $this->dnsmasq->GetSubnets();
    $data['ethlist'] = $this->dnsmasq->GetDhcpInterfaces();
} catch (Exception $e) {
    $header['exceptions'][] = $e->GetMessage();
}

Load Views

The last step in the controller is to load the view. The header and footer are required for almost all webconfig pages (though there are some exceptions!).

// Load views
//-----------
 
$header['title'] = lang('date_date');
 
$this->load->view('theme/header', $header);
$this->load->view('date', $data);
$this->load->view('theme/footer');

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.

// ...
$header['exceptions'] = array();
$header['warnings'] = array();
 
// 
try {
    $data['timezone'] = $this->ntptime->gettimezone();
} catch (TimezoneNotSetException $e) {
    // An unconfigured time zone is not fatal, but warn the user.
    $data['timezone'] = '';
    $header['warnings'][] = $e->GetMessage();
} catch (Exception $e) {
    $header['exceptions'][] = $e->GetMessage();
}
content/en_us/dev_framework_reference_guide_controllers.txt · Last modified: 2015/03/01 16:45 (external edit)

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