= sfPropelActAsRatableBehaviorPlugin =

This plugin aims at providing rating capabilities to any Propel object with the 
help of a dedicated Propel behavior.

== Installation ==

To install the plugin, run this command within your symfony project :

{{{
symfony plugin-install http://plugins.symfony-project.com/sfPropelActAsRatableBehaviorPlugin
}}}

To activate this Propel behavior in Symfony, you must first activate behaviors 
in your propel.ini file :

{{{
propel.builder.addBehaviors = true
}}}

In one (or more) of your existing model object classes, apply the behavior and 
add a {{{MIN_RATING}}} and a {{{MAX_RATING}}} class constant, eg. in an 
{{{Article}}} propel object for example:

{{{
<?php
class Article extends BaseArticle
{
  const 
    MIN_RATING = 1, // Minimum rating for an Article
    MAX_RATING = 5; // Maximum rating for an Article
}
sfPropelBehavior::add('Article', array('sfPropelActAsRatableBehavior'));
}}}

Note: The {{{MIN_RATING}}} and {{{MAX_RATING}}} int constant have been added in v0.6.0 to add security 
and consistency checking.

Then, rebuild your model :

{{{
symfony propel-build-all
}}}

And clear the cache :

{{{
symfony cc
}}}

== API Usage ==

You can rate your previously configured {{{Article}}} objects through the 
new API which as been dynamically added to your object by the behavior.

Note that you can provide a user PK to determine if one of your user has already 
rated the object. Here we imagine a {{{User}}} object instance {{{$user}}} which represent a 
member, an author, a person or anything like this.

To set a rating for a given user :

{{{
$article->setRating(10, $user->getId());
}}}

To retrieve user rating for this object :

{{{
$article->getUserRating($user->getId());
}}}

To get the average rating of the object :

{{{
$article->getRating();
}}}

To retrieve the minimum possible rating for an object (which you have defined in
the MIN_RATING class constant) :

{{{
$article->getMinRating();
}}}

To retrieve the maximum possible rating for an object (which you have defined in
the MAX_RATING class constant) :

{{{
$article->getMaxRating();
}}}

To clear user rating :

{{{
$article->clearRating($user->getId());
}}}

To clear all ratings for the object :

{{{
$article->clearRatings();
}}}

You can test if the object has already been rated :

{{{
$article->hasBeenRated();
}}}

You can also test if the object has already been rated by a particular user:

{{{
$article->hasBeenRatedByUser($user->getId());
}}}

== Using the Ajax rating system ==

This plugin provides an Ajax-based rating system, with pretty stars to click on.

Screenshot:

To activate this feature, you must enable the {{{sfRating}}} module in the 
{{{config/settings.yml}}} file of the app you want to use the helper in :

{{{
all:
  .settings:
    enabled_modules:        [default, '''sfRating''']
}}}

If you are under Microsoft Windows, you also have to manually copy the {{{./web}}} 
directory of the plugin in the {{{%SF_ROOT_DIR%/web}}} directory of your project
and rename it to {{{sfPropelActAsRatableBehaviorPlugin}}}. Then you will have 
this on the filesytem :

{{{
project_root
  [...]
  web
    sfPropelActAsRatableBehaviorPlugin
      css
        sf_rating.css
      images
        alt_star.gif
}}}

Then, you can use the {{{sf_rater}}} helper in any of your template:

{{{
<?php use_helper('sfRating') ?>
<?php echo sf_rater($article, md5($user->getId()) ?>
}}}

... where {{{$article}}} is of course an instance of your {{{Article}}} propel 
class and {{{$user->getId()}}} is an optional unique reference to the user 
currently rating your object.

The unique user reference can be an IP address:

{{{
<?php use_helper('sfRating') ?>
<?php echo sf_rater($article, md5($_SERVER['REMOTE_ADDR']) ?>
}}}

== Unit testing ==

The plugin is provided with a test suite located in the {{{./test}}} directory. 
To run the tests, type this line from the root of your project :

{{{
$ php plugins/sfPropelActAsRatableBehaviorPlugin/test/sfPropelActAsRatableBehaviorTest.php
}}}

Note that you have to provide a Propel test object class name to run the test. 
You can specify the name of the Propel object with the behavior attached to use 
for the tests creating a new file in your project located in 
{{{%SF_ROOT_DIR%/config/tests/sfPropelActAsRatableBehaviorPlugin.yml}}} :

{{{
all:
  behavior:
    object:  Article # Here the class name of your ratable propel object
}}}

== TODO ==

 * Manage messages i18n
 * --Add a component to provide a rating interface, AJAX based-- added in v0.6.0
 
== Changelog ==

 * '''v0.6.0'''
   * Added an AJAX rating system as a helper (a component is also available)
   * Added constant MAX_RATING and MIN_RATING management for consistency control 
     in ratable model class
   * Moved int fields to varchar for storing unique user reference descriptor
     (eg. storing the IP address, an email, a md5 hash, etc.)
   * {{{sfRatings}}} table has been renamed to {{{sf_ratings}}}: you have to 
     rebuild your SQL files and insert them in your DB if you upgrade from 
     0.5.0. Hopefully, one day we'll have a migration system in Symfony core...
   * Removed configuration file to set up Propel object to unit test in the test
     suite
 * '''vO.5.0'''
   * Initial release
   
== Credits ==

 * The eye-candy star-based Ajax system is based on the great work of 
 Komodomedia:
 http://komodomedia.com/blog/samples/star_rating/example2.htm