norman-disqus-api 0.2.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 [name of plugin creator]
+
+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.rdoc

@@ -0,0 +1,118 @@
+== Disqus Ruby Gem
+
+The Disqus Gem helps you easily integrate the {Disqus}[http://disqus.com]
+commenting system into your website. It works for any site programmed in Ruby,
+and has view helpers for Rails and Merb.
+
+Support for the Disqus Javascript widgets is stable. Disqus API support is
+"beta."
+
+=== What is Disqus?
+
+From the Disqus website:
+
+"Disqus, pronounced "discuss", is a service and tool for web comments and
+discussions. The Disqus comment system can be plugged into any website, blog,
+or application. Disqus makes commenting easier and more interactive, while
+connecting websites and commenters across a thriving discussion community."
+
+"Disqus is a free service to the general public with absolutely no inline advertisements."
+
+=== Get it
+
+==== Stable release (does not yet include API):
+
+  gem install disqus
+
+==== Bleeding Edge (includes API):
+
+  gem install norman-disqus  --source http://gems.github.com
+
+=== Use it:
+
+==== Configure it:
+
+===== Generic example:
+
+  Disqus::defaults[:account] = "my_disqus_account"
+  # Optional, only if you're using the API
+  Disqus::defaults[:api_key] = "my_disqus_api_key"
+
+===== Rails-specific example:
+
+  # in config/development.rb (or production.rb, test.rb, etc.)
+  config.after_initialize do
+    Disqus::defaults[:account] = "my_disqus_account"
+    # Optional, only if you're using the API
+    Disqus::defaults[:api_key] = "my_disqus_api_key"
+  end
+
+Note that here the "after initialize" is necessary, otherwise your settings
+won't be set properly.
+
+==== Show the comment threads widget on a post page:
+
+  # Loads the commenting system
+  disqus_thread
+  
+  # Or if you're not using Rails/Merb:
+  Disqus::Widget::thread
+  
+  # Sets the inner html to the comment count for any links on the page that
+  # have the anchor "disqus_thread". For example, "View Comments" below would
+  # be replaced by "1 comment" or "23 comments" etc.
+  # <a href="http://my.website/article-permalink#disqus_thread">View Comments</a>
+  # <a href="http://my.website/different-permalink#disqus_thread">View Comments</a>
+  disqus_comment_counts
+  
+  # Or if you're not using Rails/Merb:
+  Disqus::Widget::comment_counts
+
+==== Show the combo widget on a post page:
+
+  disqus_combo(:color => "blue", :hide_mods => false, :num_items => 20)
+  
+  # Or for non-Rails/Merb:
+  Disqus::Widget::combo(:color => "blue", :hide_mods => false, :num_items => 20)
+
+==== Show the comment count on a permalink:
+
+  link_to("Permalink", post_path(@post, :anchor => "disqus_thread"))
+  ...
+  disqus_comment_counts
+  
+  # Or for non-Rails/Merb:
+  Disqus::Widget::comment_counts
+
+==== Work with the Disqus API:
+
+See the Disqus::Api class for more info on the Disqus API. You can also read
+the {Disqus developer info here}[http://disqus.com/docs/api/].
+
+=== Hack it:
+
+Github repository: 
+  
+  http://github.com/norman/disqus
+
+=== Submit bug reports:
+
+Please use our {Lighthouse}[http://randomba.lighthouseapp.com/projects/16065-disqus/].
+
+=== Learn more about Disqus:
+
+{http://disqus.com}[http://disqus.com]
+
+=== Thanks to the following contributors:
+
+* {Matt Van Horn}[http://github.com/mattvanhorn] - Disqus API
+* {Quin Hoxie}[http://github.com/qhoxie] - Merb support
+
+=== Legal Stuff
+
+The Disqus Ruby gem was not created by, nor is officially supported by
+Disqus.com or Big Head Labs, Inc. Use it at your own risk and your own
+responsibility under the terms of the MIT License.
+
+Copyright (c) 2008 {Norman Clarke}[mailto:norman@randomba.org], released under
+the MIT license

data/Rakefile

@@ -0,0 +1,43 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Run unit tests.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc "Build gem"
+task :gem do
+  sh "gem build disqus.gemspec"
+end
+
+desc "Run rcov"
+task :rcov do
+  rm_f "coverage"
+  rm_f "coverage.data"
+  if PLATFORM =~ /darwin/
+    exclude = '--exclude "gems"'
+  else
+    exclude = '--exclude "rubygems"'
+  end
+  rcov = "rcov --rails -Ilib:test --sort coverage --text-report #{exclude} --no-validator-links"
+  cmd = "#{rcov} #{Dir["test/**/*.rb"].join(" ")}"
+  sh cmd
+end
+
+desc 'Generate rdocs.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = 'Disqus'
+  rdoc.main = "README.rdoc"
+  rdoc.options << '--line-numbers' << '--inline-source' << '-c UTF-8'
+  rdoc.rdoc_files.include('lib/**/*.rb')
+  rdoc.rdoc_files.include('README.rdoc')
+end

data/init.rb

@@ -0,0 +1,6 @@
+require 'disqus'
+require 'disqus/api'
+require 'disqus/author'
+require 'disqus/forum'
+require 'disqus/post'
+require 'disqus/thread'

data/lib/disqus.rb

@@ -0,0 +1,70 @@
+require 'disqus/widget'
+  
+# == From the {Disqus Website}[http://disqus.com]:
+
+# "Disqus, pronounced "discuss", is a service and tool for web comments and
+# discussions. The Disqus comment system can be plugged into any website, blog,
+# or application. Disqus makes commenting easier and more interactive, while
+# connecting websites and commenters across a thriving discussion community."
+# 
+# "Disqus is a free service to the general public with absolutely no inline
+# advertisements."
+
+# The Disqus gem helps you quickly and easily integrate Disqus's Javascript
+# widgets into your Ruby-based website. Adding Disqus to your site literally
+# takes only a few minutes. The Disqus gem also provides a complete
+# implementation of the Disqus API for more complex applications.
+
+# To use this code, please first create an account on Disqus[http://disqus.com].
+module Disqus
+  
+  @defaults = {
+    :api_key => "",
+    :account => "",
+    :avatar_size => 48,
+    :color => "grey",
+    :default_tab => "popular",
+    :hide_avatars => false,
+    :hide_mods => true,
+    :num_items => 15,
+    :show_powered_by => true,
+    :orientation => "horizontal"
+  }
+  
+  # Disqus defaults:
+  #  :account => "",
+  #  :avatar_size => 48,
+  #  :color => "grey",
+  #  :default_tab => "popular",
+  #  :hide_avatars => false,
+  #  :hide_mods => true,
+  #  :num_items => 15,
+  #  :show_powered_by => true,
+  #  :orientation => "horizontal"
+  def self.defaults
+    @defaults
+  end
+  
+  # Load the view helpers if the gem is included in a Rails app.
+  def self.enable_rails
+    return if ActionView::Base.instance_methods.include? 'disqus_thread'
+    require 'disqus/view_helpers'
+    ActionView::Base.class_eval { include Disqus::ViewHelpers }
+  end
+
+  # Load the view helpers if the gem is included in a Merb app.
+  def self.enable_merb
+    return if Merb::Controller.instance_methods.include? 'disqus_thread'
+    require 'disqus/view_helpers'
+    Merb::Controller.class_eval { include Disqus::ViewHelpers }
+  end
+
+end
+
+if defined?(Rails) and defined?(ActionView)
+  Disqus::enable_rails
+end
+
+if defined?(Merb)
+  Disqus::enable_merb
+end

data/lib/disqus/api.rb

@@ -0,0 +1,264 @@
+require 'open-uri'
+require 'rubygems'
+require 'json'
+require 'net/http'
+require 'uri'
+
+module Disqus
+  
+  # == Disqus API
+  #
+  # The Api class implements the Disqus API directly. It is not really
+  # intended to be used directly, but rather to use the domain objects of
+  # Forum, Thread, Post, Author and AnonymousAuthor. For full information on
+  # the Disqus API, please see the {Disqus developer info}[http://disqus.com/docs/api/].
+  #
+  # Each method in the Api class takes as a single argument a hash of options,
+  # and returns a Hash with 3 keys:
+  #
+  # * 'succeeded' - contains true or false indicating whether the API call succeeded
+  # * 'code' - if the API call did not succeed, this will contain an error code.
+  # * 'message' - contains the object being returned on success, or an error message on failure.
+  #
+  # === API Keys
+  # 
+  # There are two different kinds of API keys: 
+  #
+  # ==== User Keys
+  #
+  # Every Disqus account has a User Key; it is used to perform actions
+  # associated with that account. This can be passed in as an option, or
+  # configured as follows:
+  #
+  #   Disqus::defaults[:api_key] = "the_user_api_key"
+  #  
+  # ==== Forum Keys
+  #
+  # Every Disqus forum has a Forum Key. It can be shared among trusted
+  # moderators of a forum, and is used to perform actions associated with that
+  # forum. The creator of a forum can get the forum's key through the API.
+  class Api
+    
+    ROOT = 'http://disqus.com/api'
+  
+    class << self
+
+      # Creates a new post on the thread. Does not check against spam filters or ban list. 
+      # This is intended to allow automated importing of comments.
+      # 
+      # Returns a Hash containing a representation of the post just created:
+      # 
+      # Required options hash elements:
+      #
+      # * <tt>:forum_api_key</tt> - the API key for the forum
+      # * <tt>:thread_id</tt> - the thread to post to
+      # * <tt>:message</tt> - the content of the post
+      # * <tt>:author_name</tt> - the post creator's name
+      # * <tt>:author_email</tt> - the post creator's email address
+      #
+      # Optional:
+      #
+      # * <tt>:parent_post</tt> - the id of the parent post
+      # * <tt>:created_at</tt> - the UTC date this post was created, in the format <tt>%Y-%m-%dT%H:%M</tt> (the current time will be used by default)
+      # * <tt>:author_url</tt> - the author's homepage
+      # * <tt>:ip_address</tt> - the author's IP address
+      def create_post(opts = {})
+        opts[:api_key] ||= Disqus::defaults[:api_key]
+        JSON.parse(post('create_post',
+          :forum_api_key => opts[:forum_api_key],
+          :thread_id     => opts[:thread_id],
+          :message       => opts[:message],
+          :author_name   => opts[:author_name],
+          :author_email  => opts[:author_email],
+          :parent_post   => opts[:parent_post],
+          :created_at    => opts[:created_at], #UTC timestring, format: %Y-%m-%dT%H:%M
+          :author_url    => opts[:author_url],
+          :ip_address    => opts[:ip_address])
+        )
+      end
+
+      # Returns an array of hashes representing all forums the user owns. The
+      # user is determined by the API key. 
+      #
+      # Options:
+      #
+      # * <tt>:api_key</tt> - The User's API key (defaults to
+      #   Disqus::defaults[:api_key])
+      def get_forum_list(opts = {})
+        opts[:api_key] ||= Disqus::defaults[:api_key]
+        JSON.parse(get('get_forum_list', :user_api_key => opts[:api_key]))
+      end
+
+      # Returns A string which is the Forum Key for the given forum.
+      # 
+      # Required options hash elements:
+      #
+      # * <tt>:forum_id</tt> - the unique id of the forum
+      #
+      # Optional:
+      #
+      # * <tt>:api_key</tt> - The User's API key (defaults to Disqus::defaults[:api_key])
+      def get_forum_api_key(opts = {})
+        opts[:api_key] ||= Disqus::defaults[:api_key]
+        JSON.parse(get('get_forum_api_key', :user_api_key => opts[:api_key], :forum_id => opts[:forum_id]))
+      end
+      
+      # Returns: An array of hashes representing all threads belonging to the
+      # given forum. 
+      #  
+      # Required options hash elements:
+      #
+      # * <tt>:forum_api_key</tt> - the API key for the forum
+      # * <tt>:forum_id</tt> - the unique id of the forum
+      def get_thread_list(opts = {})
+        JSON.parse(get('get_thread_list', :forum_id => opts[:forum_id], :forum_api_key => opts[:forum_api_key]))
+      end
+      
+      # Returns a hash having thread_ids as keys and 2-element arrays as
+      # values. 
+      #
+      # The first array element is the number of visible comments on on the
+      # thread; this would be useful for showing users of the site (e.g., "5
+      # Comments"). 
+      #
+      # The second array element is the total number of comments on the
+      # thread. 
+      #
+      # These numbers are different because some forums require moderator
+      # approval, some messages are flagged as spam, etc.
+      #  
+      # Required options hash elements:
+      #
+      # * <tt>:forum_api_key</tt> - the API key for the forum
+      # * <tt>:thread_ids</tt> - an array of thread IDs belonging to the given forum.
+      def get_num_posts(opts = {})
+        opts[:api_key] ||= Disqus::defaults[:api_key]
+        JSON.parse(get('get_num_posts', :thread_ids => opts[:thread_ids].join(","), :forum_api_key => opts[:forum_api_key]))
+      end
+
+      # Returns a hash representing a thread if one was found, otherwise null.
+      #
+      # It only finds threads associated with the given forum.
+      #
+      # Note that there is no one-to-one mapping between threads and URL's; a
+      # thread will only have an associated URL if it was automatically
+      # created by Disqus javascript embedded on that page. Therefore, we
+      # recommend using thread_by_identifier whenever possible. This method is
+      # provided mainly for handling comments from before your forum was using
+      # the API.
+      #
+      # Required options hash elements:
+      #
+      # * <tt>:forum_api_key</tt> - the API key for the forum
+      # * <tt>:url</tt> - the URL to check for an associated thread
+      def get_thread_by_url(opts = {})
+        JSON.parse(get('get_thread_by_url', :url => opts[:url], :forum_api_key => opts[:forum_api_key]))
+      end
+
+      # Returns an array of hashes representing representing all posts
+      # belonging to the given forum. 
+      #      
+      # Required options hash elements:
+      #
+      # * <tt>:forum_api_key</tt> - the API key for the forum
+      # * <tt>:thread_id</tt> - the ID of a thread belonging to the given forum
+      def get_thread_posts(opts = {})
+        JSON.parse(get('get_thread_posts', :thread_id => opts[:thread_id], :forum_api_key => opts[:forum_api_key]))
+      end
+      
+      # Create or retrieve a thread by an arbitrary identifying string of your
+      # choice. For example, you could use your local database's ID for the
+      # thread. This method allows you to decouple thread identifiers from the
+      # URL's on which they might be appear. (Disqus would normally use a
+      # thread's URL to identify it, which is problematic when URL's do not
+      # uniquely identify a resource.) If no thread exists for the given
+      # identifier yet (paired with the forum), one will be created.
+      #      
+      # Returns a  hash with two keys: 
+      #
+      # * "thread", which is a hash representing the thread corresponding to the identifier; and 
+      # * "created", which indicates whether the thread was created as a result of this method call. If created, it will have the specified title.
+      #
+      # Required options hash elements:
+      #
+      # * <tt>:forum_api_key</tt> - the API key for the forum
+      # * <tt>:title</tt> - the title of the thread to possibly be created
+      # * <tt>:identifier</tt> - a string of your choosing
+      def thread_by_identifier(opts = {})
+        JSON.parse(post('thread_by_identifier', :forum_api_key => opts[:forum_api_key],
+                                                :identifier => opts[:identifier],
+                                                :title => opts[:title] ))
+      end
+      
+      # Sets the provided values on the thread object.
+      #
+      # Returns an empty success message.
+      #
+      # Required options hash elements:
+      #
+      # * <tt>:forum_api_key</tt> - the API key for the forum
+      # * <tt>:thread_id</tt> - the ID of a thread belonging to the given forum
+      #
+      # Optional:
+      #
+      # * <tt>:title</tt> - the title of the thread
+      # * <tt>:slug</tt> - the per-forum-unique string used for identifying this thread in disqus.com URL's relating to this thread. Composed of underscore-separated alphanumeric strings.
+      # * <tt>:url</tt> - the URL this thread is on, if known.
+      # * <tt>:allow_comment</tt> - whether this thread is open to new comments
+      def update_thread(opts = {})
+        raise opts.inspect
+        JSON.parse(post('update_thread',
+          :forum_api_key  => opts[:forum_api_key],
+          :thread_id      => opts[:thread_id],
+          :title          => opts[:title],
+          :slug           => opts[:slug],
+          :url            => opts[:url],
+          :allow_comments => opts[:allow_comments])
+        )
+      end
+      
+      # Widget to includes a comment form suitable for use with the Disqus
+      # API. This is different from the other widgets in that you can specify
+      # the thread identifier being commented on.
+      def comment_form(forum_shortname, thread_identifier)
+        url = 'http://disqus.com/api/reply.js?' + 
+          "forum_shortname=#{escape(forum_shortname)}&" + 
+          "thread_identifier=#{escape(thread_identifier)}"
+        s = '<div id="dsq-reply">'
+        s << '<script type="text/javascript" src="%s"></script>' % url
+        s << '</div>'
+        return s
+      end
+      
+      private
+
+      def escape(string)
+        URI::encode(string, /[^a-z0-9]/i)
+      end
+      
+      def get(*args)
+        open(make_url(*args)) {|u| u.read }
+      end
+      
+      def post(*args)
+        url = ROOT + '/' + args.shift 
+        post_params = {}
+        args.shift.each { |k, v| post_params[k.to_s]=v.to_s }
+        Net::HTTP.post_form(URI.parse(url),post_params)
+      end
+
+      def make_url(*args)
+        url = ROOT + '/' + args.shift + '/?'
+        args.shift.each { |k, v| url += "#{k}=#{escape(v.to_s)}&" }
+        return url.chomp('&')
+      end
+
+      def validate_opts!(opts)
+        raise ArgumentError.new("You must specify an :api_key") if !opts[:api_key]
+      end
+      
+    end
+  
+  end
+
+end