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.

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
{
    ...

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

• Simple Form App

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

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

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();

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();
    }
}

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();
}

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');

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();
}