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:
Copyright and License
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 { ...
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); }