markdown documentation

README.mdown

@@ -0,0 +1,137 @@
+Copyright 2009 - 2010, Cake Development Corporation
+                        1785 E. Sahara Avenue, Suite 490-423
+                        Las Vegas, Nevada 89104
+                        http://cakedc.com
+
+The search plugin will allow you to make any kind of data searchable, i.e. allow you to implement robust searching rapidily.
+
+== Search plugin ==
+
+Search plugin is an easy way to include search into your application. 
+Using this plugin you will able to have paginable search in any controller.
+Plugin support simple methods to search inside models using strict and non-strict comparing, but also allows you to implement any complex type of searching.
+
+### Sample of usage ### 
+
+ Example of how to implement complex search in your application.
+
+
+	class Article extends AppModel {
+
+		public $actsAs = array('Search.Searchable');
+
+		public $hasAndBelongsToMany = array('Tag' => array('with' => 'Tagged'));
+
+		public $filterArgs = array(
+			array('name' => 'title', 'type' => 'like'),
+			array('name' => 'status', 'type' => 'value'),
+			array('name' => 'blog_id', 'type' => 'value'),
+			array('name' => 'search', 'type' => 'like', 'field' => 'Article.description'),
+			array('name' => 'range', 'type' => 'expression', 'method' => 'makeRangeCondition', 'field' => 'Article.views BETWEEN ? AND ?'),
+			array('name' => 'tags', 'type' => 'subquery', 'method' => 'findByTags', 'field' => 'Article.id'),
+		);
+
+		public function findByTags($data = array()) {
+			$this->Tagged->Behaviors->attach('Containable', array('autoFields' => false));
+			$this->Tagged->Behaviors->attach('Search.Searchable');
+			$query = $this->Tagged->getQuery('all', array(
+				'conditions' => array('Tag.name'  => $data['tags']),
+				'fields' => array('foreign_key'),
+				'contain' => array('Tag')
+			));
+			return $query;
+		}
+
+	}
+
+
+
+Applicable snippet of controller class
+
+
+	class ArticlesController extends AppController {
+
+		public $components = array('Search.Prg');
+		
+		public $presetVars = array(
+			array('field' => 'title', 'type' => 'value'),
+			array('field' => 'status', 'type' => 'checkbox'),
+			array('field' => 'blog_id', 'type' => 'lookup', 'formField' => 'blog_input', 'modelField' => 'title', 'model' => 'Blog'));
+
+		public function find() {
+			$this->Prg->commonProcess();
+			$this->paginate['conditions'] = $this->Article->parseCriteria($this->passedArgs);
+			$this->set('articles', $this->paginate());
+		}
+	}
+
+
+The find.ctp view is same as index.ctp with the addition of the search form:
+
+
+	<?php
+		echo $form->create('Article', array(
+			'url' => array_merge(array('action' => 'find'), $this->params['pass'])
+			));
+		echo $form->input('title', array('div' => false));
+		echo $form->input('blog_id', array('div' => false, 'options' => $blogs));
+		echo $form->input('status', array('div' => false, 'multiple' => 'checkbox', 'options' => array('open', 'closed')));
+		echo $form->submit(__('Search', true), array('div' => false));
+		echo $form->end();
+	?>
+
+
+### Behavior and Model configuration ### 
+
+ All search fields need to be configured in the Model::filterArgs array. 
+
+ Each filter record should contain array with several keys:
+  * name - the parameter stored in Model::data. In the example above the 'search' name used to search in the Article.description field.
+  * type - one of supported search types described below.
+  * field - Real field name used for seach should be used. 
+  * method - model method name or behavior used to generate expression, subquery or query.
+
+#### Supported types of search ####
+
+  * 'like' or 'string'. This type of search used when you need to search using 'LIKE' sql keyword.
+  * 'value' or 'int'. This type of search very usefull when you need exact compare. So if you have select box in your view as a filter than you definetely should  use value type.
+  * 'expression' type usefull if you want to add condition that will generate by some method, and condition field contain several parameter like in previos sample used for 'range'. Field here contains 'Article.views BETWEEN ? AND ?' and Article::makeRangeCondition returns array of two values.
+  * 'subquery' type usefull if you want to add condition that looks like FIELD IN (SUBQUERY), where SUBQUERY generated by method declared in this filter configuration.
+  * 'query' most universal type of search. In this case method should return array(that contain condition of any compexity). Returned condition will joined to whole search conditions.
+
+### Post, redirect, get conception ### 
+
+	Post/Redirect/Get (PRG) is a common design pattern for web developers to help avoid certain duplicate form  submissions and allow user agents to behave more intuitively with bookmarks and the refresh button.
+	When a web form is submitted to a server through an HTTP POST request, a web user that attempts to refresh the server response in certain user agents can cause the contents of the original HTTP POST request to be resubmitted, possibly causing undesired results. To avoid this problem possible to use the PRG pattern instead of returning a web page directly, the POST operation returns a redirection command, instructing the browser to load a different page (or same page) using an HTTP GET request. See [http://en.wikipedia.org/wiki/Post/Redirect/Get].
+
+### PRG Component features ### 
+
+The Prg component implement PRG pattern. So you able to use it separately from search tasks when you need it.
+The component maintains passed and named parameters that come as POST parameters and transform it to the named during redirect, and set Controller::data back if used GET method during component call. 
+Most importantly the component acts as the glue between your app and searchable behavior.
+
+#### Controller configuration ####
+
+ All search fields parameters need to configure in the Controller::presetVars array. 
+Each preset variable is a array record that contains next keys:
+
+  * field - field that defined in the view search form.
+  * type - one of search types: 
+	* value - should used for value that does not require any processing, 
+	* checkbox - used for checkbox fields in view (prg component pack and unpack checkbox values when pass it through the get named action).
+	* lookup - this type used when you have autocomplete lookup field implemented in your view. This lookup field is a text field, and also you have hidden field id value. In this case component will fill both text and id values.  
+  * model - param that specifies what model used in Controller::data at a key for this field.
+  * formField - field in the form that contain text, and will populated using model.modelField based on field value.
+  * modelField - field in the model that contain text, and will used to fill formField in view.
+
+#### Prg::commonProcess method usage ####
+
+ commonProcess method defined in Prg component allow you to inject search in any index controller with just 1-2 lines of additional code.
+ You should pass model name that used for search. By default it is default Controller::modelClass model.
+ Aditonal options parameters.
+ * form - search form name.
+ * keepPassed - parameter that describe if you need to ' => true,
+ * action - some times you want to have diferent actions for post and get. In this case you can define get action using this parameter.
+ * modelMethod - method, used to filter named parameters, passed from form. By default it is validateSearch, and it defined in Searchable behavior.
+
+