Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 101 lines (63 sloc) 5.045 kb
57ff84e Colin MacKenzie IV added travis status message
authored
1 = gravatar-ultimate {<img src="https://secure.travis-ci.org/sinisterchipmunk/gravatar.png" />}[http://travis-ci.org/sinisterchipmunk/gravatar]
56d4091 Colin MacKenzie IV Initial commit to gravatar.
authored
2
8570ea9 Colin MacKenzie IV Logger support, and some helpful documentation
authored
3 The Ultimate Gravatar Gem!
4
cc83fca Colin MacKenzie IV Removed logger stuff from readme, since that's been removed
authored
5 This gem is used to interface with the entire Gravatar API: it's not just for generating image URLs, but for connecting to and communicating with the XML-RPC API too! Additionally, it can be used to download the Gravatar image data itself, rather than just a URL to that data. This saves you the extra step of having to do so.
8570ea9 Colin MacKenzie IV Logger support, and some helpful documentation
authored
6
7 == Installation
8
62af33c Colin MacKenzie IV Corrected misspellings - #1
authored
9 gem install gravatar-ultimate
8570ea9 Colin MacKenzie IV Logger support, and some helpful documentation
authored
10
4b04683 Colin MacKenzie IV Fixed documentation whoops
authored
11 == Activate the gem...
12
8570ea9 Colin MacKenzie IV Logger support, and some helpful documentation
authored
13 As with any gem, you have to type a few lines to tell Ruby to actually *use* it. Here's how to do that...
14
5f1ebbd Colin MacKenzie IV A little footnote about Rails 3 and how I'd really love to work on that ...
authored
15 ==== ...in Ruby on Rails (v3.x)
16
77fbac3 Colin MacKenzie IV Updated documentation
authored
17 * Edit your Gemfile
18 * Add this line:
62af33c Colin MacKenzie IV Corrected misspellings - #1
authored
19 gem 'gravatar-ultimate'
5f1ebbd Colin MacKenzie IV A little footnote about Rails 3 and how I'd really love to work on that ...
authored
20
21 ==== ...in Ruby on Rails (v2.x)
8570ea9 Colin MacKenzie IV Logger support, and some helpful documentation
authored
22
23 * Edit your config/environment.rb file
24 * Add this line beneath "Rails::Initializer.run do |config|":
62af33c Colin MacKenzie IV Corrected misspellings - #1
authored
25 config.gem 'gravatar-ultimate'
8570ea9 Colin MacKenzie IV Logger support, and some helpful documentation
authored
26
27 ==== ...in vanilla Ruby
28
29 require 'rubygems'
62af33c Colin MacKenzie IV Corrected misspellings - #1
authored
30 gem 'gravatar-ultimate'
31 require 'gravatar-ultimate'
8570ea9 Colin MacKenzie IV Logger support, and some helpful documentation
authored
32
33 == Usage
34 Using the gem is actually pretty simple. Let's say you want the Gravatar image URL for "generic@example.com":
35 url = Gravatar.new("generic@example.com").image_url
36
37 Cool, huh? Let's take it a step further and grab the actual image *data* so that we can render it on the screen:
38 data = Gravatar.new("generic@example.com").image_data
39
40 Fine, but how about the rest of the API as advertised at http://en.gravatar.com/site/implement/xmlrpc? Well, for
41 that you need either the user's Gravatar password, or their API key:
42
43 api = Gravatar.new("generic@example.com", :password => "helloworld")
44 api = Gravatar.new("generic@example.com", :api_key => "AbCdEfG1234")
45
46 After you have that, things get a lot easier:
47
48 api.exists? #=> true or false, depending on whether this user has an account.
49 api.addresses #=> a list of email addresses and their corresponding images
50 api.save_data!(rating, image_data) #=> saves an image to this user's account and returns a handle to it
51 api.use_user_image!(handle, an_email_address) #=> uses the specified image handle for the specified email address(es)
52 api.exists?("another@example.com") #=> true or false, depending on whether the specified email exists.
53
ca8309b Colin MacKenzie IV Fixed a few minor discrepancies in certain return values. Also, making c...
authored
54
55 == Caching
56
cc83fca Colin MacKenzie IV Removed logger stuff from readme, since that's been removed
authored
57 As you can see this is quite powerful. But it gets better. Gravatar Ultimate even manages caching of API responses for you! That way, if an error occurs, (such as the Gravatar site being offline), your code won't break. It'll instead gracefully fall back to the cached copy! By default, if you are using Rails, it'll use the Rails cache. Otherwise, it'll use whatever cache you're using with Gravatar (by default an instance of ActiveSupport::Cache::FileStore).
ca8309b Colin MacKenzie IV Fixed a few minor discrepancies in certain return values. Also, making c...
authored
58
59 This has obvious benefits when used for the API calls that do not result in changing the user's profile, but what you
60 might not have thought of yet is that it also caches #image_data, so you can hook your application up to that method
61 without fear of what might happen to all those Gravatar images if the Gravatar server should be unavailable!
62
63 To customize exactly which cache is used, see the next section...
8570ea9 Colin MacKenzie IV Logger support, and some helpful documentation
authored
64
65 === Configuration
66
cc83fca Colin MacKenzie IV Removed logger stuff from readme, since that's been removed
authored
67 To see settings and options you can give for a particular Gravatar instance, check out the Gravatar class documentation. There are a few things you can set for Gravatar on a system-wide basis, and that's what we'll go over next.
8570ea9 Colin MacKenzie IV Logger support, and some helpful documentation
authored
68
cc83fca Colin MacKenzie IV Removed logger stuff from readme, since that's been removed
authored
69 For a non-Rails project, simply set these options before you start using Gravatar. For a Rails project, you should set them within an Initializer in config/initializers/any_filename.rb in order to ensure that the settings are applied (A) after Gravatar has been included into the project, and (B) before it is actually used by Rails.
8570ea9 Colin MacKenzie IV Logger support, and some helpful documentation
authored
70
71 # You can set the default cache for Gravatar to use:
72 Gravatar.cache = ActiveSupport::Cache::SynchronizedMemoryStore.new
73
74 # You can also set the length of time an item in the Gravatar cache is valid. Default is 24.hours
75 Gravatar.duration = 20.minutes
76
f775da0 Colin MacKenzie IV Re-added logger, but with an option to disable.
authored
77 # You can also change the logger used by default. It's worth mentioning that, once again, Gravatar will use
78 # the Rails logger if it's available. Otherwise, the default is $stdout.
79 grav_log = ""
80 Gravatar.logger = StringIO.new(grav_log) # logs Gravatar output to a String
81
56d4091 Colin MacKenzie IV Initial commit to gravatar.
authored
82 == Note on Patches/Pull Requests
83
84 * Fork the project.
85 * Make your feature addition or bug fix.
cc83fca Colin MacKenzie IV Removed logger stuff from readme, since that's been removed
authored
86 * Add tests for it. This is important so I don't break it in a future version unintentionally.
87 * Don't update the version number. (If you want to have your own version, that's fine but bump version in a commit by itself I can ignore when I pull.)
56d4091 Colin MacKenzie IV Initial commit to gravatar.
authored
88 * Send me a pull request. Bonus points for topic branches.
89
90 == Copyright
91
6a07338 Colin MacKenzie IV updated copyright date (why not?)
authored
92 Copyright (c) 2010-2012 Colin MacKenzie IV. See LICENSE for details.
77fbac3 Colin MacKenzie IV Updated documentation
authored
93
94 == Contributors
95
77d0df1 Colin MacKenzie IV Updated contributors
authored
96 https://github.com/sinisterchipmunk/gravatar/contributors
97
98 Also:
99
100 {abitdodgy (Mohamad El-Husseini)}[https://github.com/abitdodgy] for https://github.com/sinisterchipmunk/gravatar/pull/7
Something went wrong with that request. Please try again.