fuck_comments 2.3.4

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