File Source for grid_ctrl.class.php

<?php
// *** Tangra (Application Framework and Tools for PHP)
// $Id$
//
/**
* Contains class Grid_Ctrl
*
* @package tangra_lib
* @subpackage grids
*/
/**
*
*/
require_once(TANGRA_MAIN_DIR.'grids/static_paginated_grid.class.php');
/**
*
*/
require_once(TANGRA_MAIN_DIR.'db/db_connection.class.php');
/**
*
*/
require_once(TANGRA_MAIN_DIR.'db/paginate_db_data.class.php');
/**
*
*/
require_once(TANGRA_MAIN_DIR.'core/tangra_parameter_method.class.php');
/**
*
*/
require_once(TANGRA_MAIN_DIR.'web_site/web_event_simple_int.class.php');
/**
*
*/
require_once(TANGRA_MAIN_DIR.'exceptions/te_key_already_exists.class.php');
/**
*
*/
require_once(TANGRA_MAIN_DIR.'exceptions/te_key_not_exists.class.php');
/**
* Controller for grids
*
* @package tangra_lib
* @subpackage grids
*/
abstract class Grid_Ctrl extends Tangra_Class {
/**
* Capture for setting page
*
*/
const SET_PAGE_CAPTURE = 'page';
/**
* Grid object
*
* @var Grid
* @internal
*/
protected $grid;
/**
* Paginator object
*
* @var Paginate_DB_Data
* @internal
*/
protected $paginate_db_data;
/**
* Controller name
*
* @var unknown_type
* @internal
*/
private $system_name;
/**
* Vars manager
*
* @var Vars_Manager
* @internal
*/
private $vm;
/**
* Method for passing set page command
*
* @var unknown_type
* @internal
*/
private $method;
/**
* Holds array of additional parameters passed to the controller.
*
* @var array
*/
protected $additional_parameters = array();
/**
* Holds name of user defined method (if set)
*
* @var string
*/
private $user_defined_post_processing_method;
/**
* Constructor
*
* @param string $system_name
* @param Vars_Manager $vm Permanent Vars_Manager that will be used. Session of Thread VM
* @param integer $method Tangra_Parameter_Method::GET or Tangra_Parameter_Method::POST or Tangra_Parameter_Method::PI
*/
function __construct($system_name, Vars_Manager $vm, $method = Tangra_Parameter_Method::GET) {
$this->set_system_name($system_name);
$this->_create_grid();
$this->_create_paginate_db_data();
$this->set_vm($vm);
$this->set_method($method);
$this->init();
}
/**
* Process the grid
*
* This method will load page passed with <var>$page</var> or will load current_page
*
* @param DB_Connection $dbc DB_Connection object
* @param integer $page Page to be loaded. Default = NULL - will load current page
*/
public function process(DB_Connection $dbc, $page = NULL) {
$page = $this->detect_page($page);
$rows = $this->retrieve_rows($dbc, $page);
$total_pages = $this->paginate_db_data->get_total_pages();
if ($total_pages - 1 < $page) {
$this->set_page($page);
if ($total_pages) {
$page = $total_pages - 1;
} else {
$page = 0;
}
$rows = $this->retrieve_rows($dbc, $page);
}
$user_pp_method = $this->get_user_defined_post_processing_method();
if ($user_pp_method) {
$rows = $this->$user_pp_method($dbc, $rows);
}
$this->send_data_to_grid($rows, $page, $this->paginate_db_data->get_total_pages(), $this->paginate_db_data->get_total_rows());
}
/**
* Get TPLE Exports for the grid
*
* @return TPLE_Exports
*/
public function get_tple_exports() {
$exports = $this->grid->get_tple_exports();
$exports->add_pair($this->get_system_name().'_additional_parameters', $this->get_additional_parameters());
return $exports;
}
/**
* Returns web event for set page command
*
* @return Web_Event_Si
*/
public function get_grid_set_page_event() {
$set_page_event = new Web_Event_Simple_Int($this->get_system_name().'_grid_'.Grid_Ctrl::SET_PAGE_CAPTURE,
$this->get_method(),
$this->get_system_name().'_grid_'.Grid_Ctrl::SET_PAGE_CAPTURE);
return $set_page_event;
}
/**
* Returns grid's system name
*
* @return unknown
*/
public function get_system_name() {
return $this->system_name;
}
/**
* Returns reference to grid object
*
* @return Grid
*/
public function get_grid() {
return $this->grid;
}
/**
* Returns reference to Paginate_DB_Data object
*
* @return Paginate_DB_Data
*/
public function get_paginate_db_data() {
return $this->paginate_db_data;
}
/**
* Sets Vars_Manager object
*
* @param Vars_Manager $vm
*/
protected function set_vm(Vars_Manager $vm) {
$this->vm = $vm;
}
/**
* Returns reference to Vars_Manager object
*
* @return unknown
* @internal
*/
protected function get_vm() {
return $this->vm;
}
/**
* Sets method for receiving command
*
* @param integer $method
* @internal
*/
protected function set_method($method) {
switch ($method) {
case Tangra_Parameter_Method::GET:
$this->method = $method;
break;
case Tangra_Parameter_Method::POST:
$this->method = $method;
break;
case Tangra_Parameter_Method::PI:
$this->method = $method;
break;
default:
throw new Tangra_Exception('Invalid parameter $method: '.$method);
break;
}
}
/**
* Returns method for receiving commands
*
* @return unknown
*/
public function get_method() {
return $this->method;
}
/**
* Sets user defined method that will be called for postprocessing of the rows
*
* Two parameters will be passed to postprocessing method: $dbc and $rows where $dbc is DB_Connection instance and $rows contains all rows of the current page of the grid.
* Postprocessing method have to return an array containing new/modified data.
* Access to postprocessing method have to be "protected" in order grid_ctrl to be able to call it.
*
* Example:
* $this->set_user_defined_post_processing_method('my_postprocessing');
*
* protected function my_posprocessing(DB_Connection $dbc, $rows) {
* // ..some processing - for example loading additional data per row, doing some calculation with existing data and populating new row cell, etc.
* return $new_rows;
* }
*
* @param string $method_name This method have to be defined in descendant class otherwise exception will be thrown
* @throws Tangra_Exception
*/
public function set_user_defined_post_processing_method($method_name) {
if (is_callable(array($this, $method_name))) {
$this->user_defined_post_processing_method = $method_name;
} else {
throw new Tangra_Exception("Method $method_name is not defined.");
}
}
/**
* Returns name of the user defined method that will be called for postprocessing of the rows
*
* @return string
*/
public function get_user_defined_post_processing_method() {
return $this->user_defined_post_processing_method;
}
/**
* Initializes the object
*
*/
protected function init() {
$vm = $this->get_vm();
if (!$vm->is_var_registered($this->get_system_name())) {
$vm->register_var($this->get_system_name());
$tmp = 0;
$vm->set_var($this->get_system_name(), $tmp);
}
}
/**
* Sets current page
*
* @param integer $page
*/
protected function set_page($page) {
tangra_if_not_int_throw_e($page);
// please note that page numbers are in human form, i.e. first page is 1, not 0
$vm = $this->get_vm();
if ($page) {
$page_num = $page - 1;
} else {
$page_num = 0;
}
$vm = $this->get_vm();
$vm->set_var($this->get_system_name(), $page_num);
}
/**
* Ensures that object returned by $this->create_grid(); will be instance of Grid
*
* @throws Tangra_Exception
*/
protected function _create_grid() {
$grid = $this->create_grid();
if ($grid instanceof Grid) {
$this->grid = $grid;
} else {
throw new Tangra_Exception('create_grid returned object that is not instance of class Static_Paginated_Grid.');
}
}
/**
* Sets system name
*
* @param unknown_type $system_name
* @throws Tangra_Exception
* @internal
*/
protected function set_system_name($system_name) {
if (ereg("^[a-z]{1}[a-z0-9_]{1,50}$", $system_name)) {
$this->system_name = strtolower($system_name);
} else {
throw new Tangra_Exception('Invalid grid name. Must be alphanumeric (underscore allowed), starting with letter, 50 characters max.');
}
}
/**
* Ensures that object returned by $this->create_paginate_db_data(); will beinstance of Paginate_DB_Data
*
* @throws Tangra_Exception
*/
protected function _create_paginate_db_data() {
$pdbd = $this->create_paginate_db_data();
if ($pdbd instanceof Paginate_DB_Data) {
$this->paginate_db_data = $pdbd;
} else {
throw new Tangra_Exception('create_paginate_db_data() returned object that is not instance of class Paginate_DB_Data.');
}
}
/**
* Have to be overwriten and sqls for the Paginate_DB_Data have to be set inside.
*
*/
protected function prepare_sqls() {
return array('sqls' => '', 'sqlc' => '');
}
/**
* Adds new additional parameter
*
* Please note that this parameter will be also added to grid's external parameters.
*
* @param string $name
* @param mixed $value
* @throws TE_Key_Already_Exists
*/
public function add_additional_parameter($name, $value) {
if (!array_key_exists($name, $this->additional_parameters)) {
$this->additional_parameters[$name] = $value;
$this->grid->add_external_parameter($name, $value);
} else {
throw new TE_Key_Already_Exists('Parameter with that name already exists: '.$name);
}
}
/**
* Sets additional_parameters at once
*
* @param array $params Simple array key => value pairs
* @throws Tangra_Exception
*/
public function set_additional_parameters($params) {
if (is_array($params)) {
foreach($params as $key => $value) {
$this->add_additional_parameter($key, $value);
}
} else {
throw new Tangra_Exception('Expecting array.');
}
}
/**
* Returns all additional parameters as array
*
* @return array Simple array, key => value pairs
*/
public function get_additional_parameters() {
return $this->additional_parameters;
}
/**
* Returns value ot additional parameter
*
* @param string $name
* @param boolean $forgiving
* @throws TE_Key_Not_Exists
*
*/
protected function get_additional_parameter($name, $forgiving = false) {
if (array_key_exists($name, $this->additional_parameters)) {
$ret = $this->additional_parameters[$name];
} else {
if (!$forgiving) {
throw new TE_Key_Not_Exists('Parameter with that name not exists: '.$name);
} else {
$ret = false;
}
}
return $ret;
}
/**
* Overoload this method, create your Grid object and return it
*
*/
abstract protected function create_grid();
/**
* Overload this method, create Paginate_DB_Data and return it
*
*/
abstract protected function create_paginate_db_data();
/**
* Detects current page number.
*
* Will return current page number. If $page is passed - will return that value otherwise will
* retrieve current page from permanent VM.
*
* @param integer $page
* @return integer
*/
protected function detect_page($page) {
$vm = $this->get_vm();
if ($page !== false && $page != NULL ) {
$this->set_page($page);
}
$page = $vm->get_var($this->get_system_name());
return $page;
}
/**
* Retrieves rows from DB
*
* @param DB_Connection $dbc
* @param integer $page Rows for page $page will be retrieved
* @return array
*/
protected function retrieve_rows(DB_Connection $dbc, $page) {
$sql = $this->prepare_sqls();
if (is_array($sql)) { //this if is used for backward compatability
if ($sql['sqls']) {
$this->paginate_db_data->set_sql_select($sql['sqls']);
}
if ($sql['sqlc']) {
$this->paginate_db_data->set_sql_count($sql['sqlc']);
}
}
$rows = $this->paginate_db_data->fetch_page($page, $dbc);
return $rows;
}
/**
* Sends retrieved rows and other data to the grid object
*
* @param array $rows
* @param integer $page
* @param integer $total_pages
* @param integer $total_rows
*/
protected function send_data_to_grid($rows, $page, $total_pages, $total_rows) {
$this->grid->set_rows($rows);
$this->grid->set_cp_and_tp($page, $total_pages);
$this->grid->set_total_rows($total_rows);
}
}

Source for file grid_ctrl.class.php