Developers Documentation



301 error for file:

User Tools

Site Tools


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 ClearFoundation}
 * @license GNU Public License
 * @copyright Copyright 2010, ClearFoundation
 * @link 
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.


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


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:


// Set validation rules
$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 {
    } 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);

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)