the_comments_ruby 2.3.3

data/docs/advanced_installation.md

@@ -0,0 +1,185 @@
+←   [documentation](documentation.md)
+
+## Advanced Installation
+
+### 1. Gems install
+
+**Gemfile**
+
+```ruby
+gem 'the_comments', "~> 2.0"
+
+gem 'haml'                # or gem 'slim'
+gem 'awesome_nested_set'  # or same gem
+```
+
+**Bundle**
+
+```
+bundle
+```
+
+### 2. Migrations install
+
+**Copy migrations**
+
+```
+rake the_comments_engine:install:migrations
+```
+
+Will create:
+
+* xxxxx_change_user.rb
+* xxxxx_create_comments.rb
+* xxxxx_change_commentable.rb
+
+:warning:   **Open and change xxxxx_change_commentable.rb migration**
+
+```ruby
+class ChangeCommentable < ActiveRecord::Migration
+  def change
+    # Additional fields to Commentable Models
+    # [:posts, :articles, ... ]
+
+    # There is only Post model is commentable
+    [:posts].each do |table_name|
+      change_table table_name do |t|
+        t.integer :draft_comments_count,     default: 0
+        t.integer :published_comments_count, default: 0
+        t.integer :deleted_comments_count,   default: 0
+      end
+    end
+  end
+end
+```
+
+**Invoke migrations**
+
+```
+rake db:migrate
+```
+
+### 3. Code install
+
+```ruby
+rails g the_comments install
+```
+
+Will create:
+
+* config/initializers/the_comments.rb
+* app/controllers/comments_controller.rb
+* app/models/comment.rb
+ 
+:warning: &nbsp; **Open each file and follow an instructions**
+
+### 4. Models modifictions
+
+**app/models/user.rb**
+
+```ruby
+class User < ActiveRecord::Base
+  include TheComments::User
+
+  has_many :posts
+
+  # Your way to define privileged users
+  def admin?
+    self == User.first
+  end
+
+  # Required TheComments methods for users restrictions
+  def comments_admin?
+    admin?
+  end
+
+  def comments_moderator? comment
+    id == comment.holder_id
+  end
+end
+```
+
+**app/models/post.rb**
+
+```ruby
+class Post < ActiveRecord::Base
+  include TheComments::Commentable
+
+  belongs_to :user
+
+  # Denormalization methods
+  # Migration: t.string :title
+  # => "My new awesome post"
+  def commentable_title
+    try(:title) || "Undefined post title"
+  end
+
+  # => your way to build URL
+  # => "/posts/254"
+  def commentable_url
+    ['', self.class.to_s.tableize, id].join('/')
+  end
+
+  # gem 'state_machine'
+  # Migration: t.string :state
+  # => "published" | "draft" | "deleted"
+  def commentable_state
+    try(:state) || "published"
+  end
+end
+```
+
+### 5. Mount Engine routes
+
+**config/routes.rb**
+
+```ruby
+MyApp::Application.routes.draw do
+  root 'posts#index'
+  resources :posts
+
+  # ...
+
+  # TheComments routes
+  concern   :user_comments,  TheComments::UserRoutes.new
+  concern   :admin_comments, TheComments::AdminRoutes.new
+  resources :comments, concerns:  [:user_comments, :admin_comments]
+end
+```
+
+Please, read [documentation](docs/documentation.md) to learn more
+
+### 6. Assets install
+
+**app/assets/stylesheets/application.css**
+
+```css
+/*
+ *= require the_comments
+*/
+```
+
+**app/assets/javascripts/application.js**
+
+```js
+//= require the_comments
+```
+
+### 7. Controller code example
+
+**app/controllers/posts_controllers.rb**
+
+```ruby
+def show
+  @post     = Post.find params[:id]
+  @comments = @post.comments.with_state([:draft, :published])
+end
+```
+
+### 8. View code example
+
+**app/views/posts/show.html.haml**
+
+```haml
+= render partial: 'the_comments/tree', locals: { commentable: @post, comments_tree: @comments }
+```

data/docs/comment_api.md

@@ -0,0 +1,58 @@
+←   [documentation](documentation.md)
+
+### Comment API
+
+```ruby
+@comment = Comment.last
+
+# Comment creator, can be nil (for Guest)
+@comment.user # => User
+
+# Comment holder
+# Owner of commentable object
+# shouldn't be nil, should be defined on create
+@comment.holder  # => User
+
+# Commentable object
+@comment.commentable # => Post
+
+# Raw user input
+@comment.raw_content
+
+# Processed user input
+# method *prepare_content* should be redefined by developer
+@comment.content
+
+# Denormalization fields
+@comment.commentable_title  # => "Harum sint error odit."
+@comment.commentable_url    # => "/posts/7"
+@comment.commentable_state  # => "published"
+
+# Stat info from request
+# Can be used for spam detection
+@comment.user_agent       # => Opera/9.80 (Windows NT 5.1; U; en) Presto/2.2.15 Version/10.10 
+@comment.tolerance_time   # => 5 (secs)
+@comment.referer          # => localhost:3000/post/7
+@comment.ip               # => 192.168.0.12
+
+# State
+@comment.state # => draft | published | deleted
+
+# Spam flag
+@comment.spam # => true
+
+# Alias for *mark_as_spam*
+@comment.to_spam
+
+# mark this comment and all descendants as spam/not spam
+@comment.mark_as_spam
+@comment.mark_as_not_spam
+
+# Comment's creator avatar
+# this method can be redefined by developer
+@comment.avatar_url # => "https://2.gravatar.com/avatar/015e ... 2f05?s=42&d=https://identicons.github.com/AVATAR.png" 
+
+# Anchor of comment
+# this method can be redefined by developer
+@comment.anchor # => b58020
+```

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,29 @@
+#### INSTALLATION
+* :white_check_mark:   [ADVANCED INSTALLATION](advanced_installation.md)
+* :white_check_mark:   [ADMIN UI INSTALLATION](admin_ui_installation.md)
+* :white_check_mark:   [Routing](routes.md)
+* :white_check_mark:   [Generators](generators.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/generators.md

@@ -0,0 +1,74 @@
+←   [documentation](documentation.md)
+
+## Generators
+
+```ruby
+rails g the_comments NAME
+rails g the_comments:views NAME
+```
+
+#### Migrations
+
+```ruby
+rake the_comments_engine:install:migrations
+```
+
+### Full list
+
+```ruby
+rails g the_comments --help
+```
+
+#### Main
+
+```ruby
+rails g the_comments install
+```
+
+This will create:
+
+* config/initializers/the_comments.rb
+* app/controllers/comments_controller.rb
+* app/models/comment.rb
+
+#### Controllers
+
+```ruby
+rails g the_comments controllers
+```
+
+This will create:
+
+* app/controllers/comments_controller.rb
+
+#### Models
+
+```ruby
+rails g the_comments models
+```
+
+This will create:
+
+* app/models/comment.rb
+
+#### Config
+
+```ruby
+rails g the_comments config
+```
+
+#### Locals
+
+```ruby
+rails g the_comments locales
+```
+
+#### Views
+
+```ruby
+rails g the_comments:views js
+rails g the_comments:views css
+rails g the_comments:views assets
+rails g the_comments:views helper
+rails g the_comments:views views
+```

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
+```