gravatarify 0.7.0 → 1.0.0

data/.gitignore

@@ -1,3 +1,4 @@
 doc/
 pkg/
 .yardoc
+*.gemspec

data/README.md

@@ -4,15 +4,19 @@ Removes any hassles building those pesky gravatar urls, it's not there arent any
 [there](http://github.com/chrislloyd/gravtastic), but none seem to support stuff like `Proc`s for the default picture url, or
 the multiple host names supported by gravatar.com (great when displaying lots of avatars).
 
-Best of it? It works with Rails, probably Merb and even plain old Ruby :)
+And it integrates seamlessly with Rails, Merb and even plain old Ruby.
+
+- **Source**: [http://github.com/lwe/gravatarify](http://github.com/lwe/gravatarify)
+- **Docs**:   [http://rdoc.info/projects/lwe/gravatarify](http://rdoc.info/projects/lwe/gravatarify)
+- **Gem**:    [http://gemcutter.org/gems/gravatarify](http://gemcutter.org/gems/gravatarify)
 
 ## Install
 
 Just install the gem (ensure you have gemcutter in your sources!)
 
-    sudo gem install gravatarify
+    [sudo] gem install gravatarify
    
-Ready to go! Using Rails? Either add (to `config/environment.rb`):
+Ready to go! Using Rails? Either add as gem (in `config/environment.rb`):
 
     config.gem 'gravatarify', :source => 'http://gemcutter.org'
     
@@ -20,34 +24,44 @@ or install as Rails plugin:
 
     ./script/plugin install git://github.com/lwe/gravatarify.git
     
-If the gem is available, just require it (for your simple ruby apps):
+Of course it's also possible to just add the library onto the `$LOAD_PATH`
+and then `require 'gravatarify'` it.
 
-    require 'rubygems'
-    require 'gravatarify'
+# Usage
+
+This library provides...
 
+ * ...object/model helpers, so that an object responds to `gravatar_url`, see [using the model helpers](#l_model_helpers).
+   Works also very well with plain old ruby objects.
+ * ...Rails view helpers, namely `gravatar_url` and `gravatar_tag`, see [using the view helpers](#l_view_helpers). This is rails only though!
+ * ...and finally, a base module which provides the gravatar url generation, ready to be integrated into
+   custom helpers, plain ruby code or whatever, see [back to the roots](#l_roots)
+
+<a id="l_view_helpers"/>
 ## Using the view helpers (Rails only!)
 
 Probably one of the easiest ways to add support for gravatar images is with the included view helpers:
 
     <%= gravatar_tag @user %> # assumes @user has email or mail field!
-    
+
 This builds a neat `<img/>`-tag, if you need to pass in stuff like the size etc. just:
 
     <%= gravatar_tag @user, :size => 25, :rating => :x, :class => "gravatar" %>
-    
+
 This will display an "X" rated avatar which is 25x25 pixel in size and the image tag will have the class `"gravatar"`.
 If more control is required, or just the URL, well then go ahead and use `gravatar_url` instead:
 
-     <%= image_tag gravatar_url(@user.author_email, :size => 16), :size => "16x16",
-          :alt => @user.name, :class => "avatar avatar-16"}/
-    
+    <%= image_tag gravatar_url(@user.author_email, :size => 16), :size => "16x16",
+         :alt => @user.name, :class => "avatar avatar-16"}/
+
 Using rails `image_tag` to create an `<img/>`-tag with `gravatar_url`. It's important to know that 
 also an object can be passed to `gravatar_url`, if it responds to either `email` or `mail`. If not (like
 in the example above), the email address must be passed in.
 
+<a id="l_model_helpers"/>
 ## Using the model helpers
 
-Another way (especially cool) for models is to do:
+A very simple method to add `gravatar_url` support to models is by using the `gravatarify` class method.
 
     class User < ActiveRecord::Base
      gravatarify
@@ -94,6 +108,7 @@ class:
 Tadaaa! Works exactly like the model helpers, so it's now possible to call `gravatar_url` on instances
 of `PoroUser`.
 
+<a id="l_roots"/>
 ## Back to the roots?
 
 No need for sophisticated stuff like view helpers and ActiveRecord integration, want to go back to the roots?
@@ -178,6 +193,27 @@ Into the block is passed the options hash and as second parameter the object its
 Not only the `:default` option accepts a Proc, but also `:secure`, can be useful to handle cases where
 it should evaluate against `request.ssl?` for example.
 
+## About the code
+
+Eventhough this library has less than 100 LOC, it's split into four files, maybe a bit
+of an overkill, though I like neat and tidy classes :)
+
+    lib/gravatarify.rb                      # loads the other files from lib/gravatarify
+                                            # and hooks the necessary modules into
+                                            # ActionView, ActiveRecord and DataMapper
+                                            # (if available)
+                                            
+    lib/gravatarify/base.rb                 # Provides all logic required to generate
+                                            # gravatar.com urls from an email address.
+                                            # Check out Gravatarify::Base.build_gravatar_url,
+                                            # this is the absolute core method.
+                                            
+    lib/gravatarify/object_support.rb       # Module which (when) included provides the
+                                            # gravatarify class method to add a gravatar_url
+                                            # to any object.
+                                            
+    lib/gravatarify/view_helper.rb          # Defines rails view helpers.
+
 ## Licence
 
 Copyright (c) 2009 Lukas Westermann

data/Rakefile

@@ -2,6 +2,10 @@ require 'rake'
 require 'rake/testtask'
 require 'yard'
 
+def gravatarify_version
+  @gravatarify_version ||= (tmp = YAML.load(File.read('VERSION.yml'))) && [tmp[:major], tmp[:minor], tmp[:patch]] * '.'
+end
+
 desc 'Default: run unit tests.'
 task :default => :test
 
@@ -18,7 +22,7 @@ YARD::Rake::YardocTask.new(:doc) do |t|
   t.files = ['lib/**/*.rb']
   t.options = [
       "--readme", "README.md",
-      "--title", "Gravatarify API Documentation"
+      "--title", "gravatarify (v#{gravatarify_version}) API Documentation"
   ]
 end
 
@@ -26,10 +30,17 @@ begin
   require 'jeweler'
   Jeweler::Tasks.new do |gemspec|
     gemspec.name = "gravatarify"
-    gemspec.summary = "Gravatar URLs for your ruby"
+    gemspec.summary = "Awesome gravatar support for ruby (and rails)."
+    description = <<-DESC
+    Yet another ruby/rails gravatar plugin - though, one with unique options like 
+    `Proc`s for default images, or support for gravatar.com's multiple host names.
+    DESC
+    gemspec.description = description.strip
     gemspec.email = "lukas.westermann@gmail.com"
     gemspec.homepage = "http://github.com/lwe/gravatarify"
     gemspec.authors = ["Lukas Westermann"]
+    gemspec.licenses = %w{LICENSE}
+    gemspec.extra_rdoc_files = %w{README.md}
   end
   Jeweler::GemcutterTasks.new
 rescue LoadError
@@ -40,6 +51,7 @@ desc 'Clean all generated files (.yardoc and doc/*)'
 task :clean do |t|
   FileUtils.rm_rf "doc"
   FileUtils.rm_rf "pkg"
+  FileUtils.rm_rf "gravatarify.gemspec"
   FileUtils.rm_rf ".yardoc"
 end
 

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
 :patch: 0
-:major: 0
-:minor: 7
+:major: 1 
+:minor: 0

data/lib/gravatarify/base.rb

@@ -2,9 +2,11 @@ require 'digest/md5'
 require 'cgi'
 
 module Gravatarify
+  # Subdomains used for balancing
+  GRAVATAR_SUBDOMAINS = %w{ 0 1 2 www } 
   
-  # Hosts used for balancing
-  GRAVATAR_HOSTS = %w{ 0 1 2 www }
+  # Fallback if no subdomain is found
+  GRAVATAR_DEFAULT_SUBDOMAIN = 'www'
   
   # If no size is specified, gravatar.com returns 80x80px images
   GRAVATAR_DEFAULT_SIZE = 80
@@ -18,8 +20,43 @@ module Gravatarify
   # Hash of :ultra_long_option_name => 'abbrevated option'
   GRAVATAR_ABBREV_OPTIONS = { :default => 'd', :rating => 'r', :size => 's' }
   
-  # Options which can be globally overriden by the application
-  def self.options; @options ||= {} end
+  class << self
+    # Globally define options which are then merged on every call to
+    # +build_gravatar_url+, this is useful to e.g. define the default image.
+    #
+    # Setting global options should be done (for Rails apps) in an initializer:
+    #
+    #     # set the default image using a Proc
+    #     Gravatarify.options[:default] = Proc.new { |*args| "http://example.com/avatar-#{args.first[:size] || 80}.jpg" }
+    #
+    #     # or set a custom default rating
+    #     Gravatarify.options[:rating] = :R
+    #
+    def options; @options ||= {} end
+  
+    # Globally overide subdomains used to build gravatar urls, normally
+    # +gravatarify+ picks from either +0.gravatar.com+, +1.gravatar.com+,
+    # +2.gravatar.com+ or +www.gravatar.com+ when building hosts, to use a custom
+    # set of subdomains (or none!) do something like:
+    #
+    #     Gravatarify.subdomains = %w{ 0 www } # only use 0.gravatar.com and www.gravatar.com
+    #
+    #     Gravatarify.subdomain = 'www' # only use www! (PS: subdomain= is an alias)
+    #
+    def subdomains=(subdomains) @subdomains = [*subdomains] end
+    alias_method :subdomain=, :subdomains=
+    
+    # Shortcut method to reset subdomains to only build +www.gravatar.com+ urls,
+    # i.e. disable host balancing!
+    def use_www_only!; self.subdomains = %w{ www } end
+
+    # Access currently defined subdomains, defaults are +GRAVTAR_SUBDOMAINS+.
+    def subdomains; @subdomains ||= GRAVATAR_SUBDOMAINS end
+    
+    # Get subdomain for supplied string or returns +GRAVATAR_DEFAULT_SUBDOMAIN+ if none is
+    # defined.
+    def subdomain(str); subdomains[str.hash % subdomains.size] || GRAVATAR_DEFAULT_SUBDOMAIN end
+  end
   
   # Provides core support to build gravatar urls based on supplied e-mail strings.
   module Base
@@ -70,7 +107,7 @@ module Gravatarify
     private
       def build_gravatar_host(str_hash, secure = false)
         secure = secure.call(self) if secure.respond_to?(:call)
-        secure ? "https://secure.gravatar.com" : "http://#{GRAVATAR_HOSTS[str_hash.hash % GRAVATAR_HOSTS.size] || 'www'}.gravatar.com"        
+        secure ? "https://secure.gravatar.com" : "http://#{Gravatarify.subdomain(str_hash)}.gravatar.com"        
       end
     
       def build_gravatar_options(url_options = {})

data/lib/gravatarify/view_helper.rb

@@ -1,3 +1,5 @@
+# The view helper, especially for the +gravatar_tag+ helper, requires
+# rails!
 module Gravatarify::ViewHelper
   include Gravatarify::Base
 

data/test/gravatarify_base_test.rb

@@ -8,10 +8,7 @@ end
 class GravatarifyBaseTest < Test::Unit::TestCase
   include Gravatarify::Base
   
-  def setup
-    # just ensure that no global options are defined when starting next test
-    Gravatarify.options.clear
-  end
+  def setup; reset_gravatarify! end
     
   context "#build_gravatar_url, but without any options yet" do
     should "generate correct url for hash without options" do

data/test/gravatarify_integration_test.rb

@@ -4,7 +4,7 @@ begin; require 'dm-core'; rescue LoadError; end
 require 'gravatarify'
 
 class GravatarifyIntegrationTest < Test::Unit::TestCase
-  def setup; Gravatarify.options.clear end
+  def setup; reset_gravatarify! end
 
   context "ActiveRecord::Base" do
     if defined?(ActiveRecord)    

data/test/gravatarify_object_support_test.rb

@@ -3,7 +3,7 @@ require 'gravatarify/base'
 require 'gravatarify/object_support'
 
 class GravatarifyObjectSupportTest < Test::Unit::TestCase
-  def setup; Gravatarify.options.clear end
+  def setup; reset_gravatarify! end
   
   context "#gravatarify" do
     should "add support for #gravatar_url to POROs (plain old ruby objects, yeah POJO sounds better!)" do

data/test/gravatarify_subdomain_test.rb

@@ -0,0 +1,36 @@
+require 'test_helper'
+require 'gravatarify/base'
+
+class GravatarifySubdomainTest < Test::Unit::TestCase
+  include Gravatarify::Base
+  
+  def setup; reset_gravatarify! end
+    
+  context "changing hosts through Gravatarify#subdomains" do
+    should "override default subdomains (useful to e.g. switch back to 'www' only)" do
+      Gravatarify.subdomains = ['0', '1']
+      assert_equal "http://0.gravatar.com/avatar/4979dd9653e759c78a81d4997f56bae2.jpg", build_gravatar_url('info@initech.com')
+      assert_equal "http://1.gravatar.com/avatar/d4489907918035d0bc6ff3f6c76e760d.jpg", build_gravatar_url('support@initech.com')
+    end
+    
+    should "take in a string only argument, like www (and be aliased to 'subdomain' to singularize it :D)" do
+      Gravatarify.subdomain = 'www'
+      assert_equal "http://www.gravatar.com/avatar/4979dd9653e759c78a81d4997f56bae2.jpg", build_gravatar_url('info@initech.com')
+      assert_equal "http://www.gravatar.com/avatar/d4489907918035d0bc6ff3f6c76e760d.jpg", build_gravatar_url('support@initech.com')      
+    end
+    
+    should "still work as expected if passed in `nil` and return urls with default subdomain `www`" do
+      Gravatarify.subdomain = nil
+      assert_equal "http://www.gravatar.com/avatar/4979dd9653e759c78a81d4997f56bae2.jpg", build_gravatar_url('info@initech.com')
+      assert_equal "http://www.gravatar.com/avatar/d4489907918035d0bc6ff3f6c76e760d.jpg", build_gravatar_url('support@initech.com')            
+    end
+  end
+  
+  context "Gravatarify#use_only_www!" do
+    should "only generate www.gravatar.com urls" do
+      Gravatarify.use_www_only!
+      assert_equal "http://www.gravatar.com/avatar/4979dd9653e759c78a81d4997f56bae2.jpg", build_gravatar_url('info@initech.com')
+      assert_equal "http://www.gravatar.com/avatar/d4489907918035d0bc6ff3f6c76e760d.jpg", build_gravatar_url('support@initech.com')      
+    end
+  end  
+end

data/test/gravatarify_view_helper_test.rb

@@ -1,6 +1,7 @@
 require 'test_helper'
 require 'active_support'
 require 'action_view/helpers'
+require 'gravatarify'
 require 'gravatarify/view_helper'
 
 class GravatarifyViewHelperTest < Test::Unit::TestCase
@@ -9,7 +10,7 @@ class GravatarifyViewHelperTest < Test::Unit::TestCase
   
   def setup
     # just ensure that no global options are defined when starting next test
-    Gravatarify.options.clear
+    reset_gravatarify!
   end
   
   context "#gravatar_tag helper" do

data/test/test_helper.rb

@@ -4,3 +4,9 @@ require 'shoulda'
 require 'rr'
 
 Test::Unit::TestCase.send :include, RR::Adapters::TestUnit
+
+# Reset +Gravatarify+ to default hosts and cleared options
+def reset_gravatarify!
+  Gravatarify.options.clear
+  Gravatarify.subdomains = Gravatarify::GRAVATAR_SUBDOMAINS
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: gravatarify
 version: !ruby/object:Gem::Version 
-  version: 0.7.0
+  version: 1.0.0
 platform: ruby
 authors: 
 - Lukas Westermann
@@ -9,18 +9,19 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-09-29 00:00:00 +02:00
+date: 2009-10-02 00:00:00 +02:00
 default_executable: 
 dependencies: []
 
-description: 
+description: |-
+  Yet another ruby/rails gravatar plugin - though, one with unique options like 
+      `Proc`s for default images, or support for gravatar.com's multiple host names.
 email: lukas.westermann@gmail.com
 executables: []
 
 extensions: []
 
 extra_rdoc_files: 
-- LICENSE
 - README.md
 files: 
 - .gitignore
@@ -36,12 +37,13 @@ files:
 - test/gravatarify_base_test.rb
 - test/gravatarify_integration_test.rb
 - test/gravatarify_object_support_test.rb
+- test/gravatarify_subdomain_test.rb
 - test/gravatarify_view_helper_test.rb
 - test/test_helper.rb
 has_rdoc: true
 homepage: http://github.com/lwe/gravatarify
-licenses: []
-
+licenses: 
+- LICENSE
 post_install_message: 
 rdoc_options: 
 - --charset=UTF-8
@@ -65,10 +67,11 @@ rubyforge_project:
 rubygems_version: 1.3.5
 signing_key: 
 specification_version: 3
-summary: Gravatar URLs for your ruby
+summary: Awesome gravatar support for ruby (and rails).
 test_files: 
 - test/gravatarify_base_test.rb
 - test/gravatarify_integration_test.rb
 - test/gravatarify_object_support_test.rb
+- test/gravatarify_subdomain_test.rb
 - test/gravatarify_view_helper_test.rb
 - test/test_helper.rb