Add comments for scaffold, minor changes to TActiveRecord

7 files changed, 181 insertions, 23 deletions

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 <weizho[at]gmail[dot]com>

  * @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 @@
-<?php
+<?php

+/**

+ * TScaffoldSearch class file.

+ *

+ * @author Wei Zhuo <weizhuo[at]gmail[dot]com>

+ * @link http://www.pradosoft.com/

+ * @copyright Copyright &copy; 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 <weizhuo[at]gmail[dot]com>

+ * @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 @@
 <?php

+/**

+ * TScaffoldView class.

+ *

+ * @author Wei Zhuo <weizhuo[at]gmail[dot]com>

+ * @link http://www.pradosoft.com/

+ * @copyright Copyright &copy; 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 <weizhuo[at]gmail[dot]com>

+ * @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();

 	}