From 4c86659bc90d9134b0f901572c5417aa7d9cec18 Mon Sep 17 00:00:00 2001 From: wei <> Date: Tue, 27 Feb 2007 23:27:14 +0000 Subject: Add comments for scaffold, minor changes to TActiveRecord --- .../Data/ActiveRecord/Exceptions/messages.txt | 3 +- .../ActiveRecord/Scaffold/TScaffoldListView.php | 21 +++++- .../Data/ActiveRecord/Scaffold/TScaffoldSearch.php | 75 +++++++++++++++++++--- .../Data/ActiveRecord/Scaffold/TScaffoldView.php | 62 ++++++++++++++++++ framework/Data/ActiveRecord/TActiveRecord.php | 5 +- .../Data/ActiveRecord/TActiveRecordCriteria.php | 27 ++++++-- .../Data/ActiveRecord/TActiveRecordGateway.php | 11 ++-- 7 files changed, 181 insertions(+), 23 deletions(-) (limited to 'framework/Data/ActiveRecord') diff --git a/framework/Data/ActiveRecord/Exceptions/messages.txt b/framework/Data/ActiveRecord/Exceptions/messages.txt index 2af62bb5..1d7d6e7d 100644 --- a/framework/Data/ActiveRecord/Exceptions/messages.txt +++ b/framework/Data/ActiveRecord/Exceptions/messages.txt @@ -14,4 +14,5 @@ ar_value_must_not_be_null = Property '{0}::${2}' must not be null as defined ar_missing_pk_values = Missing primary key values in forming IN(key1, key2, ...) for table '{0}'. ar_pk_value_count_mismatch = Composite key value count mismatch in forming IN( (key1, key2, ..), (key3, key4, ..)) for table '{0}'. ar_must_copy_from_array_or_object = $data in {0}::copyFrom($data) must be an object or an array. -ar_mismatch_column_names = In dynamic __call() method '{0}', no matching columns were found, valid columns for table '{2}' are '{1}'. \ No newline at end of file +ar_mismatch_column_names = In dynamic __call() method '{0}', no matching columns were found, valid columns for table '{2}' are '{1}'. +ar_invalid_table = Missing, invalid or no permission for table/view '{0}'. \ No newline at end of file diff --git a/framework/Data/ActiveRecord/Scaffold/TScaffoldListView.php b/framework/Data/ActiveRecord/Scaffold/TScaffoldListView.php index 62bf351b..6cb490e3 100644 --- a/framework/Data/ActiveRecord/Scaffold/TScaffoldListView.php +++ b/framework/Data/ActiveRecord/Scaffold/TScaffoldListView.php @@ -21,10 +21,27 @@ Prado::using('System.Data.ActiveRecord.Scaffold.TScaffoldBase'); * The {@link getHeader Header} property is a TRepeater displaying the * Active Record property/field names. The {@link getSort Sort} property * is a drop down list displaying the combination of properties and its possible - * ordering. The {@link getPager Pager} property is a TPager control that - * determines the number of records display in one page (e.g. Page.. + * ordering. The {@link getPager Pager} property is a TPager control displaying + * the links and/or buttons that navigate to different pages in the Active Record data. + * The {@link getList List} property is a TRepeater that renders a row of + * Active Record data. * + * Custom rendering of the each Active Record can be achieved by specifying + * the ItemTemplate or AlternatingItemTemplate property of the main {@linnk getList List} + * repeater. * + * The TScaffoldListView will listen for two command events named "delete" and + * "edit". A "delete" command will delete a the record for the row where the + * "delete" command is originates. An "edit" command will push + * the record data to be edited by a TScaffoldEditView with ID specified by the + * {@link setEditViewID EditViewID}. + * + * Additional {@link setSearchCondition SearchCondition} and + * {@link setSearchParameters SearchParameters} (takes array values) can be + * specified to customize the records to be shown. The {@link setSearchCondition SearchCondition} + * will be used as the Condition property of TActiveRecordCriteria, and similarly + * the {@link setSearchParameters SearchParameters} will be the corresponding + * Parameters property of TActiveRecordCriteria. * * @author Wei Zhuo * @version $Id$ diff --git a/framework/Data/ActiveRecord/Scaffold/TScaffoldSearch.php b/framework/Data/ActiveRecord/Scaffold/TScaffoldSearch.php index a47a1a47..fdfddd4f 100644 --- a/framework/Data/ActiveRecord/Scaffold/TScaffoldSearch.php +++ b/framework/Data/ActiveRecord/Scaffold/TScaffoldSearch.php @@ -1,12 +1,49 @@ - + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005 PradoSoft + * @license http://www.pradosoft.com/license/ + * @version $Id$ + * @package System.Data.ActiveRecord.Scaffold + */ +/** + * Import the scaffold base. + */ Prado::using('System.Data.ActiveRecord.Scaffold.TScaffoldBase'); +/** + * TScaffoldSearch provide a simple textbox and a button that is used + * to perform search on a TScaffoldListView with ID given by {@link setListViewID ListViewID}. + * + * The {@link getSearchText SearchText} property is a TTextBox and the + * {@link getSearchButton SearchButton} property is a TButton with label value "Search". + * + * Searchable fields of the Active Record can be restricted by specifying + * a comma delimited string of allowable fields in the + * {@link setSearchableFields SearchableFields} property. The default is null, + * meaning that most text type fields are searched (the default searchable fields + * are database dependent). + * + * @author Wei Zhuo + * @version $Id$ + * @package System.Data.ActiveRecord.Scaffold + * @since 3.1 + */ class TScaffoldSearch extends TScaffoldBase { + /** + * @var TScaffoldListView the scaffold list view. + */ private $_list; - public function getListView() + /** + * @return TScaffoldListView the scaffold list view this search box belongs to. + */ + protected function getListView() { if($this->_list===null && ($id = $this->getListViewID()) !== null) { @@ -17,21 +54,26 @@ class TScaffoldSearch extends TScaffoldBase return $this->_list; } - public function setListView($value) - { - $this->_list = $value; - } - + /** + * @param string ID of the TScaffoldListView this search control belongs to. + */ public function setListViewID($value) { $this->setViewState('ListViewID', $value); } + /** + * @return string ID of the TScaffoldListView this search control belongs to. + */ public function getListViewID() { return $this->getViewState('ListViewID'); } + /** + * Sets the SearchCondition of the TScaffoldListView as the search terms + * given by the text of the search text box. + */ public function bubbleEvent($sender, $param) { if(strtolower($param->getCommandName())==='search') @@ -39,7 +81,6 @@ class TScaffoldSearch extends TScaffoldBase if(($list = $this->getListView()) !== null) { $list->setSearchCondition($this->createSearchCondition()); - $list->setSearchParameters(array()); return false; } } @@ -47,6 +88,9 @@ class TScaffoldSearch extends TScaffoldBase return true; } + /** + * @return string the search criteria for the search terms in the search text box. + */ protected function createSearchCondition() { $table = $this->getTableMetaData(); @@ -54,6 +98,9 @@ class TScaffoldSearch extends TScaffoldBase return $table->getSearchRegExpCriteria($this->getFields(), $str); } + /** + * @return array list of fields to be searched. + */ protected function getFields() { if(strlen(trim($str=$this->getSearchableFields()))>0) @@ -63,22 +110,34 @@ class TScaffoldSearch extends TScaffoldBase return $fields; } + /** + * @return string comma delimited list of fields that may be searched. + */ public function getSearchableFields() { return $this->getViewState('SearchableFields',''); } + /** + * @param string comma delimited list of fields that may be searched. + */ public function setSearchableFields($value) { $this->setViewState('SearchableFields', $value, ''); } + /** + * @return TButton button with default label "Search". + */ public function getSearchButton() { $this->ensureChildControls(); return $this->getRegisteredObject('_search'); } + /** + * @return TTextBox search text box. + */ public function getSearchText() { $this->ensureChildControls(); diff --git a/framework/Data/ActiveRecord/Scaffold/TScaffoldView.php b/framework/Data/ActiveRecord/Scaffold/TScaffoldView.php index 5401c764..c144fe37 100644 --- a/framework/Data/ActiveRecord/Scaffold/TScaffoldView.php +++ b/framework/Data/ActiveRecord/Scaffold/TScaffoldView.php @@ -1,12 +1,49 @@ + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005 PradoSoft + * @license http://www.pradosoft.com/license/ + * @version $Id$ + * @package System.Data.ActiveRecord.Scaffold + */ +/** + * Import scaffold base, list, edit and search controls. + */ Prado::using('System.Data.ActiveRecord.Scaffold.TScaffoldBase'); Prado::using('System.Data.ActiveRecord.Scaffold.TScaffoldListView'); Prado::using('System.Data.ActiveRecord.Scaffold.TScaffoldEditView'); Prado::using('System.Data.ActiveRecord.Scaffold.TScaffoldSearch'); +/** + * TScaffoldView is a composite control consisting of TScaffoldListView + * with a TScaffoldSearch. In addition, it will display a TScaffoldEditView + * when an "edit" command is raised from the TScaffoldListView (when the + * edit button is clicked). Futher more, the "add" button can be clicked + * that shows an empty data TScaffoldListView for creating new records. + * + * The {@link getListView ListView} property gives a TScaffoldListView for + * display the record data. The {@link getEditView EditView} is the + * TScaffoldEditView that renders the + * inputs for editing and adding records. The {@link getSearchControl SearchControl} + * is a TScaffoldSearch responsible to the search user interface. + * + * Set the {@link setRecordClass RecordClass} property to the name of + * the Active Record class to be displayed/edited/added. + * + * @author Wei Zhuo + * @version $Id$ + * @package System.Data.ActiveRecord.Scaffold + * @since 3.0 + */ class TScaffoldView extends TScaffoldBase { + /** + * Copy basic record details to the list/edit/search controls. + */ public function onLoad($param) { parent::onLoad($param); @@ -15,30 +52,46 @@ class TScaffoldView extends TScaffoldBase $this->getSearchControl()->copyFrom($this); } + /** + * @return TScaffoldListView scaffold list view. + */ public function getListView() { $this->ensureChildControls(); return $this->getRegisteredObject('_listView'); } + /** + * @return TScaffoldEditView scaffold edit view. + */ public function getEditView() { $this->ensureChildControls(); return $this->getRegisteredObject('_editView'); } + /** + * @return TScaffoldSearch scaffold search textbox and button. + */ public function getSearchControl() { $this->ensureChildControls(); return $this->getRegisteredObject('_search'); } + /** + * @return TButton "Add new record" button. + */ public function getAddButton() { $this->ensureChildControls(); return $this->getRegisteredObject('_newButton'); } + /** + * Handle the "edit" and "new" commands by displaying the edit view. + * Default command shows the list view. + */ public function bubbleEvent($sender,$param) { switch(strtolower($param->getCommandName())) @@ -53,6 +106,9 @@ class TScaffoldView extends TScaffoldBase return false; } + /** + * Shows the edit record view. + */ protected function showEditView($sender, $param) { $this->getListView()->setVisible(false); @@ -63,6 +119,9 @@ class TScaffoldView extends TScaffoldBase $this->getEditView()->getClearButton()->setVisible(false); } + /** + * Shows the view for listing the records. + */ protected function showListView($sender, $param) { $this->getListView()->setVisible(true); @@ -71,6 +130,9 @@ class TScaffoldView extends TScaffoldBase $this->getSearchControl()->setVisible(true); } + /** + * Shows the add record view. + */ protected function showAddView($sender, $param) { $this->getEditView()->setRecordPk(null); diff --git a/framework/Data/ActiveRecord/TActiveRecord.php b/framework/Data/ActiveRecord/TActiveRecord.php index ea33035d..7ab45a2b 100644 --- a/framework/Data/ActiveRecord/TActiveRecord.php +++ b/framework/Data/ActiveRecord/TActiveRecord.php @@ -172,7 +172,7 @@ abstract class TActiveRecord extends TComponent */ public function save() { - $this->commitChanges(); + return $this->commitChanges(); } /** @@ -524,7 +524,8 @@ abstract class TActiveRecord extends TComponent $fields = array(); foreach($matches as $match) { - $sql = $meta->getColumn($match[1])->getName() . ' = ? '; + $column = $meta->getColumn($match[1]); + $sql = $column->getName() . ' = ? '; if(count($match) > 2) $sql .= strtoupper(str_replace('_', '', $match[2])); $fields[] = $sql; diff --git a/framework/Data/ActiveRecord/TActiveRecordCriteria.php b/framework/Data/ActiveRecord/TActiveRecordCriteria.php index 6adfe4ce..533ff50a 100644 --- a/framework/Data/ActiveRecord/TActiveRecordCriteria.php +++ b/framework/Data/ActiveRecord/TActiveRecordCriteria.php @@ -149,14 +149,29 @@ class TActiveRecordCriteria extends TComponent $this->_offset=$value; } + /** + * @return string string representation of the criteria. Useful for debugging. + */ public function __toString() { - return $this->getCondition(); - } - - public function repr() - { - return var_export($this->getParameters()->toArray(),true); + $str = ''; + if(strlen((string)$this->getCondition()) > 0) + $str .= '"'.(string)$this->getCondition().'"'; + $params = array(); + foreach($this->getParameters() as $k=>$v) + $params[] = "{$k} => ${v}"; + if(count($params) > 0) + $str .= ', "'.implode(', ',$params).'"'; + $orders = array(); + foreach($this->getOrdersBy() as $k=>$v) + $orders[] = "{$k} => ${v}"; + if(count($orders) > 0) + $str .= ', "'.implode(', ',$orders).'"'; + if($this->_limit !==null) + $str .= ', '.$this->_limit; + if($this->_offset !== null) + $str .= ', '.$this->_offset; + return $str; } } diff --git a/framework/Data/ActiveRecord/TActiveRecordGateway.php b/framework/Data/ActiveRecord/TActiveRecordGateway.php index 1486e9c3..c925f3c9 100644 --- a/framework/Data/ActiveRecord/TActiveRecordGateway.php +++ b/framework/Data/ActiveRecord/TActiveRecordGateway.php @@ -126,7 +126,10 @@ class TActiveRecordGateway extends TComponent $conn = $record->getDbConnection(); $inspector = $this->getManager()->getTableInspector($conn); $table = $this->getTableName($record); - $data = $this->cacheMetaData($record,$inspector->getTableMetaData($table)); + $meta = $inspector->getTableMetaData($table); + if(count($meta->getColumns()) == 0) + throw new TActiveRecordException('ar_invalid_table', $table); + $data = $this->cacheMetaData($record,$meta); } return $data; } @@ -176,7 +179,7 @@ class TActiveRecordGateway extends TComponent $meta = $this->getMetaData($record); $command = $meta->getFindByCriteriaCommand($record->getDbConnection(),$criteria); $this->raiseCommandEvent(TActiveRecordStatementType::Select,$command,$record,$criteria); - Prado::trace(get_class($record).'::FindRecordsByCriteria('.is_string($criteria) ? $criteria : $criteria->repr().')', 'System.Data.ActiveRecord'); + Prado::trace(get_class($record).'::FindRecordsByCriteria('.((string)$criteria).')', 'System.Data.ActiveRecord'); return $iterator ? $meta->postQuery($command->query()) : $meta->postQueryRow($command->queryRow()); } @@ -207,7 +210,7 @@ class TActiveRecordGateway extends TComponent $meta = $this->getMetaData($record); $command = $meta->getCountRecordsCommand($record->getDbConnection(),$criteria); $this->raiseCommandEvent(TActiveRecordStatementType::Select,$command,$record,$criteria); - Prado::trace(get_class($record).'::CountRecords('.is_string($criteria) ? $criteria : $criteria->repr().')', 'System.Data.ActiveRecord'); + Prado::trace(get_class($record).'::CountRecords('.((string)$criteria).')', 'System.Data.ActiveRecord'); return intval($command->queryScalar()); } @@ -281,7 +284,7 @@ class TActiveRecordGateway extends TComponent $meta = $this->getMetaData($record); $command = $meta->getDeleteByCriteriaCommand($record->getDBConnection(),$criteria); $this->raiseCommandEvent(TActiveRecordStatementType::Delete,$command,$record,$criteria); - Prado::trace(get_class($record).'::DeleteRecordsByCriteria('.is_string($criteria) ? $criteria : $criteria->repr().')', 'System.Data.ActiveRecord'); + Prado::trace(get_class($record).'::DeleteRecordsByCriteria('.((string)$criteria).')', 'System.Data.ActiveRecord'); return $command->execute(); } -- cgit v1.2.3