norman-disqus-api 0.2.0

data/lib/disqus/author.rb

@@ -0,0 +1,27 @@
+module Disqus
+  
+  class BaseAuthor
+    attr_reader :url, :email_hash
+  end
+  
+  class Author < BaseAuthor
+    attr_reader :id, :username, :display_name, :has_avatar
+    def initialize(id, username, display_name, url, email_hash, has_avatar)
+      @id, @username, @display_name, @url, @email_hash, @has_avatar = id, username, display_name, url, email_hash, has_avatar
+    end
+    
+    # Returns the user's <tt>display_name</tt> or <tt>username</tt> if <tt>display_name</tt> is blank.
+    def name
+      @display_name.blank? ? @username : @display_name
+    end
+    
+  end
+  
+  class AnonymousAuthor < BaseAuthor
+    attr_reader :name
+    def initialize(name, url, email_hash)
+      @name, @url, @email_hash = name, url, email_hash
+    end
+  end
+end
+

data/lib/disqus/forum.rb

@@ -0,0 +1,126 @@
+module Disqus
+
+  class Forum
+    attr_reader :id, :shortname, :name, :created_at, :threads
+    
+    def initialize(id, shortname, name, created_at, include_threads = false)
+      @id, @shortname, @name, @created_at = id.to_i, shortname, name, Time.parse(created_at.to_s)
+      @key = nil
+      @threads = include_threads ? load_threads : []
+    end
+
+    def ==(other_forum)
+      id        == other_forum.id        &&
+      shortname == other_forum.shortname &&
+      name      == other_forum.name      &&
+      key       == other_forum.key
+    end
+
+    # Returns an array of Forum objects belonging to the user indicated by the API key.
+    def self.list(user_api_key = nil)
+      opts = user_api_key ? {:api_key => user_api_key} : {}
+      response = Disqus::Api::get_forum_list(opts)
+      if response["succeeded"]
+        return response["message"].map{|forum| Forum.new(forum["id"], forum["shortname"], forum["name"], forum["created_at"])}
+      else
+        raise_api_error(response)
+      end
+    end
+    
+    # Returns a Forum object corresponding to the given forum_id or nil if it was not found.
+    def self.find(forum_id, user_api_key = nil)
+      opts = user_api_key ? {:api_key => user_api_key} : {}
+      list = Forum.list(opts)
+      if list
+        list.select{|f| f.id == forum_id}.first
+      end
+    end
+    
+    # Returns the forum API Key for this forum.
+    def key(user_api_key = nil)
+      @key ||= load_key(user_api_key)
+    end
+    
+    # Returns an array of threads belonging to this forum.
+    def threads(force_update = false)
+      if (@threads.nil? or @threads.empty? or force_update)
+        @threads = Disqus::Thread.list(self)
+      end
+      @threads
+    end
+    
+    # Returns a thread associated with the given URL.
+    #
+    # A thread will only have an associated URL if it was automatically
+    # created by Disqus javascript embedded on that page.
+    def get_thread_by_url(url)
+      response = Disqus::Api::get_thread_by_url(:url => url, :forum_api_key => key)
+      if response["succeeded"]
+        t = response["message"]
+        Thread.new(t["id"], self, t["slug"], t["title"], t["created_at"], t["allow_comments"], t["url"], t["identifier"])
+      else
+        raise_api_error(response)
+      end
+    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 (paired with the forum) yet, one will be created.
+    #
+    # Returns a Thread object representing the thread that was created or
+    # retrieved.
+    def thread_by_identifier(identifier, title)
+      # TODO - should we separate thread retrieval from thread creation? The API to me seems confusing here.
+      response = Disqus::Api::thread_by_identifier(:identifier => identifier, :title => title, :forum_api_key => key)
+      if response["succeeded"]
+        t = response["message"]["thread"]
+        Thread.new(t["id"], self, t["slug"], t["title"], t["created_at"], t["allow_comments"], t["url"], t["identifier"])
+      else
+        raise_api_error(response)
+      end
+    end
+    
+    # Sets the provided values on the thread object.
+    #
+    # Returns an empty success message.
+    #
+    # Options:
+    #
+    # * <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(thread_id, opts = {})
+      result = Disqus::Api::update_thread(
+        :forum_api_key  => key,
+        :thread_id      => thread_id,
+        :title          => opts[:title],
+        :slug           => opts[:slug],
+        :url            => opts[:url],
+        :allow_comments => opts[:allow_comments]
+      )
+      return result["succeeded"]
+    end
+    
+    private
+    
+    def raise_api_error(response)
+      raise "Error: #{response['code']}: #{response['message']}"
+    end
+    
+    def load_key(user_api_key = nil)
+      opts = user_api_key ? {:api_key => user_api_key} : {}
+      response = Disqus::Api::get_forum_api_key(opts.merge(:forum_id => self.id))
+      if response["succeeded"]
+        return @key = response["message"] 
+      else
+        raise_api_error(response)
+      end
+    end
+    
+  end
+end

