gravatarify 1.2.1 → 2.0.3

data/README.md

@@ -2,15 +2,22 @@ Gravatarify
 ===========
 
 Hassle-free construction of those pesky gravatar.com urls, with out-of-the-box support for
-Rails, DataMapper and Haml. It's not that there aren't any alternatives [out](http://github.com/mdeering/gravitar_image_tag),
+Rails, Haml and _your favorite framework_. It's not that there aren't any alternatives [out](http://github.com/mdeering/gravitar_image_tag),
 [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).
 
 - **Source**: <http://github.com/lwe/gravatarify>
 - **Docs**:   <http://rdoc.info/projects/lwe/gravatarify>
+- **List**:   <http://groups.google.com/group/gravatarify-plugin>
 - **Gem**:    <http://gemcutter.org/gems/gravatarify>
 
+**UPGRADE NOTES:** Version 2.x is a clean-up release which breaks backwards compatibility
+with 1.x releases (in some cases!). HTML attributes must be passed like:
+`gravatar_tag(@user, :size => 30, :html => { :class => "gravatar" })`, i.e. in a `:html` hash.
+Furthermore the `gravatarify` method for ActiveRecord and DataMapper no longer exists,
+see "Upgrading from 1.x" for more.
+
 Ready, Set, Go!
 ---------------
 
@@ -38,10 +45,9 @@ and then `require 'gravatarify'`'d somehow.
 **More!?** Allright, that was just the quickstart, to get up and running with ease. However, this library provides
 quite a bit more, like:
 
- * ...view helpers, namely `gravatar_url` and `gravatar_tag`, see "Using the view helpers".
- * ...object/model helpers, so that an object responds to `gravatar_url`, see "Using the model helpers"
-   Works also very well with plain old ruby objects.
- * ...and finally, a base module which provides the gravatar url generation, ready to be integrated into
+ * View helpers, namely `gravatar_url` and `gravatar_tag`, see "Using the view helpers".
+ * Styles are like reusable definitions of options, nice to DRY-up your code, see "Using styles".
+ * 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".
 
 Using the view helpers
@@ -67,73 +73,55 @@ or a string containing the e-mail address:
 This builds a neat `<img/>`-tag. To display an "X" rated avatar which is 25x25 pixel in size
 and the `<img/>` tag should have a class attribute, do:
 
-    <%= gravatar_tag @user, :size => 25, :rating => :x, :class => "gravatar" %>
+    <%= gravatar_tag @user, :size => 25, :rating => :x, :html => { :class => "gravatar" } %>
 
-If more control is needed, or just the plain URL is required, resort to `gravatar_url`, which
-returns a string with the (unescaped) url:
+If any additional HTML attributes are needed on the tag, or in the `gravatar_attrs`, just
+pass them in the `:html` option as hash. If more control is needed, or just the plain URL is
+required, resort to `gravatar_url`, which returns a string with the (unescaped) url:
     
     <img src="<%= h(gravatar_url(@user.author_email, :size => 16)) %>" alt="Gravatar"/>
-        
-Using the model helpers
------------------------
-
-A very simple method to add `gravatar_url` support to models is by using the `gravatarify` class method.
-
-    # Assuming User has a field named email or mail!
-    class User < ActiveRecord::Base
-      gravatarify
-    end
-
-Thats it! Well, at least if the `User` model responds to `email` or `mail`. Then in the views all left to do is:
-
-    <%= image_tag @user.gravatar_url %>
-
-Neat, isn't it? Of course passing options works just like with the view helpers:
-
-    <%= image_tag @user.gravatar_url(:size => 16, :rating => :r) %>
-
-Defaults can even be passed to the `gravatarify` call, so no need to repeat them on every `gravatar_url` call.
-
-    gravatarify :employee_mail, :size => 16, :rating => :r
-
-All gravatars will now come from the `employee_mail` field, not the default `email` or `mail` field and be in 16x16px in size
-and have a rating of 'r'. Of course these can be overriden in calls to `gravatar_url` like before. Pretty cool is also the
-fact that an object can be passed directly to `gravatar_tag` if it responds to `gravatar_url`, like:
-
-    # model:
-    class User < ActiveRecord::Base
-      gravatarify :size => 16, :secure => true
-    end
-
-    # view:
-    <%= gravatar_tag @user %> # -> <img ... width="16" src="https://secure.gravatar..." height="16" />
+    
+Using styles
+------------
+
+With styles it's possible to easily change e.g. the size of all gravatars based on a name,
+these are reusable presets of options:
+  
+    # in config/initializers/gravatarify.rb or similar:
+    Gravatarify.styles[:mini] = { :size => 16, :html => { :class => 'gravatar gravatar-mini' } }
+    Gravatarify.styles[:default] = { :size => 45, :html => { :class => 'gravatar' } }
+ 
+    # then in/some/view.html.erb:
+    <%= gravatar_tag @user, :mini %> # => <img alt="" class="gravatar gravatar-mini" height="16" src.... />
+    
+    # or in/another/view.html.haml:    
+    %img{gravatar_attrs(@user, :default)/ # => <img alt="" class="gravatar" height="45" ... />
+    
+Need to change to size of all `:mini` gravatars? Easy, just change the definition in `Gravatarify.styles`.
+Of course settings via `Gravatarify.options` are "mixed-in" as well, so:
 
-The `gravatar_tag` looks if the object responds to `gravatar_url` and if so, just passes the options to it,
-it works also with plain old ruby objects, of course :)
+    Gravatarify.options[:default] = Proc.new { |*params| "http://example.com/avatar-#{params.first[:size] || 80}.jpg" }
+    Gravatarify.styles[:mini] => { :size => 16 }
+    
+    <%= gravatar_tag @user, :mini %> # => <img alt="" height="16" src=".....?d=http://example.com/avatar-16.jpg" width="16" />
 
-### PORO - plain old ruby objects (yeah, POJO sounds smoother :D)
+All methods accept a style, i.e. a style parameter can be passed in to `gravatar_attrs`, `gravatar_tag` and
+of course to `gravatar_url`. Any option can be passed in after a style, to customize the gravatar
+if the styles needs slight alteration:
 
-Not using Rails, ActiveRecord or DataMapper? It's as easy as including `Gravatarify::ObjectSupport` to your
-class:
+    gravatar_url(@user, :mini, :filetype => false, :rating => :x) # => "http://........123ab12?s=16&r=x"
 
-    require 'gravatarify'
-    class PoroUser
-      include Gravatarify::ObjectSupport
-      gravatarify
-    end
-    
-Tadaaa! Works exactly like the model helpers, so it's now possible to call `gravatar_url` on instances
-of `PoroUser`.
 
-## Back to the roots?
+Back to the roots?
+------------------
 
-No need for sophisticated stuff like view helpers and ActiveRecord integration, want to go back to the roots?
-Then feel free to use `Gravatarify::Base#build_gravatar_url` directly.
+No need for sophisticated stuff like view helpers, want to go back to the roots?
+Then feel free to use `Gravatarify::Base#gravatar_url` directly.
     
 When the ability to display image tags is required in different view frameworks (like liquid!?),
 then just ensure that `Gravatarify::Helper` is included in the framework in question.
-See {Gravatarify::Base#build_gravatar_url} and of course {Gravatarify::Helper}
-for more informations and usage examples.
+See {Gravatarify::Base#gravatar_url} and of course {Gravatarify::Helper} for more informations
+and usage examples.
 
 Need more control?
 ==================
@@ -186,6 +174,13 @@ Need more control?
       then a URL without an extension will be built (and gravatar.com then returns a JPG image).</td>
     <td><tt>:jpg</tt></td>
   </tr>
+  <tr>
+    <td><tt>:html</tt></td>
+    <td>Hash</td>
+    <td>Ignored in URL generation, only used in <tt>gravatar_attrs</tt> and <tt>gravatar_tag</tt> to pass in additional
+      HTML attributes (like <tt>class</tt>, <tt>id</tt> etc.).</td>
+    <td>-</td>
+  </tr>
 </table>
 
 To set the options globally, access the `Gravatarify.options` hash and set any options which should apply to all
@@ -198,13 +193,12 @@ gravatar urls there. Of course all settings can be overridden locally:
     gravatar_url(@user.email) # => http://0.gravatar.com/avatar/..f93ff1e?s=16
     gravatar_url(@user.email, :filetype => :png) # => http://0.gravatar.com/avatar/..f93ff1e.png?s=16
     
-A pretty nifty option also exists to set options globally for `gravatar_tag` and `gravatar_attrs`, e.g.
-to always add a title attribute:
+To define global HTML attributes go ahead and do something like:
 
     # add title attribute
-    Gravatarify::Helper.html_options[:title] = "Gravatar"
+    Gravatarify.options[:html] = { :title => "Gravatar" }
     
-### Not yet enough?
+## Not yet enough?
 
 The `:default` option can be passed in a `Proc`, so this is certainly useful to for example
 to generate an image url, based on the request size:
@@ -231,6 +225,53 @@ 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.
 
+## Upgrading from 1.x
+
+All HTML options must be passed in the `:html` attribute. This allows for predictable results for
+all methods and no magic involved! So instead of doing:
+
+    gravatar_tag(@user, :size => 30, :class => "gravatar", :title => "Gravatar")
+    # Note: in Version 2.0 this would build an image src like http://..gravatar.com/...../?class=gravatar&s=30&title=Gravatar
+    
+do:
+
+    gravatar_tag(@user, :size => 30, :html => { :class => "Gravatar", :title => "Gravatar" })
+    
+An important thing to know is that the `:html` is deep merged, with defaults, so stuff like:
+
+    Gravatarify.options[:html] = { :title => "Gravatar" }
+    gravatar_tag(@user, :html => { :class => "gravatar" }) # => <img alt="" class="gravatar" ... title="Gravatar" .../>
+    
+Furthermore the option `:html` is ignored when building the url parameters.
+
+If the `gravatarify` method was not used, there's no need to change anything at all :) Though if
+it's used, then...
+
+ 1. Remove all occurences of `gravatarify` in the models
+ 2. Change calls from `<%= image_tag @user.gravatar_url %>` to
+    saner `<%= gravatar_tag @user %>` calls or of course if just the url
+    is required to `gravatar_url(@user)`.
+
+If the model used `gravatarify :author_email`, then changes in the views must reflect that and use it
+directly: `<%= gravatar_tag @user.author_email %>`. If the model defines `author_email`, but **not**
+`email` (and has no attribute named `email`), then it could be safely aliased like:
+
+    # Fields: (id, name, author_email, ...)
+    class Author < ActiveRecord::Base
+      alias_attribute :email, :author_email
+    end
+    
+    # and in the views:
+    <%= gravatar_tag @author %>
+
+In most cases the migration path should be pretty easy, just always use the helper
+methods! The `gravatarify` method was introduced to provide compatibility with
+`gravtastic`, yet it's not way to go in my opinion. If for some reason it's required
+then feel free to fallback and use an older version (i.e. 1.2.1):
+
+    [sudo] gem install gravatarify -v 1.2.1
+    
+
 About the code
 ==============
 
@@ -239,20 +280,21 @@ 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)
+                                            # HAML or ActionView.
                                             
     lib/gravatarify/base.rb                 # Provides all logic required to generate
                                             # gravatar.com urls from an email address.
-                                            # Check out Gravatarify::Base.build_gravatar_url,
+                                            # Check out Gravatarify::Base.gravatar_url,
                                             # this is the absolute core method.
+                                                                                        
+    lib/gravatarify/helper.rb               # Defines the view helpers: gravatar_attrs
+                                            # and gravatar_tag
                                             
-    lib/gravatarify/object_support.rb       # Module which (when) included provides the
-                                            # gravatarify class method to add a gravatar_url
-                                            # to any object.
+    lib/gravatarify/utils.rb                # Provides commonly used methods, like helpers to
+                                            # uri and html escape strings or deep mergeing
+                                            # hashes. Though these utils are only for internal
+                                            # uses :)
                                             
-    lib/gravatarify/helper.rb               # Defines those view helpers, mainly gravatar_attrs
-                                            # and gravatar_tag
 ### Contribute
 
  1. Fork the project and hack away
@@ -285,4 +327,4 @@ 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.
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -30,9 +30,9 @@ begin
   require 'jeweler'
   Jeweler::Tasks.new do |gemspec|
     gemspec.name = "gravatarify"
-    gemspec.summary = "Awesome gravatar support for Ruby (and Rails, DataMapper, Haml)."
+    gemspec.summary = "Awesome gravatar support for Ruby (and Rails)."
     description = <<-DESC
-    Awesome gravatar support for Ruby (and Rails, DataMapper, Haml) -
+    Awesome gravatar support for Ruby (and Rails) -
     with unique options like Proc's for default images, or
     support for gravatar.com's multiple host names.
     DESC

data/VERSION.yml

@@ -1,4 +1,4 @@
 --- 
-:major: 1
-:minor: 2
-:patch: 1
+:major: 2
+:minor: 0
+:patch: 3

data/lib/gravatarify.rb

@@ -3,13 +3,8 @@
 # Base -> provides the basic gravatar_url method, can also be used for
 # custom implementations, just include Gravatarify::Base.
 require 'gravatarify/base'
-require 'gravatarify/object_support'
+require 'gravatarify/utils'
 require 'gravatarify/helper'
 
-# setup for AR und DataMapper, note: DataMapper yet untested :) but I suppose it works, because
-# it works as expected on plain old ruby objects!
-ActiveRecord::Base.send(:include, Gravatarify::ObjectSupport) if defined?(ActiveRecord)
-DataMapper::Model.append_inclusions(Gravatarify::ObjectSupport) if defined?(DataMapper)
-
 # and HAML support (if defined)
 Haml::Helpers.send(:include, Gravatarify::Helper) if defined?(Haml)

data/lib/gravatarify/base.rb

@@ -1,16 +1,13 @@
 require 'digest/md5'
-begin; require 'rack/utils'; rescue LoadError; require 'cgi' end
 
-module Gravatarify  
-  # List of known and valid gravatar options (includes shortened options).
-  GRAVATAR_OPTIONS = [ :default, :d, :rating, :r, :size, :s, :secure, :filetype ]
-
-  # Hash of :ultra_long_option_name => 'abbrevated option'
-  GRAVATAR_ABBREV_OPTIONS = { :default => 'd', :rating => 'r', :size => 's' }
+module Gravatarify
+  # Hash of 'ultra_long_option_name' => 'abbrevated option'
+  # :nodoc:
+  GRAVATAR_ABBREV_OPTIONS = { 'default' => 'd', 'rating' => 'r', 'size' => 's' }
   
   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.
+    # +gravatar_url+, this is useful to e.g. define the default image.
     #
     # Setting global options should be done (for Rails apps) in an initializer:
     #
@@ -25,6 +22,15 @@ module Gravatarify
     #
     def options; @options ||= { :filetype => :jpg } end
   
+    # Allows to define some styles, makes it simpler to call by name, instead of always giving a size etc.
+    # 
+    #   Gravatarify.styles[:mini] => { :size => 30, :default => "http://example.com/gravatar-mini.jpg" }
+    # 
+    #   # in the views, it will then use the stuff defined by styles[:mini]:
+    #   <%= gravatar_tag @user, :mini %>
+    #
+    def styles; @styles ||= {} 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
@@ -32,27 +38,13 @@ module Gravatarify
     #
     #     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 +%w{ 0 1 2 www }+.
-    def subdomains; @subdomains ||= %w{ 0 1 2 www } end
     
     # Get subdomain for supplied string or returns +www+ if none is
     # defined.
-    def subdomain(str); subdomains[str.hash % subdomains.size] || 'www' end
-    
-    # Helper method to URI escape a string using either <tt>Rack::Utils#escape</tt> if available or else
-    # fallback to <tt>CGI#escape</tt>.
-    def escape(str) #:nodoc:
-      str = str.to_s unless str.is_a?(String) # convert to string!
-      defined?(Rack::Utils) ? Rack::Utils.escape(str) : CGI.escape(str)
+    def subdomain(str) #:nodoc:
+      @subdomains ||= %w{ 0 1 2 www }
+      @subdomains[str.hash % @subdomains.size] || 'www'
     end
   end
   
@@ -62,7 +54,7 @@ module Gravatarify
     # Method which builds a gravatar url based on a supplied email and options as
     # defined by gravatar.com (http://en.gravatar.com/site/implement/url).
     #
-    #    build_gravatar_url('peter.gibbons@initech.com', :size => 16) # => "http://0.gravatar.com/avatar/cb7865556d41a3d800ae7dbb31d51d54.jpg?s=16"
+    #    gravatar_url('peter.gibbons@initech.com', :size => 16) # => "http://0.gravatar.com/avatar/cb7865556d41a3d800ae7dbb31d51d54.jpg?s=16"
     #
     # It supports multiple gravatar hosts (based on email hash), i.e. depending
     # on the hash, either <tt>0.gravatar.com</tt>, <tt>1.gravatar.com</tt>, <tt>2.gravatar.com</tt> or <tt>www.gravatar.com</tt>
@@ -72,18 +64,18 @@ module Gravatarify
     # is used instead to build the gravatar hash. Very useful to just pass in ActiveRecord object for instance:
     #    
     #    @user = User.find_by_email("samir@initech.com")
-    #    build_gravatar_url(@user) # => "http://2.gravatar.com/avatar/58cf31c817d76605d5180ce1a550d0d0.jpg"
-    #    build_gravatar_url(@user.email) # same as above!
+    #    gravatar_url(@user) # => "http://2.gravatar.com/avatar/58cf31c817d76605d5180ce1a550d0d0.jpg"
+    #    gravatar_url(@user.email) # same as above!
     # 
     # Among all options as defined by gravatar.com's specification, there also exist some special options:
     #
-    #    build_gravatar_url(@user, :secure => true) # => https://secure.gravatar.com/ava....
+    #    gravatar_url(@user, :secure => true) # => https://secure.gravatar.com/ava....
     #
     # Useful when working on SSL enabled sites. Of course often used options should be set through
     # +Gravatarify.options+.
     #
     # @param [String, #email, #mail] email a string representing an email, or object which responds to +email+ or +mail+
-    # @param [Hash] url_options customize generated gravatar.com url
+    # @param [Symbol, Hash] *params customize generated gravatar.com url. First argument can also be a style.
     # @option url_options [String, Proc] :default (nil) URL of an image to use as default when no gravatar exists. Gravatar.com
     #                                    also accepts special values like +identicon+, +monsterid+ or +wavater+ which just displays
     #                                    a generic icon based on the hash or <tt>404</tt> which return a HTTP Status 404.
@@ -96,12 +88,15 @@ module Gravatarify
     #                                      if an set to +false+, +nil+ or an empty string no extension is added.
     # @return [String] In any case (even if supplied +email+ is +nil+) returns a fully qualified gravatar.com URL.
     #                  The returned string is not yet HTML escaped, *but* all +url_options+ have been URI escaped.
-    def build_gravatar_url(email, url_options = {})
-      url_options = Gravatarify.options.merge(url_options)
-      email_hash = Digest::MD5.hexdigest(Base.get_smart_email_from(email).strip.downcase)
+    def gravatar_url(email, *params)
+      url_options = Utils.merge_gravatar_options(*params)
+      email_hash = Digest::MD5.hexdigest(Utils.smart_email(email))
       extension = (ext = url_options.delete(:filetype) and ext != '') ? ".#{ext || 'jpg'}" : '' # slightly adapted from gudleik's implementation
-      build_gravatar_host(email_hash, url_options.delete(:secure)) << "/avatar/#{email_hash}#{extension}#{build_gravatar_options(email, url_options)}"
+      build_gravatar_host(email_hash, url_options.delete(:secure)) + "/avatar/#{email_hash}#{extension}#{build_gravatar_options(email, url_options)}"
     end
+    
+    # For backwards compatibility.
+    alias_method :build_gravatar_url, :gravatar_url
   
     private
       # Builds gravatar host name from supplied e-mail hash.
@@ -116,22 +111,19 @@ module Gravatarify
         secure = secure.call(self) if secure.respond_to?(:call)
         secure ? "https://secure.gravatar.com" : "http://#{Gravatarify.subdomain(str_hash)}.gravatar.com"        
       end
-    
+          
       # Builds a query string from all passed in options.
       def build_gravatar_options(source, url_options = {})
-        params = []
-        url_options.each_pair do |key, value|
-          key = GRAVATAR_ABBREV_OPTIONS[key] if GRAVATAR_ABBREV_OPTIONS.include?(key) # shorten key!
-          value = value.call(url_options, source.is_a?(String) ? self : source) if key.to_s == 'd' and value.respond_to?(:call)
-          params << "#{Gravatarify.escape(key)}=#{Gravatarify.escape(value)}" if value
+        params = url_options.inject([]) do |params, (key, value)|
+          key = key.to_s
+          if key != 'html'
+            key = GRAVATAR_ABBREV_OPTIONS[key] if GRAVATAR_ABBREV_OPTIONS.include?(key) # shorten key!
+            value = value.call(url_options, source) if key == 'd' and value.respond_to?(:call)
+            params << "#{Utils.escape(key)}=#{Utils.escape(value)}" if value
+          end
+          params
         end
         "?#{params.sort * '&'}" unless params.empty?
-      end
-      
-      # Tries first to call +email+, then +mail+ then +to_s+ on supplied
-      # object.
-      def self.get_smart_email_from(obj) #:nodoc:
-        (obj.respond_to?(:email) ? obj.email : (obj.respond_to?(:mail) ? obj.mail : obj)).to_s
-      end
-  end
+      end      
+    end
 end