Commontator is a Rails engine for comments. Being an engine means it is fully functional as soon as you install and configure its 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.
There are 4 steps you must follow to install commontator:
- Gem
Add this line to your application's Gemfile (for Rails 4+):
gem 'commontator', '~> 4.0.0'
If you are still using rails 3, use Commontator version 2.0.1 instead.
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/intializers/commontator.rb.
- 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.
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 make comments):
acts_as_commontator
Add this line to any models you want to be able to comment on:
acts_as_commontable
- Views
Add the following line to any erb view where you would like to display comments:
<%= commontator_thread(commontable) %>
Where commontable is an instance of some model that acts_as_commontable. 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. When you do this, it is up to you to ensure that the user has the proper permission to read the thread or else a SecurityTransgression will be raised.
- Controllers
Instead of linking to the thread, you might want to have the thread display right away, when the corresponding view page is loaded. If that's the case, add the following to the controller action that displays the view where the thread is located:
commontator_thread_show(commontable)
Note that the above method also checks the current user's read permission on the thread. It will raise a SecurityTransgression if the user is not allowed to read the thread. You can specify the name of the method that determines which users are allowed to read which threads in the initializer.
That's it! Commontator is now ready for use.
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 set to true.
No incompatibilities are currently known with any of the major browsers. Currently commontator requires javascript enabled to function properly.
Copy commontator's files to your app using any of the following commands:
$ 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.
- 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
- 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
To run all existing tests for commontator, simply execute the following from the main folder:
$ rake
Or if the above fails:
$ bundle exec rake
This engine is distributed under the terms of the MIT license. See the MIT-LICENSE file for details.