fuck_comments 2.3.4

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

data/docs/routes.md

@@ -0,0 +1,77 @@
+←   [documentation](documentation.md)
+
+## TheComments 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
+```
+
+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_path
+= link_to 'link', manage_comments_path
+= link_to 'link', new_comment_path
+
+= link_to 'link', comment_path(@comment)
+= link_to 'link', to_spam_comment_path(@comment)
+```
+
+### Way 2. Array notation
+
+```ruby
+= link_to 'link', [:index,  :comments]
+= link_to 'link', [:manage, :comments]
+= link_to 'link', [:draft,  :comments]
+
+= link_to 'link', [@comment]
+= link_to 'link', [:to_spam, @comment]
+```

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