Skip to content
Newer
Older
100644 101 lines (63 sloc) 4.81 KB
8570ea9 @sinisterchipmunk Logger support, and some helpful documentation
authored
1 = gravatar-ultimate
56d4091 @sinisterchipmunk Initial commit to gravatar.
authored
2
8570ea9 @sinisterchipmunk Logger support, and some helpful documentation
authored
3 The Ultimate Gravatar Gem!
4
cc83fca @sinisterchipmunk 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 @sinisterchipmunk Logger support, and some helpful documentation
authored
6
7 == Installation
8
62af33c @sinisterchipmunk Corrected misspellings - #1
authored
9 gem install gravatar-ultimate
8570ea9 @sinisterchipmunk Logger support, and some helpful documentation
authored
10
4b04683 @sinisterchipmunk Fixed documentation whoops
authored
11 == Activate the gem...
12
8570ea9 @sinisterchipmunk 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 @sinisterchipmunk A little footnote about Rails 3 and how I'd really love to work on th…
authored
15 ==== ...in Ruby on Rails (v3.x)
16
77fbac3 @sinisterchipmunk Updated documentation
authored
17 * Edit your Gemfile
18 * Add this line:
62af33c @sinisterchipmunk Corrected misspellings - #1
authored
19 gem 'gravatar-ultimate'
5f1ebbd @sinisterchipmunk A little footnote about Rails 3 and how I'd really love to work on th…
authored
20
21 ==== ...in Ruby on Rails (v2.x)
8570ea9 @sinisterchipmunk 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 @sinisterchipmunk Corrected misspellings - #1
authored
25 config.gem 'gravatar-ultimate'
8570ea9 @sinisterchipmunk Logger support, and some helpful documentation
authored
26
27 ==== ...in vanilla Ruby
28
29 require 'rubygems'
62af33c @sinisterchipmunk Corrected misspellings - #1
authored
30 gem 'gravatar-ultimate'
31 require 'gravatar-ultimate'
8570ea9 @sinisterchipmunk 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 @sinisterchipmunk Fixed a few minor discrepancies in certain return values. Also, makin…
authored
54
55 == Caching
56
cc83fca @sinisterchipmunk 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 @sinisterchipmunk Fixed a few minor discrepancies in certain return values. Also, makin…
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 @sinisterchipmunk Logger support, and some helpful documentation
authored
64
65 === Configuration
66
cc83fca @sinisterchipmunk 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 @sinisterchipmunk Logger support, and some helpful documentation
authored
68
cc83fca @sinisterchipmunk 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 @sinisterchipmunk 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 @sinisterchipmunk 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 @sinisterchipmunk 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 @sinisterchipmunk 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 @sinisterchipmunk Initial commit to gravatar.
authored
88 * Send me a pull request. Bonus points for topic branches.
89
90 == Copyright
91
6a07338 @sinisterchipmunk updated copyright date (why not?)
authored
92 Copyright (c) 2010-2012 Colin MacKenzie IV. See LICENSE for details.
77fbac3 @sinisterchipmunk Updated documentation
authored
93
94 == Contributors
95
77d0df1 @sinisterchipmunk 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.