disqus 0.1.1 → 1.0.0

data/History.txt

@@ -0,0 +1,5 @@
+== 1.0.0 2009-01-05
+* 1 major enhancement:
+  * Support for Disqus API added (Matthew Van Horn)
+* 1 minor enhancement:
+  * Reorganized gem to use newgem

data/Manifest.txt

@@ -0,0 +1,38 @@
+History.txt
+MIT-LICENSE
+Manifest.txt
+README.rdoc
+Rakefile
+disqus.gemspec
+init.rb
+lib/disqus.rb
+lib/disqus/api.rb
+lib/disqus/author.rb
+lib/disqus/forum.rb
+lib/disqus/post.rb
+lib/disqus/thread.rb
+lib/disqus/version.rb
+lib/disqus/view_helpers.rb
+lib/disqus/widget.rb
+tasks/rcov.rake
+test/api_test.rb
+test/config.yml
+test/config.yml.sample
+test/forum_test.rb
+test/merb_test.rb
+test/post_test.rb
+test/rails_test.rb
+test/responses/bad_api_key.json
+test/responses/create_post.json
+test/responses/get_forum_api_key.json
+test/responses/get_forum_list.json
+test/responses/get_num_posts.json
+test/responses/get_thread_by_url.json
+test/responses/get_thread_list.json
+test/responses/get_thread_posts.json
+test/responses/thread_by_identifier.json
+test/responses/update_thread.json
+test/test_helper.rb
+test/thread_test.rb
+test/view_helpers_test.rb
+test/widget_test.rb

data/README.rdoc

@@ -0,0 +1,116 @@
+== 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
+
+  gem install disqus
+
+==== Bleeding Edge
+
+  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

@@ -1,42 +1,23 @@
-require 'rake'
-require 'rake/testtask'
-require 'rake/rdoctask'
+require 'newgem'
+require 'lib/disqus/version'
 
-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
+$hoe = Hoe.new("disqus", Disqus::Version::STRING) do |p|
+  p.rubyforge_name = "disqus"
+  p.author = ['Norman Clarke', 'Matthew Van Horn']
+  p.email = ['norman@randomba.org', 'mattvanhorn@gmail.com']
+  p.summary = "Integrates Disqus commenting system into your Ruby-powered site."
+  p.description = 'Integrates Disqus into your Ruby-powered site. Works with any Ruby website, and has view helpers for Rails and Merb.'
+  p.url = 'http://disqus.rubyforge.org'
+  p.test_globs = ['test/**/*_test.rb']
+  p.extra_deps << ['json']
+  p.extra_dev_deps = [
+    ['newgem', ">= #{::Newgem::VERSION}"],
+    ['mocha']
+  ]
+  p.rsync_args = '-av --delete --ignore-errors'
+  changes = p.paragraphs_of('History.txt', 0..1).join("\n\n")
+  p.remote_rdoc_dir = ""
 end
 
-desc 'Generate rdocs.'
-Rake::RDocTask.new(:rdoc) do |rdoc|
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'Disqus'
-  rdoc.options << '--line-numbers' << '--inline-source' << '-c UTF-8'
-  rdoc.rdoc_files.include('lib/**/*.rb')
-  rdoc.rdoc_files.include('README.textile')
-end
+require 'newgem/tasks'
+Dir['tasks/**/*.rake'].each { |t| load t }

data/disqus.gemspec

@@ -0,0 +1,46 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{disqus}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Norman Clarke", "Matthew Van Horn"]
+  s.cert_chain = ["/Users/norman/.gem/gem-public_cert.pem"]
+  s.date = %q{2009-01-05}
+  s.description = %q{Integrates Disqus into your Ruby-powered site. Works with any Ruby website, and has view helpers for Rails and Merb.}
+  s.email = ["norman@randomba.org", "mattvanhorn@gmail.com"]
+  s.extra_rdoc_files = ["History.txt", "Manifest.txt", "README.rdoc"]
+  s.files = ["History.txt", "MIT-LICENSE", "Manifest.txt", "README.rdoc", "Rakefile", "disqus.gemspec", "init.rb", "lib/disqus.rb", "lib/disqus/api.rb", "lib/disqus/author.rb", "lib/disqus/forum.rb", "lib/disqus/post.rb", "lib/disqus/thread.rb", "lib/disqus/version.rb", "lib/disqus/view_helpers.rb", "lib/disqus/widget.rb", "tasks/rcov.rake", "test/api_test.rb", "test/config.yml", "test/config.yml.sample", "test/forum_test.rb", "test/merb_test.rb", "test/post_test.rb", "test/rails_test.rb", "test/responses/bad_api_key.json", "test/responses/create_post.json", "test/responses/get_forum_api_key.json", "test/responses/get_forum_list.json", "test/responses/get_num_posts.json", "test/responses/get_thread_by_url.json", "test/responses/get_thread_list.json", "test/responses/get_thread_posts.json", "test/responses/thread_by_identifier.json", "test/responses/update_thread.json", "test/test_helper.rb", "test/thread_test.rb", "test/view_helpers_test.rb", "test/widget_test.rb"]
+  s.has_rdoc = true
+  s.homepage = %q{http://disqus.rubyforge.org}
+  s.rdoc_options = ["--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{disqus}
+  s.rubygems_version = %q{1.3.1}
+  s.signing_key = %q{/Users/norman/.gem/gem-private_key.pem}
+  s.summary = %q{Integrates Disqus commenting system into your Ruby-powered site.}
+  s.test_files = ["test/api_test.rb", "test/forum_test.rb", "test/merb_test.rb", "test/post_test.rb", "test/rails_test.rb", "test/thread_test.rb", "test/view_helpers_test.rb", "test/widget_test.rb"]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<json>, [">= 0"])
+      s.add_development_dependency(%q<newgem>, [">= 1.2.3"])
+      s.add_development_dependency(%q<mocha>, [">= 0"])
+      s.add_development_dependency(%q<hoe>, [">= 1.8.0"])
+    else
+      s.add_dependency(%q<json>, [">= 0"])
+      s.add_dependency(%q<newgem>, [">= 1.2.3"])
+      s.add_dependency(%q<mocha>, [">= 0"])
+      s.add_dependency(%q<hoe>, [">= 1.8.0"])
+    end
+  else
+    s.add_dependency(%q<json>, [">= 0"])
+    s.add_dependency(%q<newgem>, [">= 1.2.3"])
+    s.add_dependency(%q<mocha>, [">= 0"])
+    s.add_dependency(%q<hoe>, [">= 1.8.0"])
+  end
+end

data/init.rb

@@ -1 +1,7 @@
-require 'disqus'
+require 'disqus'
+require 'disqus/api'
+require 'disqus/author'
+require 'disqus/forum'
+require 'disqus/post'
+require 'disqus/thread'
+require 'disqus/version'

data/lib/disqus.rb

@@ -1,12 +1,25 @@
 require 'disqus/widget'
   
-# Disqus is a javascript embed that enhances your blog's comments and
-# integrates it with a fully moderated community forum. The Disqus gem helps
-# you quickly and easily integrate Disqus's widgets into your Ruby-based 
-# website. To use it, please first create an account on Disqus.
+# == 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",

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