= Inkwell
=======

Inkwell добавляет в ваше приложение возможности социальных сетей - комментарии, избранное, реблоги (репост/share), систему подписок на блоги юзеров (followers) и ленты пользователей (ленты блогов, избранного и агрегированную ленту с постами и реблогами юзеров, на которых подписан пользователь).

== Требования
У вас должны быть два класса: <code>User</code> и <code>Post</code> или похожие на них по назначению. Они должны быть связаны один-ко-многим. Пример:

  class User < ActiveRecord::Base
    has_many :posts
  end

  class Post < ActiveRecord::Base
    belongs_to :user
  end

== Установка и настройка

Добавьте в <code>Gemfile</code>:

  gem 'inkwell', :git => 'git://github.com/salkar/inkwell.git'


После этого сделайте <code>bundle install</code>

Добавьте в вашу <code>User</code> модель <code>acts_as_inkwell_user</code> и в <code>Post</code> модель <code>acts_as_inkwell_post</code>

  class User < ActiveRecord::Base
    has_many :posts
    acts_as_inkwell_user
  end
  
  class Post < ActiveRecord::Base
    belongs_to :user
    acts_as_inkwell_post
  end

Создайте <code>inkwell.rb</code> файл в <code>config/initializers</code> и добавьте туда следующий код с названиями таблиц <code>User</code> и <code>Post</code> (или соответствующих им):

  module Inkwell
    class Engine < Rails::Engine
      config.post_table = :posts
      config.user_table = :users
    end
  end

Далее, сделайте

  rake inkwell:install:migrations

и <code>db:migrate</code>.

== Использование

=== Избранное

Юзер может добавлять в избранное как посты, так и комментарии:

  @user.favorite @post
  @user.favorite @comment

Удаление из избранного:

  @user.unfavorite @post

Проверка на нахождение в избранном:

  @user.favorite? @post

Вы можете получить ленту избранного для пользователя, состоящую из добавленных им в избранное постов и комментариев (последние добавленные сверху):

  @user.favoriteline(:last_shown_obj_id => nil, :limit => 10, :for_user => nil)

где
* <code>last_shown_obj_id</code> - id последнего элемента уже показанной юзеру ленты. Взять его можно из <code>item_id_in_line</code> свойства последнего объекта из предыдущей ленты избранного. Этот параметр нужен для того, чтобы забрать часть ленты, начиная со следующего поста за указанным. Например:

    fline = @user.favoriteline    #забрать первые 10 элементов ленты избранного юзера @user
    last_shown_obj_id = fline.last.item_id_in_line
    fline_next_page = @user.favoriteline :last_shown_obj_id => last_shown_obj_id    #забрать следующие 10 элементов его ленты

* <code>limit</code> - количество элементов возвращаемой ленты, по дефолту - 10

    fline = @user.favoriteline :limit => 20    #забрать первые 20 элементов ленты избранного юзера @user

* <code>for_user</code> - <code>User</code>, для которого показывается эта лента. Для него формируются свойства <code>is_reblogged</code> и <code>is_favorited</code>, которые обозначают, добавлял ли этот юзер в избранное этот элемент или делал ли его реблог. 
  
    @user.favorite @another_user_post
    @user.reblog @another_user_post
      
    fline_for_unknown_user = @another_user.favoriteline
    # Для примера предположим, что fline_for_unknown_user.first == @another_user_post
    fline_for_unknown_user.first.is_reblogged    # => false
    fline_for_unknown_user.first.is_favorited    # => false
        
    fline_for_user_who_reblog_and_favorite_another_user_post = @another_user.favoriteline :for_user => @user
    # Для примера предположим, что fline_for_user_who_reblog_and_favorite_another_user_post.first == @another_user_post
    fline_for_user_who_reblog_and_favorite_another_user_post.first.is_reblogged    # => true
    fline_for_user_who_reblog_and_favorite_another_user_post.first.is_favorited    # => true

