Opinio
Description
Opinio is an engine used to add comments behaviour to your application. The engine is designed to work only with *Rails 3*
Intallation
Simply add the following line to your Gemfile:
gem "opinio"
and run:
bundle
Documentation
Rdocs here:
http://rubydoc.info/github/Draiken/opinio/master/frames
Usage
Opinio provides generators to facilitate it’s usage. The most common way to quickly get Opinio working is:
rails g opinio:install comment
This will generate the Comment model, migration and also generate the opinio initializer for customization of the engine. A ‘opinio_model` will be added on the `routes.rb`. This method adds the default urls for the model that will acts as the comment
In order to add the comments functionallity to a model, you use the opinio_subjectum method
class Post < ActiveRecord::Base
opinio_subjectum
end
On the ‘routes.rb` you should simply add an `opinio` for your resource that will have comments
resources :posts do
opinio
end
If you want to display the comments for the item outside of the resource, you can simply add this to your views:
<%= comments_for @post %>
And there you go, you can now comment in your post.
Alternatively you can render just the comments or just the form like this:
<%= render_comments @post %>
<%= render_comments_form @post %>
If you need to render the comments with a specific page or limit you can use Kaminari’s configurations like ‘paginates_per 10` on your comment model or you can customize it for specific views on the helpers
<%= render_comments @post, :page => params[:page], :limit => 5 %>
This can also be used on the ‘comments_for` helper.
Customization
Views
Of course you will want to customize how the comments are displayed or any other customization to the view. To generate the view files on your application, run:
rails g opinio:views
And you can customize all the views used by the engine.
Behaviour
Pretty Urls
Often times you will want the engine to show the index of comments for a specific item without having to pass :commentable_type or :commentable_id.
In order to do that, opinio provides a method to ActionController::Base:
opinio_identifier do |params|
next Review.find(params[:review_id]) if params[:review_id]
next Product.find(params[:product_id]) if params[:product_id]
end
Note: you use next instead of return because it is a proc that will be executed later on, and you cannot return on procs
Basically on this method you receive the params variable and you tell the engine, who owns the comments from that page. This allows you to use routes like:
/products/1/comments
/products/1/reviews/1/comments
Without passing those 2 parameters. I suggest you put this method on the ApplicationController
Customize destroy conditions
By default, anyone can destroy any comment in the engine. We don’t want that. To setup a custom destroy condition we can use the methods provided by opinio in our controllers. For instance, if our opinio model is called ‘comment’ it would be like this:
comment_destroy_conditions do |comment|
comment.owner == current_user
end
This would make users only be able to remove their own comments. Another example would be using the CanCan:
comment_destroy_conditions do |comment|
:destroy, comment
end
You get the picture, you’re inside your controller’s methods on that block so you can call anything your normal controllers call on actions.
Testing
Opinio provides a few shared examples for testing of your model with rspec On your opinio model test case you can require opinio’s shared examples and use them
require 'opinio/shared_examples'
describe Comment do
it_should_behave_like :opinio
end
describe Post do
it_should_behave_like :opinio_subjectum
end
Contribution
If you want to help in any way with Opinio please message me or fork the project, make the changes and send me a pull request. For issues please use the github issues tracker
TODO
* Haml views
* Better controller overriding (coding and documentation)
* Support for deeper levels of replies
* Refactor the `comments_for` helper
* Extract documentation to wiki