From dc459efbdb141a8a4483fa23b451ba37a4ebc5ff Mon Sep 17 00:00:00 2001
From: Ingo Schommer <ingo@silverstripe.com>
Date: Tue, 15 Sep 2009 21:18:21 +0000
Subject: [PATCH] ENHANCEMENT Added SearchContext->getFullName() to preserve
 the original fieldname including the relationship MINOR Documentation in
 SearchContext and SearchFilter

git-svn-id: svn://svn.silverstripe.com/silverstripe/open/modules/sapphire/trunk@86402 467b73ca-7a2a-4603-9d3b-597d59a354a9
---
 search/SearchContext.php        | 20 ++++++++---
 search/filters/SearchFilter.php | 60 +++++++++++++++++++++++++++------
 2 files changed, 66 insertions(+), 14 deletions(-)

diff --git a/search/SearchContext.php b/search/SearchContext.php
index a38af0a4b..2506ec2b4 100644
--- a/search/SearchContext.php
+++ b/search/SearchContext.php
@@ -11,6 +11,14 @@
 * 
 * In case you need multiple contexts, consider namespacing your request parameters
 * by using {@link FieldSet->namespace()} on the $fields constructor parameter.
+* 
+* Each DataObject subclass can have multiple search contexts for different cases,
+* e.g. for a limited frontend search and a fully featured backend search.
+* By default, you can use {@link DataObject->getDefaultSearchContext()} which is automatically
+* scaffolded. It uses {@link DataObject::$searchable_fields} to determine which fields
+* to include.
+* 
+* @see http://doc.silverstripe.com/doku.php?id=searchcontext
 *
 * @package sapphire
 * @subpackage search
@@ -96,8 +104,12 @@ class SearchContext extends Object {
 	 * Returns a SQL object representing the search context for the given
 	 * list of query parameters.
 	 *
-	 * @param array $searchParams
-	 * @param string|array $sort Database column to sort on. Falls back to {@link DataObject::$default_sort} if not provided.
+	 * @param array $searchParams Map of search criteria, mostly taked from $_REQUEST.
+	 *  If a filter is applied to a relationship in dot notation,
+	 *  the parameter name should have the dots replaced with double underscores,
+	 *  for example "Comments__Name" instead of the filter name "Comments.Name".
+	 * @param string|array $sort Database column to sort on. 
+	 *  Falls back to {@link DataObject::$default_sort} if not provided.
 	 * @param string|array $limit 
 	 * @param SQLQuery $existingQuery
 	 * @return SQLQuery
@@ -124,7 +136,7 @@ class SearchContext extends Object {
 		} else {
 			$searchParamArray = $searchParams;
 		}
-		
+
  		foreach($searchParamArray as $key => $value) {
 			$key = str_replace('__', '.', $key);
 			if($filter = $this->getFilter($key)) {
@@ -219,7 +231,7 @@ class SearchContext extends Object {
 	 * @param SearchFilter $filter
 	 */
 	public function addFilter($filter) {
-		$this->filters[$filter->getName()] = $filter;
+		$this->filters[$filter->getFullName()] = $filter;
 	}
 	
 	/**
diff --git a/search/filters/SearchFilter.php b/search/filters/SearchFilter.php
index 12c80259c..a4e3f909f 100644
--- a/search/filters/SearchFilter.php
+++ b/search/filters/SearchFilter.php
@@ -1,24 +1,53 @@
 <?php
 /**
- * @package sapphire
- * @subpackage search
- */
-
-/**
- * @todo documentation
+ * Base class for filtering implementations,
+ * which work together with {@link SearchContext}
+ * to create or amend a query for {@link DataObject} instances.
+ * See {@link SearchContext} for more information.
  *
  * @package sapphire
  * @subpackage search
  */
 abstract class SearchFilter extends Object {
 	
+	/**
+	 * @var string Classname of the inspected {@link DataObject}
+	 */
 	protected $model;
+	
+	/**
+	 * @var string
+	 */
 	protected $name;
+	
+	/**
+	 * @var string 
+	 */
+	protected $fullName;
+	
+	/**
+	 * @var mixed
+	 */
 	protected $value;
+	
+	/**
+	 * @var string Name of a has-one, has-many or many-many relation (not the classname).
+	 * Set in the constructor as part of the name in dot-notation, and used in 
+	 * {@link applyRelation()}.
+	 */
 	protected $relation;
 	
-	function __construct($name, $value = false) {
-		$this->addRelation($name);
+	/**
+	 * @param string $fullName Determines the name of the field, as well as the searched database 
+	 *  column. Can contain a relation name in dot notation, which will automatically join
+	 *  the necessary tables (e.g. "Comments.Name" to join the "Comments" has-many relationship and
+	 *  search the "Name" column when applying this filter to a SiteTree class).
+	 * @param mixed $value
+	 */
+	function __construct($fullName, $value = false) {
+		$this->fullName = $fullName;
+		// sets $this->name and $this->relation
+		$this->addRelation($fullName);
 		$this->value = $value;
 	}
 	
@@ -26,7 +55,7 @@ abstract class SearchFilter extends Object {
 	 * Called by constructor to convert a string pathname into
 	 * a well defined relationship sequence.
 	 *
-	 * @param unknown_type $name
+	 * @param string $name
 	 */
 	protected function addRelation($name) {
 		if (strstr($name, '.')) {
@@ -76,6 +105,16 @@ abstract class SearchFilter extends Object {
 		return $this->name;
 	}
 	
+	/**
+	 * The full name passed to the constructor,
+	 * including any (optional) relations in dot notation.
+	 * 
+	 * @return string
+	 */
+	public function getFullName() {
+		return $this->fullName;
+	}
+	
 	/**
 	 * Normalizes the field name to table mapping.
 	 * 
@@ -113,7 +152,8 @@ abstract class SearchFilter extends Object {
 	
 	/**
 	 * Traverse the relationship fields, and add the table
-	 * mappings to the query object state.
+	 * mappings to the query object state. This has to be called
+	 * in any overloaded {@link SearchFilter->apply()} methods manually.
 	 * 
 	 * @todo try to make this implicitly triggered so it doesn't have to be manually called in child filters
 	 * @param SQLQuery $query