Skip to content
Newer
Older
100644 87 lines (60 sloc) 4.1 KB
8570ea9 @sinisterchipmunk Logger support, and some helpful documentation
authored Jun 16, 2010
1 = gravatar-ultimate
56d4091 @sinisterchipmunk Initial commit to gravatar.
authored Jun 15, 2010
2
8570ea9 @sinisterchipmunk Logger support, and some helpful documentation
authored Jun 16, 2010
3 The Ultimate Gravatar Gem!
4
5 This gem is used to interface with the entire Gravatar API: it's not just for generating image URLs, but for connecting
6 to and communicating with the XML-RPC API too! Additionally, it can be used to download the Gravatar image data itself,
7 rather than just a URL to that data. This saves you the extra step of having to do so.
8
9 == Installation
10
11 gem install gravitar-ultimate
12
13 === Activate the gem...
14 As with any gem, you have to type a few lines to tell Ruby to actually *use* it. Here's how to do that...
15
16 ==== ...in Ruby on Rails
17
18 * Edit your config/environment.rb file
19 * Add this line beneath "Rails::Initializer.run do |config|":
20 * config.gem 'gravitar-ultimate'
21
22 ==== ...in vanilla Ruby
23
24 require 'rubygems'
25 gem 'gravitar-ultimate'
26 require 'gravitar-ultimate'
27
28 == Usage
29 Using the gem is actually pretty simple. Let's say you want the Gravatar image URL for "generic@example.com":
30 url = Gravatar.new("generic@example.com").image_url
31
32 Cool, huh? Let's take it a step further and grab the actual image *data* so that we can render it on the screen:
33 data = Gravatar.new("generic@example.com").image_data
34
35 Fine, but how about the rest of the API as advertised at http://en.gravatar.com/site/implement/xmlrpc? Well, for
36 that you need either the user's Gravatar password, or their API key:
37
38 api = Gravatar.new("generic@example.com", :password => "helloworld")
39 api = Gravatar.new("generic@example.com", :api_key => "AbCdEfG1234")
40
41 After you have that, things get a lot easier:
42
43 api.exists? #=> true or false, depending on whether this user has an account.
44 api.addresses #=> a list of email addresses and their corresponding images
45 api.save_data!(rating, image_data) #=> saves an image to this user's account and returns a handle to it
46 api.use_user_image!(handle, an_email_address) #=> uses the specified image handle for the specified email address(es)
47 api.exists?("another@example.com") #=> true or false, depending on whether the specified email exists.
48
49 As you can see this is quite powerful. But it gets better. Gravatar Ultimate actually manages caching for you! That way,
50 if an error occurs, (such as the Gravatar site being offline), your code won't break. It'll instead gracefully fall
51 back to the cached copy! By default, if you are using Rails, it'll use the Rails cache. Otherwise, it'll use whatever
52 cache you're using with Gravatar (by default an instance of ActiveSupport::Cache::FileStore).
53
54 === Configuration
55
56 To see settings and options you can give for a particular Gravatar instance, check out the Gravatar class documentation.
57 There are a few things you can set for Gravatar on a system-wide basis, and that's what we'll go over next.
58
59 For a non-Rails project, simply set these options before you start using Gravatar. For a Rails project, you should set
60 them within an Initializer in config/initializers/any_filename.rb in order to ensure that the settings are applied
61 (A) after Gravatar has been included into the project, and (B) before it is actually used by Rails.
62
63 # You can set the default cache for Gravatar to use:
64 Gravatar.cache = ActiveSupport::Cache::SynchronizedMemoryStore.new
65
66 # You can also set the length of time an item in the Gravatar cache is valid. Default is 24.hours
67 Gravatar.duration = 20.minutes
68
69 # You can also change the logger used by default. It's worth mentioning that, once again, Gravatar will use
70 # the Rails logger if it's available. Otherwise, the default is $stdout.
71 grav_log = ""
72 Gravatar.logger = StringIO.new(grav_log) # logs Gravatar output to a String
56d4091 @sinisterchipmunk Initial commit to gravatar.
authored Jun 15, 2010
73
74 == Note on Patches/Pull Requests
75
76 * Fork the project.
77 * Make your feature addition or bug fix.
78 * Add tests for it. This is important so I don't break it in a
79 future version unintentionally.
80 * Commit, do not mess with rakefile, version, or history.
81 (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
82 * Send me a pull request. Bonus points for topic branches.
83
84 == Copyright
85
86 Copyright (c) 2010 Colin MacKenzie IV. See LICENSE for details.
Something went wrong with that request. Please try again.