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
The source code is also available:
* from the code browser
* from the SVN repository
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.
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
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 