the_comments 1.1.0 → 2.0.0

data/docs/commentable_api.md

@@ -0,0 +1,59 @@
+←   [documentation](documentation.md)
+
+### Commentable API
+
+```ruby
+class Post < ActiveRecord::Base
+  include TheCommentsCommentable
+
+  belongs_to :user
+
+  def commentable_title
+    try(:title) || "Undefined title" 
+  end
+
+  def commentable_url
+    ['', self.class.to_s.tableize, id].join('/')
+  end
+
+  def commentable_state
+    try(:state) || "published"
+  end
+end
+```
+
+```ruby
+@post = Post.last
+
+# Post owner
+@post.user # => User
+
+# All comments for commentable object
+@post.comments # => ActiveRecord:Collection
+
+# Cache counters
+@post.draft_comments_count      # => 1
+@post.published_comments_count  # => 2
+@post.deleted_comments_count    # => 0
+
+# equal values with direct request to database
+@post.comments.with_state([:draft]).count      # => 1
+@post.comments.with_state([:published]).count  # => 2
+@post.comments.with_state([:deleted]).count    # => 0
+
+# Alias for:
+# draft_comments_count + published_comments_count
+@post.comments_sum # => 3
+
+# Spam comments
+@post.comments.where(spam: true) # => ActiveRecord::Relation
+
+# recalculate cache counters
+@post.recalculate_comments_counters!
+
+# Default Denormalization methods
+# should be redefined by developer
+@post.commentable_title   => "Maiores eos rerum numquam aut."
+@post.commentable_url     => "/posts/9"
+@post.commentable_state   => "published"
+```

data/docs/config_file.md

@@ -0,0 +1,27 @@
+←   [documentation](documentation.md)
+
+### TheComments config
+
+Following rails generator will copy default config file into your application
+
+```ruby
+bundle exec rails g the_comments config
+```
+
+**config/initializers/the_comments.rb**
+
+```ruby
+# TheComments.config.param_name => value
+
+TheComments.configure do |config|
+  config.max_reply_depth     = 3                 # comments tree depth
+  config.tolerance_time      = 5                 # sec - after this delay user can post a comment
+  config.default_state       = :draft            # default state for comment
+  config.default_owner_state = :published        # default state for comment for Moderator
+  config.empty_inputs        = [:commentBody]    # array of spam trap fields
+  config.default_title       = 'Undefined title' # default commentable_title for denormalization
+
+  config.empty_trap_protection     = true
+  config.tolerance_time_protection = true
+end
+```

data/docs/content_preprocessors.md

@@ -0,0 +1,73 @@
+←   [documentation](documentation.md)
+
+### Text preprocessors
+
+TheComments designed for using with text preprocessors: Textile, Markdown, Sanitize, Coderay etc.
+
+That is why Comment model has 2 fields for user input: **raw_content** and **content**
+
+```ruby
+class CreateComments < ActiveRecord::Migration
+  def change
+    create_table :comments do |t|
+    # ...
+    
+    t.text :raw_content
+    t.text :content
+      
+    # ...
+    end
+  end
+end
+```
+
+**raw_content** - field with original user's input
+
+**content** - field with processed user's input
+
+<hr>
+
+**before_save :prepare_content** - provides processing of raw user's input
+
+By default **prepare_content** looks like this:
+
+```ruby
+  def prepare_content
+    self.content = self.raw_content
+  end
+```
+
+I think every developer should redefine this behaviour. To do this you should to use following instructions.
+
+### Comment Model customization
+
+invoke TheComments generator
+
+```ruby
+bundle exec rails g the_comments models
+```
+
+This will create **app/models/comment.rb**
+
+```ruby
+class Comment < ActiveRecord::Base
+  include TheCommentsBase
+
+  # ---------------------------------------------------
+  # Define your filters for content
+  # Expample for: gem 'RedCloth', gem 'sanitize'
+  # your personal SmilesProcessor
+
+  # def prepare_content
+  # text = self.raw_content
+  # text = RedCloth.new(text).to_html
+  # text = SmilesProcessor.new(text)
+  # text = Sanitize.clean(text, Sanitize::Config::RELAXED)
+  # self.content = text
+  # end
+  # ---------------------------------------------------
+end
+```
+
+Just redefine **prepare_content** for your purposes
+

data/docs/customazation_of_views.md

