sfPropelActAsRatableBehaviorPlugin - 0.6.0

Propel ratable behavior

You are currently browsing
the website for symfony 1

Visit the Symfony2 website


« Back to the Plugins Home

Signin


Forgot your password?
Create an account

Tools

Stats

advanced search
Information Readme Releases Changelog Contribute
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.
Show source | Show as Markdown

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
    • 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