commontator 5.1.0 → 6.0.0.pre.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: acf6d8175a90bff17e463df97782fd7bf93b8565
-  data.tar.gz: 7320feebb54d1995b15e2d5627ff2845eac42756
+SHA256:
+  metadata.gz: 5eff6c0a48d5f543bfb93305eac807e923acf0542f10afb4720aae10220b6447
+  data.tar.gz: 4875720a501fbf2087ab5d350b9e570f94271623f9df6834d30002afbf545f72
 SHA512:
-  metadata.gz: 2ce7dec91a95320fa1ee613a8a62021eba0d88501d7a740ee069a0ce886346a734bd1903bd332b84cc71ccbacf8c408fd8adf67d26d9ae7b24bf85b231b36fba
-  data.tar.gz: 8829fd206d56d284d9ea23d9fb781602de7f136479c4b2828ae04f4211bf8322954065193fe247b0ea3ee0a64458c12fae9b8c58482c5e073121e70b1aad203f
+  metadata.gz: 96c05e5272b89801962355a629f22be1662c4fe9cce699d7c7be01ad4139275ab0c604c529252deba630117b9e0bd916b195bc669bb8797bce94ab896a4a34e8
+  data.tar.gz: 4e319ccd0514499cf691509ed1a15262e319c32d80f9f04ce4d1b4b873b07a94e83d5071310d07c741979ffb50c22106c1f7afabd0788f65085775538985ca1c

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright 2012-14 Rice University
+Copyright 2012-19 Rice University
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,36 +1,44 @@
 # Commontator
 
