= sfPropelActAsCommentableBehaviorPlugin =

== Introduction ==
This behavior permits to attach comments to Propel objects. It provides a module for enabling comments in your application in less than 3 minutes.

== Features ==

 * add/remove comment(s) on an object
 * unit-tested
 * comment module, with ajax support and layout customization
 * comment admin-module

== Sreenshots ==
[[Image(sfPropelActAsCommentableBehaviorPlugin_comment_1.png, 25%)]]
[[Image(sfPropelActAsCommentableBehaviorPlugin_comment_2.png, 25%)]]
[[Image(sfPropelActAsCommentableBehaviorPlugin_comment_3.png, 25%)]]


== Philosophy of the stuff ==

 * commentable objects must have a primary key
 * comments can only be attached on objects that have already been saved
 * comments are saved when applied

== Get it installed ==

 * go to your project's root

 * Install the plugin:
   {{{
     ./symfony plugin-install http://plugins.symfony-project.com/sfPropelActAsCommentableBehaviorPlugin
   }}}

 * if not already done, enabled behaviors in config/propel.ini:
   {{{
     propel.builder.addBehaviors = true
   }}}

 * edit the classes that you want to make taggable. For instance, for lib/model/Post.php:
   {{{
   #!php
   <?php
     class Post extends BasePost
     {
     }

     sfPropelBehavior::add('Post', array('sfPropelActAsCommentableBehavior'));
   }}}

 * rebuild the model:
   {{{
     ./symfony propel-build-all
   }}}

 * clear cache:
   {{{
     ./symfony cc
   }}}

If you want to take profit of the included comment module, you should also complete the following steps :
 * activate the "sfComment" module in your app's settings.yml:
   {{{
      enabled_modules:   [default, sfComment]
   }}}

 * add the following lines in you app.yml:
   {{{
all:
  sfPropelActAsCommentableBehaviorPlugin:
    use_ajax:         true
    anonymous:
      enabled:        true
      layout:
        name:         required
        email:        required
        title:        optionnal
        comment:      required
      name:           Anonymous User
    user:
      enabled:        true
      layout:
        title:        optionnal
        comment:      required
      table:          sf_guard_user
      id:             id
      class:          sfGuardUser
      id_method:      getId
      toString:       __toString
   }}}

=== Optional settings ===
The plugin has been designed to allow comments from authenticated users, as well as anonymous users. But in general, you will want to adapt the layout of the form, depending on whether the user is authenticated or not. In the app.yml file, you can tweak the default setup:
 * the '''use_ajax''' rule indicates whether or not the comment system must use ajax.
 * the '''anonymous''' rules will tweak the way the plugin handles anonymous comments:
   * '''enabled''' : enables or disables anonymous comments.
   * '''layout''' : defines the layout of the comment form. Required fields will get a "required class" and will get validated. If you want a field not to appear (for instance, the "title" field), simply remove the associated line.
   * '''name''' : the default name of the user, in case the anonymous comment form does not as for an author name.
 * the '''user''' rules will tweak the way the plugin handles comments from authenticated users:
   * '''enabled''' : enables or disables comments from authenticated users.
   * '''layout''' : defines the layout of the comment form. Required fields will get a "required class" and will get validated. If you want a field not to appear (for instance, the "title" field), simply remove the associated line.
   * '''table''' : name of the table that stores the users data.
   * '''id''' : name of the primary key of a user in the users table.
   * '''class''' : class associated to the users.
   * '''id_method''' : name of a method of your user's class, that permits to get the authenticated user id. Usually, you will have to define this method in the myUser.class.php file.
   * '''toString''' : name of a method that outputs the name of a user (an instance of the class defined two lines before)

== Usage ==

=== How to use the comments module ===
You do not have to know the plugin internals in order to get started with the behavior. You simply have to include two components:
 * one for displaying the comments associated to an object
 * an other for displaying the comment form

For instance, when displaying a blog post, add in the view PHP file:
{{{
#!php
<h2><?php echo $post->getTitle(); ?></h2>

<p><?php echo $post->getText(); ?></p>

<h3>Comments</h3>
<?php
include_component('sfComment', 'commentList', array('object' => $post));
include_component('sfComment', 'commentForm', array('object' => $post));
?>
}}}

=== Attaching comments to a commentable object ===
Consider a Propel "Post" class:

{{{
#!php
<?php
class Post extends BasePost
{
}

sfPropelBehavior::add('Post', array('sfPropelActAsCommentableBehavior'));
}}}

When the sfPropelActAsCommentableBehaviorPlugin is applied to the Post class, that class automagically gets commentable:
{{{
#!php
<?php
$post = new Post();
// blah
$post->save();
$post->addComment('This is a cool comment.');
$post->addComment(array('title' => 'this is a cool title', 'text' => 'this is a cool comment', 'author_id' => sfContext::getInstance()->getUser()->getUserId()));
$post->addComment(array('This is a cool comment.', 'this is one other comment'));
}}}

=== Retrieving one object's comments ===
It is possible to retrieve comments from a commentable object:
{{{
#!php
<?php
$post = PostPeer::retrieveByPk(1);
$comments = $post->getComments();

foreach ($comments as $comment)
{
  echo '<p>'.$comment->getText().'</p>';
}
}}}

=== Removing one object's comment ===
Of course, comments can also be removed:
{{{
#!php
<?php
$post = PostPeer::retrieveByPk(1);
$post->removeComment(12);
$post->clearComments();
}}}

== API ==
The behavior implement the following methods:
 * '''addComment($comment)''' - Adds a comment to the object. The "comment" param can be an associative array (in which each element represents one of the comment properties), or an array of associative arrays. In this case, it adds all the comments to the object.
 * '''clearComments()''' - Deletes all the comments attached to the object
 * '''getComments($options = array())''' - Returns the list of the comments attached to the object. The options array can contain several options
 * '''getNbComments()''' - Returns the number of the comments attached to the object.
 * '''removeComment($comment_id)''' - Removes one comment from the object.

== Unit testing ==
The plugin has been deeply unit-tested. The tests are located in test/unit/sfPropelActAsCommentableBehaviorTest.php. If you want to run them:
 * install the plugin
 * configure a model for using it, for instance "Post"
 * edit this file and, if required, modify the application name and the TEST_CLASS constant, line 3:
   {{{
     define('TEST_CLASS', 'Post');
   }}}
 * run the tests:
   {{{
     php plugins/sfPropelActAsCommentableBehaviorPlugin/test/unit/sfPropelActAsCommentableBehaviorTest.php
   }}}

== License and credits ==
This plugin is licensed under the MIT license. You can contact the maintainer at xavier@lacot.org

== Changelog ==

=== version 0.2 - 2007-09-26 ===
 * added a Symfony module for posting and displaying comments
   * ajax support
   * authenticated users support
   * form customization
 * added an administration module

=== version 0.1 - 2007-09-13 ===
Initial public release. Features comments attachment to heterogene Propel objects.

== Roadmap / Wishlist ==
 * handle other custom fields in comments
 * handle comment namespaces (front-office comments, back-office comments, etc.)