@@ -0,0 +1,30 @@
+←   [documentation](documentation.md)
+
+## Customization
+
+You can use **rails generators** for copy files into your Application. After that you can customize almost everything
+
+Generators list:
+
+```ruby
+bundle exec rails g the_comments --help
+```
+
+### Customization of views
+
+Copy View files for customization:
+
+```ruby
+bundle exec rails g the_comments:views assets
+bundle exec rails g the_comments:views views
+```
+
+### Customization of comments tree
+
+Copy Helper file for tree customization:
+
+```ruby
+bundle exec rails g the_comments:views helper
+```
+
+For more info read [TheSortableTree doc](https://github.com/the-teacher/the_sortable_tree)

data/docs/denormalization_and_recent_comments.md

@@ -0,0 +1,40 @@
+←   [documentation](documentation.md)
+
+## Denormalization
+
+For building of Recent comments list (for polymorphic relationship) we need to have many additional requests to database. It's classic problem of polymorphic comments.
+
+I use denormalization of commentable objects to solve this problem.
+
+My practice shows - We need 3 denormalized fields into comment for (request-free) building of recent comments list:
+
+<img src="https://raw.github.com/the-teacher/the_comments/master/docs/the_comments_view_5.gif" alt="the_comments">
+
+* **Comment#commentable_title** - for example: "My first post about Ruby On Rails"
+* **Comment#commentable_url** - for example: "/posts/1-my-first-post-about-ruby-on-rails"
+* **Comment#commentable_state** - for example: "draft"
+
+That is why any **Commentable Model should have few methods** to provide denormalization for Comments.
+
+## Recent comments building
+
+Denormalization makes building of Recent comments (for polymorphic relationship) very easy!
+
+Controller:
+
+```ruby
+@comments = Comment.with_state(:published)
+                   .where(commentable_state: [:published])
+                   .order('created_at DESC')
+                   .page(params[:page])
+```
+
+View:
+
+```ruby
+- @comments.each do |comment|
+  %div
+    %p= comment.commentable_title
+    %p= link_to comment.commentable_title, comment.commentable_url
+    %p= comment.content
+```

data/docs/documentation.md

@@ -0,0 +1,28 @@
+#### INSTALLATION
+* :white_check_mark:   [ADVANCED INSTALLATION](advanced_installation.md)
+* :white_check_mark:   [ADMIN UI INSTALLATION](admin_ui_installation.md)
+* :white_check_mark:   [Mountable Routing](mountable_routes.md)
+
+#### API
+* :white_check_mark:   [User API](user_api.md)
+* :white_check_mark:   [Comment API](comment_api.md)
+* :white_check_mark:   [Commentable API](commentable_api.md)
+
+#### Understanding
+* :white_check_mark:   [What is ComComs?](what_is_comcoms.md)
+* :white_check_mark:   [Denormalization and Recent comments](denormalization_and_recent_comments.md)
+* :white_check_mark:   [What's wrong with other gems?](whats_wrong_with_other_gems.md)
+* :white_check_mark:   [Why TheComments is better than others gems?](whats_wrong_with_other_gems.md#why-thecomments-is-better-than-others-gems)
+
+#### Customazation
+* :white_check_mark:   [Views](customazation_of_views.md)
+* :white_check_mark:   [Text Preprocessors - Sanitize, Markdown etc.](content_preprocessors.md)
+
+#### Configuration
+* :white_check_mark:   [the_comments.rb config file](config_file.md)
+
+#### Q&A
+* :white_check_mark:   [I want not to use kaminari for Admin UI](pagination.md)
+* :white_check_mark:   [Where is example application?](where_is_example_application.md)
+* :white_check_mark:   [How can I run tests?](where_is_example_application.md#run-tests)
+

data/docs/mountable_routes.md

@@ -0,0 +1,80 @@
+←   [documentation](documentation.md)
+
+## Mountable Routes
+
+Now gem has mountable routes. It's was not my idea, but guys said - it's very helpful. So, ok!
+
+You should mount routes to your app.
+
+:warning:   Default views based on **as: :comments** argument. If, you want to change it - you should customize default views.
+
+**config/routes.rb**
+
+```ruby
+MyApp::Application.routes.draw do
+  root 'posts#index'
+  resources :posts
+
+  # ...
+
+  mount TheComments::Engine => '/', as: :comments
+end
+```
+
+And after that you can see routes:
+
+```ruby
+rake routes | grep comments
+```
+
+```ruby
+ comments        /                         TheComments::Engine
+         to_spam_comment POST   /comments/:id/to_spam(.:format)      comments#to_spam
+        to_draft_comment POST   /comments/:id/to_draft(.:format)     comments#to_draft
+    to_published_comment POST   /comments/:id/to_published(.:format) comments#to_published
+      to_deleted_comment DELETE /comments/:id/to_deleted(.:format)   comments#to_deleted
+         manage_comments GET    /comments/manage(.:format)           comments#manage
+       my_draft_comments GET    /comments/my_draft(.:format)         comments#my_draft
+   my_published_comments GET    /comments/my_published(.:format)     comments#my_published
+    my_comments_comments GET    /comments/my_comments(.:format)      comments#my_comments
+    total_draft_comments GET    /comments/total_draft(.:format)      comments#total_draft
+total_published_comments GET    /comments/total_published(.:format)  comments#total_published
+  total_deleted_comments GET    /comments/total_deleted(.:format)    comments#total_deleted
+     total_spam_comments GET    /comments/total_spam(.:format)       comments#total_spam
+          draft_comments GET    /comments/draft(.:format)            comments#draft
+      published_comments GET    /comments/published(.:format)        comments#published
+        deleted_comments GET    /comments/deleted(.:format)          comments#deleted
+           spam_comments GET    /comments/spam(.:format)             comments#spam
+                comments GET    /comments(.:format)                  comments#index
+                         POST   /comments(.:format)                  comments#create
+             new_comment GET    /comments/new(.:format)              comments#new
+            edit_comment GET    /comments/:id/edit(.:format)         comments#edit
+                 comment GET    /comments/:id(.:format)              comments#show
+                         PATCH  /comments/:id(.:format)              comments#update
+                         PUT    /comments/:id(.:format)              comments#update
+                         DELETE /comments/:id(.:format)              comments#destroy
+```
+
+And now you can use url helpers with 2 ways:
+
+### Way 1. Url Helpers
+
+```ruby
+= link_to 'link', comments.comments_path
+= link_to 'link', comments.manage_comments_path
+= link_to 'link', comments.new_comment_path
+
+= link_to 'link', comments.comment_path(@comment)
+= link_to 'link', comments.to_spam_comment_path(@comment)
+```
+
+### Way 2. Array notation
+
+```ruby
+= link_to 'link', [comments, :index]
+= link_to 'link', [comments, :manage]
+= link_to 'link', [comments, :new]
+
+= link_to 'link', [comments, @comment]
+= link_to 'link', [comments, :to_spam, @comment]
+```

data/docs/pagination.md

@@ -0,0 +1,123 @@
+←   [documentation](documentation.md)
+
+## I want not to use kaminari for Admin UI
+
+By default we use Kaminari pagination for Admin UI.
+
+But you can change this. For example, your **comments_controller.rb** looks like this:
+
+**app/controllers/comments_controller.rb**
+
+```ruby
+class CommentsController < ApplicationController
+  # layout 'admin'
+
+  # Define your restrict methods and use them like this:
+  #
+  # before_action :user_required,  except: %w[index create]
+  # before_action :owner_required, except: %w[index create]
+  # before_action :admin_required, only:   %w[total_draft total_published total_deleted total_spam]
+  
+  include TheComments::Controller
+
+  # >>> include TheComments::Controller <<<
+  # (!) Almost all methods based on *current_user* method
+  #
+  # 1. Controller's public methods list:
+  # You can redifine it for your purposes
+  # public
+  # %w[ manage index create edit update ]
+  # %w[ my_comments my_draft my_published ]
+  # %w[ draft published deleted spam ]
+  # %w[ to_draft to_published to_deleted to_spam ]
+  # %w[ total_draft total_published total_deleted total_spam ]
+  #
+  #
+  # 2. Controller's private methods list:
+  # You can redifine it for your purposes
+  #
+  # private
+  # %w[ comment_template comment_partial ]
+  # %w[ denormalized_fields request_data_for_comment define_commentable ]
+  # %w[ comment_params patch_comment_params ]
+  # %w[ ajax_requests_required cookies_required ]
+  # %w[ empty_trap_required tolerance_time_required ]
+
+  # KAMINARI pagination:
+  # following methods based on gem "kaminari"
+  # You should redefine them if you use something else
+  #
+  # public
+  # %w[ manage index edit ]
+  # %w[ draft published deleted spam ]
+  # %w[ my_comments my_draft my_published ]
+  # %w[ total_draft total_published total_deleted total_spam ]
+end
+```
+
+There is we can see comments about kaminari. So, we can try to change it.
+
+There is example how it can be in your real app:
+
+```ruby
+class CommentsController < ApplicationController
+  layout 'admin'
+
+  before_action :user_required,  except: %w[index create]
+  before_action :owner_required, except: %w[index create]
+  before_action :admin_required, only:   %w[total_draft total_published total_deleted total_spam]
+  
+  include TheComments::Controller
+
+  public
+
+    def index
+      @comments = ::Comment.with_state(:published).recent.super_paginator(params)
+      render comment_template(:index)
+    end
+
+    def manage
+      @comments = current_user.comcoms.active.recent.super_paginator(params)
+      render comment_template(:manage)
+    end
+
+    def my_comments
+      @comments = current_user.my_comments.active.recent.super_paginator(params)
+      render comment_template(:my_comments)
+    end
+
+    def edit
+      @comments = current_user.comcoms.where(id: params[:id]).super_paginator(params)
+      render comment_template(:manage)
+    end
+
+    %w[draft published deleted].each do |state|
+      define_method "#{state}" do
+        @comments = current_user.comcoms.with_state(state).recent.super_paginator(params)
+        render comment_template(:manage)
+      end
+
+      define_method "total_#{state}" do
+        @comments = ::Comment.with_state(state).recent.super_paginator(params)
+        render comment_template(:manage)
+      end
+
+      unless state == 'deleted'
+        define_method "my_#{state}" do
+          @comments = current_user.my_comments.with_state(state).recent.super_paginator(params)
+          render comment_template(:my_comments)
+        end
+      end
+    end
+
+    def spam
+      @comments = current_user.comcoms.where(spam: true).recent.super_paginator(params)
+      render comment_template(:manage)
+    end
+
+    def total_spam
+      @comments = ::Comment.where(spam: true).recent.super_paginator(params)
+      render comment_template(:manage)
+    end
+end
+```

data/docs/user_api.md

@@ -0,0 +1,75 @@
+←   [documentation](documentation.md)
+
+### User API
+
+**When User is not commentable model**
+
+```ruby
+class User < ActiveRecord::Base
+  include TheCommentsUser
+
+  has_many :posts     # commentable model
+  has_many :products  # commentable model
+end
+```
+
+:warning: &nbsp; Please, read this: [What is ComComs?](what_is_comcoms.md)
+
+
+We can use following methods
+
+```ruby
+@user = User.first
+
+@user.comcoms #=> all comments for posts and products, where user is owner
+
+# cache counters
+@user.draft_comcoms_count     # => 1
+@user.published_comcoms_count # => 5
+@user.deleted_comcoms_count   # => 3
+@user.spam_comcoms_count      # => 2
+
+# equal values, but with request to database
+@user.comcoms.with_state([:draft]).count      # => 1
+@user.comcoms.with_state([:published]).count  # => 5
+@user.comcoms.with_state([:deleted]).count    # => 3
+@user.comcoms.where(spam: true).count         # => 2
+
+# draft and published comments
+# written by this user
+@user.my_comments  # => ActiveRecord::Relation
+
+# cache counters for comments
+# written by this user
+# there is no cache counter for deleted state!
+@user.my_draft_comments_count         # => 3
+@user.my_published_comments_count     # => 7
+
+# equal values, but with request to database
+@user.my_draft_comments.count       # => 3
+@user.my_published_comments.count   # => 7
+@user.my_deleted_comments.count     # => 1
+
+# helper methods to get comments
+# written by this user
+@user.my_draft_comments      # => ActiveRecord::Relation
+@user.my_published_comments  # => ActiveRecord::Relation
+@user.my_deleted_comments    # => ActiveRecord::Relation
+
+# recalculate cache counters
+@user.recalculate_my_comments_counter!
+```
+
+**When User is commentable model**
+
+```ruby
+class User < ActiveRecord::Base
+  include TheCommentsUser
+  include TheCommentsCommentable
+
+  has_many :posts     # commentable model
+  has_many :products  # commentable model
+end
+```
+
+you should to use following instruction [Commentable API](commentable_api.md)

data/docs/what_is_comcoms.md

@@ -0,0 +1,63 @@
+←   [documentation](documentation.md)
+
+### What is ComComs?
+
+:warning:   **comcoms** - is main method to get all comments related with user's commentable models.
+
+:warning:   **comments** - is main method to get comments related with any commentable model.
+
+**ComComs** - **com**ments of **com**mentable models
+
+ComComs are all incoming comments for all models, where this user is owner.
+
+For example, some user **has_many :posts**, and  **has_many :products** - all comments for all user's posts and all user's products called as **comcoms**.
+
+#### Why we need ComComs?
+
+User model can be commentable too. For example to build user's "public wall" (like tweets list for current user).
+
+And we should to separate **comments** attached to user model (tweets) and comments attached to any another user's model.
+
+That is why User model in-fact has following relationship declarations:
+
+```ruby
+class User < ActiveRecord::Base
+  has_many :comcoms, class_name: :Comment, foreign_key: :holder_id
+  
+  # and if User model is commentable model
+  # has_many :comments, as: :commentable
+  
+  has_many :posts
+  has_many :products
+end
+```
+
+in real application it should be described like this:
+
+```ruby
+class User < ActiveRecord::Base
+  include TheCommentsUser
+  include TheCommentsCommentable
+  
+  has_many :posts
+  has_many :products
+end
+```
+
+But in most popular situation User model should not be commentable, and you should use only **comcoms** method to get all comments related with this user:
+
+```ruby
+class User < ActiveRecord::Base
+  include TheCommentsUser
+
+  has_many :posts
+  has_many :products
+end
+```
+
+and later in your application
+
+```ruby
+@user = User.find params[:id]
+@user.comcoms.count # => 42
+```

data/docs/whats_wrong_with_other_gems.md

@@ -0,0 +1,18 @@
+←   [documentation](documentation.md)
+
+### What's wrong with other gems?
+
+Just look at [Ruby-Toolbox](https://www.ruby-toolbox.com/categories/rails_comments). What we can see?
+
+* [Acts as commentable with threading](https://github.com/elight/acts_as_commentable_with_threading) - so, guys, where is the render helper for the tree? There is no helper! Should  I make render helper for tree by myself? Nooooo!!! I'm so sorry, but I can't use this gem. 
+* [acts_as_commentable](https://github.com/jackdempsey/acts_as_commentable) - so, I can see code for models. But I can't see code for controllers and views. Unfortunately, there is no threading. It's not enough for me.
+* [opinio](https://github.com/Draiken/opinio) - looks better, but there is no threading. I want to have more!
+* [has_threaded_comments](https://github.com/aarongough/has_threaded_comments) - Nice work! Nice gem! Models, controllers, views, view helper for tree rendering! **But**, last activity 2 years ago, I need few features, I think - I can make it better.
+
+### Why TheComments is better than others gems?
+
+1. Only TheComments has special helper for tree rendering ([TheSortableTree](https://github.com/the-teacher/the_sortable_tree)).
+2. TheComments designed to reduce requests to database. I say about useful cache counters.
+3. TheComments has solution for [building of Recent Comments](https://github.com/the-teacher/the_comments/blob/master/docs/denormalization_and_recent_comments.md) (for polymorphic relations)
+4. TheComments designed for text preprocessors (Textile, Markdown, Sanitize, Coderay etc.)
+5. TheComments has admin UI based on bootstrap 3

data/docs/where_is_example_application.md

@@ -0,0 +1,37 @@
+←   [documentation](documentation.md)
+
+### Dummy Application
+
+Repo of TheComments has dummy application for developmet and testing.
+
+It's here: [Dummy App](https://github.com/the-teacher/the_comments/tree/master/spec/dummy_app)
+
+For run dummy app, your should do that:
+
+```ruby
+git clone https://github.com/the-teacher/the_comments.git
+
+cd the_comments/spec/dummy_app/
+
+bundle
+
+rake db:bootstrap_and_seed
+
+rails s -p 3000 -b localhost
+```
+
+### Run tests
+
+Following instructions should helps to run simple tests:
+
+```ruby
+git clone https://github.com/the-teacher/the_comments.git
+
+cd the_comments/spec/dummy_app/
+
+bundle
+
+rake db:bootstrap RAILS_ENV=test
+
+rspec --format documentation
+```

data/gem_version.rb

@@ -0,0 +1,3 @@
+module TheComments
+  VERSION = "2.0.0"
+end