{"id":13462941,"url":"https://github.com/lml/commontator","last_synced_at":"2025-03-25T06:31:24.084Z","repository":{"id":3673812,"uuid":"4743151","full_name":"lml/commontator","owner":"lml","description":"A Rails engine for comments","archived":false,"fork":false,"pushed_at":"2024-08-15T16:11:18.000Z","size":963,"stargazers_count":354,"open_issues_count":26,"forks_count":98,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-03-01T22:06:13.302Z","etag":null,"topics":["comment-threads","jquery-ujs","rails-engine"],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lml.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-06-21T19:03:15.000Z","updated_at":"2024-12-27T14:33:01.000Z","dependencies_parsed_at":"2024-06-18T21:37:11.991Z","dependency_job_id":"2b39f1e0-80b6-4c03-9dce-2ee8e0fa6b8d","html_url":"https://github.com/lml/commontator","commit_stats":{"total_commits":411,"total_committers":29,"mean_commits":"14.172413793103448","dds":0.3284671532846716,"last_synced_commit":"856ff205ffbbb0c32aab39afe5fce3da958c650f"},"previous_names":[],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lml%2Fcommontator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lml%2Fcommontator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lml%2Fcommontator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lml%2Fcommontator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lml","download_url":"https://codeload.github.com/lml/commontator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245413752,"owners_count":20611353,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["comment-threads","jquery-ujs","rails-engine"],"created_at":"2024-07-31T13:00:41.515Z","updated_at":"2025-03-25T06:31:23.549Z","avatar_url":"https://github.com/lml.png","language":"Ruby","funding_links":[],"categories":["Active Record Plugins"],"sub_categories":["Rails Comments"],"readme":"# Commontator\n\n[![Gem Version](https://badge.fury.io/rb/commontator.svg)](https://badge.fury.io/rb/commontator)\n[![Tests](https://github.com/lml/commontator/workflows/Tests/badge.svg)](https://github.com/lml/commontator/actions?query=workflow:Tests)\n[![Code Climate](https://codeclimate.com/github/lml/commontator/badges/gpa.svg)](https://codeclimate.com/github/lml/commontator)\n[![Code Coverage](https://codeclimate.com/github/lml/commontator/badges/coverage.svg)](https://codeclimate.com/github/lml/commontator)\n\nCommontator is a Rails engine for comments. It is compatible with Rails 5.2+.\nBeing an engine means it is fully functional as soon as you install and\nconfigure the gem, providing models, views and controllers of its own.\nAt the same time, almost anything about it can be configured or customized to suit your needs.\n\n## Installation\n\nFollow the steps below to install Commontator:\n\n1. Gem\n\n  Add this line to your application's Gemfile:\n\n  ```rb\n  gem 'commontator'\n  ```\n\n  You will also need jquery and a sass compiler, which can be either be installed through\n  the webpacker gem and yarn/npm/bower or through the jquery-rails and sass[c]-rails gems:\n\n  ```rb\n  gem 'jquery-rails'\n  gem 'sassc-rails'\n  ```\n\n  Then execute:\n\n  ```sh\n  $ bundle install\n  ```\n\n2. Initializer and Migrations\n\n  Run the following command to copy Commontator's initializer and migrations to your app:\n\n  ```sh\n  $ rake commontator:install\n  ```\n\n  Or alternatively:\n\n  ```sh\n  $ rake commontator:install:initializers\n\n  $ rake commontator:install:migrations\n  ```\n\n  And then execute:\n\n  ```sh\n  $ rails db:migrate\n  ```\n\n3. Configuration\n\n  Change Commontator's configurations to suit your needs by editing `config/initializers/commontator.rb`.\n  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.\n  If you have deprecated options in your initializer, Commontator will issue warnings (usually printed to your console).\n\n  Commontator relies on Rails's `sanitize` helper method to sanitize user input before display.\n  The default allowed tags and attributes are very permissive, basically\n  only blocking tags, attributes and attribute values that could be used for XSS.\n  [Read more about configuring the Rails sanitize helper.](https://edgeapi.rubyonrails.org/classes/ActionView/Helpers/SanitizeHelper.html).\n\n4. Routes\n\n  Add this line to your Rails application's `routes.rb` file:\n\n  ```rb\n  mount Commontator::Engine =\u003e '/commontator'\n  ```\n\n  You can change the mount path if you would like a different one.\n\n### Assets\n\n1. Javascripts\n\n  Make sure your application.js requires jquery and rails-ujs or jquery-ujs:\n\n  Rails 5.1+:\n  ```js\n  //= require jquery\n  //= require rails-ujs\n  ```\n\n  Rails 5.0:\n  ```js\n  //= require jquery\n  // If jquery-ujs was installed through jquery-rails\n  //= require jquery_ujs\n  // If jquery-ujs was installed through webpacker and yarn/npm/bower\n  //= require jquery-ujs\n  ```\n\n  If using Commontator's mentions functionality, also require Commontator's application.js:\n\n  ```js\n  //= require commontator/application\n  ```\n\n2. Stylesheets\n\n  In order to display comment threads properly, you must\n  require Commontator's application.scss in your `application.[s]css`:\n\n  ```css\n  *= require commontator/application\n  ```\n\n#### Sprockets 4+\n\n  You must require Commontator's manifest.js in your app's manifest.js for images to work properly:\n\n  ```js\n  //= link commontator/manifest.js\n  ```\n\n  You also need to either add the necessary link tag commands to your layout to load\n  commontator/application.js and commontator/application.css or require them in your app's\n  application.js and application.css like in Sprockets 3.\n\n## Usage\n\nFollow the steps below to add Commontator to your models and views:\n\n1. Models\n\n  Add this line to your user model(s) (or any models that should be able to post comments):\n\n  ```rb\n  acts_as_commontator\n  ```\n\n  Add this line to any models you want to be able to comment on (i.e. models that have comment threads):\n\n  ```rb\n  acts_as_commontable\n  ```\n  if you want the thread and all its comments removed when your commontable model is destroyed pass\n  :destroy as the :dependent option to`acts_as_commontable`:\n\n  ```rb\n  acts_as_commontable dependent: :destroy\n  ```\n\n  instead of `:destroy` you may use any other supported `:dependent` option from rails `has_one`\n  association.\n\n2. Views\n\n  In the following instructions, `@commontable` is an instance of a model that `acts_as_commontable`.\n  You must supply this variable to the views that will use Commontator.\n\n  Wherever you would like to display comments, call `commontator_thread(@commontable)`:\n\n  ```erb\n  \u003c%= commontator_thread(@commontable) %\u003e\n  ```\n\n  This will create a link that can be clicked to display the comment thread.\n\n  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 views.\n  We recommend you use this in the model's `show.html.erb` view or the equivalent for your app.\n\n3. Controllers\n\n  By default, the `commontator_thread` method only provides a link to the desired comment thread.\n  Sometimes it may be desirable to have the thread display right away when the corresponding page is loaded.\n  In that case, just add the following method call to the controller action that displays the page in question:\n\n  ```rb\n  commontator_thread_show(@commontable)\n  ```\n\n  Note that the call to `commontator_thread` in the view is still necessary in either case.\n\n  The `commontator_thread_show` method checks the current user's read permission on the thread and will display the thread if the user is allowed to read it, according to the options in the initializer.\n\nThat's it! Commontator is now ready for use.\n\n## Emails\n\nWhen you enable subscriptions, emails are sent automatically by Commontator.\nIf sending emails, remember to add your host URL's to your environment files\n(test.rb, development.rb and production.rb):\n\n```rb\nconfig.action_mailer.default_url_options = { host: \"https://www.example.com\" }\n```\n\nSometimes you may need to subscribe (commontator) users automatically when some event happens.\nYou can call `object.commontator_thread.subscribe(user)` to subscribe users programmatically.\nBatch sending through Mailgun is also supported and automatically detected.\nRead the Customization section to see how to customize subscription emails.\n\n## Voting\n\nYou can allow users to vote on each others' comments\nby adding the `acts_as_votable` gem to your Gemfile:\n\n```rb\ngem 'acts_as_votable'\n```\n\nAnd enabling the relevant option in Commontator's initializer:\n\n```rb\nconfig.comment_voting = :ld # See the initializer for available options\n```\n\n## Mentions\n\nYou can allow users to mention other users in the comments.\nMentioned users are automatically subscribed to the thread and receive email notifications.\n\nFirst make sure you required Commontator's application.js\nin your `application.js` as explained in the Javascripts section.\nThen enable mentions in Commontator's initializer:\n\n```rb\nconfig.mentions_enabled = true\n```\n\nFinally configure the user_mentions_proc, which receives the current user, the current thread,\nand the search query inputted by that user and should return a relation containing the users\nthat can be mentioned and match the query string:\n\n```rb\nconfig.user_mentions_proc = -\u003e(current_user, thread, query) { ... }\n```\n\nPlease be aware that with mentions enabled, any registered user\ncan use the `user_mentions_proc` to search for other users.\nMake sure to properly escape SQL in this proc and do not allow searches on sensitive fields.\n\nUse '@' with at least three other characters to mention someone in a new/edited comment.\n\nThe mentions script assumes that Commontator is mounted at `/commontator`,\nso make sure that is indeed the case if you plan to use mentions.\n\n## Browser Support\n\nCommontator should work properly on any of the major browsers.\nThe mentions functionality won't work with IE before version 8.\nTo function properly, this gem requires that visitors to the site have javascript enabled.\n\n## Customization\n\nCopy Commontator's files to your app using any of the following commands:\n\n```sh\n$ rake commontator:copy:locales\n\n$ rake commontator:copy:images\n$ rake commontator:copy:javascripts\n$ rake commontator:copy:stylesheets\n\n$ rake commontator:copy:views\n$ rake commontator:copy:helpers\n\n$ rake commontator:copy:controllers\n$ rake commontator:copy:mailers\n\n$ rake commontator:copy:models\n```\n\nYou are now free to modify them and have any changes made manifest in your application.\nYou can safely remove files you do not want to customize.\n\nYou can customize subscription emails (mailer views) with `rake commontator:copy:views`.\n\nIf copying Commontator's locales, please note that by default Rails will not autoload locales in\nsubfolders of `config/locales` (like ours) unless you add the following to your `application.rb`:\n\n```rb\nconfig.i18n.load_path += Dir[root.join('config', 'locales', '**', '*.yml')]\n```\n\n## Contributing\n\n1. Fork the lml/commontator repo on Github\n2. Create a feature or bugfix branch (`git checkout -b my-new-feature`)\n3. Write tests for the feature/bugfix\n4. Implement the new feature/bugfix\n5. Make sure both new and old tests pass (`rake`)\n6. Commit your changes (`git commit -am 'Added some feature'`)\n7. Push the branch (`git push origin my-new-feature`)\n8. Create a new Pull Request to lml/commontator on Github\n\n## Development Environment Setup\n\n1. Use bundler to install all dependencies:\n\n  ```sh\n  $ bundle install\n  ```\n\n2. Setup the database:\n\n  ```sh\n  $ rails db:setup\n  ```\n\n## Testing\n\nTo run all existing tests for Commontator, simply execute the following from the main folder:\n\n```sh\n$ rake\n```\n\n## License\n\nThis gem is distributed under the terms of the MIT license.\nSee the MIT-LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flml%2Fcommontator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flml%2Fcommontator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flml%2Fcommontator/lists"}