Commontator

Commontator is a Rails engine for comments. It is compatible with Rails 3.1+ and Rails 4. Being an engine means it is fully functional as soon as you install and configure the gem, providing models, views and controllers of its own. At the same time, almost anything about it can be configured or customized to suit your needs.

Installation

There are 4 steps you must follow to install commontator:

Add this line to your application's Gemfile:

gem 'commontator', '~> 4.5.0'

And then execute:

$ bundle

Or install it yourself as:

$ gem install commontator

Initializer and Migration

Run the following command to copy commontator's initializer and migration to your own app:

$ rake commontator:install

And then execute:

$ rake db:migrate

Or run each rake task manually:

$ rake commontator:install:initializers

$ rake commontator:install:migrations

$ rake db:migrate

Configuration

Change commontator's configurations to suit your needs by editing config/initializers/commontator.rb. Make sure to check that your configuration file is up to date every time you update the gem, as available options can change with each minor version.

Routes

Add this line to your application's routes file:

mount Commontator::Engine => '/commontator'

You can change the mount path if you would like a different one.

Usage

Follow the steps below to add commontator to your models and views:

Models

Add this line to your user model(s) (or any models that should be able to post comments):

acts_as_commontator

Add this line to any models you want to be able to comment on:

acts_as_commontable

Views

In the following instructions, commontable is an instance of a model that acts_as_commontable.

Add the following line to any erb view where you would like to display comments:

<%= commontator_thread(commontable) %>

This will create a link in the view that the user will be able to click to display the comment thread.

Note that model's record must already exist in the database, so do not use this in new.html.erb, _form.html.erb or similar. We recommend you use this in the model's show.html.erb or similar.

Controllers

By default, the commontator_thread method only links to the desired comment thread. If you want, instead, to have the thread display right away when the corresponding view page is loaded, just add the following method call to the controller action that displays the view in question:

commontator_thread_show(commontable)

Note that the call to commontator_thread in the view is still necessary in either case.

The commontator_thread_show method checks the current user's read permission on the thread and will raise an exception if the user is not allowed to read it according to the configuration options in the initializer. It is up to you to ensure that this method is only called if the user is authorized to read the thread.

That's it! Commontator is now ready for use.

Voting

You can allow users to vote on each others' comments by adding the acts_as_votable gem to your gemfile:

gem 'acts_as_votable'

And enabling the relevant option in commontator's initializer:

config.can_vote_on_comments = true

Note that acts_as_votable is currently incompatible with the protected_attributes gem if config.active_record.whitelist_attributes is true.

Browser Support

Commontator should work properly on any of the major browsers. To function properly, this gem requires that visitors to the site have javascript enabled.

Customization

Copy commontator's files to your app using any of the following commands:

$ rake commontator:copy:locales

$ rake commontator:copy:images
$ rake commontator:copy:stylesheets

$ rake commontator:copy:views
$ rake commontator:copy:mailers
$ rake commontator:copy:helpers

$ rake commontator:copy:controllers
$ rake commontator:copy:models

You are now free to modify them and have any changes made manifest in your application.

If copying commontator's locales, please note that by default Rails will not autoload locales in subfolders of config/locales (like ours) unless you add the following to your application's configuration file:

config.i18n.load_path += Dir[root.join('config', 'locales', '**', '*.{rb,yml}')]

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Write tests for your feature
Implement your new feature
Test your feature (rake)
Commit your changes (git commit -am 'Added some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

Development Environment Setup

Browse to commontator's spec/dummy folder
Use bundler to install all dependencies:

$ bundle install

Load the schema:

$ rake db:schema:load

Or if the above fails:

$ bundle exec rake db:schema:load

Testing

To run all existing tests for commontator, simply execute the following from the main folder:

$ rake