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/Scaffold/TScaffoldSearch.php | 75 +++++++++++++++++++---
 1 file changed, 67 insertions(+), 8 deletions(-)

(limited to 'framework/Data/ActiveRecord/Scaffold/TScaffoldSearch.php')

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();
-- 
cgit v1.2.3