# sfDoctrineActAsRattablePlugin #

## Introduction ##
This plugin permits to attach rates to Doctrine objects

You can discuss about this plugin on the [google group sfDoctrineActAsRattable](http://groups.google.com/group/sfdoctrineactasrattableplugin)

Full (and up to date) documentation available on the [symfony wiki](http://trac.symfony-project.org/wiki/SfDoctrineActAsRattablePlugin)

### Features ###

 * add/remove ratings
 * manage multiple ratings
 * get average rating
 * get commented ratings
 * be notified when an object is rated
 
### How it works ###

Giving Rattable behavior to an object the same as [Doctrine I18n](http://www.doctrine-project.org/documentation/manual/1_1/en/behaviors#core-behaviors:i18n)

It create an object_rate table with how many column as criterias OR default one : rate

Example :

    hotel_room:
      actAs: 
        Rattable:
          criterias: [clean_state, receptionist, equipment]
          max_rate: 5
          rounding_rate: 1
          
Will create 2 tables:

     1 hotel_room
     1 hotel_room_rate, with columns:
         clean_state
         reception
         equipment
         comment
         user_id # foreignKey to sfGuardUser if exists

## Installation ##

### Symfony way ###

 * go to your project's root
 * Install the plugin: 
        
        ./symfony plugin-install http://svn.symfony-project.com/plugins/sfDoctrineActAsRattblePlugin/branches/1.2

### SVN way ###

 * from the terminal, go to your plugin directory:
 * enter
 
        svn pe svn:externals .
 
 * write add a line
 
        sfDoctrineActAsRattblePlugin http://svn.symfony-project.com/plugins/sfDoctrineActAsRattblePlugin/branches/1.2
 
 * close the editor
 * do a ``svn update`` an that's all

## Configuration ##

 * configure your object :

        my_object:
          actAs:
            Rattable:
              criterias:     rate # or [clean_state, receptionist, equipment] only if you wanna rate specifics parts
              max_rate:      5    # 2,10 etc. any integer number you want (more than 20 is a bad idea, work with rounding instead)
              rounding_rate: 1    # or 0.1, 0.2 etc.
              with_comment:  true # false

 * rebuild the model: 

        ./symfony doctrine-build-all

 * clear cache:

        ./symfony cc

## API ##

The plugin implements the following methods to the object:

 * getRates()
 * getRating()
 * addRate(RategObject $rateObject)
 * removeRatings()
 * getRatesQuery()

## Events notifications types ##

 * rate.add     notify
 * rate.remove  notify

## Helpers ##

## Examples ##

## Todo ##
 * notification management
 * give examples
 * create helpers
 * create components to show ratings
 * add icons possibility for ratings types

## Unit testing ##
The plugin has been unit-tested, perhaps not fully (I'm a newbie in unit tests). The tests are located in [developpment branch](http://svn.symfony-project.com/plugins/sfDoctrineActAsRattablePlugin/branches/developpment_env/test/unit/sfDoctrineActAsRattableTest.php).

## Side notes ##
I won't release pear packages, if someone is interested in managing them, let met know and I will add you as package manager.

## License and credits ##
This plugin has been created by [Mickael Kurmann](http://www.vieuxsteak.ch/) and is licensed under the MIT license.

I took my inspiration from :

 * [sfPropelActasRatableBehaviorPlugin](http://www.symfony-project.org/plugins/sfPropelActAsRatableBehaviorPlugin)
 * [Unobtrusive AJAX Star Rating bar from Masuga](http://www.masugadesign.com/the-lab/scripts/unobtrusive-ajax-star-rating-bar/)
 * [jQuery Star Rating plugin](http://www.fyneworks.com/jquery/star-rating/#tab-Overview)