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), [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**: - **Docs**: - **Gem**: Ready, Set, Go! --------------- **READY** Install gravatarify as a gem (requires gemcutter): [sudo] gem install gravatarify or as Rails plugin: ./script/plugin install git://github.com/lwe/gravatarify.git **SET** When using the Rails plugin, skip this step. Anyhow, just ensure that when installed as a gem it's bundled using `bundler` or defined in `config/environment.rb`, or just that it's on the `$LOAD_PATH` and then `require 'gravatarify'`'d somehow. **GO** Use it! When using Rails or Haml then just give it an email and it will return the gravatar url: # creates an 20x20 pixel tag in your Rails ERB views: <%= gravatar_tag @user.email, :size => 20 %> # or in HAML views # (Note: how it's possible to skip the email attribute, btw - that's a feature) %img{ gravatar_attrs(@user, :size => 20) }/ **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 custom helpers, plain ruby code or whatever, see "Back to the roots". Using the view helpers ---------------------- Probably one of the easiest ways to add support for gravatar images is with the included view helpers. When using Rails or HAML these should be automatically available, if not do something like: # e.g. for Sinatra helpers Gravatarify::Helper # or include for Haml Haml::Helpers.send(:include, Gravatarify::Helper) # NOTE: basically just include the Gravatarify::Helper module This then provides three helper methods: `gravatar_url`, `gravatar_attrs` and `gravatar_tag`. To just build a simple `` tag, pass in an object (if it responds to `email` or `mail`) or a string containg the e-mail address: <%= gravatar_tag @user %> # => assumes @user has email or mail field! This builds a neat ``-tag. To display an "X" rated avatar which is 25x25 pixel in size and the `` tag should have a class attribute, do: <%= gravatar_tag @user, :size => 25, :rating => :x, :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: 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 %> # -> 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 :) ### PORO - plain old ruby objects (yeah, POJO sounds smoother :D) Not using Rails, ActiveRecord or DataMapper? It's as easy as including `Gravatarify::ObjectSupport` to your class: 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? 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. 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. Need more control? ==================
Option Type Description Default
:default String, Proc Fully qualified URL to an image, which is used if gravatar.com has no image for the supplied email. Procs can be used to return e.g. an image based on the request size (see Advanced stuff). Furthermore gravatar.com provides several "special values" which generate icons, these are "wavatar", "monsterid" and "identicon", finally if set to 404 gravatar.com returns the HTTP 404 Not Found error. If nothing is specified gravatar.com returns it's gravatar icon. -
:rating String, Symbol Each avatar at gravatar.com has a rating associated (which is based on MPAAs rating system), valid values are:
g - general audiences, pg - parental guidance suggested, r - restricted and x - x-rated :). Gravatar.com returns g-rated avatars, unless anything else is specified. 		-
:size Integer Avatars are square, so :size defines the length of the sides in pixel, if nothing is specified gravatar.com returns 80x80px images. -
:secure Boolean, Proc If set to true gravatars secure host (https://secure.gravatar.com/) is used to serve the avatars from. Can be a Proc to inflect wheter or not to use the secure host based on request parameters. false
:filetype String, Symbol Change image type, gravatar.com supports :gif, :png and :jpg. If set to false then a URL without an extension will be built (and gravatar.com then returns a JPG image). :jpg
To options globally, access the `Gravatarify.options` hash and set any options which should apply to all gravatar urls there. Of course all settings can be overridden locally: # disable suffix and set default size to 16x16px Gravatarify.options[:filetype] = false Gravatarify.options[:size] = 16 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 ### 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: # in an initializer Gravatarify.options[:default] = Proc.new do |options, object| "http://example.com/avatar-#{options[:size] || 80}.jpg" end # now each time a gravatar url is generated, the Proc is evaluated: @user.gravatar_url # => "http://0.gravatar.com/...jpg?d=http%3A%2F%2Fexample.com%2Fgravatar-80.jpg" @user.gravatar_url(:size => 16) # => "http://0.gravatar.com/...jpg?d=http%3A%2F%2Fexample.com%2Fgravatar-16.jpg&s=16" Into the block is passed the options hash and as second parameter the object itself, so it's possible to do stuff like # doing stuff like showing default avatar based on gender... @user = User.new(:gender => :female, :email => 'bella@gmail.com') # => @user.female? = true @user.gravatar_url :default => Proc.new { |opts, obj| "http://example.com/avatar#{obj.respond_to?(:female) && obj.female? ? '_female' : ''}.jpg" } # => http://0.gravatar.com/...jpg?d=http%3A%2F%2Fexample.com%2Fgravatar_female.jpg 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/helper.rb # Defines those view helpers, mainly gravatar_tag ### Contribute 1. Fork the project and hack away 2. Ensure that the changes are well tested 3. Send me a pull request Licence ======= Copyright (c) 2009 Lukas Westermann Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 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.