the_comments 1.1.0 → 2.0.0

data/app/views/the_comments/slim/my_comments.html.slim

@@ -0,0 +1,28 @@
+- cuser = current_user
+
+- content_for :title do
+  = t "the_comments.management"
+
+- content_for :comments_sidebar do
+  = render partial: 'the_comments/slim/sidebar'
+
+- content_for :comments_main do
+  = paginate @comments
+
+  - if @comments.blank?
+    .alert.alert-info= t 'the_comments.no_comments_here'
+
+  .comments
+    - @comments.each do |comment|
+      - klass = { published: :primary, draft: :warning, deleted: :danger }[comment.state.to_sym]
+      .panel  class: "panel-#{klass}"  
+        .panel-heading= comment.title
+        .panel-body
+          = render partial: 'the_comments/slim/comment_body', locals: { comment: comment }
+          
+          - if cuser.comments_admin?
+            = render partial: 'the_comments/slim/comment_edit',    locals: { comment: comment }
+            = render partial: 'the_comments/slim/manage_controls', locals: { comment: comment }
+            = render partial: 'the_comments/slim/additional_info', locals: { comment: comment }
+        
+  = paginate @comments

data/{lib/generators/the_comments/templates → config/initializers}/the_comments.rb

@@ -7,4 +7,7 @@ TheComments.configure do |config|
   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/config/locales/en.yml

@@ -12,22 +12,26 @@ en:
               # blank: '%{attribute} should not be empty'
 
   the_comments:
-    trap: Trap
-    trap_message: should be empty
+    incoming: "Incoming:"
+    in_system: "In system:"
+    written_by_me: "Written by me:"
+    back_to_root: "← To root"
 
-    tolerance_time: Page view time
-    tolerance_time_message: "Please wait %{time} seconds before send a comment and try again"
+    my_comments:        "My comments (%{num})"
+    draft_comments:     "New (%{num})"
+    published_comments: "Published (%{num})"
+    deleted_comments:   "Deleted (%{num})"
+    spam_comments:      "Spam (%{num})"
 
-    cookies: Cookies
-    cookies_required: 'Please enable cookies and try to reload page'
+    management: Comments management
+    new: "New comment"
+    update: "Update comment"
+    additional_info: "Additional info"
+    cancel: "Cancel"
 
-    ajax_requests_required: 'Sorry, JavaScript/Ajax Requests required'
-
-    black_ip: Black IP adress
-    black_ip_message: Sorry! Your IP banned
-
-    black_user_agent: Black User Agent
-    black_user_agent_message: Sorry! Your User Agent banned
+    title: "Title on name:"
+    contacts: "Contacts:"
+    content: "Message:"
 
     guest_name: Guest
     reply: Reply to this comment
@@ -37,7 +41,28 @@ en:
     to_published: Publicate
     to_deleted:   Delete
 
+    no_comments_here: No comments here
+
+    nav:
+      header: "Navigation"
+
+    form:
+      title: "Your name:"
+      contacts: "Contacts (only admin can see this):"
+      content: "Comment* :"
+      create: "Submit comment"
+      thank_you:  "Thank you!"
+
+    trap: Trap
+    trap_message: should be empty
+
+    tolerance_time: Page view time
+    tolerance_time_message: "Please wait %{time} seconds before send a comment and try again"
+
     delete_confirm: Are you sure?
 
+    cookies: Cookies
+    cookies_required: 'Please enable cookies and try to reload page'
+    ajax_requests_required: 'Sorry, JavaScript/Ajax Requests required'
     waiting_for_moderation: Waiting for moderation
-    item_not_found: Black list Item not found
+    undefined_commentable: Commentable object is undefined

data/config/locales/ru.yml

@@ -0,0 +1,67 @@
+ru:
+  activerecord:
+    attributes:
+      comment:
+        raw_content: Содержимое
+    errors:
+      models:
+        comment:
+          attributes:
+            raw_content:
+              blank: 'Не может быть пустым'
+
+  the_comments:
+    incoming: "Входящие:"
+    in_system: "Все в системе:"
+    written_by_me: "Написанные мной:"
+    back_to_root: "← На главную"
+    
+    my_comments:        "Мои комментарии (%{num})"
+    draft_comments:     "Новые (%{num})"
+    published_comments: "Опубликованные (%{num})"
+    deleted_comments:   "Удаленные (%{num})"
+    spam_comments:      "Спам (%{num})"
+
+    management: Управление комментариями
+    new: "Написать новый комментарий"
+    update: "Обновить"
+    additional_info: "Подробнее"
+    cancel: "Отмена"
+
+    title: "Имя или тема:"
+    contacts: "Контакты:"
+    content: "Сообщение:"
+
+    guest_name: Гость
+    reply: Ответить на этот комментарий
+    edit: Править
+    to_spam: Спам!
+    to_draft: Черновик
+    to_published: Публиковать
+    to_deleted:   Удалить
+
+    no_comments_here: Здесь нет комментариев
+
+    nav:
+      header: "Навигация"
+
+    form:
+      title: "Ваше имя:"
+      contacts: "Контакты (не отображаются на сайте):"
+      content: "Текст комментария* :"
+      create: "Отправить комментарий"
+      thank_you:  "Спaсибо!"
+
+    trap: Ловушка
+    trap_message: Должна быть пустой
+
+    tolerance_time: Просмотр времени
+    tolerance_time_message: "Пожалуйста ожидайте %{time} сек. перед отправкой сообщения"
+
+    cookies: Куки
+    cookies_required: 'Включите куки и перезагрузите страницу'
+
+    delete_confirm: Вы уверены?
+    waiting_for_moderation: Ожидает модерации
+    ajax_requests_required: 'Извините, ожидается JavaScript/Ajax запрос'
+    undefined_commentable: Комментируемый объект не определен