data/lib/disqus/post.rb

@@ -0,0 +1,51 @@
+module Disqus
+
+  class Post
+    attr_reader :id, :forum, :thread, :created_at, :message, :parent_post, :shown, :is_anonymous, :author
+    
+    def initialize(id, forum, thread, created_at, message, parent_post, shown, is_anonymous, author)
+         @id, @forum, @thread, @created_at, @message, @parent_post, @shown, @is_anonymous, @author = id.to_i, forum, thread, Time.parse(created_at.to_s), message, parent_post, shown, is_anonymous, author
+    end
+    
+    # Returns an array of Post objects representing all posts belonging to the
+    # given thread. The array is sorted by the "created_at" date descending.
+    def self.list(thread)
+      response = Disqus::Api::get_thread_posts(:thread_id =>thread.id, :forum_api_key => thread.forum.key)
+      if response["succeeded"]
+        posts = response["message"].map do |post|
+          author = nil
+          if post["is_anonymous"] 
+            author = AnonymousAuthor.new(
+              post["anonymous_author"]["name"],
+              post["anonymous_author"]["url"],
+              post["anonymous_author"]["email_hash"]
+            )
+          else
+            author = Author.new(
+              post["author"]["id"].to_i,
+              post["author"]["username"],
+              post["author"]["display_name"],
+              post["author"]["url"],
+              post["author"]["email_hash"],
+              post["author"]["has_avatar"]
+            )
+          end
+          Post.new( 
+            post["id"],
+            thread.forum,
+            thread,
+            post["created_at"],
+            post["message"],
+            post["parent_post"],
+            post["shown"],
+            post["is_anonymous"],
+            author
+          )
+        end
+        posts.sort!{|a,b| a.created_at <=> b.created_at}
+      end
+    end
+  end
+end
+
+

data/lib/disqus/thread.rb

@@ -0,0 +1,73 @@
+module Disqus
+
+  class Thread
+    attr_reader :id, :forum, :slug, :title, :created_at, :allow_comments, :url, :identifier, :forum
+    
+    def initialize(id, forum, slug, title, created_at, allow_comments, url, identifier)
+      @id, @forum, @slug, @title, @created_at, @allow_comments, @url, @identifier = id.to_i, forum, slug, title, Time.parse(created_at.to_s), allow_comments, url, identifier
+      @posts = []
+    end
+
+    # Threads are equal if all their attributes are equal.
+    def ==(other_thread)
+      id             == other_thread.id             &&
+      forum          == other_thread.forum          &&
+      slug           == other_thread.slug           &&
+      title          == other_thread.title          &&
+      created_at     == other_thread.created_at     &&
+      allow_comments == other_thread.allow_comments &&
+      url            == other_thread.url            &&
+      identifier     == other_thread.identifier
+    end
+    
+    # Returns an array of Thread objects representing the threads belonging to the given Forum.
+    def self.list(forum, opts = {})
+      response = Disqus::Api::get_thread_list(opts.merge(:forum_id =>forum.id, :forum_api_key => forum.key))
+      if response["succeeded"]
+        list = response["message"].map do |thread| 
+          Thread.new(
+            thread["id"],
+            forum,
+            thread["slug"],
+            thread["title"],
+            thread["created_at"],
+            thread["allow_comments"],
+            thread["url"],
+            thread["identifier"]
+          )
+        end
+      end
+    end
+
+    # Returns an array of posts belonging to this thread.
+    def posts(force_update = false)
+      if (@posts.nil? or @posts.empty? or force_update)
+        @posts = Disqus::Post.list(self)
+      end
+      @posts
+    end
+    
+    # Sets the provided values on the thread object.
+    #
+    # Options:
+    #
+    # * :thread_id
+    # * :title
+    # * :slug
+    # * :url
+    # * :allow_comments
+    def update(opts = {})
+      result = Disqus::Api::update_thread(opts.merge(
+        :forum_api_key  => forum.key,
+        :thread_id      => id,
+        :title          => title,
+        :slug           => slug,
+        :url            => url,
+        :allow_comments => allow_comments)
+      )
+      return result["succeeded"]
+    end
+    
+  end
+
+end

data/lib/disqus/view_helpers.rb

