disqus_rails 0.0.5

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.rspec

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in disqus_rails.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Anton Kirichenko
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,296 @@
+# DisqusRails
+
+DisqusRails is a gem for including [Disqus](http://disqus.com/) service into Ruby on Rails application.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+  `gem 'disqus_rails'`
+
+And then execute:
+
+  `$ bundle`
+
+Or install it yourself as:
+
+  `$ gem install disqus_rails`
+
+And add to your javascript manifest file:
+
+  `//= require disqus_rails`
+
+## Usage
+### Getting started
+
+Create new initializer, lets say 'disqus_rails.rb' in config/initializers directory with this:
+```ruby
+DisqusRails.setup do |config|
+  config::SHORT_NAME = "your_short_name"
+  config::SECRET_KEY = "your_secret_disqus_key" #leave blank if not used
+  config::PUBLIC_KEY = "your public_disqus_key" #leave blank if not used
+  config::ACCESS_TOKEN = "your_access_token" #you got it, right? ;-)
+end
+```
+In your layout file place 'disqus_init' helper:
+```erb
+<%= disqus_init %>
+```
+In your view, where you want to display Disqus thread, place 'disqus_thread' helper:
+```erb
+<%= disqus_thread %>
+```
+And you are ready to go.
+
+####additional params:
+
+You can omit creating initializer if you want - you can pass all those params right into 'disqus_init' helper as hash:
+```erb
+<%= disqus_init :short_name => "short_name", :public_key => "public key", :secret_key => "secret_key", :access_token => "access_token" %>
+```
+also you can pass reset option to 'disqus_init' to invoke 'DISQUS.reset' function to be triggered on 'onReady' disqus event:
+```erb
+<%= disqus_init :reset => true %>
+```
+This is for ajax-heavy sites, read more [here](http://help.disqus.com/customer/portal/articles/472107-using-disqus-on-ajax-sites)
+
+'disqus_thread' has two params - first is 'ident' identifier and the second is title:
+```erb
+<%= disqus_thread 1, "some title, that will preferred to document.title"  %>
+```
+
+###Api
+
+####Api calls
+
+'DisqusRails::Api' stands for [Disqus API](http://disqus.com/api/docs/) calls. Each entity of Disqus API (Posts, Users, Forums, etc...)
+has its own class in 'DisqusRails::Api' module. Lets say you want to get all reactions for some forum with limit of 50 results, with desc order:
+```ruby
+DisqusRails::Api::Reactions.list(:forum => "forum_id", :limit => 50, :order => "desc")
+```
+or, for example to update some post:
+```ruby
+DisqusRails::Api::Posts.update(:post => post_id, :message => "some updated message")
+```
+Disqus return data as json, 'DisqusRails::Api' requests translates it to hash with symbolized keys.
+All methods with required and optional params you can see in 'api.yml' file. If any of required params not passed - it will generate
+exeption, so as if passed param neither required nor optional. Also, you have to initialize access_token for methods that has
+'require authentication' option set to true.
+
+####Models
+
+For more flexibility and using Disqus entities as an ActiveRecord model there is 'DisqusRails::Model' class that is inherited by
+'DisqusRails::Forum', 'DisqusRails::Category', 'DisqusRails::Thread', 'DisqusRails::Post' and 'DisqusRails::User'.
+Lets take previous example and turn it into model's presentation:
+```ruby
+new_post = DisqusRails::Post.create(:message => "initial message")
+new_post.update(:message => "updated message")
+new_post.author.checkUsername("John Doe")
+new_post.remove
+new_post.restore
+```
+If Disqus entity has 'details' api method, than model has 'find' singleton method
+```ruby
+user = DisqusRails::User.find(:user => "user_id")
+user_posts.follow()
+```
+Each 'DisqusRails::Model' has number of attributes that you can find in model's code. For example, here is Posts:
+```ruby
+class Post < Model
+    attr_accessor :id,
+                  :isJuliaFlagged,
+                  :isFlagged,
+                  :parent,
+                  :media,
+                  :isApproved,
+                  :dislikes,
+                  :raw_message,
+                  :points,
+                  :createdAt,
+                  :isEdited,
+                  :message,
+                  :isHighlighted,
+                  :ipAddress,
+                  :isSpam,
+                  :isDeleted,
+                  :likes,
+
+                  :author,
+                  :thread,
+                  :forum
+```
+
+####Collections
+
+Collections, as you may guess, is a list of similar Models. Its inherited from Enumerable. There is similar to models
+number of collection - 'DisqusRails::Forums', 'DisqusRails::Categories', 'DisqusRails::Threads', 'DisqusRails::Posts' and 'DisqusRails::Users'.
+Here some examples:
+```ruby
+user = DisqusRails.User.find(:user => "user_id")
+user.active_threads(:limit => 50)[15].posts.each do |post|
+  post.update(:message => "my post is nothing comparing to #{user.username} writings...")
+end
+```
+If there is 'list' method in Disqus entity - it transforms to 'where' singleton method of model that creates corresponding collection. For example:
+```ruby
+forum_categories = DisqusRails::Category.where(:forum => "forum_id")
+```
+Disqus API is designed in such way, that you can only get maximum 100 results for list query, and by default its 25. To get more
+results you are given with 'cursor' object that have 'next' and 'prev' values, passing which into query you can walk through
+results as if it was a list data structure. To define if there is more values to get, Disqus provides 'hasNext' and 'hasPrev' boolean
+values. For example, to get first 225 posts you can use this code:
+```ruby
+posts = DisqusRails::Post.where(:limit => 75)
+2.times do
+  if posts.has_cursor_next?
+    previous_items = posts.items
+    posts.cursor_next!
+    posts.items = previous_items + posts.items
+  end
+end
+```
+In future I, may be, will rewrite this to handle common cases for :limit attribute to be set to any number. As you saw, in
+previous example were used 'cursor_next!' method. There is both 'cursor_next', 'cursor_next!' and 'cursor_prev', 'cursor_prev!' methods.
+The difference is in returned values - method with bang in the end initializes new collection right in invoked instance,
+when method without it - just returns new collection.
+Also, each collection has singleton method 'find_all_#collection_class_name#!' that will get all results for query:
+```ruby
+threads = Disqus::Thread.where(:forum => "forum_name", :limit => 100).find_all_threads!
+```
+
+###Connection to ActiveRecord models
+
+####acts_as_disqusable and disqus_thread
+
+Lets say you have a 'Content' ActiveRecord model that implements logic for displaying some content information, and you add to that displaying
+Disqus thread. Then you may want to match threads info with different Content model instances. For example you may want to know
+how many comments and what is the last comment for each model instance.
+For this you need to wright 'acts_as_disqusable' in models definition:
+```ruby
+class Content < ActiveRecord::Base
+  acts_as_disqusable
+  ...
+end
+```
+And then all your model instances will be populated with 'disqus_thread' method that will return 'DisqusRails::Thread' instance
+that is found by Disqus 'ident' identifier which you can pass to 'disqus_thread' helper in your view. Here is full example:
+
+Your model:
+```ruby
+class Content < ActiveRecord::Base
+  acts_as_disqusable
+  ...
+end
+```
+Your model's details view
+```erb
+<%= disqus_thread @content.id %>
+
+```
+And now, when you run this
+```ruby
+disqus_thread = Content.first.disqus_thread #It will be thanslated to DisqusRails::Thread.find(:'thread:ident' => Content.first.id)
+disqus_thread.posts_count #number of posts
+disqus_thread.posts(:limit => 1).createdAt #last comment date
+```
+This work also in opposite direction - after you include 'acts_as_disqusable' in your model definition, all 'DisqusRails::Thread'
+instances you will have method 'disqusable' what will return your model instance that is linked to Disqus thread via 'ident' identificator.
+As an example lets say that we want to get all threads from Disqus service and update comments_count attribute in Content model:
+```ruby
+DisqusRails.Thread.where().find_all_threads!.each do |thread|
+  thread.disqusable.comments_count = thread.posts_count
+  thread.disqusable.save()
+end
+```
+
+####acts_as_disquser and Single Sign On
+
+Disqus provides [SSO service](http://help.disqus.com/customer/portal/articles/236206-integrating-single-sign-on) which gives
+ability to link your local users info to Disqus users, read more in Disqus tutorial. To do this, as and for linking model to
+Disqus thread - you have to add 'acts_as_disquser' line in your users model. You need pass there four attributes:
+'id', 'username', 'email' and 'avatar'(avatar is an optional field, so you can omit this). Here is example:
+```ruby
+class User < ActiveRecord::Base
+  acts_as_disquser :username => :full_name, :email => :email, :avatar => Proc.new{ avatar.url }
+  ...
+end
+```
+As you see, you can pass there or symbols, or procs. First will try to get instance variable with such name from model's instance,
+second will evaluate code inside Proc with context of model's instance. Important - only Proc are available for second way of
+defining attribute, no lambdas.
+Also, you may not implicitly pass `acts_as_disquser :id => :id` - it will try to get id automatically if it is not defined.
+Next, you need to specify in disqus_init helper attributes 'disquser' with current user instance, and 'sso' as
+boolean to enable or disable SSO.
+```erb
+<%= disqus_init :disquser => current_user, :sso => true %>
+```
+After this is done, when users will post comments via Disqus, their username, email and avatar will be taken from your site.
+
+###Javascript events
+
+Disqus provides developer with set of events which could be used to implement some logic that depends on it. The problem is
+that instead of triggering events we have to append function definitions in array for each of this events - for example look
+at [this article](http://help.disqus.com/customer/portal/articles/466258-how-can-i-capture-disqus-commenting-activity-in-my-own-analytics-tool-).
+I found that it might be a little bit more useful to set event listener for this, so I defined separate event for every Disqus event
+that developer can implicitly create listener:
+```coffeescript
+@callbacks.afterRender = [->
+  $(document).trigger "disqus:after_render"
+]
+@callbacks.onInit = [->
+  $(document).trigger "disqus:on_init"
+]
+@callbacks.onNewComment = [->
+  $(document).trigger "disqus:on_new_comment"
+]
+@callbacks.onPaginate = [->
+  $(document).trigger "disqus:on_paginate"
+]
+@callbacks.onReady = [->
+  $(document).trigger "disqus:on_ready"
+]
+@callbacks.preData = [->
+  $(document).trigger "disqus:pre_data"
+]
+@callbacks.preInit = [->
+  $(document).trigger "disqus:pre_init"
+]
+@callbacks.preReset = [->
+  $(document).trigger "disqus:pre_reset"
+]
+```
+For more information about coffeescript global class 'DisqusRails' look into 'disqus_rails.js.coffee' file.
+
+### Keeping data up to date
+It is equally little hard to do that with Disqus for now, as for me. The problem is that you can not set some callback for user
+actions - all you can is to set event listener for 'disqus:on_new_comment', but that will not be valid for all circumstances.
+Lets say user deleted or created new post from his users admin page in Disqus site. Disqus does not provide any callback for setting url
+where should query go, or some other futuristic way like web socket channel (sarcasm tag). So we should create some cron task for keeping data
+that we need up to date. For example, lets go back to problem of getting comments count and last comment for each Disqus thread.
+Here is example of such rake task that could be scheduled with whenever (or any else) gem:
+
+```ruby
+require 'resque/tasks'
+
+namespace :disqus do
+  desc "Refreshing local data about remote disqus comments"
+  task :refresh => :environment do
+    threads = DisqusRails::Thread.where(:forum => "forum_name", :limit => 100).find_all_threads!
+    threads.each do |thread|
+      if thread.disqusable_id && Content.find_by_id(thread.disqusable_id)
+        content = thread.disqusable
+        if (content.comments_count != thread.posts_count) || (thread.posts_count > 0 && thread.posts(:limit => 1).first.createdAt != content.last_comment_at)
+          content.comments_count = thread.posts_count
+          if thread.posts_count > 0
+            content.last_comment_at = DateTime.parse(thread.posts(:limit => 1).first.createdAt)
+          else
+            content.last_comment_at = nil
+          end
+          content.save
+        end
+      end
+    end
+  end
+end
+
+```

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/disqus_rails.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'disqus_rails/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "disqus_rails"
+  spec.version       = DisqusRails::VERSION
+  spec.authors       = ["Anton Kyrychenko"]
+  spec.email         = ["kyrychenkoanton@gmail.com"]
+  spec.description   = "Disqus 2012 Ruby on Rails wrapper"
+  spec.summary       = "Integrates Disqus service into your Ruby on Rails application"
+  spec.homepage      = "https://github.com/sandric/disqus_rails"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rails"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+
+  spec.add_dependency "rails"
+end

data/lib/disqus_rails.rb

@@ -0,0 +1,31 @@
+require "disqus_rails/version"
+
+%w[api helpers collection model user post thread forum category].each do |file|
+  require File.join(File.dirname(__FILE__), "disqus_rails", file)
+end
+
+%w[acts_as_disqusable acts_as_disquser].each do |file|
+  require File.join(File.dirname(__FILE__), "disqus_rails/active_record", file)
+end
+
+module DisqusRails
+  module Rails
+    class Engine < ::Rails::Engine
+      initializer 'acts_as_disqusable.extend_active_record' do
+        ::ActiveRecord::Base.extend DisqusRails::Disqusable::ActiveRecordMethods
+      end
+
+      initializer 'acts_as_disquser.extend_active_record' do
+        ::ActiveRecord::Base.extend DisqusRails::Disquser::ActiveRecordMethods
+      end
+    end
+  end
+
+  def self.setup
+    yield self
+  end
+end
+
+module ApplicationHelper
+  include DisqusRails::Helpers
+end

data/lib/disqus_rails/active_record/acts_as_disqusable.rb

@@ -0,0 +1,24 @@
+module DisqusRails
+  module Disqusable
+    module ActiveRecordMethods
+      def acts_as_disqusable
+        include ActsAsDisqusable
+      end
+    end
+
+    module ActsAsDisqusable
+
+      def disqus_thread
+        DisqusRails::Thread.find_by_ident(self.id)
+      end
+
+      def self.included(disqusable)
+        Thread.class_exec do
+          define_method :disqusable do
+            disqusable.find(@disqusable_id)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/disqus_rails/active_record/acts_as_disquser.rb

@@ -0,0 +1,48 @@
+module DisqusRails
+  module Disquser
+    module ActiveRecordMethods
+      def acts_as_disquser(attributes={})
+
+        define_method :disqus_params do
+          data = {}
+
+          if attributes.has_key?(:id)
+            if attributes[:id].is_a? Proc
+              data[:id] = instance_eval &attributes[:id]
+            else
+              data[:id] = send attributes[:id]
+            end
+          else
+            data[:id] = self.id
+          end
+
+          if attributes.has_key?(:username)
+            if attributes[:username].is_a? Proc
+              data[:username] = instance_eval &attributes[:username]
+            else
+              data[:username] = send attributes[:username]
+            end
+          end
+
+          if attributes.has_key?(:email)
+            if attributes[:email].is_a? Proc
+              data[:email] = instance_eval &attributes[:email]
+            else
+              data[:email] = send attributes[:email]
+            end
+          end
+
+          if attributes.has_key?(:avatar)
+            if attributes[:avatar].is_a? Proc
+              data[:avatar] = instance_eval &attributes[:avatar]
+            else
+              data[:avatar] = send attributes[:avatar]
+            end
+          end
+
+          data
+        end
+      end
+    end
+  end
+end