Больше примеров можно найти в этом спеке[https://github.com/salkar/inkwell/blob/master/test/dummy/spec/functional/favorite_spec.rb].

=== Реблоги (репосты)

Реблог подразумевает под собой, что элемент попадет в блог самого юзера и в ленты новостей его подписчиков. Таким образом, его поведение будет аналогично поведению поста самого юзера, за исключением того, что это не его пост.
Юзер может сделать реблог как поста, так и комментария:

  @user.reblog @post
  @user.reblog @comment

Отмена реблога:

  @user.unreblog @post

Проверка на наличие реблога элемента:

  @user.reblog? @post

У реблогов нет своей ленты, они показываются в самом блоге пользователя (ленте с его постами).

Больше примеров можно нати в этом спеке[https://github.com/salkar/inkwell/blob/master/test/dummy/spec/functional/reblog_spec.rb].

=== Комментарии

Юзер может комментировать пост или другой комментарий. Комментарий для поста создается так:

  @user.create_comment :for_object => @post, :body => "comment_body"

Если вы хотите создать комментарий для другого комментария, необходимо добавить <code>parent_comment_id</code> родительского комментария:

  @user.create_comment :for_object => @parent_post, :body => "comment_body", :parent_comment_id => @parent_comment.id

Для удаления комментария используйте <code>destroy</code> метод:

  @comment.destroy

Вы можете получить ленту комментариев как для поста, так и для комментария. Она состоит из комментариев данного объекта, возвращаемых в обратном хронологическом порядке.

<i>Примечание: возвращаемый массив для простоты использования будет иметь обратную сортировку. Это связано с тем, что обычно в соц. сетях последний комментарий находится внизу, а более старые комментарии располагаются выше.</i>

Для того, чтобы получить ленту комментариев, необходимо:

  commentline(:last_shown_comment_id => nil, :limit => 10, :for_user => nil)

где <code>last_shown_comment_id</code> - id последнего комментария для этого объекта из предыдущего вызова ленты комментариев. Например:

  cline = @post.commentline    #забираем первые 10 комментариев для @post
  last_shown_comment_id = cline.first.id    # Первый элемент берется из-за обратного порядка. По факту, это самый старый комментарий в <code>cline</code>.
  cline_next_page = @post.commentline :last_shown_comment_id => last_shown_comment_id    #забираем следующие 10 комментариев для @post

<code>Limit</code> и <code>for_user</code> обозначают тоже самое, что и одноименные параметры в favoriteline[https://github.com/salkar/inkwell/blob/master/README_RU.rdoc#%D0%98%D0%B7%D0%B1%D1%80%D0%B0%D0%BD%D0%BD%D0%BE%D0%B5].

Больше примеров вы можете найти в этом спеке[https://github.com/salkar/inkwell/blob/master/test/dummy/spec/functional/comments_spec.rb].

=== Подписки

Юзер может подписаться на другого юзера. При этом он будет видеть все его элементы блога (посты и реблоги) на своей новостной ленте.

Добавление в подписки:

  @user.follow @another_user

После этого последние 10 элементов блога <code>@another_user</code> появятся в новостной ленте у <code>@user</code>. Каждый новый элемент блога <code>@another_user</code> также будет добавляться в новостную ленту <code>@user</code>.

Удаление из подписок:

  @user.unfollow @another_user

Так можно проверить, подписан ли юзер на другого юзера:

  @user.follow? @another_user

Для получения id юзеров, на которых подписан пользователь, и которые подписаны на него, надо сделать так:

  @user.followers_row
  @user.followings_row

Оба метода возвращают массивы id.

Больше примеров вы можете найти в этом спеке[https://github.com/salkar/inkwell/blob/master/test/dummy/spec/functional/following_spec.rb].

=== Блог юзера

Блог юзера состоит из его постов и реблогов. Он реализован лентой, идентичной <code>favoriteline</code>. Получить его можно так:

  @user.blogline(:last_shown_obj_id => nil, :limit => 10, :for_user => nil)

где параметры идентичны описанным ранее <code>favoriteline</code> параметрам[https://github.com/salkar/inkwell/blob/master/README_RU.rdoc#%D0%98%D0%B7%D0%B1%D1%80%D0%B0%D0%BD%D0%BD%D0%BE%D0%B5].

Больше примеров вы можете найти в этом спеке[https://github.com/salkar/inkwell/blob/master/test/dummy/spec/functional/blogline_spec.rb].

=== Timeline feature

Новостная лента юзера состоит из элементов блогов юзеров, на которых этот юзер подписан. Получить ее можно так:

  @user.timeline(:last_shown_obj_id => nil, :limit => 10, :for_user => nil)

где параметры идентичные описанным ранее <code>favoriteline</code> параметрам[https://github.com/salkar/inkwell/blob/master/README_RU.rdoc#%D0%98%D0%B7%D0%B1%D1%80%D0%B0%D0%BD%D0%BD%D0%BE%D0%B5].

Больше примеров вы можете найти в этом спеке[https://github.com/salkar/inkwell/blob/master/test/dummy/spec/functional/timeline_spec.rb].