Addthis.com provides widgets that make sharing, bookmarking and emailing pages, and subscribing to feeds easy for your visitors. It supports a broad range of social network sites and web applications.
This helper makes it easy to add plain or customized Addthis.com widgets to your Ruby (on Rails) application.
If you want to use the Rails 2.1 dependency manager add this environment.rb:
config.gem 'jaap3-addthis', :lib => 'addthis', :source => 'http://gems.github.com'
Then run the following command in your Rails application root:
rake gems:install
Or use it as a plain plugin:
script/plugin install git://github.com/jaap3/addthis.git
This plugin adds 4 new methods to be used in your html views:
addthis_bookmark_button addthis_share_button addthis_email_button addthis_feed_button(url)
The bookmark_button and share_button are identical except for the default graphic. The names of email_button and feed_button are self explanitory.
The most basic use is simply providing no arguments, this is possible for the following methods:
addthis_bookmark_button addthis_share_button addthis_email_button
The code generated by Addthis will then try to figure out the url and title by itself. This is not possible for addthis_feed_button.
You can set a custom url, a required argument for addthis_feed_button:
addthis_bookmark_button("http://www.example.com/") addthis_share_button("http://www.example.com/") addthis_email_button("http://www.example.com/") addthis_feed_button("http://www.example.com/")
Setting a title is also possible when adding a bookmark, share or email button:
addthis_bookmark_button("http://www.example.com/", "Example website") addthis_share_button("http://www.example.com/", "Example website") addthis_email_button("http://www.example.com/", "Example website")
To only set a custom title you can use to options hash:
addthis_bookmark_button(:page_title => "Example title") addthis_share_button(:page_title => "Example title") addthis_email_button(:page_title => "Example title")
The options hash can be used to customize the widget to a great extent. Each of the shown examples can take the options hash as an optional extra argument.
If you wish to track analytics for your button, you must create an account at Addthis.com. Joining is free!
After signing up create a new ruby file in config/initializers called addthis.rb. You can use this file to configure your publisher name (your Addthis.com username) like so:
Jaap3::Addthis::CONFIG[:publisher] = "YOUR_USERNAME_HERE"
You can then use this initializer to further override any other settings you might like.
The default settings are stored in the following constants. You can look in the source to see what they are.
Jaap3::Addthis::CONFIG Jaap3::Addthis::DEFAULT_OPTIONS Jaap3::Addthis::BOOKMARK_BUTTON_DEFAULTS Jaap3::Addthis::SHARE_BUTTON_DEFAULTS Jaap3::Addthis::FEED_BUTTON_DEFAULTS Jaap3::Addthis::EMAIL_BUTTON_DEFAULTS
Besides overriding the default settings using the initializer, each helper method takes an options hash that can be used to override any setting for a specific button.
To change the initial list of services shown when opening the bookmark menu pass the options hash a list of services you wish to see.
addthis_bookmark_button(:options => "facebook, email, twitter, more")
For a list of available services see addthis.com/help/customize/services. By modifying the defaults in the initializer you can avoid having to set your preferred set of services every call.
Jaap3::Addthis::DEFAULT_OPTIONS[:options] = "facebook, email, twitter, more"
Using a different image or link text is achieved by using the methods with a block:
addthis_bookmark_button { "Click here to AddThis!" }
This will output a textlink that behaves exactly like a normal bookmark_button but withouth the image.
You can also use the block to call the Rails image_tag helper to embed your own images.
addthis_bookmark_button { "#{image_tag("bookmark.gif") Bookmark...}" }
You can permanently change the default image of each button by modifying the following constants in you initializer:
Jaap3::Addthis::BOOKMARK_BUTTON_DEFAULTS[:button_html] = "Click here to bookmark this" Jaap3::Addthis::SHARE_BUTTON_DEFAULTS[:button_html] = "Click here to share this" Jaap3::Addthis::FEED_BUTTON_DEFAULTS[:button_html] = "Click here to subscribe" Jaap3::Addthis::EMAIL_BUTTON_DEFAULTS[:button_html] = "Click here to email this"
Addthis.com allows for a few variables to be set to change the appearance of the widget. These can either be given during a method call:
addthis_bookmark_button({ :brand => "Example brand", :header_color => "white", :header_background => "black", :offset_top => -100, :offset_left => 125, :hover_delay => 200 })
Or by having your initializer change the defaults stored in:
Jaap3::Addthis::DEFAULT_OPTIONS
Note that you cannot customize individual buttons on a page. Custom settings will be applied to all the buttons on a page. This is a limitation of the Addthis.com widget.
Read more about these options on the the addthis.com website:
Calling one of the addthis_button methods with the secure option set to true like this:
addthis_bookmark_button(:secure => true)
will output a button usable on https pages.
The default value of the secure option is false, this default can be changed by setting
Jaap3::Addthis::DEFAULT_OPTIONS[:secure] = true
in your initializer.
The Addthis widget language will automatically choose a language based on the user’s browser settings. To override this behaviour you can set a custom language.
addthis_bookmark_button(:language => "nl")
or
Jaap3::Addthis::DEFAULT_OPTIONS[:language] = "nl"
For a list of supported language codes see the bottom of addthis.com/help/localization/translations
If you would like to contribute to the Addthis plugin, just fork the code and send me a pull request after you are done fiddling.
Copyright © 2009 Jaap Roes. See LICENSE for details.