File Source for gform_ctrl_with

<?php
/**
* Contains class GForm_Ctrl_With_Object
*
* @package tangra_lib
* @subpackage form
*/
/**
*
*/
require_once(TANGRA_MAIN_DIR.'interfaces/i_db_storable.class.php');
/**
*
*/
require_once(TANGRA_MAIN_DIR.'form/gform_ctrl.class.php');
/**
*
*/
require_once(TANGRA_MAIN_DIR.'exceptions/te_gform_ctrl_wo_record_not_exists.class.php');
/**
* Controller for Guarded_Form with I_DB_Storable Object
*
* Abstract class that provides basic infrastructure for controllers that will use Guarded_Form and
* I_DB_Storable objects.
*
* @package tangra_lib
* @subpackage form
*/
abstract class GForm_Ctrl_With_Object extends GForm_Ctrl {
/**
* array that holds Object to form_ids links
*
* @var array
* @internal
*/
protected $object_to_form_id_links;
/**
* This string will be searched in $_GET to capture object id
*
* @var string
* @internal
*/
private $object_id_capture;
/**
* Object that will be controlled. It must be instance of I_DB_Storable
*
* @var unknown_type
* @internal
*/
private $object;
/**
* DB_Connection object
*
* @var unknown_type
* @internal
*/
private $dbc;
/**
* Conctructor
*
* @param string $system_name Controller's name
* @param Vars_Manager $vm Permanent Vars_Manager that will be used. Session of Thread VM
* @param DB_Connection $dbc Database connection
* @param string $object_id_capture This string will be searched in $_GET to capture object id
*/
function __construct($system_name, Vars_Manager $vm, DB_Connection $dbc, $object_id_capture = 'obj_id') {
$this->dbc = $dbc;
parent::__construct($system_name, $vm);
$this->object_id_capture = $object_id_capture;
$this->init_object_to_form_id_links();
$this->_create_object();
}
/**
* Returns the event for receiving object id
*
* @return Web_Event_Simple
*/
public function get_object_id_event() {
$object_id_event = new Web_Event_Simple($this->compose_object_id_event_name(),
Tangra_Form_Submit_Method::GET,
$this->form->get_name().'_'.$this->query_object_id_capture());
return $object_id_event;
}
/**
* Returns the event for adding new record
*
* @return Web_Event_Simple
*/
public function get_add_new_event() {
$add_new_event = new Web_Event_Simple($this->compose_add_new_event_name(),
Tangra_Form_Submit_Method::GET,
$this->form->get_name().'_add_new');
return $add_new_event;
}
/**
* Loads object from the DB, transfers data to form, prepares for show
*
* @param integer $object_id - ID of the object
* @throws Tangra_Exception
* @return boolean Returns true if record is loaded, false if not found
*/
public function process_object_id($object_id) {
$dbc = $this->get_dbc();
tangra_if_not_int_throw_e($object_id);
$object = $this->get_object();
if ($object->load_by_id($dbc, $object_id)) {
$form = $this->get_form();
$this->transfer_obj2form();
$this->prepare_for_show();
$this->export($this->form->get_name().'_obj_id', $object->get_id());
$ret = true;
} else {
$ret = false;
}
return $ret;
}
/**
* Called when receives command to show "empty" form that will be used to add new record
*
* Transfers data to form, prepares for show
*
*/
public function process_add_new() {
$this->transfer_obj2form();
$this->prepare_for_show();
$this->export($this->form->get_name().'_add_new', 1);
}
/**
* Returns string for capture of the object id
*
* @return string
*/
public function query_object_id_capture() {
return $this->object_id_capture;
}
/**
* Returns I_DB_Storable object
*
* @return I_DB_Storable
*/
public function get_object() {
return $this->object;
}
/**
* Prepares form for show
*
*/
public function prepare_for_show() {
parent::prepare_for_show();
$form_id = $this->form->get_field_value('form_id');
$this->object_to_form_id_links->register_var($form_id);
$tmp = $this->object->get_id() ?
$this->object->get_id()
: 0;
$this->object_to_form_id_links->set_var($form_id, $tmp);
}
/**
*
* @return DB_Connection
*/
public function get_dbc() {
return $this->dbc;
}
/**
* Transfers data from form to object. Saves the object into DB
*
*/
public function on_process_submit() {
$object = $this->get_object();
$object_id = $object->get_id();
if ($object_id) {
$dbc = $this->get_dbc();
if (!$object->load_by_id($dbc,$object_id)) {
throw new TE_Gform_Ctrl_WO_Record_Not_Exists('Record with that id no longer exists.');
}
}
$this->transfer_form2obj();
$this->save_object();
$this->after_save();
}
/**
* Save the object into DB
*
* Please note that saving is in DB transaction.
*
*/
protected function save_object() {
$dbc = $this->get_dbc();
$object = $this->get_object();
$dbc->start_trans();
try {
$this->on_trans_started($dbc);
$this->_save_object($dbc, $object);
$this->on_trans_ending($dbc);
} catch (Exception $e) {
$dbc->fail_trans();
$dbc->complete_trans();
throw $e;
}
$dbc->complete_trans();
}
/**
* Actual save is called here.
*
* You can overload this method in order to provide additional parameters to save(), e.g. user id.
*
* @param DB_Connection $dbc
*/
protected function _save_object(DB_Connection $dbc, I_DB_Storable $object) {
$object->save($dbc);
}
/**
* This method will be called just before saving the object and after db transaction is stared
*
* Feel free to overload this method if you need some processing just before save. For example: inserting other records and getting their ids that are needed for current object.
*
* @param DB_Connection $dbc
*/
protected function on_trans_started(DB_Connection $dbc) {
}
/**
* This method will be called just after saving the object and before db transaction end
*
* Feel free to overload this method if you need some postprocessing just after save. For example: creating additional records that depends on result of object saving (its id)
*
* @param DB_Connection $dbc
*/
protected function on_trans_ending(DB_Connection $dbc) {
}
/**
* Initializes array that will hold object to form_id links
*
*/
protected function init_object_to_form_id_links() {
$vm = $this->get_vm();
if (!$vm->is_var_registered($this->get_system_name().'_object_to_form_id_links')) {
$vm->register_var($this->get_system_name().'_object_to_form_id_links');
$vm->set_var($this->get_system_name().'_object_to_form_id_links', new Vars_Manager());
}
$this->object_to_form_id_links = &$vm->get_var($this->get_system_name().'_object_to_form_id_links');
}
/**
* @see GForm_Ctrl::on_accepted_submit()
*
* @throws Tangra_Exception
*/
protected function on_accepted_submit() {
$form_id = $this->form->get_field_value('form_id');
if ($this->object_to_form_id_links->is_var_registered($form_id)) {
$this->object->set_id($this->object_to_form_id_links->get_var($form_id));
} else {
throw new Tangra_Exception('form_id not found in object_to_form_id_links.');
}
}
/**
* Ensures that create_object() returns object that is instance of I_DB_Storable
*
* @throws Tangra_Exception
*/
private function _create_object() {
$object = $this->create_object();
if ($object instanceof I_DB_Storable) {
$this->object = $object;
} else {
throw new Tangra_Exception('$object is not instance of I_DB_Storable.');
}
}
/**
* Creates and returns I_DB_Storable object.
*
* This method have to be implemented by the user. At the end I_DB_Storable object have to be returned.
*
*/
abstract protected function create_object();
/**
* Transfers date from object to form
*
* User have to implement this method and to transfer each field from object to form
*
* Example:
* <code>
* $object = $this->get_object();
* $form = $this->get_form();
*
* $form->set_field_value('name', $object->get_name());
* </code>
*
*/
abstract protected function transfer_obj2form();
/**
* Transfers data from object to form
*
* User have to implement this method and to transfer each field from form to object
* Example:
* <code>
* $object = $this->get_object();
* $form = $this->get_form();
*
* $object->set_name($form->get_field_value('name'));
* </code>
*
*/
abstract protected function transfer_form2obj();
/**
* Called right after object is saved.
*
* Useful for some post processing. For example: notifying other controllers, etc.
*
*/
protected function after_save() {
}
/**
* Composes name for receiving object id event
*
* @return string
*/
public function compose_object_id_event_name() {
return $this->form->get_name().'_object_id';
}
/**
* Composes name for add new event
*
* @return string
*/
public function compose_add_new_event_name() {
return $this->form->get_name().'_add_new';
}
protected function on_bad_submit() {
$object = $this->get_object();
if ($object->get_id()) {
$this->export($this->form->get_name().'_obj_id', $object->get_id());
} else {
$this->export($this->form->get_name().'_add_new', 1);
}
}
}

Source for file gform_ctrl_with_obj.class.php