# sfPropelActAsRatableBehaviorPlugin

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

![rating_capture.png](http://trac.symfony-project.org/attachment/wiki/sfPropelActAsRatableBehaviorPlugin/rating_capture.png?format=raw)

## Installation

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

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

The source code is also available:
  * [from the code browser](source:plugins/sfPropelActAsRatableBehaviorPlugin)
  * [from the SVN repository](http://svn.symfony-project.com/plugins/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. Eg. 
for an `Article` Propel model class:

    
    <?php
    class Article extends BaseArticle
    {
    }
    sfPropelBehavior::add('Article', array('sfPropelActAsRatableBehavior'));
    

### Behavior optional parameters

You can add this optionals parameters when applying the bahavior:

  * `max_rating`: sets the maximum rating available for an object (this must 
   be an integer greater than 0 - default is 5)
  * `reference_field`: sets the name of the field which will reference the 
   object (by default it is **automatically set to its primary key field**, so 
   leave this if you're unsure). A reference field can be: 
   * a column name, eg. `ArticlePeer::STRIPPED_TITLE` 
   * a field name, eg. `'StrippedTitle'`
   * a Propel phpName, eg. `'stripped_title'` 

Example of use of these parameters:

    
    <?php
    class Article extends BaseArticle
    {
    }
    sfPropelBehavior::add('Article', 
                          array('sfPropelActAsRatableBehavior',
                                array('max_rating'      => 10,
                                      'reference_field' => ArticlePeer::STRIPPED_TITLE)));
    

Then, rebuild your model :

    
    symfony propel-build-all
    

And clear the cache :

    
    symfony cc
    

## Using the Ajax rating system

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

![rating_capture.png](http://trac.symfony-project.org/attachment/wiki/sfPropelActAsRatableBehaviorPlugin/rating_capture.png?format=raw)

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:        [sfRating](default,)
    

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']) ?>
    

## 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 (`$unique_user_reference` is a string representing a 
unique reference to a user - eg. `md5($_SERVER['REMOTE_ADDR'])` or 
`md5($user->getEmail())`) :

    
    $article->setRating(10, $unique_user_reference);
    

To retrieve user rating for this object :

    
    $article->getUserRating($unique_user_reference);
    

To get the average rating of the object :

    
    $article->getRating();
    

To retrieve the maximum possible rating for an object (which you have defined in
the `max_rating` behavior optional parameter - default is 5) :

    
    $article->getMaxRating();
    

To clear user rating :

    
    $article->clearRating($unique_user_reference);
    

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($unique_user_reference);
    

## 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/unit/sfPropelActAsRatableBehaviorTest.php
    

Note that you have to provide a Propel test object class name to run the test in the test file:

    
    define('TEST_CLASS', 'Article');
    

## TODO

  * Manage messages i18n
  * Add functional tests
  * ~~Add a component to provide a rating interface, AJAX based~~ added in v0.6.0
 
## Changelog

  * 2006-09-12 | v0.6.2
   * Reference keys are now stored as a md5 hash
   * Corrected custom reference keys handling bug in Ajax rater widget
   * Added a `isRatable` static method in behavior class
   * Some bugs corrected
  * 2006-09-09 | v0.6.1
   * Added a way to specify a custom reference field to identify a ratable 
     Propel object
   * Added ability to set the maximum rating for an object when the behavior is
     added
   * Key length as also been decreased to avoid a strange MySQL bug on KEY length
   * Added unit tests
  * 2006-09-07 | v0.6.0
   * Added an AJAX rating system as a helper
   * Added constant MAX_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
  * 2006-09-05 | v0.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