|
|
sfPropelActAsRatableBehaviorPlugin - 0.7.2Propel ratable behavior |
|
 |
22
users
Sign-in
to change your status |
This Symfony plugin allow rating capacity to a Propel object through a Propel behavior. |
This plugin aims at providing rating capabilities to any Propel object with the help of a dedicated Propel behavior.
| Name | Status | |
|---|---|---|
Nicolas Perriault |
lead | moc.liamg <<ta>> tluairrepn |
Copyright (c) 2007 Nicolas Perriault
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
| Version | License | API | Released |
|---|---|---|---|
| 0.7.2beta | MIT license | 0.7.2beta | 10/02/2008 |
| 0.7.1beta | MIT license | 0.7.1beta | 29/10/2007 |
| 0.6.2beta | MIT license | 0.6.2beta | 12/09/2007 |
| 0.6.1beta | MIT license | 0.6.1beta | 09/09/2007 |
| 0.6.0beta | MIT license | 0.6.0beta | 07/09/2007 |
| 0.5.0beta | MIT license | 0.5.0beta | 05/09/2007 |
This plugin aims at providing rating capabilities to any Propel object with the help of a dedicated Propel behavior.
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 (please always use a tagged version in production)
The plugin is also available through the Symfony SVN repository.
Stable versions are available in the tags folder, experimental ones in the branches one and the current alpha in the trunk.
Caution: Never use the trunk version in a production environment.
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'));
You can fine-tune behavior with optional parameters, see the advanced configuration section.
Once your model configured, you have to rebuild it:
symfony propel-build-all
And clear the cache :
symfony cc
<?php
class Article extends BaseArticle
{
}
sfPropelBehavior::add(
'Article',
array('sfPropelActAsRatableBehavior' =>
array('max_rating' => 10, // Max rating value for an Article
'rating_field' => 'AverageRating', // refers to ArticlePeer::AVERAGE_RATING
'reference_field' => 'Reference'))); // refers to ArticlePeer::REFERENCE
max_rating parameter sets the maximum rating available for an object
(this must be an integer greater than 0 - default is 5)rating_field parameter, which refer to a float
column in phpName format of your ratable object table which will store cached
value of actual rating for the object. Useful for queries performances and
sorting ;)reference_field parameter sets the name of the field where you
store the identifier of the object to rate. By default, the plugin will use
the primary key of the object. You must return an integer fo referencing a
custom identifier.A clean way to ensure rating consistency is to associate a rating to a unique identified user reference stored server side, typically the primary key of a user record in your database.
If no user reference can be retrieved, the plugin will rely on cookies, but you should consider this alternative solution with caution, as cookies are easily deletable by the user.
By default, the plugin will search for an sfGuardPlugin(/plugins/sfGuardPlugin sfGuardPlugin) installation to retrieve authenticated user primary key. If you are using sfGuard, you have nothing more to configure.
If you don't use sfGuard, you can specify the way a unique user reference (eg.
primary key) will be retrieved, using these available plugin settings in your
app.yml file:
You can specify a PHP function, eg. get_connected_user_id():
rating: user_id_getter: get_connected_user_id
Or a static method of a PHP class, eg.
MyCustomUtilsClass::getConnectedUserId():
rating: user_id_getter: getConnectedUserId
The return value of these calls should always be the primary key of your connected user.
This plugin provides an Ajax-based rating system, with pretty stars to click on. You must note that this web module is provided for illustration purpose, it has weak chances to fit exactly your project needs.
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 templates:
<?php sfLoader::loadHelpers('sfRating') ?>
<?php echo sf_rater($article) ?>
Just call the component from any of your templates:
<?php include_component('sfRating', 'ratingDetails', array('object' => $article) ?>
Note: In below examples, $user_id is a string representing a
unique reference to a user, eg. if you're using the sfGuardPlugin,
sfContext::getInstance()->getUser()->getGuardUser()->getId().
If you don't provide this parameter, the configured user reference retrieval configuration will apply.
To set a rating for a given user:
$article->setRating(10, $user_id);
To test if the object has already been rated :
$article->hasBeenRated();
To test if the object has already been rated by a particular user:
$article->hasBeenRatedByUser($user_id);
To retrieve user rating for this object :
$article->getUserRating($user_id);
To get the average rating of the object :
$article->getRating([$precision]);
Note: If you have concerns about performances, you will better use the cached
value of rating stored in the rating_column you configured previously.
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->clearUserRating($user_id);
To retrieve rating details :
$details = $article->getRatingDetails();
Results will be this form:
array(
2 => 12, // 12 people has rated the object 2
5 => 7 // 7 people has rated the object 5
)
You can also retrieve details for all available ratings:
$full_details = $article->getRatingDetails(true);
Results will be this form:
array(
1 => 0, // Nobody has rated the object 1
2 => 12, // 12 people has rated the object 2
3 => 0, // Nobody has rated the object 3
4 => 0, // Nobody has rated the object 4
5 => 7, // 7 people has rated the object 5
)
To clear all ratings for the object :
$article->clearRatings();
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');
symfony plugin-uninstall symfony/sfPropelActAsRatableBehaviorPlugin
You will need to remove the behavior to all your model, then rebuild your model and purge your cache.
getPrimaryKey() method: fast, portable and reliableisRatable static method in behavior classsfRatings 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...This plugin is maintened by Nicolas Perriault
(nperriault -> gmail.com)
Feel free to send feture request, enhancement suggestion or idealy a patch.