-[![Gem Version](https://badge.fury.io/rb/commontator.svg)](http://badge.fury.io/rb/commontator)
+[![Gem Version](https://badge.fury.io/rb/commontator.svg)](https://badge.fury.io/rb/commontator)
 [![Build Status](https://travis-ci.org/lml/commontator.svg?branch=master)](https://travis-ci.org/lml/commontator)
 [![Code Climate](https://codeclimate.com/github/lml/commontator/badges/gpa.svg)](https://codeclimate.com/github/lml/commontator)
 [![Code Coverage](https://codeclimate.com/github/lml/commontator/badges/coverage.svg)](https://codeclimate.com/github/lml/commontator)
 
-Commontator is a Rails engine for comments. It is compatible with Rails 3.1+ and Rails 4.
+Commontator is a Rails engine for comments. It is compatible with Rails 5.
 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:
+Follow the steps below to install Commontator:
 
 1. Gem
 
   Add this line to your application's Gemfile:
 
   ```rb
-  gem 'commontator', '~> 5.1.0'
+  gem 'commontator'
   ```
 
-  And then execute:
+  You will also need jquery-ujs and a sass compiler, which can be either be installed through
+  the webpacker gem and yarn/npm/bower or through the jquery-rails and sass[c]-rails gems:
+
+  ```rb
+  gem 'jquery-rails'
+  gem 'sassc-rails'
+  ```
+
+  Then execute:
 
   ```sh
   $ bundle install
   ```
 
-2. Initializer and Migration
+2. Initializer and Migrations
 
-  Run the following command to copy commontator's initializer and migration to your app:
+  Run the following command to copy Commontator's initializer and migrations to your app:
 
   ```sh
   $ rake commontator:install
@@ -47,15 +55,20 @@ There are 4 steps you must follow to install commontator:
   And then execute:
 
   ```sh
-  $ rake db:migrate
+  $ rails db:migrate
   ```
 
 3. Configuration
 
-  Change commontator's configurations to suit your needs by editing `config/initializers/commontator.rb`.
+  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.
   If you have deprecated options in your initializer, Commontator will issue warnings (usually printed to your console).
 
+  Commontator relies on Rails's `sanitize` helper method to sanitize user input before display.
+  The default allowed tags and attributes are very permissive, basically
+  only blocking tags, attributes and attribute values that could be used for XSS.
+  [Read more about configuring the Rails sanitize helper.](https://edgeapi.rubyonrails.org/classes/ActionView/Helpers/SanitizeHelper.html).
+
 4. Routes
 
   Add this line to your Rails application's `routes.rb` file:
@@ -66,10 +79,28 @@ There are 4 steps you must follow to install commontator:
 
   You can change the mount path if you would like a different one.
 
-5. Stylesheets
+5. Javascripts
 
-  In order to display comment threads properly,
-  you must add the following to your `application.css`:
+  Make sure your application.js requires jquery and jquery-ujs:
+
+  ```js
+  //= require jquery
+  // If jquery-ujs was installed through jquery-rails
+  //= require jquery_ujs
+  // If jquery-ujs was installed through webpacker and yarn/npm/bower
+  //= require jquery-ujs
+  ```
+
+  If using Commontator's mentions functionality, also require Commontator's application.js:
+
+  ```js
+  //= require commontator/application
+  ```
+
+6. Stylesheets
+
+  In order to display comment threads properly, you must
+  require Commontator's application.scss in your `application.[s]css`:
 
   ```css
   *= require commontator/application
@@ -77,7 +108,7 @@ There are 4 steps you must follow to install commontator:
 
 ## Usage
 
-Follow the steps below to add commontator to your models and views:
+Follow the steps below to add Commontator to your models and views:
 
 1. Models
 
@@ -130,35 +161,35 @@ Follow the steps below to add commontator to your models and views:
 
   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 a
-  Commontator::SecurityTransgression exception if the user is not allowed to read it, according to the 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.
+  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.
 
 That's it! Commontator is now ready for use.
 
 ## Emails
 
-When you enable subscriptions, emails are sent automatically by Commontator. If sending emails, remember to add your host URL's to your environment files (test.rb, development.rb and production.rb):
+When you enable subscriptions, emails are sent automatically by Commontator.
+If sending emails, remember to add your host URL's to your environment files
+(test.rb, development.rb and production.rb):
 
 ```rb
-config.action_mailer.default_url_options = { host: "www.example.com" }
+config.action_mailer.default_url_options = { host: "https://www.example.com" }
 ```
 
+Sometimes you may need to subscribe (commontator) users automatically when some event happens.
+You can call `object.commontator_thread.subscribe(user)` to subscribe users programmatically.
 Batch sending through Mailgun is also supported and automatically detected.
-
-You may need to customize the mailer views with `rake commontator:copy:views` though only `app/views/commontator/subscriptions_mailer/` may be necessary. These in turn may require that you customize the localizations as well (see below for more details on that).
-
-Sometimes you may need to add users automatically upon some event. For example, you may wish to automatically "subscribe" a (commontator) `user` to a (commontable) `event` so they get messages sent to the event automatically after joining the event. To do this you call `event.thread.subscribe(user)` when adding that `user` to that `event`.
+Read the Customization section to see how to customize subscription emails.
 
 ## Voting
 
-You can allow users to vote on each others' comments by adding the `acts_as_votable` gem to your gemfile:
+You can allow users to vote on each others' comments
+by adding the `acts_as_votable` gem to your Gemfile:
 
 ```rb
 gem 'acts_as_votable'
 ```
 
-And enabling the relevant option in commontator's initializer:
+And enabling the relevant option in Commontator's initializer:
 
 ```rb
 config.comment_voting = :ld # See the initializer for available options
@@ -169,22 +200,17 @@ config.comment_voting = :ld # See the initializer for available options
 You can allow users to mention other users in the comments.
 Mentioned users are automatically subscribed to the thread and receive email notifications.
 
-First add the following to your application.js file:
-
-```js
-//= require commontator/application
-```
-
-Then enable mentions in commontator's initializer:
+First make sure you required Commontator's application.js
+in your `application.js` as explained in the Javascripts section.
+Then enable mentions in Commontator's initializer:
 
 ```rb
 config.mentions_enabled = true
 ```
 
-Finally configure the user_mentions_proc, which receives the current user,
-the current thread, and the search query inputted by that user and should
-return a relation containing the users that can be mentioned and match the
-query string:
+Finally configure the user_mentions_proc, which receives the current user, the current thread,
+and the search query inputted by that user and should return a relation containing the users
+that can be mentioned and match the query string:
 
 ```rb
 config.user_mentions_proc = ->(current_user, thread, query) { ... }
@@ -192,11 +218,11 @@ config.user_mentions_proc = ->(current_user, thread, query) { ... }
 
 Please be aware that with mentions enabled, any registered user
 can use the `user_mentions_proc` to search for other users.
-Make sure to properly escape SQL in this proc and to not allow searches on sensitive fields.
+Make sure to properly escape SQL in this proc and do not allow searches on sensitive fields.
 
 Use '@' with at least three other characters to mention someone in a new/edited comment.
 
-The mentions script assumes that commontator is mounted at `/commontator`,
+The mentions script assumes that Commontator is mounted at `/commontator`,
 so make sure that is indeed the case if you plan to use mentions.
 
 ## Browser Support
@@ -207,40 +233,46 @@ To function properly, this gem requires that visitors to the site have javascrip
 
 ## Customization
 
-Copy commontator's files to your app using any of the following commands:
+Copy Commontator's files to your app using any of the following commands:
 
 ```sh
 $ rake commontator:copy:locales
 
 $ rake commontator:copy:images
+$ rake commontator:copy:javascripts
 $ rake commontator:copy:stylesheets
 
 $ rake commontator:copy:views
-$ rake commontator:copy:mailers
 $ rake commontator:copy:helpers
 
 $ rake commontator:copy:controllers
+$ rake commontator:copy:mailers
+
 $ rake commontator:copy:models
 ```
 
 You are now free to modify them and have any changes made manifest in your application.
+You can safely remove files you do not want to customize.
 
-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:
+You can customize subscription emails (mailer views) with `rake commontator:copy:views`.
+
+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.rb`:
 
 ```rb
-config.i18n.load_path += Dir[root.join('config', 'locales', '**', '*.{rb,yml}')]
+config.i18n.load_path += Dir[root.join('config', 'locales', '**', '*.yml')]
 ```
 
 ## Contributing
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Write tests for your feature
-4. Implement your new feature
-5. Test your feature (`rake`)
+1. Fork the lml/commontator repo on Github
+2. Create a feature or bugfix branch (`git checkout -b my-new-feature`)
+3. Write tests for the feature/bugfix
+4. Implement the new feature/bugfix
+5. Make sure both new and old tests pass (`rake`)
 6. Commit your changes (`git commit -am 'Added some feature'`)
-7. Push to the branch (`git push origin my-new-feature`)
-8. Create new Pull Request
+7. Push the branch (`git push origin my-new-feature`)
+8. Create a new Pull Request to lml/commontator on Github
 
 ## Development Environment Setup
 
@@ -250,32 +282,20 @@ config.i18n.load_path += Dir[root.join('config', 'locales', '**', '*.{rb,yml}')]
   $ bundle install
   ```
 
-2. Load the schema:
+2. Setup the database:
 
   ```sh
-  $ rake db:schema:load
-  ```
-
-  Or if the above fails:
-
-  ```sh
-  $ bundle exec rake db:schema:load
+  $ rails db:setup
   ```
 
 ## Testing
 
-To run all existing tests for commontator, simply execute the following from the main folder:
+To run all existing tests for Commontator, simply execute the following from the main folder:
 
 ```sh
 $ rake
 ```
 
-Or if the above fails:
-
-```sh
-$ bundle exec rake
-```
-
 ## License
 
 This gem is distributed under the terms of the MIT license.

data/app/assets/javascripts/commontator/mentions.js

@@ -1,7 +1,7 @@
 window.Commontator = {};
 Commontator._ = window._.noConflict();
 Commontator.initMentions = function() {
-    $('.comment_form_field textarea:not(.mentions-added)').each(function(_index, textarea){
+    $('.commontator .field textarea:not(.mentions-added)').each(function(_index, textarea){
         $textarea = $(textarea);
         $form = $textarea.parents('form');
         threadId = $textarea.parents('.thread').attr('id').match(/[\d]+/)[0];
@@ -13,7 +13,7 @@ Commontator.initMentions = function() {
             allowRepeat: true,
             minChars: 3,
             onDataRequest:function (mode, query, callback) {
-                $.getJSON('/commontator/threads/'+threadId+'/mentions.json', {q: query}, function(responseData) {
+                $.getJSON('/commontator/threads/' + threadId + '/mentions.json', {q: query}, function(responseData) {
                     callback.call(this, responseData.mentions);
                 });
             }

data/app/assets/stylesheets/commontator/application.scss

@@ -0,0 +1,101 @@
+/*
+ *= require mentionsInput/jquery.mentionsInput
+ *= require_self
+ *= require_tree .
+ */
+
+.commontator {
+  *:not(input):not(textarea) {
+    margin: 0;
+    border: none;
+    padding: 0;
+  }
+
+  .hidden {
+    display: none;
+  }
+
+  .header {
+    display: block;
+
+    overflow: hidden;
+  }
+
+  .actions {
+    float: right;
+
+    margin-left: 10px;
+  }
+
+  .status {
+    font-size: 120%;
+    font-weight: bold;
+    font-style: normal;
+  }
+
+  .comment-list {
+    background-color: #FFF;
+  }
+
+  /* Modified from: https://www.strangerstudios.com/sandbox/pagination/diggstyle.php */
+  .page-entries-info, .will-paginate {
+  	margin-top: 10px;
+    margin-bottom: 10px;
+  }
+
+  .pagination {
+    a {
+    	margin-right: 4px;
+    	padding: 2px 5px 2px 5px;
+    	border: 1px solid #999;
+
+    	color: #666;
+    	text-decoration: none;
+
+      &:hover, &:active {
+        border: 1px solid #555;
+
+        color: #000;
+      }
+    }
+
+    em {
+    	margin-right: 4px;
+      border: 1px solid #555;
+    	padding: 2px 5px 2px 5px;
+
+      background-color: #555;
+
+      font-weight: bold;
+      color: #FFF;
+    }
+
+    span {
+    	margin-right: 4px;
+      border: 1px solid #EEE;
+      padding: 2px 5px 2px 5px;
+
+      color: #DDD;
+    }
+  }
+
+  .mentions {
+    left: -8px;
+    top: -8px;
+
+    font-family: monospace;
+    font-size: 13.3333px;
+  }
+
+  .field textarea {
+    width: 100%;
+
+    padding: 0;
+
+    overflow: auto;
+  }
+
+  .submit {
+    margin: 10px 0;
+  }
+}

data/app/assets/stylesheets/commontator/comments.scss

@@ -0,0 +1,103 @@
+.commontator .comment {
+  &, .body blockquote {
+    border: none;
+    border-top: 1px solid;
+    border-left: 1px solid;
+
+    font-weight: normal;
+    color: #000;
+  }
+
+  & {
+    clear: both;
+
+    margin: 15px 0;
+    border-color: #DDD;
+    padding: 0;
+
+    font-style: normal;
+  }
+
+  .section {
+  	clear: both;
+
+    margin: 5px 7px;
+  }
+
+  .author {
+    font-size: 110%;
+  }
+
+  .actions {
+    font-size: 90%;
+  }
+
+  .avatar {
+    float: left;
+
+    margin-right: 7px;
+  }
+
+  .votes {
+    float: right;
+
+    margin-left: 7px;
+
+    text-align: center;
+
+    input, img {
+      background-color: transparent;
+    }
+  }
+
+  .upvote, .downvote {
+    display: block;
+
+    height: 18px;
+
+    margin: 5px 0;
+  }
+
+  .like {
+    float: left;
+
+    margin: 0 5px;
+  }
+
+  .vote-count {
+    font-size: 110%;
+  }
+
+  .body {
+    overflow: hidden;
+
+    blockquote {
+      border-color: #CCC;
+      padding: 5px 7px;
+
+      background-color: #EEE;
+
+      font-style: italic;
+    }
+  }
+
+  .reply, .timestamp {
+    font-size: 90%;
+  }
+
+  .timestamp {
+    color: #666;
+  }
+
+  .error-explanation {
+    margin-bottom: 10px;
+
+    h3 {
+      margin-top: 5px;
+    }
+
+    ul {
+      list-style-position: inside;
+    }
+  }
+}