data/config/routes.rb

@@ -1,24 +1,28 @@
-Rails.application.routes.draw do
-  resources :ip_black_lists do
-    patch :to_state
-  end
-
-  resources :user_agent_black_lists do 
-    patch :to_state
-  end
-
+TheComments::Engine.routes.draw do
   resources :comments do
     member do
       post   :to_spam
       post   :to_draft
       post   :to_published
-      delete :to_trash
+      delete :to_deleted
     end
 
     collection do
-      get :my
-      get :incoming
-      get :trash
+      get :manage
+
+      get :my_draft
+      get :my_published
+      get :my_comments
+
+      get :total_draft
+      get :total_published
+      get :total_deleted
+      get :total_spam
+
+      get :draft
+      get :published
+      get :deleted
+      get :spam
     end
   end
 end

data/db/migrate/20130101010101_change_user.rb

@@ -0,0 +1,18 @@
+# null: false => de-facto db-level validation
+class ChangeUser < ActiveRecord::Migration
+  def change
+    change_table :users do |t|
+      # "Written by me" (cache counters)
+      t.integer :my_draft_comments_count,      default: 0
+      t.integer :my_published_comments_count,  default: 0
+      t.integer :my_comments_count,            default: 0 # my_draft_comments_count + my_published_comments_count
+
+      # commentable's comments => comcoms (cache counters)
+      # Relation through Comment#holder_id field
+      t.integer :draft_comcoms_count,     default: 0
+      t.integer :published_comcoms_count, default: 0
+      t.integer :deleted_comcoms_count,   default: 0
+      t.integer :spam_comcoms_count,      default: 0
+    end
+  end
+end

data/db/migrate/20130101010102_create_comments.rb

@@ -0,0 +1,50 @@
+class CreateComments < ActiveRecord::Migration
+  def change
+    create_table :comments do |t|
+      # relations
+      t.integer :user_id
+      t.integer :holder_id
+      
+      # polymorphic, commentable object
+      t.integer :commentable_id
+      t.string  :commentable_type
+
+      # denormalization
+      t.string  :commentable_url
+      t.string  :commentable_title
+      t.string  :commentable_state
+
+      # comment
+      t.string :anchor
+      
+      t.string :title
+      t.string :contacts
+
+      t.text :raw_content
+      t.text :content
+
+      # moderation token
+      t.string :view_token
+
+      # state machine => :draft | :published | :deleted
+      t.string :state, default: :draft
+
+      # base user data (BanHammer power)
+      t.string  :ip,             default: :undefined
+      t.string  :referer,        default: :undefined
+      t.string  :user_agent,     default: :undefined
+      t.integer :tolerance_time
+
+      # unusable: for future versions
+      t.boolean :spam, default: false
+
+      # nested set
+      t.integer :parent_id
+      t.integer :lft
+      t.integer :rgt
+      t.integer :depth, default: 0
+
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20130101010103_change_commentable.rb

@@ -0,0 +1,13 @@
+class ChangeCommentable < ActiveRecord::Migration
+  def change
+    # Uncomment this. Add fields to Commentable Models
+    #
+    # [:users, :posts, :blogs, :articles, :pages].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

data/docs/admin_ui_installation.md

@@ -0,0 +1,145 @@
+←   [documentation](documentation.md)
+
+## Admin UI installation
+
+### 1. Gems install
+
+**Gemfile**
+
+```ruby
+# TheComments base
+gem 'the_comments', "~> 2.0"
+
+gem 'haml'                # or gem 'slim'
+gem 'awesome_nested_set'  # or same gem
+
+# TheComments Admin UI gems
+
+# pagination
+gem 'kaminari'
+
+# bootstrap 3
+gem 'bootstrap-sass', github: 'thomas-mcdonald/bootstrap-sass'
+```
+
+**Bundle**
+
+```
+bundle
+```
+
+### 2. Assets install
+
+**app/assets/stylesheets/admin_ui.css**
+
+```css
+/*
+*= require bootstrap
+*/
+```
+
+**app/assets/javascripts/admin_ui.js**
+
+```js
+//= require jquery
+//= require jquery_ujs
+
+//= require bootstrap
+//= require the_comments_manage
+```
+
+### 3. Admin layout
+
+You can use following yields to insert TheComments management tools in your Layout.
+
+```haml
+= yield :comments_sidebar
+= yield :comments_main
+```
+
+For example:
+
+```haml
+!!! 5
+%html(lang="en")
+  %head
+    %meta(charset="utf-8")
+    %meta(http-equiv="X-UA-Compatible" content="IE=Edge,chrome=1")
+    %meta(name="viewport" content="width=device-width, initial-scale=1.0")
+    %title= content_for?(:title) ? yield(:title) : "Admin Panel"
+    %link(href="favicon.ico" rel="shortcut icon")
+
+    = stylesheet_link_tag    :admin_ui
+    = javascript_include_tag :admin_ui
+    = csrf_meta_tags
+
+  %body
+    .container
+      .row
+        .col-md-12
+          %h3= content_for?(:title) ? yield(:title) : "Admin Panel"
+      .row
+        .col-md-3= yield :comments_sidebar
+        .col-md-9= yield :comments_main
+
+    = stylesheet_link_tag "//netdna.bootstrapcdn.com/font-awesome/3.2.1/css/font-awesome.min.css"
+```
+
+### 4. Comments controller modifications
+
+by default your comments controller 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
+```
+
+You must define protection methods to restrict access to Admin UI for regular users.
+
+### 5. Visit Admin UI
+
+**localhost:3000/comments/manage**

data/docs/advanced_installation.md

@@ -0,0 +1,182 @@
+←   [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
+
+  # ...
+
+  mount TheComments::Engine => '/', as: :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
+```