markbates-content_o_matic 0.0.2.20090721162019 → 0.1.0.20090721175910

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) 2009 markbates
+Copyright (c) 2009 Mark Bates
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/lib/content_o_matic/content_cache.rb

@@ -1,4 +1,10 @@
 module ContentOMatic
+  # This class is used to cache results of succesful retrieval of a web page.
+  # It uses Cachetastic to do the caching. You can expect to receive
+  # ContentOMatic::Response objects, if they are in the cache.
+  # 
+  # Caching can be turned on (it's off by default) with the following configatron setting:
+  #   configatron.content_o_matic.cache_results = true
   class ContentCache < Cachetastic::Cache
     
   end # ContentCache

data/lib/content_o_matic/content_o_matic.rb

@@ -2,10 +2,37 @@ module ContentOMatic
   
   class << self
     
+    # Returns the logger being used by ContentOMatic.
+    # The logger can be set with the following configatron setting:
+    #   configatron.content_o_matic.logger = ::Logger.new(STDOUT)
+    # 
+    # In a Rails environment this defaults to the <tt>RAILS_DEFAULT_LOGGER</tt>.
+    # The non-Rails default is:
+    #   <pwd>/log/content_o_matic.log
     def logger
       configatron.content_o_matic.logger
     end
     
+    # This method does pretty much all of the heavy work. You pass it a url
+    # and it will fetch the contents of that page and return a ContentOMatic::Response
+    # object to you.
+    # 
+    # If you pass in a 'relative' url it will be joined with a default url that can be
+    # set with the following configatron setting:
+    #   configatron.content_o_matic.url = 'http://www.example.com'
+    # 
+    # url examples:
+    #   'foo.html' => 'http://www.example.com/foo.html'
+    #   '/foo.html' => 'http://www.example.com/foo.html'
+    #   '/foo/bar.html' => 'http://www.example.com/foo/bar.html'
+    #   'http://www.example.com/index.html' => 'http://www.example.com/index.html'
+    # 
+    # Any options passed into will become query string parameters passed to the 
+    # requested url.
+    # 
+    # If you have caching enabled it will look first in the cache, if it doesn't find
+    # it there, it will do a fetch of the page and store it in the cache, if it was successful.
+    # See ContentOMatic::ContentCache for more details on caching.
     def get(slug_url, options = {})
       if configatron.content_o_matic.retrieve(:cache_results, false)
         url = url_from_slug(slug_url, options)
@@ -21,7 +48,7 @@ module ContentOMatic
       end
     end
     
-    def get_without_cache(slug_url, options = {})
+    def get_without_cache(slug_url, options = {}) # :nodoc:
       url = url_from_slug(slug_url, options)
       begin
         Timeout::timeout(configatron.content_o_matic.response.time_out) do
@@ -34,7 +61,7 @@ module ContentOMatic
       end
     end # get_without_cache
     
