README.md in gravatarify-1.2.1 vs README.md in gravatarify-2.0.3

- old
+ new

@@ -1,18 +1,25 @@ Gravatarify =========== Hassle-free construction of those pesky gravatar.com urls, with out-of-the-box support for -Rails, DataMapper and Haml. It's not that there aren't any alternatives [out](http://github.com/mdeering/gravitar_image_tag), +Rails, Haml and _your favorite framework_. It's not that there aren't any alternatives [out](http://github.com/mdeering/gravitar_image_tag), [there](http://github.com/chrislloyd/gravtastic), but none seem to support stuff like `Proc`s for the default picture url, or the multiple host names supported by gravatar.com (great when displaying lots of avatars). - **Source**: <http://github.com/lwe/gravatarify> - **Docs**: <http://rdoc.info/projects/lwe/gravatarify> +- **List**: <http://groups.google.com/group/gravatarify-plugin> - **Gem**: <http://gemcutter.org/gems/gravatarify> +**UPGRADE NOTES:** Version 2.x is a clean-up release which breaks backwards compatibility +with 1.x releases (in some cases!). HTML attributes must be passed like: +`gravatar_tag(@user, :size => 30, :html => { :class => "gravatar" })`, i.e. in a `:html` hash. +Furthermore the `gravatarify` method for ActiveRecord and DataMapper no longer exists, +see "Upgrading from 1.x" for more. + Ready, Set, Go! --------------- **READY** Install gravatarify as a gem (requires gemcutter): @@ -36,14 +43,13 @@ %img{ gravatar_attrs(@user, :size => 20) }/ **More!?** Allright, that was just the quickstart, to get up and running with ease. However, this library provides quite a bit more, like: - * ...view helpers, namely `gravatar_url` and `gravatar_tag`, see "Using the view helpers". - * ...object/model helpers, so that an object responds to `gravatar_url`, see "Using the model helpers" - Works also very well with plain old ruby objects. - * ...and finally, a base module which provides the gravatar url generation, ready to be integrated into + * View helpers, namely `gravatar_url` and `gravatar_tag`, see "Using the view helpers". + * Styles are like reusable definitions of options, nice to DRY-up your code, see "Using styles". + * A base module which provides the gravatar url generation, ready to be integrated into custom helpers, plain ruby code or whatever, see "Back to the roots". Using the view helpers ---------------------- @@ -65,77 +71,59 @@ <%= gravatar_tag @user %> # => assumes @user has email or mail field! This builds a neat `<img/>`-tag. To display an "X" rated avatar which is 25x25 pixel in size and the `<img/>` tag should have a class attribute, do: - <%= gravatar_tag @user, :size => 25, :rating => :x, :class => "gravatar" %> + <%= gravatar_tag @user, :size => 25, :rating => :x, :html => { :class => "gravatar" } %> -If more control is needed, or just the plain URL is required, resort to `gravatar_url`, which -returns a string with the (unescaped) url: +If any additional HTML attributes are needed on the tag, or in the `gravatar_attrs`, just +pass them in the `:html` option as hash. If more control is needed, or just the plain URL is +required, resort to `gravatar_url`, which returns a string with the (unescaped) url: <img src="<%= h(gravatar_url(@user.author_email, :size => 16)) %>" alt="Gravatar"/> - -Using the model helpers ------------------------ + +Using styles +------------ -A very simple method to add `gravatar_url` support to models is by using the `gravatarify` class method. +With styles it's possible to easily change e.g. the size of all gravatars based on a name, +these are reusable presets of options: + + # in config/initializers/gravatarify.rb or similar: + Gravatarify.styles[:mini] = { :size => 16, :html => { :class => 'gravatar gravatar-mini' } } + Gravatarify.styles[:default] = { :size => 45, :html => { :class => 'gravatar' } } + + # then in/some/view.html.erb: + <%= gravatar_tag @user, :mini %> # => <img alt="" class="gravatar gravatar-mini" height="16" src.... /> + + # or in/another/view.html.haml: + %img{gravatar_attrs(@user, :default)/ # => <img alt="" class="gravatar" height="45" ... /> + +Need to change to size of all `:mini` gravatars? Easy, just change the definition in `Gravatarify.styles`. +Of course settings via `Gravatarify.options` are "mixed-in" as well, so: - # Assuming User has a field named email or mail! - class User < ActiveRecord::Base - gravatarify - end + Gravatarify.options[:default] = Proc.new { |*params| "http://example.com/avatar-#{params.first[:size] || 80}.jpg" } + Gravatarify.styles[:mini] => { :size => 16 } + + <%= gravatar_tag @user, :mini %> # => <img alt="" height="16" src=".....?d=http://example.com/avatar-16.jpg" width="16" /> -Thats it! Well, at least if the `User` model responds to `email` or `mail`. Then in the views all left to do is: +All methods accept a style, i.e. a style parameter can be passed in to `gravatar_attrs`, `gravatar_tag` and +of course to `gravatar_url`. Any option can be passed in after a style, to customize the gravatar +if the styles needs slight alteration: - <%= image_tag @user.gravatar_url %> + gravatar_url(@user, :mini, :filetype => false, :rating => :x) # => "http://........123ab12?s=16&r=x" -Neat, isn't it? Of course passing options works just like with the view helpers: - <%= image_tag @user.gravatar_url(:size => 16, :rating => :r) %> +Back to the roots? +------------------ -Defaults can even be passed to the `gravatarify` call, so no need to repeat them on every `gravatar_url` call. - - gravatarify :employee_mail, :size => 16, :rating => :r - -All gravatars will now come from the `employee_mail` field, not the default `email` or `mail` field and be in 16x16px in size -and have a rating of 'r'. Of course these can be overriden in calls to `gravatar_url` like before. Pretty cool is also the -fact that an object can be passed directly to `gravatar_tag` if it responds to `gravatar_url`, like: - - # model: - class User < ActiveRecord::Base - gravatarify :size => 16, :secure => true - end - - # view: - <%= gravatar_tag @user %> # -> <img ... width="16" src="https://secure.gravatar..." height="16" /> - -The `gravatar_tag` looks if the object responds to `gravatar_url` and if so, just passes the options to it, -it works also with plain old ruby objects, of course :) - -### PORO - plain old ruby objects (yeah, POJO sounds smoother :D) - -Not using Rails, ActiveRecord or DataMapper? It's as easy as including `Gravatarify::ObjectSupport` to your -class: - - require 'gravatarify' - class PoroUser - include Gravatarify::ObjectSupport - gravatarify - end +No need for sophisticated stuff like view helpers, want to go back to the roots? +Then feel free to use `Gravatarify::Base#gravatar_url` directly. -Tadaaa! Works exactly like the model helpers, so it's now possible to call `gravatar_url` on instances -of `PoroUser`. - -## Back to the roots? - -No need for sophisticated stuff like view helpers and ActiveRecord integration, want to go back to the roots? -Then feel free to use `Gravatarify::Base#build_gravatar_url` directly. - When the ability to display image tags is required in different view frameworks (like liquid!?), then just ensure that `Gravatarify::Helper` is included in the framework in question. -See {Gravatarify::Base#build_gravatar_url} and of course {Gravatarify::Helper} -for more informations and usage examples. +See {Gravatarify::Base#gravatar_url} and of course {Gravatarify::Helper} for more informations +and usage examples. Need more control? ================== <table> @@ -184,10 +172,17 @@ <td>String, Symbol</td> <td>Change image type, gravatar.com supports <tt>:gif</tt>, <tt>:png</tt> and <tt>:jpg</tt>. If set to <tt>false</tt> then a URL without an extension will be built (and gravatar.com then returns a JPG image).</td> <td><tt>:jpg</tt></td> </tr> + <tr> + <td><tt>:html</tt></td> + <td>Hash</td> + <td>Ignored in URL generation, only used in <tt>gravatar_attrs</tt> and <tt>gravatar_tag</tt> to pass in additional + HTML attributes (like <tt>class</tt>, <tt>id</tt> etc.).</td> + <td>-</td> + </tr> </table> To set the options globally, access the `Gravatarify.options` hash and set any options which should apply to all gravatar urls there. Of course all settings can be overridden locally: @@ -196,17 +191,16 @@ Gravatarify.options[:size] = 16 gravatar_url(@user.email) # => http://0.gravatar.com/avatar/..f93ff1e?s=16 gravatar_url(@user.email, :filetype => :png) # => http://0.gravatar.com/avatar/..f93ff1e.png?s=16 -A pretty nifty option also exists to set options globally for `gravatar_tag` and `gravatar_attrs`, e.g. -to always add a title attribute: +To define global HTML attributes go ahead and do something like: # add title attribute - Gravatarify::Helper.html_options[:title] = "Gravatar" + Gravatarify.options[:html] = { :title => "Gravatar" } -### Not yet enough? +## Not yet enough? The `:default` option can be passed in a `Proc`, so this is certainly useful to for example to generate an image url, based on the request size: # in an initializer @@ -229,32 +223,80 @@ # => http://0.gravatar.com/...jpg?d=http%3A%2F%2Fexample.com%2Fgravatar_female.jpg Not only the `:default` option accepts a Proc, but also `:secure`, can be useful to handle cases where it should evaluate against `request.ssl?` for example. +## Upgrading from 1.x + +All HTML options must be passed in the `:html` attribute. This allows for predictable results for +all methods and no magic involved! So instead of doing: + + gravatar_tag(@user, :size => 30, :class => "gravatar", :title => "Gravatar") + # Note: in Version 2.0 this would build an image src like http://..gravatar.com/...../?class=gravatar&s=30&title=Gravatar + +do: + + gravatar_tag(@user, :size => 30, :html => { :class => "Gravatar", :title => "Gravatar" }) + +An important thing to know is that the `:html` is deep merged, with defaults, so stuff like: + + Gravatarify.options[:html] = { :title => "Gravatar" } + gravatar_tag(@user, :html => { :class => "gravatar" }) # => <img alt="" class="gravatar" ... title="Gravatar" .../> + +Furthermore the option `:html` is ignored when building the url parameters. + +If the `gravatarify` method was not used, there's no need to change anything at all :) Though if +it's used, then... + + 1. Remove all occurences of `gravatarify` in the models + 2. Change calls from `<%= image_tag @user.gravatar_url %>` to + saner `<%= gravatar_tag @user %>` calls or of course if just the url + is required to `gravatar_url(@user)`. + +If the model used `gravatarify :author_email`, then changes in the views must reflect that and use it +directly: `<%= gravatar_tag @user.author_email %>`. If the model defines `author_email`, but **not** +`email` (and has no attribute named `email`), then it could be safely aliased like: + + # Fields: (id, name, author_email, ...) + class Author < ActiveRecord::Base + alias_attribute :email, :author_email + end + + # and in the views: + <%= gravatar_tag @author %> + +In most cases the migration path should be pretty easy, just always use the helper +methods! The `gravatarify` method was introduced to provide compatibility with +`gravtastic`, yet it's not way to go in my opinion. If for some reason it's required +then feel free to fallback and use an older version (i.e. 1.2.1): + + [sudo] gem install gravatarify -v 1.2.1 + + About the code ============== Eventhough this library has about 100 LOC, it's split into four files, maybe a bit of an overkill, though I like neat and tidy classes :) lib/gravatarify.rb # loads the other files from lib/gravatarify # and hooks the necessary modules into - # ActionView, ActiveRecord and DataMapper - # (if available) + # HAML or ActionView. lib/gravatarify/base.rb # Provides all logic required to generate # gravatar.com urls from an email address. - # Check out Gravatarify::Base.build_gravatar_url, + # Check out Gravatarify::Base.gravatar_url, # this is the absolute core method. + + lib/gravatarify/helper.rb # Defines the view helpers: gravatar_attrs + # and gravatar_tag - lib/gravatarify/object_support.rb # Module which (when) included provides the - # gravatarify class method to add a gravatar_url - # to any object. + lib/gravatarify/utils.rb # Provides commonly used methods, like helpers to + # uri and html escape strings or deep mergeing + # hashes. Though these utils are only for internal + # uses :) - lib/gravatarify/helper.rb # Defines those view helpers, mainly gravatar_attrs - # and gravatar_tag ### Contribute 1. Fork the project and hack away 2. Ensure that the changes are well tested 3. Send me a pull request @@ -283,6 +325,6 @@ EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION -WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. \ No newline at end of file +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.