File: README — Documentation for jaap3-addthis (0.8.0)

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.

Installation

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

Quick Start

The most basic use is simply providing no arguments:

addthis_bookmark_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_email_button("http://www.example.com/")
addthis_feed_button("http://www.example.com/")

Setting a title is also possible when adding a bookmark or email button:

addthis_bookmark_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_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.

Usage

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::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.

Custom services

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"

Custom images / text

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.

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 AddThis"
Jaap3::Addthis::FEED_BUTTON_DEFAULTS[:button_html] = "Click here to AddThis"
Jaap3::Addthis::EMAIL_BUTTON_DEFAULTS[:button_html] = "Click here to AddThis"

Script options

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:

Secure pages

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.

Custom language

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")

Jaap3::Addthis::DEFAULT_OPTIONS[:language] = "nl"

For a list of supported language codes see the bottom of addthis.com/help/localization/translations

Contributing

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.

Addthis