-    def url_from_slug(slug_url, options = {})
+    def url_from_slug(slug_url, options = {}) # :nodoc:
       return slug_url if slug_url.nil?
       url = slug_url
       if !slug_url.match(/^([a-zA-Z]+):\/\//)

data/lib/content_o_matic/errors.rb

@@ -1,5 +1,5 @@
 module ContentOMatic
-    
+  
   class InvalidResponseError < StandardError
   end # InvalidResponseError
 

data/lib/content_o_matic/response.rb

@@ -1,33 +1,58 @@
 module ContentOMatic
-    
+  # This class wraps the response received from pulling down content from a web page.
   class Response
     
+    # The status of the response
     attr_accessor :status
+    # The full body of the response
     attr_accessor :body
+    # The url of the requested page
     attr_accessor :url
     
+    # Takes the url of the requested page, the status code of the
+    # response, and the body of the response.
     def initialize(url, status, body = '')
       self.url = url
       self.status = status.to_i
       self.body = body
     end
     
+    # Returns <tt>true</tt> if the status of the page was 200
     def success?
       self.status == 200
     end
     
-    def to_s
+    def to_s # :nodoc:
       self.success? ? self.body : ''
     end
     
-    def to_str
+    def to_str # :nodoc:
       self.to_s
     end
     
+    # Returns <tt>true</tt> if the page is wrapped in <tt>html</tt> tags.
     def has_layout?
       return self.body != self.html_body
     end
     
+    # Returns the 'full' HTML body of the requested page.
+    # If you pass in <tt>true</tt> it will normalize all the links
+    # found in the body.
+    # 
+    # Example:
+    #   # http://www.example.com/foo/bar.html
+    #   <img src='image.jpg'> # => <img src='http://www.example.com/foo/image.jpg'>
+    #   <img src='/image.jpg'> # => <img src='http://www.example.com/image.jpg'>
+    #   <img src='http://www.example.org/image.jpg'> # => <img src='http://www.example.org/image.jpg'>
+    # 
+    # The following tags get 'normalized' with the <tt>true</tt> parameter:
+    #   img
+    #   script
+    #   link
+    #   a
+    #   iframe
+    #   form
+    #   object
     def body(normalize_assets = false)
       if normalize_assets
         unless @__normalized_body
@@ -50,6 +75,10 @@ module ContentOMatic
       @body
     end
     
+    # Returns just the content within the HTML 'body' tag.
+    # If there is no 'body' tag, then the whole response body is returned.
+    # If you pass in <tt>true</tt> it will normalize all the links
+    # found in the body. See the body method for more details.
     def html_body(normalize_assets = false)
       unless @__doc_body
         doc = Nokogiri::HTML(self.body(normalize_assets))
@@ -59,8 +88,10 @@ module ContentOMatic
       return @__doc_body
     end
     
+    # Returns a ContentOMatic::InvalidResponseError exception if the
+    # response was not a success.
     def exception
-      ContentOMatic::InvalidResponseError.new("URL: '#{self.url}' did not return a valid response! Status: '#{self.status}' Body: '#{self.body}'") unless self.success?
+      ContentOMatic::InvalidResponseError.new("URL: '#{self.url}' did not return a valid response! Status: '#{self.status}'") unless self.success?
     end
     
     private

data/lib/content_o_matic/text_helper.rb

@@ -1,21 +1,23 @@
-module ActionView
-  module Helpers
+module ActionView # :nodoc:
+  module Helpers # :nodoc:
     module TextHelper
       
+      # This convenience method automatically plugs into Rails views, however,
+      # this module could easily be included in a non-Rails environment.
+      # 
+      # This method wraps the ContentOMatic.get method with some nice HTML
+      # comments to let you know what has been loaded. It also normalizes
+      # links in that content by default. See ContentOMatic::Response body for more
+      # information on normalizing links.
+      # 
+      # This method will also, by default, return just the contents of the HTML
+      # 'body' tag.
       def content_o_matic(slug, options = {})
         options = {} if options.nil?
-        comments = true
-        if options.has_key?(:print_comments)
-          comments = options.delete(:print_comments)
-        end
-        html_body = true
-        if options.has_key?(:html_body)
-          html_body = options.delete(:html_body)
-        end
-        normalize_assets = true
-        if options.has_key?(:normalize_assets)
-          normalize_assets = options.delete(:normalize_assets)
-        end
+        options = {:print_comments => true, :html_body => true, :normalize_assets => true}.merge(options)
+        comments = options.delete(:print_comments)
+        html_body = options.delete(:html_body)
+        normalize_assets = options.delete(:normalize_assets)
         text = "<!-- Loading Content: '#{slug}' -->\n" if comments
         begin
           res = ContentOMatic.get(slug, options)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: markbates-content_o_matic
 version: !ruby/object:Gem::Version 
-  version: 0.0.2.20090721162019
+  version: 0.1.0.20090721175910
 platform: ruby
 authors: 
 - markbates