faces 0.5.0

data/LICENSE

@@ -0,0 +1,14 @@
+Author: Nick Pellant <contact@nickpellant.com>
+Copyright: (C) 2010 Silentale.com SAS
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.markdown

@@ -0,0 +1,201 @@
+# Faces
+
+<small>Avatars made easy, by [Nick Pellant](http://nickpellant.com).</small>
+
+Faces is an avatar provider/management library. It allows developers to fetch avatars from multiple sources in a consistent manner. Faces was built to rectify a problem originally faced when improving the avatars system at [Silentale](http://silentale.com). Faces has default support for the following avatar sources:
+
+* [Facebook](http://facebook.com)
+* [Twitter](http://twitter.com) via [Tweet Images](http://tweetimag.es/)
+* [Highrise](http://highrisehq.com)
+* [Flickr](http:/flickr.com)
+* [Gravatar](http://gravatar.com)
+
+Faces is now available in both [Ruby](http://github.com/nickpellant/faces) and [PHP](http://github.com/nickpellant/faces-php) with a Python version in its way soon. As Faces is available in multiple languages provider support may vary from one project to another however it will be attempted to keep default provider support synchronized.
+
+## Public methods
+
+    avatar_url(identifier, provider, configuration = {})
+
+The **avatar\_url** method is an accessor point to pull an avatar from a provider. The method will only return a value if the provider exists and the **url** method exists for the provider, otherwise it will return the default avatar url (**avatar\_default\_url**).
+
+    avatar_html(identifier, provider, configuration = {})
+
+The **avatar\_html** method is an accessor point to pull an avatar from a provider and encase it in a img html tag. It will also add any configurations you've set regarding markup to the tag. The method will only return a value if the provider exists and the **html** method exists for the provider, otherwise it will return the default avatar html (**avatar\_default\_html**).
+
+    generate_html(url, configuration = {})
+  
+The **generate\_html** method allows you to pass an avatar URL for which a provider does not exist so as to use the Faces configuration architecture, allowing you to keep a level of consistency. (We do suggest however you build your own providers directly, as it's a hell of a lot cooler)
+
+    avatar_default_url(configuration = {})
+
+The **avatar\_default\_url** method returns the default avatar url.
+ 
+    avatar_default_html(configuration = {})
+
+The **avatar\_default\_html** method returns the default avatar html img tag.
+
+    avatar_exists?(identifier, provider, configuration = {})
+
+The **avatar\_exists?** method returns true/false as to whether an avatar exists for the given details.
+
+    provider_exists?(provider)
+
+The **provider\_exists?** method returns true/false as to whether a provider with the given string exists and is available.
+
+    provider_method_exists?(method, provider)
+
+The **provider\_method\_exists?** method returns true/false as to whether said method exists for said provider (also returns false if provider does not exist).
+
+### Note
+
+Make sure to check out the relevant documentation for each provider. Providers are standardized as much as possible but there are sometimes special requirements (Flickr requires an API key in it's configuration, for example).
+
+## Installation
+
+Install the gem (**Recommended**)
+
+    sudo gem install faces
+
+### Ruby on Rails
+
+Add this to your `environment.rb` (gem setup only)
+
+    config.gem 'faces', :version => '>= x.x'
+
+If you don't like gems for some reason, install it as a plugin
+
+    script/plugin install git://github.com/nickpellant/faces.git
+
+We also suggest you setup your configuration via an initializer (find an example file on how to do this in the 'examples/rails' folder)
+
+## Configuration options
+
+Faces has a hierarchy system for configuration. We start of with a universal configuration and gradually override as we go down the chain like so:
+
+**Custom Configuration (method set)** > **Provider Configuration** > **Universal Configuration** 
+
+Faces by default sets a whole bunch of values for provider & universal configurations, but we highly recommend you change them to suit your needs. I've listed the universal ones below and provider specific configuration options with their provider documentations.
+
+  * ::Faces::Configuration::UNIVERSAL
+    * Fallback avatar url (string)
+      * :default      => 'http://www.gravatar.com/avatar/?d=identicon'
+    * Max dimension constraints for width/height of avatar (integer)
+      * :size         => 50
+    * Universally assigned classes to all avatars (string)
+      * :html\_classes => 'faces avatars'
+    * Use secure connection where possible (boolean)
+      * :html\_classes => false
+    * Restrict dimensions, to activate set 'square-only' (string)
+      * :dimension\_restriction => ''
+
+## Facebook Provider
+
+The Facebook provider supports all the functionality available from it's API. It supports only **html** calls however (which are, in fact FBML, but we keep the name for sake of consistency).
+
+There are a few additional configuration options available for Facebook that you may want to look at.
+  
+  * ::Faces::Configuration::FACEBOOK
+    * Layer facebook logo ontop of avatar (boolean)
+      * :facebook\_logo => false
+    * Auto-link avatar back to Facebook (boolean)
+      * :facebook\_auto\_linked => false
+    * Provider specific html classes (string)
+      * :html\_provider\_classes => 'facebook'
+
+To get this provider working you will also need a Facebook application/API key (this is because the provider uses FBML to generate it's avatars).
+
+Once you have the application & API key add the following before the close of your body tag
+
+    <script src="http://static.ak.connect.facebook.com/js/api_lib/v0.4/FeatureLoader.js.php/en_GB" type="text/javascript"></script>
+    <script type="text/javascript">FB.init("INSERT PUBLIC API KEY HERE");</script>
+
+Make sure you have setup Facebook Connect for your Facebook application with the site url and base url in the application settings. If they are setup incorrectly this will not work!
+
+You will also need to add the following to your html tag to complete the setup
+
+    xmlns:fb="http://www.facebook.com/2008/fbml"
+    
+Facebook avatar sizes are calculated dynamically from your configuration. Available sizes are 50x50, <=100 and >100. Faces calculates which of the available sizes provided by facebook best matches the dimensions you provided. If you select to receive only square images but choose a size over 50x50 there will be pixilation.
+
+### Further reading
+
+* [Full Facebook provider documentation](http://nickpellant.com/open-source/faces/ruby/provider/facebook)
+* [Fb:profile-pic Documentation](http://wiki.developers.facebook.com/index.php/Fb:profile-pic)
+
+## Twitter Provider
+
+The Twitter provider uses the [Tweet Images](http://tweetimag.es/) mapper to provide urls (an awesome project from [Joe Stump](http://stu.mp)). It supports both **html** and **url** calls.
+
+There are a few additional configuration options available for Gravatar that you may want to look at.
+  
+  * ::Faces::Configuration::TWITTER
+    * Provider specific html classes (string)
+      * :html\_provider\_classes => 'gravatar'
+      
+Twitter avatar sizes are calculated dynamically from your configuration. Available sizes are 24x24, 48x48, 73x73 and the original size. Faces calculates which of the available sizes provided by twitter best matches the dimensions you provided. If you select to receive only square images but choose a size over 73x73 you will be given the largest possible square avatar.
+      
+### Further reading
+
+* [Full Gravatar provider documentation](http://nickpellant.com/open-source/faces/ruby/provider/gravatar)
+* [Tweet Images](http://tweetimag.es/)
+
+## Highrise Provider
+
+Supports both **html** and **url** calls.
+
+Highrise expects a **contact\_id** as it's identifier parameter. It also expects the configuration option :highrise\_account\_name to be set appropriately.
+
+<small>_for those who do not know the account name for highrise is the subdomain, i.e. myaccountname.highrisehq.com_</small>
+
+There are a few additional configuration options available for Highrise that you may want to look at.
+  
+  * ::Faces::Configuration::FLICKR
+    * Provider specific html classes (string)
+      * :html\_provider\_classes => 'flickr'
+
+Highrise avatar sizes are calculated dynamically from your configuration. Available sizes are 32x32 and 53x53. Faces calculates which of the available sizes provided by Highrise best matches the dimensions you provided.
+
+### Further reading
+
+* [Full Highrise provider documentation](http://nickpellant.com/open-source/faces/ruby/provider/highrise)
+* [Highrise API](http://developer.37signals.com/highrise/)
+
+## Flickr Provider
+
+The Flickr provider supports all the functionality of the API. It supports both **html** and **url** calls.
+
+To have the Flickr provider working you will _need_ to set an API key.
+
+  * ::Faces::Configuration::FLICKR
+    * API key of application on Flickr (string)
+      * :flickr\_api\_key => 'dzgasgji3ewaojodsgojw'
+
+There are a few additional configuration options available for Flickr that you may want to look at.
+  
+  * ::Faces::Configuration::FLICKR
+    * Provider specific html classes (string)
+      * :html\_provider\_classes => 'flickr'
+
+Flickr only provides avatars at 48x48 - if you're using a higher size than this there will be pixilation.
+
+### Further reading
+
+* [Full Flickr provider documentation](http://nickpellant.com/open-source/faces/ruby/provider/flickr)
+* [Flickr Buddyicons](http://www.flickr.com/services/api/misc.buddyicons.html)
+
+## Gravatar Provider
+
+The Gravatar provider supports all the functionality available from it's API. It supports both **html** and **url** calls.
+
+There are a few additional configuration options available for Gravatar that you may want to look at.
+  
+  * ::Faces::Configuration::GRAVATAR
+    * Gravatar rating, minimum requirement (string)
+      * :gravatar\_rating => 'G'
+    * Provider specific html classes (string)
+      * :html\_provider\_classes => 'gravatar'
+      
+### Further reading
+
+* [Full Gravatar provider documentation](http://nickpellant.com/open-source/faces/ruby/provider/gravatar)
+* [Gravatar URL construction](http://en.gravatar.com/site/implement/url)

data/Rakefile

@@ -0,0 +1,17 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "faces"
+    gemspec.summary = "Faces manages external and internal avatar sources in one unified format."
+    gemspec.description = "Avatars made super simple."
+    gemspec.email = "nick@silentale.com"
+    gemspec.homepage = "http://github.com/nickpellant/faces"
+    gemspec.authors = ["Nick Pellant"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install jeweler -s http://gemcutter.org"
+end

data/VERSION

@@ -0,0 +1 @@
+0.5.0

data/faces.gemspec

@@ -0,0 +1,65 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{faces}
+  s.version = "0.5.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Nick Pellant"]
+  s.date = %q{2010-03-15}
+  s.description = %q{Avatars made super simple.}
+  s.email = %q{nick@silentale.com}
+  s.extra_rdoc_files = [
+    "LICENSE",
+     "README.markdown"
+  ]
+  s.files = [
+    "LICENSE",
+     "README.markdown",
+     "Rakefile",
+     "VERSION",
+     "faces.gemspec",
+     "init.rb",
+     "lib/faces.rb",
+     "lib/providers/facebook.rb",
+     "lib/providers/flickr.rb",
+     "lib/providers/gravatar.rb",
+     "lib/providers/highrise.rb",
+     "lib/providers/twitter.rb",
+     "test/providers/test_facebook.rb",
+     "test/providers/test_flickr.rb",
+     "test/providers/test_gravatar.rb",
+     "test/providers/test_highrise.rb",
+     "test/providers/test_twitter.rb",
+     "test/test_faces.rb",
+     "test/test_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/nickpellant/faces}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.6}
+  s.summary = %q{Faces manages external and internal avatar sources in one unified format.}
+  s.test_files = [
+    "test/providers/test_facebook.rb",
+     "test/providers/test_flickr.rb",
+     "test/providers/test_gravatar.rb",
+     "test/providers/test_highrise.rb",
+     "test/providers/test_twitter.rb",
+     "test/test_faces.rb",
+     "test/test_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end
+

data/init.rb

@@ -0,0 +1 @@
+require 'faces'

data/lib/faces.rb

@@ -0,0 +1,104 @@
+Dir.glob(File.join(File.dirname(__FILE__), '/providers/*.rb')).each { |f| require f }
+
+require 'net/http'
+require 'net/https'
+require 'rexml/document'
+require 'digest/md5'
+
+module Faces
+  module Configuration
+    # Universal configuration for avatars
+    UNIVERSAL = {
+      # Avatar to default to
+      :default      => 'http://www.gravatar.com/avatar/?d=identicon',
+      # Max height or width pixel size for returned avatar
+      :size         => 50,
+      # CSS classes to be assigned to all <img /> tags
+      :html_classes => 'faces avatar',
+      # Use a secure connection when one is available
+      :use_secure   => false,
+      # If we only ever want to return square images, set to square-only
+      :dimension_restriction  => ''
+    }
+  end
+  module Public
+    # Returns the avatar in an <img /> HTML tag based on identifier, provider and configuration
+    # Uses local provider classes to generate the result
+    # Does not check for existance of Avatar, this is the responsibility of the developer
+    def avatar_html(identifier, provider, configuration = {})
+      if provider_method_exists?('html', provider)
+        obj  = "::Faces::Providers::#{provider.to_s.classify}".constantize.new
+        obj.html(identifier, configuration)
+      else
+        avatar_default_html(configuration)
+      end
+    end
+    # Returns avatar url based on identifier, provider and configuration
+    # Uses local provider classes to generate the result
+    # Does not check for existance of Avatar, this is the responsibility of the developer
+    def avatar_url(identifier, provider, configuration = {})
+      if provider_method_exists?('url', provider)
+        obj = "::Faces::Providers::#{provider.to_s.classify}".constantize.new
+        obj.url(identifier, configuration) 
+      else
+        avatar_default_url(configuration)
+      end
+    end
+    # Returns true if avatar exists, false if not 
+    def avatar_exists?(identifier, provider, configuration = {})
+      obj = "::Faces::Providers::#{provider.to_s.classify}".constantize.new
+      obj.exists?(identifier, configuration)
+    end
+    # Returns the default avatar in an <img /> HTML tag
+    def avatar_default_html(configuration = {})
+      url = configuration[:default].present? ? configuration[:default] : ::Faces::Configuration::UNIVERSAL[:default]
+      generate_html(url, configuration)
+    end
+    # Returns the default avatar as a url   
+    def avatar_default_url(configuration = {})
+      configuration[:default].present? ? configuration[:default] : ::Faces::Configuration::UNIVERSAL[:default]
+    end
+    # Returns true if provider exists, false if not 
+    def provider_exists?(provider)
+      true if ::Faces::Providers.const_get("#{provider.to_s.classify}")
+    rescue NameError
+      false
+    end
+    # Returns true if provider method exists, false if not 
+    def provider_method_exists?(method, provider)
+      if ::Faces::Providers.const_get("#{provider.to_s.classify}")
+        obj = "::Faces::Providers::#{provider.to_s.classify}".constantize.new
+        obj.respond_to?(method) 
+      end
+    rescue NameError
+      false
+    end
+    # Generates a HTML <img /> tag for the given url
+    def generate_html(url, configuration = {})
+      m_configuration = Faces::Common.merge_configurations([Faces::Configuration::UNIVERSAL, configuration])
+      combined_classes = m_configuration[:html_provider_classes].present? ? m_configuration[:html_classes] + ' ' + m_configuration[:html_provider_classes] : m_configuration[:html_classes]
+      
+      html  = '<img src="' + url + '" class="' + combined_classes + '"'
+      html += 'id="' + m_configuration[:id] + '"' if m_configuration[:id].present?
+      html += ' />'
+    end
+    
+    module_function :avatar_exists?, :provider_exists?, :provider_method_exists?, :avatar_url, :avatar_html, :generate_html, :avatar_default_html, :avatar_default_url
+  end  
+  module Common
+    # Merges together all configurations given from first to last in order of priority
+    def merge_configurations(configurations)
+      configuration = Faces::Configuration::UNIVERSAL
+      configurations.each do |config|
+        configuration = configuration.merge(config)
+      end
+      configuration
+    end
+    # Builds a url query parameter string
+    def build_param(key, value, first = false)
+      value.present? ? (first == true ? "?#{key}=#{value}" : "&#{key}=#{value}") : ''
+    end
+    
+    module_function :merge_configurations, :build_param
+  end
+end

data/lib/providers/facebook.rb

@@ -0,0 +1,52 @@
+module Faces
+  module Configuration
+    # Configuration for facebook avatars
+    FACEBOOK = {
+      # Show facebook logo
+      :facebook_logo      => false,
+      # Additional HTML classes specific to Facebook provider (merged with :html_classes)
+      :html_provider_classes => 'facebook',
+      # Link back to Facebook automatically?
+      :facebook_auto_linked => false    
+    }
+  end
+  module Providers
+    # Facebook class handles all Facebook based avatar methods, check the information page for more details:
+    # http://nickpellant.com/open-source/faces/ruby/providers/facebook
+    #
+    # Default required methods for providers are +url+ and/or +html+, +exists?+
+    # All other methods are at the discretion of the developer
+    # Check the provider creation guide for more details:
+    # http://nickpellant.com/open-source/faces/ruby/developing-providers
+    class Facebook
+      # Constructs FBML tag for avatar
+      def html(user_id, configuration = {})
+        m_configuration = Faces::Common.merge_configurations([Faces::Configuration::FACEBOOK, configuration])
+        fbml = '<fb:profile-pic uid="' + user_id + '" facebook-logo="' + m_configuration[:facebook_logo].to_s + '" linked="' + m_configuration[:facebook_auto_linked].to_s +
+          '" size="' + size(m_configuration) + '" class="' + m_configuration[:html_classes] + ' ' + m_configuration[:html_provider_classes] + '"'
+        fbml += m_configuration[:html_id] if m_configuration[:html_id].present?
+        fbml += '"></fb:profile-pic>'
+      end
+      # Botch job as it's not possible to check for FBML avatar presence :(
+      def exists?(identifier, configuration = {}); true; end
+    private
+      # Calculates the size of image to pull from Facebook
+      # This is decided based on the configuration settings of Faces
+      def size(m_configuration = {})
+        # Square avatar
+        if m_configuration[:size] <= 50
+          'square'
+        # Small avatar
+        elsif m_configuration[:size] <= 100 && m_configuration[:dimension_restriction] != 'square-only'
+          'small'
+        # Normal size
+        elsif m_configuration[:size] > 100 && m_configuration[:dimension_restriction] != 'square-only'
+          'normal'
+        # Default back to square
+        else
+          'square'
+        end
+      end
+    end
+  end
+end

data/lib/providers/flickr.rb

@@ -0,0 +1,54 @@
+module Faces
+  module Configuration
+    # Configuration for Flickr avatars
+    FLICKR = {
+      # Required to use the Flickr provider
+      :flickr_api_key => '',
+      # Additional HTML classes specific to Twitter provider (merged with :html_classes)
+      :html_provider_classes => 'twitter'
+    }
+  end
+  module Providers
+    # Flickr class handles all Flickr based avatar methods, check the information page for more details:
+    # http://nickpellant.com/open-source/faces/ruby/providers/flickr
+    #
+    # Default required methods for providers are +url+ and/or +html+, +exists?+
+    # All other methods are at the discretion of the developer
+    # Check the provider creation guide for more details:
+    # http://nickpellant.com/open-source/faces/ruby/developing-providers
+    class Flickr
+      # Constructs Flickr url from user_id/configuration
+      def url(user_id, configuration = {})
+        m_configuration = Faces::Common.merge_configurations([Faces::Configuration::FLICKR, configuration])
+        hostname(flickr_avatar_details(user_id, m_configuration)) + user_id + '.jpg'
+      end
+      # Constructs HTML <img /> tag for Flickr
+      def html(user_id, configuration = {})
+        m_configuration = Faces::Common.merge_configurations([Faces::Configuration::FLICKR, configuration])
+        Faces::Public.generate_html(url(user_id, configuration), m_configuration)
+      end
+      # Checks Avatar exists
+      def exists?(user_id, configuration = {})
+        url = URI.parse(url(user_id, configuration))
+        http = Net::HTTP.new(url.host, url.port)
+        http.use_ssl = (url.scheme == 'https')
+        request = Net::HTTP::Get.new(url.path)
+        response = http.request(request)
+        response.code == '200' ? true : false
+      end
+    private
+      # Fetches the buddyicon farm details based on the user_id given
+      # An avatar can not be pulled from Flickr without this method
+      def flickr_avatar_details(user_id, m_configuration = {})
+        url = URI.parse('http://api.flickr.com/services/rest/?method=flickr.people.getInfo&api_key=' + m_configuration[:flickr_api_key] + '&user_id=' + user_id)
+        xml = Net::HTTP.get_response(url).body
+        doc = REXML::Document.new(xml)
+        { :icon_server => doc.root.elements['person'].attributes['iconserver'], :icon_farm => doc.root.elements['person'].attributes['iconfarm'] }
+      end
+      # Constructs appropriate hostname based on return of flickr_avatar_details
+      def hostname(flickr_details)
+        'http://farm' + flickr_details[:icon_farm] + '.static.flickr.com/' + flickr_details[:icon_server] + '/buddyicons/'
+      end
+    end
+  end
+end

data/lib/providers/gravatar.rb

@@ -0,0 +1,63 @@
+module Faces
+  module Configuration
+    # Configuration for Gravatar avatars
+    GRAVATAR = {
+      # Apply a Gravatar rating requirement ('G', 'PG', 'R', 'X')
+      # We default to 'G' to remain consistant with Gravatar
+      :gravatar_rating       => 'G',
+      # Additional HTML classes specific to Gravatar provider (merged with :html_classes)
+      :html_provider_classes => 'gravatar'
+    }
+  end
+  module Providers
+    # Gravatar class handles all Gravatar based avatar methods, check the information page for more details:
+    # http://nickpellant.com/open-source/faces/ruby/providers/gravatar
+    #
+    # Default required methods for providers are +url+ and/or +html+, +exists?+
+    # All other methods are at the discretion of the developer
+    # Check the provider creation guide for more details:
+    # http://nickpellant.com/open-source/faces/ruby/developing-providers
+    class Gravatar
+      # Constructs Gravatar url from email/configuration
+      # It can be passed either an MD5 hash as email or a string email
+      def url(email, configuration = {})
+        m_configuration = Faces::Common.merge_configurations([Faces::Configuration::GRAVATAR, configuration])
+        email = md5_email(email) if email.include? "@"
+        url = hostname(m_configuration) + email + build_params_string(m_configuration)
+      end
+      # Constructs HTML <img /> tag for Gravatar
+      def html(email, configuration = {})
+        m_configuration = Faces::Common.merge_configurations([Faces::Configuration::GRAVATAR, configuration])
+        Faces::Public.generate_html(url(email, configuration), m_configuration)
+      end
+      # Checks Avatar exists
+      def exists?(email, configuration = {})
+        m_configuration = Faces::Common.merge_configurations([Faces::Configuration::GRAVATAR, configuration, {:default => '404'}])
+        url = URI.parse(url(email, m_configuration))
+        http = Net::HTTP.new(url.host, url.port)
+        http.use_ssl = (url.scheme == 'https')
+        request = Net::HTTP::Get.new(url.path + '?' + url.query)
+        response = http.request(request)
+        response.code == '200' ? true : false
+      end
+      # Formats email and converts into MD5 hash for use with Gravatar url
+      def md5_email(email)
+        Digest::MD5.hexdigest(email.strip.downcase)
+      end
+    private
+      # Constructs appropriate hostname based on secure preferences
+      def hostname(m_configuration = {})
+        'http' + (m_configuration[:use_secure] ? 's://secure.' : '://') + 'gravatar.com/avatar/'
+      end
+      # Build url parameters string
+      def build_params_string(m_configuration = {})
+        # Set the size of the avatar we want to fetch
+        Faces::Common.build_param('s', m_configuration[:size], true) + 
+          # Set the rating of the avatar we want to fetch
+          Faces::Common.build_param('r', m_configuration[:gravatar_rating])  +
+          # Default image to defer too (or possibily a generator in the case of Gravatar)
+          Faces::Common.build_param('d', m_configuration[:default])
+      end
+    end
+  end
+end

data/lib/providers/highrise.rb

@@ -0,0 +1,49 @@
+module Faces
+  module Configuration
+    # Configuration for highrise avatars
+    HIGHRISE = {
+      # Base account name (http://accountname.highrisehq.com)
+      :highrise_account_name => '',
+      # Additional HTML classes specific to Highrise provider (merged with :html_classes)
+      :html_provider_classes => 'highrise'
+    }
+  end
+  module Providers
+    # Highrise class handles all Highrise based avatar methods
+    # Default required methods for providers are +url+ and/or +html+, +exists?+
+    # All other methods are at the discretion of the developer
+    # Check the provider creation guide for more details:
+    # http://nickpellant.com/open-source/faces/ruby/developing-providers
+    class Highrise
+      # Constructs Highrise url from contact_id/configuration
+      def url(contact_id, configuration = {})
+        m_configuration =  Faces::Common.merge_configurations([Faces::Configuration::HIGHRISE, configuration])
+        hostname(m_configuration) + contact_id[0..3] + '/' + contact_id[4..-1] + '-' + size(m_configuration) + '.png'
+      end
+      # Constructs HTML <img /> tag for Highrise avatar
+      def html(contact_id, configuration = {})
+        m_configuration = Faces::Common.merge_configurations([Faces::Configuration::HIGHRISE, configuration])
+        Faces::Public.generate_html(url(contact_id, configuration), m_configuration)
+      end
+      # Checks Avatar exists
+      def exists?(contact_id, configuration = {})
+        url = URI.parse(url(contact_id, configuration))
+        http = Net::HTTP.new(url.host, url.port)
+        http.use_ssl = (url.scheme == 'https')
+        request = Net::HTTP::Get.new(url.path)
+        response = http.request(request)
+        response.code == '200' ? true : false
+      end
+    private
+      # Constructs appropriate hostname based on secure preferences and account name
+      def hostname(m_configuration)
+        'http' + (m_configuration[:use_secure] ? 's' : '') + "://" + m_configuration[:highrise_account_name] + ".highrisehq.com/dl/avatars/person/"
+      end
+      # Calculates the size of image to pull from Highrise
+      # This is decided based on the configuration settings of Faces
+      def size(m_configuration)
+        m_configuration[:size] <= 32 ? 'small' : 'large'
+      end
+    end
+  end
+end

data/lib/providers/twitter.rb

@@ -0,0 +1,60 @@
+module Faces
+  module Configuration
+    # Configuration for Twitter avatars
+    TWITTER = {
+      # Additional HTML classes specific to Twitter provider (merged with :html_classes)
+      :html_provider_classes => 'twitter'
+    }
+  end
+  module Providers
+    # Twitter class handles all Twitter based avatar methods, check the information page for more details:
+    # http://nickpellant.com/open-source/faces/ruby/providers/twitter
+    #
+    # Default required methods for providers are +url+ and/or +html+, +exists?+
+    # All other methods are at the discretion of the developer
+    # Check the provider creation guide for more details:
+    # http://nickpellant.com/open-source/faces/ruby/developing-providers
+    class Twitter
+      # Constructs Twitter url from username/configuration
+      def url(username, configuration = {})
+        m_configuration = Faces::Common.merge_configurations([Faces::Configuration::TWITTER, configuration])
+        'http://img.tweetimag.es/i/' + username + '_' + size(m_configuration)
+      end
+      # Constructs HTML <img /> tag for Twitter
+      def html(username, configuration = {})
+        m_configuration = Faces::Common.merge_configurations([Faces::Configuration::TWITTER, configuration])
+        Faces::Public.generate_html(url(username, configuration), m_configuration)
+      end
+      # Checks Avatar exists
+      def exists?(username, configuration = {})
+        url = URI.parse(url(username, configuration))
+        http = Net::HTTP.new(url.host, url.port)
+        http.use_ssl = (url.scheme == 'https')
+        request = Net::HTTP::Get.new(url.path)
+        response = http.request(request)
+        response.code == '200' ? true : false
+      end
+    private
+      # Calculates the size of image to pull from Twitter
+      # This is decided based on the configuration settings of Faces
+      def size(m_configuration = {})
+        # Mini sized
+        if m_configuration[:size] <= 24
+          'm'
+        # Normal sized
+        elsif m_configuration[:size] <= 48
+          'n'
+        # Large sized
+        elsif m_configuration[:size] <= 73
+          'b'
+        # Originally uploaded image
+        elsif m_configuration[:size] > 73 && m_configuration[:dimension_restriction] != 'square-only'
+          'o'
+        # Default back to large size for anything above 73px but still square requirement
+        else
+          'b'
+        end
+      end
+    end
+  end
+end

data/test/providers/test_facebook.rb

@@ -0,0 +1,36 @@
+require File.dirname(__FILE__) + '/../test_helper'
+
+class FacebookTest < Test::Unit::TestCase
+
+  ####################
+  #--- html       ---#
+  ####################
+  def test_html_should_return_facebook_html
+    obj = ::Faces::Providers::Facebook.new
+    html = obj.html('711246611')
+    assert_match '<fb:profile-pic uid="', html
+  end
+  
+  ####################
+  #--- size       ---#
+  ####################
+  def test_size_should_return_square
+    obj = ::Faces::Providers::Facebook.new
+    assert_equal 'square', obj.__send__(:size, {:size => 50})
+  end
+  
+  def test_size_should_return_small
+    obj = ::Faces::Providers::Facebook.new
+    assert_equal 'small', obj.__send__(:size, {:size => 100})
+  end
+  
+  def test_size_should_return_normal
+    obj = ::Faces::Providers::Facebook.new
+    assert_equal 'normal', obj.__send__(:size, {:size => 150})
+  end
+
+  def test_size_should_return_square_when_set_to_square_only
+    obj = ::Faces::Providers::Facebook.new
+    assert_equal 'square', obj.__send__(:size, {:size => 150, :dimension_restriction => 'square-only'})
+  end
+end

data/test/providers/test_flickr.rb

@@ -0,0 +1,33 @@
+require File.dirname(__FILE__) + '/../test_helper'
+
+class FlickrTest < Test::Unit::TestCase
+
+  ####################
+  #--- url        ---#
+  ####################
+  def test_url_should_return_non_secure_flickr_url
+    obj = ::Faces::Providers::Flickr.new
+    url = obj.url('12037949754@N01', {:flickr_api_key => '5ad55b17c6964b3c83651522576af9ca'})
+    assert_match 'static.flickr.com', url
+    assert_match 'http://farm', url
+  end
+  
+  ####################
+  #--- html       ---#
+  ####################
+  def test_html_should_return_non_secure_flickr_html
+    obj = ::Faces::Providers::Flickr.new
+    html = obj.html('12037949754@N01', {:flickr_api_key => '5ad55b17c6964b3c83651522576af9ca'})
+    assert_match 'static.flickr.com', html
+    assert_match '<img src="http://farm', html
+  end
+  
+  ####################
+  #--- exists?    ---#
+  ####################
+  def test_exists_should_return_true_if_avatar_exists
+    obj = ::Faces::Providers::Flickr.new
+    result = obj.exists?('12037949754@N01', {:flickr_api_key => '5ad55b17c6964b3c83651522576af9ca'})
+    assert_equal true, result, 'Avatar does exist, should have returned true'
+  end
+end

data/test/providers/test_gravatar.rb

@@ -0,0 +1,88 @@
+require File.dirname(__FILE__) + '/../test_helper'
+
+class GravatarTest < Test::Unit::TestCase
+ 
+  ####################
+  #--- url        ---#
+  ####################
+  def test_url_should_return_non_secure_gravatar_url
+    obj = ::Faces::Providers::Gravatar.new
+    url = obj.url('da9658571a8ca10cf8b0f91625a8c3d5')
+    assert_match 'http://gravatar.com/avatar', url
+  end
+  
+  def test_url_should_return_secure_gravatar_url
+    obj = ::Faces::Providers::Gravatar.new
+    url = obj.url('da9658571a8ca10cf8b0f91625a8c3d5', {:use_secure => true})
+    assert_match 'https://secure.gravatar.com/avatar', url
+  end
+  
+  ####################
+  #--- html       ---#
+  ####################
+  def test_html_should_return_non_secure_gravatar_image_html
+    obj = ::Faces::Providers::Gravatar.new
+    html = obj.html('da9658571a8ca10cf8b0f91625a8c3d5')
+    assert_match '<img src="http://gravatar.com/', html
+  end
+  
+  def test_html_should_return_secure_gravatar_image_html
+    obj = ::Faces::Providers::Gravatar.new
+    html = obj.html('da9658571a8ca10cf8b0f91625a8c3d5', {:use_secure => true})
+    assert_match '<img src="https://secure.gravatar.com/', html
+  end
+  
+  def test_html_should_work_with_string_emails
+    obj = ::Faces::Providers::Gravatar.new
+    html = obj.html('someone@something.com')
+    assert_match '<img src="http://gravatar.com/', html
+  end
+  
+  ####################
+  #--- exists?    ---#
+  ####################
+  def test_exists_should_return_false_if_avatar_doesnt_exist
+    obj = ::Faces::Providers::Gravatar.new
+    result = obj.exists?('someone@example.com')
+    assert_equal false, result, 'Avatar does not exist, should have returned false'
+  end
+  
+  def test_exists_should_return_true_if_avatar_exists
+    obj = ::Faces::Providers::Gravatar.new
+    result = obj.exists?('da9658571a8ca10cf8b0f91625a8c3d5')
+    assert_equal true, result, 'Avatar exists, should have returned true'
+  end
+  
+  def test_exists_should_return_false_if_avatar_doesnt_exist_on_secure
+    obj = ::Faces::Providers::Gravatar.new
+    result = obj.exists?('someone@example.com', {:use_secure => true})
+    assert_equal false, result, 'Avatar does not exist, should have returned false'
+  end
+  
+  def test_exists_should_return_true_if_avatar_does_exist_on_secure
+    obj = ::Faces::Providers::Gravatar.new
+    result = obj.exists?('da9658571a8ca10cf8b0f91625a8c3d5', {:use_secure => true})
+    assert_equal true, result, 'Avatar does exist, should have returned true'
+  end
+  ####################
+  #--- md5_email  ---#
+  ####################
+  def test_md5_email_should_return_correct_md5_hash
+    obj = ::Faces::Providers::Gravatar.new
+    result = obj.md5_email(' soMEonE@exaMPle.com  ')
+    assert_equal Digest::MD5.hexdigest('someone@example.com'), result, 'MD5 has does not match correctly'
+  end
+  
+  ####################
+  #--- hostname   ---#
+  ####################
+  def test_hostname_should_return_non_secure_hostname
+    obj = ::Faces::Providers::Gravatar.new
+    assert_match 'http://gravatar.com', obj.__send__(:hostname, {:use_secure => false})
+  end
+  
+  def test_hostname_should_return_secure_hostname
+    obj = ::Faces::Providers::Gravatar.new
+    assert_match 'https://secure.gravatar.com', obj.__send__(:hostname, {:use_secure => true})
+  end
+end

data/test/providers/test_highrise.rb

@@ -0,0 +1,73 @@
+require File.dirname(__FILE__) + '/../test_helper'
+
+class HighriseTest < Test::Unit::TestCase
+
+  ####################
+  #--- url        ---#
+  ####################
+  def test_url_should_return_non_secure_highrise_url
+    obj = ::Faces::Providers::Highrise.new
+    url = obj.url('31479012', {:highrise_account_name => 'silentaletest'})
+    assert_match 'http://silentaletest.highrisehq.com/dl/avatars/person/3147/9012', url
+  end
+  
+  def test_url_should_return_secure_highrise_url
+    obj = ::Faces::Providers::Highrise.new
+    url = obj.url('31479012', {:highrise_account_name => 'silentaletest', :use_secure => true})
+    assert_match 'https://silentaletest.highrisehq.com/dl/avatars/person/3147/9012', url
+  end
+  
+  ####################
+  #--- html       ---#
+  ####################
+  def test_html_should_return_non_secure_highrise_image
+    obj = ::Faces::Providers::Highrise.new
+    html = obj.html('31479012', {:highrise_account_name => 'silentaletest'})
+    assert_match '<img src="http://silentaletest.highrisehq.com/dl/avatars/person/3147/9012', html
+  end
+  
+  def test_html_should_return_secure_highrise_image
+    obj = ::Faces::Providers::Highrise.new
+    html = obj.html('31479012', {:highrise_account_name => 'silentaletest', :use_secure => true})
+    assert_match '<img src="https://silentaletest.highrisehq.com/dl/avatars/person/3147/9012', html
+  end
+
+  ####################
+  #--- exists?    ---#
+  ####################
+  def test_exists_should_return_true_if_avatar_exists_non_secure
+    obj = ::Faces::Providers::Highrise.new
+    result = obj.exists?('31479012', {:highrise_account_name => 'silentaletest', :use_secure => true})
+    assert_equal true, result, 'Avatar does exist, should have returned true'
+  end
+
+  def test_exists_should_return_true_if_avatar_exists_secure
+    obj = ::Faces::Providers::Highrise.new
+    result = obj.exists?('31479012', {:highrise_account_name => 'silentaletest', :use_secure => true})
+    assert_equal true, result, 'Avatar does exist, should have returned true'
+  end
+  
+  def test_exists_should_return_false_if_avatar_doesnt_exist_non_secure
+    obj = ::Faces::Providers::Highrise.new
+    result = obj.exists?('31706827', {:highrise_account_name => 'silentaletest', :use_secure => true})
+    assert_equal false, result, 'Avatar doesn\'t exist, should have returned false'
+  end
+
+  def test_exists_should_return_false_if_avatar_doesnt_exist_secure
+    obj = ::Faces::Providers::Highrise.new
+    result = obj.exists?('31706827', {:highrise_account_name => 'silentaletest', :use_secure => true})
+    assert_equal false, result, 'Avatar doesn\'t exist, should have returned false'
+  end
+  ####################
+  #--- size       ---#
+  ####################
+  def test_size_should_return_small
+    obj = ::Faces::Providers::Highrise.new
+    assert_equal 'small', obj.__send__(:size, {:size => 32})
+  end
+  
+  def test_size_should_return_large
+    obj = ::Faces::Providers::Highrise.new
+    assert_equal 'large', obj.__send__(:size, {:size => 54})
+  end
+end

data/test/providers/test_twitter.rb

@@ -0,0 +1,59 @@
+require File.dirname(__FILE__) + '/../test_helper'
+
+class TwitterTest < Test::Unit::TestCase
+
+  ####################
+  #--- url        ---#
+  ####################
+  def test_url_should_return_non_secure_tweetimages_url
+    obj = ::Faces::Providers::Twitter.new
+    url = obj.url('npellant')
+    assert_match 'http://img.tweetimag.es/i/', url
+  end
+  
+  ####################
+  #--- html       ---#
+  ####################
+  def test_html_should_return_twitter_image_html
+    obj = ::Faces::Providers::Twitter.new
+    html = obj.html('npellant')
+    assert_match '<img src="http://img.tweetimag.es/i/', html
+  end
+  
+  ####################
+  #--- exists?    ---#
+  ####################
+  def test_exists_should_return_true_if_avatar_exists
+    obj = ::Faces::Providers::Twitter.new
+    result = obj.exists?('npellant')
+    assert_equal true, result, 'Avatar does exist, should have returned true'
+  end
+  
+  ####################
+  #--- size       ---#
+  ####################
+  def test_size_should_return_mini
+    obj = ::Faces::Providers::Twitter.new
+    assert_equal 'm', obj.__send__(:size, {:size => 24})
+  end
+  
+  def test_size_should_return_normal
+    obj = ::Faces::Providers::Twitter.new
+    assert_equal 'n', obj.__send__(:size, {:size => 48})
+  end
+  
+  def test_size_should_return_big
+    obj = ::Faces::Providers::Twitter.new
+    assert_equal 'b', obj.__send__(:size, {:size => 73})
+  end
+
+  def test_size_should_return_original
+    obj = ::Faces::Providers::Twitter.new
+    assert_equal 'o', obj.__send__(:size, {:size => 100})
+  end
+  
+  def test_size_should_return_big_when_set_to_square_only
+    obj = ::Faces::Providers::Twitter.new
+    assert_equal 'b', obj.__send__(:size, {:size => 100, :dimension_restriction => 'square-only'})
+  end
+end

data/test/test_faces.rb

@@ -0,0 +1,60 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+class FacesTest < Test::Unit::TestCase
+  def setup
+  end
+  
+  ####################
+  #--- avatar_url ---#
+  ####################
+  def test_avatar_url_should_return_avatar_url_non_secure
+    url = Faces::Public.avatar_url('someone@something.com', 'gravatar')
+    assert_match 'http', url
+  end
+  
+  def test_avatar_url_should_return_avatar_url_secure
+    url = Faces::Public.avatar_url('someone@something.com', 'gravatar', {:use_secure => true})
+    assert_match 'https', url
+  end
+  
+  def test_avatar_url_should_return_default_when_provider_doesnt_exist
+    url = Faces::Public.avatar_url('someone@something.com', 'imnotreal')
+    assert_equal url, Faces::Public.avatar_default_url
+  end
+  
+  def test_avatar_url_should_return_default_when_provider_method_doesnt_exist
+    url = Faces::Public.avatar_url('xyz', 'facebook')
+    assert_equal url, Faces::Public.avatar_default_url
+  end
+  
+  #####################
+  #--- avatar_html ---#
+  #####################
+  def test_avatar_html_should_return_avatar_url_non_secure
+    url = Faces::Public.avatar_html('someone@something.com', 'gravatar')
+    assert_match 'http', url
+  end
+  
+  def test_avatar_html_should_return_avatar_url_secure
+    url = Faces::Public.avatar_html('someone@something.com', 'gravatar', {:use_secure => true})
+    assert_match 'https', url
+  end
+  
+  def test_avatar_html_should_return_default_when_provider_doesnt_exist
+    url = Faces::Public.avatar_html('someone@something.com', 'imnotreal')
+    assert_equal url, Faces::Public.avatar_default_html
+  end
+  
+  ########################
+  #--- avatar_exists? ---#
+  ########################
+  def test_avatar_exists_should_return_true_when_an_avatar_exists
+    exists = Faces::Public.avatar_exists?('da9658571a8ca10cf8b0f91625a8c3d5', 'gravatar')
+    assert_equal exists, true
+  end
+  
+  def test_avatar_exists_should_return_false_when_an_avatar_doesnt_exists
+    exists = Faces::Public.avatar_exists?('someone@something.com', 'gravatar')
+    assert_equal exists, false
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,8 @@
+require 'rubygems'
+require 'active_support'
+require 'test/unit'
+require 'faces'
+
+require 'net/http'
+require 'rexml/document'
+require 'digest/md5'

metadata

@@ -0,0 +1,87 @@
+--- !ruby/object:Gem::Specification 
+name: faces
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 5
+  - 0
+  version: 0.5.0
+platform: ruby
+authors: 
+- Nick Pellant
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-03-15 00:00:00 +01:00
+default_executable: 
+dependencies: []
+
+description: Avatars made super simple.
+email: nick@silentale.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.markdown
+files: 
+- LICENSE
+- README.markdown
+- Rakefile
+- VERSION
+- faces.gemspec
+- init.rb
+- lib/faces.rb
+- lib/providers/facebook.rb
+- lib/providers/flickr.rb
+- lib/providers/gravatar.rb
+- lib/providers/highrise.rb
+- lib/providers/twitter.rb
+- test/providers/test_facebook.rb
+- test/providers/test_flickr.rb
+- test/providers/test_gravatar.rb
+- test/providers/test_highrise.rb
+- test/providers/test_twitter.rb
+- test/test_faces.rb
+- test/test_helper.rb
+has_rdoc: true
+homepage: http://github.com/nickpellant/faces
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: Faces manages external and internal avatar sources in one unified format.
+test_files: 
+- test/providers/test_facebook.rb
+- test/providers/test_flickr.rb
+- test/providers/test_gravatar.rb
+- test/providers/test_highrise.rb
+- test/providers/test_twitter.rb
+- test/test_faces.rb
+- test/test_helper.rb