= MephistoGravatarCache = == Installation == Install the plugin from the repository with: ruby script/plugin install http://svn.hiddenloop.com/public/plugins/mephisto_gravatar_cache/ From your Rails Root, the install script will attempt to create 'tmp/cache/gravatars' and a symbolic link in 'public/images/gravatars' to this directory. If the install script fails you can try creating these folders manually. To complete the plugin installation, change the Mephisto Comment model and run the rake task (see below) **NOTE** - for some reason my install.rb script seems to fall over using the normal 'script/plugin install' command. When it runs successfully, you should be asked if you want to run the rake task and see this README file after the installation. To ensure the plugin DOES get installed correctly, after using the above 'script/plugin install' command, run the install.rb directly from your Rails Root with; ruby vendor/plugins/mephisto_gravatars_cache/install.rb === Windows OS Users === The symbolic link cannot be created, since ln -s isn't available. Because of this, it is a better idea to have your cache directory and image directory as the folders. So after a failed install, in 'lib/gravatar_api.rb' change your cache_dir setting to match your image_dir setting ('public/images/gravatar'). Then change the Comment model as described below. == Amend Comment Model == The following code should be added to the Comment model (in Mephisto) at '/app/models/comment.rb' On submission of a comment this code will attempt to cache a gravatar image using 'author_email'. # add cache_gravatar before saving comment before_save :update_counter_cache, :cache_gravatar # attempt to cache the gravatar def cache_gravatar GravatarAPI.cache_gravatar(author_email) if author_email end == Run Rake Task == Run the 'cache_gravatars' task from your rails root folder with: rake cache_gravatars This command will find all comments (in the contents table) that have email addresses. It will then attempt to cache a gravatar image for each one (in the gravatar cache directory). If gravatar image is already cached, a check is made on expiry of the image, before requesting gravatar.com for an update. Output is well logged in the normal rails environment.log, and shown on screen. By default this task targets the development environment, to run against your production database use: rake cache_gravatars RAILS_ENV=production == Show Cached Gravatars In Your Liquid Templates, the Liquid Filter == To show the gravatar in your Liquid templates use the 'gravatar_image' filter like this: # will return an image tag if gravatar is found, otherwise returns nothing {{ comment | gravatar_image }} # this allows you to specify a default image in the event no avatar is found in the cache {{ comment | gravatar_image '/images/no-avatar.gif' }} # you can also specify the css class on the image tag (the default class is 'photo') {{ comment | gravatar_image '/images/no-avatar.gif', 'css_class' }} # == Setting up a Cron == Depending on your expiry time setting (default 3 days), to regularly refresh the gravatar cache, you'll want to setup a cron job (e.g. daily or weekly). This ensures that your bank of cached gravatar images is up to date with any new gravatar images a user may have uploaded for their email address at gravatar.com E.g. to setup bash script and daily cron to run the rake task do something like this: === Bash Script (e.g. save it at /home/username/gravatar_cache.sh) === cd /path/to/your/rails_root rake cache_gravatars RAILS_ENV=production === Cron === 0 5 * * * /home/username/gravatar_cache.sh This will cause your bash script to run the rake task every day at 5AM. For more information on crons and building them see here; http://en.wikipedia.org/wiki/Crontab == Configuration == You can configure a few things in 'lib/gravatar_api.rb' * default_image # image to use if user has no gravatar * image_size # size of image gravatar site will return (60, e.g. 60x60 square) * rating # e.g. G | PG | R | X - see http://site.gravatar.com/site/implement * cache_dir # directory relative to rails_root/ where cached gravatar images will be saved * image_dir # directory relative to rails_root/public/ set, must symlink to cache_dir * base_url # for the gravatar site, e.g. www.gravatar.com * expire_ago # e.g. 3.days.ago - means gravatars will live in cache for 3 days before expiring on next cron run of rake task 'cache_gravatars' * clear_cache_on_every_check # see description below Normally during a cache refresh, the existing gravatar is deleted from the cache. The setting clear_cache_on_every_check = false (in lib/gravatar_api.rb) will make sure the old gravatar image doesn't get removed. This is useful in cases when a user has disabled or left gravatar.com but you still want to show their old gravatar image in your application. == Caveats == Gravatar are (highly) likely to change their API (again!), doing so may cause this plugin to fail. In this event, important methods you should be concerned about are: (in 'lib/gravatar_api.rb') * has_gravatar (detects if user has a gravatar) * build_gravatar_path (constructs the URL to request a gravatar, see http://site.gravatar.com/site/implement === Improvements / Todo === While this plugin is a Mephisto Gravatar Cache - with only a little modification it could work with any Rails app. The rake task 'cache_gravatars' in 'tasks/mephisto_gravatar_cache_tasks.rb' would need to be modified, and a call to cache_gravatar in 'lib/gravatar_api.rb' made on any email addresses needing cached. I've tried to comment my code as best as possible, to encourage further development of this plugin. * add tests for gravatar_api and liquid filter. == Uninstall == Run 'ruby vendor/plugins/mephisto_gravatar_cache/uninstall.rb' to unistall the plugin. This script should remove the caching directory and symbolic link. You will also need to undo your changes to the Comment model (see above). After this you are free to delete vendor/plugins/mephisto_gravatar_cache == Bugs == Please report all bugs and/or submit patches to matt@hiddenloop.com. Your comments, criticisms and thoughts are also welcome. == Credits == * plugin: http://svn.hiddenloop.com/public/plugins/mephisto_gravatar_cache/ * author: Matthew Hutchinson * email: matt@hiddenloop.com * web: http://matthewhutchinson.net * license: The terms of the BSD License have been utilized (see LICENSE) * thanks to: http://snippets.dzone.com/posts/show/2587 (chebuctonian)