@@ -0,0 +1,45 @@
+module Disqus
+
+  # Shortcuts to access the widgets as simple functions as opposed to using
+  # their full qualified names. These helpers are loaded automatically in
+  # Rails and Merb apps. 
+  #
+  # For Sinatra, Camping, Nitro or other frameworks, you can include the
+  # helper if you wish, or use the fully-qualified names. Really this is just
+  # here for aesthetic purposes and to make it less likely to step on anyone's
+  # namespace.
+  module ViewHelpers
+    
+    # See Disqus::Widget.thread
+    def disqus_thread(options = {})
+      Disqus::Widget::thread(options)
+    end
+    
+    # See Disqus::Widget.comment_counts
+    def disqus_comment_counts(options = {})
+      Disqus::Widget::comment_counts(options)
+    end
+    
+    # See Disqus::Widget.top_commenters
+    def disqus_top_commenters(options = {})
+      Disqus::Widget::top_commenters(options)
+    end
+    
+    # See Disqus::Widget.popular_threads
+    def disqus_popular_threads(options = {})
+      Disqus::Widget::popular_threads(options)
+    end
+    
+    # See Disqus::Widget.recent_comments
+    def disqus_recent_comments(options = {})
+      Disqus::Widget::recent_comments(options)
+    end
+    
+    # See Disqus::Widget.combo
+    def disqus_combo(options = {})
+      Disqus::Widget::combo(options)
+    end
+    
+  end
+
+end

data/lib/disqus/widget.rb

