EvReview Plugin
===============

Authors: Andy Carter


Introduction
------------

Plugin that enables reviews for models.

Installation
------------

This is a composer plugin so from www/app just run composer as:-

	composer require evoluted/review

To setup the database use the CakeDC Migrations plugin. To run the migrations and setup the database run:-

	Console/cake Migrations.migration run all --plugin EvReview

Add the following to the plugin load array in 'app/Config/bootstrap.php':-

	'EvReview' => array(
		'bootstrap' => true,
		'routes' => true
	)

You will want to add an item to the admin menu for managing reviews:-

* /admin/ev_review/reviews/

To setup/override the plugin's default config create a new config file 'app/Config/Plugin/ev_review.php'. The following options are available:-

* review_relation - use to define the belongsTo relationships for the Review model (see app/Config/config_example.php for an example).


Using EvReview
--------------

EvReview needs a small amount of setup to get working, but should be relatively simple.

For each model that you want reviews add the Reviewable behaviour:-

	$this->Behaviors->load('EvReview.Reviewable');

This will handle the hasMany relationship and add some additional useful methods for retrieving reviews.

Review Form
~~~~~~~~~~~

EvReview comes with a View template for including a review submission form in a template. Just add it to your template:-

	echo $this->Element('EvReview./reviews_form');

Then in your controller load in the EvReview.Reviews component and call the processForm method from within your action:-

	$this->Reviews->processForm($id);

$id is the primary key of the model item you want to associate the review with. The component will then handle the form submission for you and ensure that the review is associated with the correct model item.

After a review is submitted it will be flagged as hidden (is_active=false) and a notification email will be sent out so that a site administrator is notified of the new review and can enable the review on the site.

Retrieving Reviews
~~~~~~~~~~~~~~~~~~

Return all reviews for a model item (uses the Reviewable behaviour):-

	$Model->reviews($id);

You can pass an optional array of find parameters as the second parameter of reviews to fine tune the returned data.

Return paginated reviews for a model item (uses the Reviews component):-

	$this->Reviews->paginate($id);

Average Ratings
~~~~~~~~~~~~~~~

Every time a review is created/updated the average rating for the related model item is updated and stored in the ev_review_rating_averages table. The Reviewable behaviour will automatically associate this table with your model so you just need to contain 'RatingAverage' when retrieving the model item to access it's average rating. For example, in your model:-

	public function readForView($id, $query = []) {
	
		$query['contain'][] = 'RatingAverage';
	
		return parent::readForView($id, $query);
	
	}

Average ratings only take into account active reviews.


Extending Plugin
----------------

The usual rules apply, don't edit the plugin directly but override it from within your own app. For example, you can override the view templates by creating new views in '/app/View/Plugin/EvReview/'.