A ClearOS controller is almost identical to a CodeIgniter controller. This document highlights the differences as well as some best practices.
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.
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(); }