@@ -0,0 +1,181 @@
+module Disqus
+
+  # Disqus Widget generator.
+  #
+  # All of the methods accept various options, and "account" is required for
+  # all of them. You can avoid having to pass in the account each time by
+  # setting it in the defaults like this:
+  #
+  #  Disqus::defaults[:account] = "my_account"
+  class Widget
+  
+    VALID_COLORS = ['blue', 'grey', 'green', 'red', 'orange']
+    VALID_NUM_ITEMS = 5..20
+    VALID_DEFAULT_TABS = ['people', 'recent', 'popular']
+    VALID_AVATAR_SIZES = [24, 32, 48, 92, 128]
+    VALID_ORIENTATIONS = ['horizontal', 'vertical']
+
+    ROOT_PATH = 'http://disqus.com/forums/%s/'
+    THREAD = ROOT_PATH + 'embed.js'
+    COMBO = ROOT_PATH + 'combination_widget.js?num_items=%d&color=%s&default_tab=%s'
+    RECENT = ROOT_PATH + 'recent_comments_widget.js?num_items=%d&avatar_size=%d'
+    POPULAR = ROOT_PATH + 'popular_threads_widget.js?num_items=%d'
+    TOP = ROOT_PATH + 'top_commenters_widget.js?num_items=%d&avatar_size=%d&orientation=%s'
+    class << self
+      
+      # Show the main Disqus thread widget.
+      # Options:
+      # * <tt>account:</tt> Your Discus account (required).
+      def thread(opts = {})
+        opts = Disqus::defaults.merge(opts)
+        opts[:view_thread_text] ||= "View the discussion thread"
+        validate_opts!(opts)
+        s = '<div id="disqus_thread"></div>'
+        s << '<script type="text/javascript" src="' + THREAD + '"></script>'
+        s << '<noscript><a href="http://%s.disqus.com/?url=ref">'
+        s << opts[:view_thread_text]
+        s << '</a></noscript>'
+        if opts[:show_powered_by]
+          s << '<a href="http://disqus.com" class="dsq-brlink">blog comments '
+          s << 'powered by <span class="logo-disqus">Disqus</span></a>'
+        end
+        s % [opts[:account], opts[:account]]
+      end
+      
+      # Loads Javascript to show the number of comments for the page.
+      #
+      # The Javascript 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>
+      # Options:
+      # * <tt>account:</tt> Your Discus account (required).
+      def comment_counts(opts = {})
+        opts = Disqus::defaults.merge(opts)        
+        validate_opts!(opts)
+        s = <<-WHIMPER
+        <script type="text/javascript">
+        //<[CDATA[
+        (function() {
+            var links = document.getElementsByTagName('a');
+            var query = '?';
+            for(var i = 0; i < links.length; i++) {
+              if(links[i].href.indexOf('#disqus_thread') >= 0) {
+                query += 'url' + i + '=' + encodeURIComponent(links[i].href) + '&';
+              }
+            }
+            document.write('<script type="text/javascript" src="#{ROOT_PATH}get_num_replies.js' + query + '"></' + 'script>');
+          })();
+        //]]>
+        </script>
+        WHIMPER
+        s % opts[:account]
+      end
+      
+      # Show the top commenters Disqus thread widget.
+      # Options:
+      # * <tt>account:</tt> Your Discus account (required).
+      # * <tt>header:</tt> HTML snipper with header (default h2) tag and text.
+      # * <tt>show_powered_by:</tt> Show or hide the powered by Disqus text.
+      # * <tt>num_items:</tt>: How many items to show.
+      # * <tt>hide_mods:</tt> Don't show moderators.
+      # * <tt>hide_avatars:</tt> Don't show avatars.
+      # * <tt>avatar_size:</tt> Avatar size.
+      def top_commenters(opts = {})
+        opts = Disqus::defaults.merge(opts)
+        opts[:header] ||= '<h2 class="dsq-widget-title">Top Commenters</h2>'
+        validate_opts!(opts)        
+        s = '<div id="dsq-topcommenters" class="dsq-widget">'
+        s << opts[:header]
+        s << '<script type="text/javascript" src="'
+        s << TOP
+        s << '&hide_avatars=1' if opts[:hide_avatars]
+        s << '&hide_mods=1' if opts[:hide_mods]
+        s << '"></script>'
+        s << '</div>'
+        if opts[:show_powered_by]
+          s << '<a href="http://disqus.com">Powered by Disqus</a>'
+        end
+        s % [opts[:account], opts[:num_items], opts[:avatar_size], opts[:orientation]]
+      end
+      
+      # Show the popular threads Disqus widget.
+      # Options:
+      # * <tt>account:</tt> Your Discus account (required).
+      # * <tt>header:</tt> HTML snipper with header (default h2) tag and text.
+      # * <tt>num_items:</tt>: How many items to show.
+      # * <tt>hide_mods:</tt> Don't show moderators.
+      def popular_threads(opts = {})
+        opts = Disqus::defaults.merge(opts)
+        opts[:header] ||= '<h2 class="dsq-widget-title">Popular Threads</h2>'
+        validate_opts!(opts)
+        s = '<div id="dsq-popthreads" class="dsq-widget">'
+        s << opts[:header]
+        s << '<script type="text/javascript" src="'
+        s << POPULAR
+        s << '&hide_mods=1' if opts[:hide_mods]
+        s << '"></script>'
+        s << '</div>'
+        s << '<a href="http://disqus.com">Powered by Disqus</a>' if opts[:show_powered_by]
+        s % [opts[:account], opts[:num_items]]
+      end
+    
+      # Show the recent comments Disqus widget.
+      # Options:
+      # * <tt>account:</tt> Your Discus account (required).
+      # * <tt>header:</tt> HTML snipper with header (default h2) tag and text.
+      # * <tt>num_items:</tt>: How many items to show.
+      # * <tt>hide_avatars:</tt> Don't show avatars.
+      # * <tt>avatar_size:</tt> Avatar size.
+      def recent_comments(opts = {})
+        opts = Disqus::defaults.merge(opts)
+        opts[:header] ||= '<h2 class="dsq-widget-title">Recent Comments</h2>'
+        validate_opts!(opts)
+        s = '<div id="dsq-recentcomments" class="dsq-widget">'
+        s << opts[:header]
+        s << '<script type="text/javascript" src="'
+        s << RECENT 
+        s << '&hide_avatars=1' if opts[:hide_avatars]
+        s << '"></script>'
+        s << '</div>'
+        if opts[:show_powered_by]
+          s << '<a href="http://disqus.com">Powered by Disqus</a>'
+        end
+        s % [opts[:account], opts[:num_items], opts[:avatar_size]]
+      end
+    
+      # Show the Disqus combo widget. This is a three-tabbed box with links
+      # popular threads, top posters, and recent threads.
+      # Options:
+      # * <tt>:account:</tt> Your Discus account (required).
+      # * <tt>:num_items:</tt> How many items to show.
+      # * <tt>:hide_mods:</tt> Don't show moderators.
+      # * <tt>:default_tab:</tt> Should be 'people', 'recent', or 'popular'.
+      def combo(opts = {})
+        opts = Disqus::defaults.merge(opts)
+        validate_opts!(opts)
+        s = '<script type="text/javascript" src="'
+        s << COMBO
+        s << '&hide_mods=1' if opts[:hide_mods]
+        s << '"></script>' 
+        s % [opts[:account], opts[:num_items], opts[:color], opts[:default_tab]]
+      end
+      
+      private
+
+      def validate_opts!(opts)
+        raise ArgumentError.new("You must specify an :account") if !opts[:account]
+        raise ArgumentError.new("Invalid color") if opts[:color] && !VALID_COLORS.include?(opts[:color])
+        raise ArgumentError.new("Invalid num_items") if opts[:num_items] && !VALID_NUM_ITEMS.include?(opts[:num_items])
+        raise ArgumentError.new("Invalid default_tab") if opts[:default_tab] && !VALID_DEFAULT_TABS.include?(opts[:default_tab])
+        raise ArgumentError.new("Invalid avatar size") if opts[:avatar_size] && !VALID_AVATAR_SIZES.include?(opts[:avatar_size])
+        raise ArgumentError.new("Invalid orientation") if opts[:orientation] && !VALID_ORIENTATIONS.include?(opts[:orientation])
+      end
+      
+    end
+  
+  end
+
+end