This plugin is deprecated and is not maintained anymore.
I don't use Propel anymore. Feel free to request if you want to take over the plugin development.
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: [**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']) ?>
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
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
Nicolas Perriault 