AddThis Menu API

Overview

The AddThis API is based on the principles of unobtrusive JavaScript, taking a page from modern JavaScript toolkits like jQuery that separate markup and behavior with the following goals in mind:

• If you're not a JavaScript wizard, the most common customizations should still be easy
• In fact, most use cases should be covered with as little JavaScript as possible
• But even the most complicated configurations should be possible (for example, multiple buttons on a page behaving differently)

Our API supports global configuration as well as per-element configuration--every button on a page can behave differently in almost every regard. You might not need to ever go that far. But you could.

An Illustrative Example

<a class="addthis_button"></a>

Configuration

UI Configuration

var addthis_config =
{
   // ... members go here
}

UI Configuration Options

Section 508 Compliance

You can make your AddThis button Section 508 compliant by using ui_508_compliant.

<script type="text/javascript">
var addthis_config =
{
   ui_508_compliant: true
}
</script>
<a class="addthis_button"></a>

Sharing Configuration

var addthis_share =
{
   // ... members go here
}

Sharing Configuration Options

Templates

Some destinations let users post arbitrary content. By using a template, you can customize the default post.

Sample template:

    twitter: 'check out {{url}} (from @addthis)'

We'll fill in a few different tokens for you -- you can use all, some or none of them:

• {{url}} - the URL being shared; on destinations that have a length limit (i.e., Twitter), we'll automatically shorten the URL for you
• {{lurl}} - the URL being shared; even on destinations that have a length limit, this token (short for "long URL") will never shorten your URL
• {{title}} - the title being shared
• {{html}} - the arbitrary HTML shared (the "html" parameter above)

You can provide one template per destination that supports them:

var addthis_share = 
{ 
// ...
    templates: {
                   twitter: 'check out {{url}} (from @example_dot_com)',
               }
}

The following services currently support these types of templates:

• Twitter

Specifying Embedded Content

We recommend that you tag your page with meta tags to identify any Flash content located on it (you can also provide Flash object details directly thorugh this API, via swfurl and related parameters). See this guide to sharing rich content for a full explanation of this feature, including an example.

Note:Some destinations, notably iGoogle, support Flash content but do NOT currently also support simple link content. For this reason, if you are sharing a URL page that is tagged with Flash information, enable these destinations in the menu by setting the ui_use_embeddable_services_beta UI configuration parameter.

Rendering with JavaScript

addthis.function(target(s), [configurationObject], [sharingObject]);

where target(s) can be

1. a classname, specified with a dot: '.sharing-button'
2. an id, specified with a hash: '#addthis_button_1'
3. an actual HTML element reference
4. an array of HTML element references

If configurationObject is unspecified, global defaults (i.e., the addthis_config object) are used. If sharingObject is unspecified, global defaults (i.e., the addthis_share object) are used. At present, we only support rendering of buttons via JavaScript, but we plan to support inline menus as well in the future.

The Button

Renders a normal AddThis button at an anchor tag. If the tag has no image in it, we load our default image. If the tag has an image in it, that image is used as for the button graphic.

addthis.button(target(s), [configurationObject], [sharingObject]);

Examples

Render a button at a tag:

<a id="atbutton"></a>

<script type="text/javascript">
addthis.button("#atbutton");
</script>

Render a button at every anchor with a certain class:

<a class="sharing-button"></a>
.
.
.
<a class="sharing-button"></a>
.
.
.
<a class="sharing-button"></a>
<script type="text/javascript">
addthis.button('.sharing-button');
</script>

Each "sharing-button"-classed anchor would become a regular AddThis button.

Share many different blog posts:

<a id="blog-post-24"></a>
<script type="text/javascript">
addthis.button('#blog-post-24', {}, {url: "http://example.com/blog/24", title: "The 24th post"});
</script>
.
.
.
<!-- blog content -->
.
.
.
<a id="blog-post-25"></a>
<script type="text/javascript">
addthis.button('#blog-post-25', {}, {url: "http://example.com/blog/25", title: "The 25th post"});
</script>
.
.
.

Render a button at an HTML element passed by reference:

<a id="button-1"></a>
<script type="text/javascript">
addthis.button(document.getElementById('button-1'));
</script>

Render a button at an array of HTML elements:

<a id="button-1"></a>
<a id="button-2"></a>
<a id="button-3"></a>
<a id="button-4"></a>
<script type="text/javascript">
addthis.button([document.getElementById('button-1'),
                document.getElementById('button-2'),
                document.getElementById('button-3'),
                document.getElementById('button-4')]);
</script>

The Toolbox

Renders an AddThis toolbox inside the given div. In normal operation, all appropriately-classed anchors are rendered automatically through link decoration, described below. But when building a toolbox dynamically using JavaScript, after the page has finished loading, you can use this function to force AddThis to update any newly decorated links. (If the div has no appropriately-classed anchors inside it, nothing happens.)

addthis.toolbox(target(s), [configurationObject], [sharingObject]);

Example

Render a dynamically-created toolbox:

<div id="toolbox"></div>

<script type="text/javascript">
var tbx = document.getElementById("toolbox"),
    svcs = {email: 'Email', print: 'Print', facebook: 'Facebook', expanded: 'More'};

for (var s in svcs) {
    tbx.innerHTML += '<a class="addthis_button_'+s+'">'+svcs[s]+'</a>';
}
addthis.button("#tbx");
</script>

Rendering with Link Decoration

While the JavaScript rendering methods are powerful, in most cases we believe they're more powerful than what's actually necessary. Following the principles of Unobtrusive JavaScript as discussed above, you can now create and configure an AddThis button in three simple steps:

• Add plain old anchor tags where you want your buttons to appear
• Add the appropriate CSS classes for the kinds of buttons you want them to be
• Add our JavaScript

Upon loading, our script will look for all our standard classes and render buttons as specified. Here's some simple examples to demonstrate:

A button:


The code used to generate it: <a class="addthis_button"></a>

An email button:
The code used to generate it: <a class="addthis_button_email"></a>

See where we're going with this? The links aren't processed until after the DOM's ready, so it won't even slow down your page. (If you don't want your layout to shift when the images are loaded, however, you should make sure to provide static images or content for all the links.)

Decoration Class Reference

Note: Class-based configuration trumps global JavaScript configuration objects. For example:

<script type="text/javascript">
var addthis_config = {
    ui_click: true /* normally would disable mouseover behavior */
}
</script>

<div class="addthis_toolbox"></div>
<a class="addthis_button_compact">Share</a>

The compact menu button rendered by this code will have mouseover behavior, as the class-based configuration is considered authoritative.

Preferred Services (beta)

Oftentimes explicit toolbox buttons make sense--your CEO is demanding one-click sharing to Facebook, for example. But since we support over 200 services, each with different popularities across our supported languages, sometimes it's best to let us pick services for you. We do this automatically in our compact menu, but you can also select preferred services using the toolbox:

<div class="addthis_toolbox addthis_default_style">
<a class="addthis_button_preferred_1" style="cursor:pointer"></a><a class="addthis_button_preferred_2" style="cursor:pointer"></a><a class="addthis_button_preferred_3" style="cursor:pointer"></a></div>

Attribute-based Configuration

So you've probably noticed that the JavaScript-based configuration and the decoration-based rendering only work together for global configurations. If you want different configurations for each button, you can't pass a JavaScript configuration object in to the default renderer. You can, however, specify parameters as custom attributes on the anchors themselves. All the parameters described above are available, with the prefix addthis:. Let's look at some examples:

To specify a custom URL and title:

<a class="addthis_button" addthis:url="http://example.com" addthis:title="An excellent website"></a>

To specify a hover delay:

<a class="addthis_button" addthis:ui_hover_delay="200"></a>

Note: Attribute-based configuration trumps global JavaScript configuration objects.

Configuration Inheritance

Configuration is inherited by the elements nested within toolbox divs. This way, you could easily customize an entire toolbox without having to add configuration attributes to every single button. For example:

<div class="addthis_toolbox" addthis:url="http://example.com/blog/post/2009/05/01" addthis:title="Hooray!">
<a class="addthis_button_compact">Share</a>
<a class="addthis_button_email"></a>
<a class="addthis_button_facebook"></a>
<a class="addthis_button_buzz"></a>
</div>

Each of the buttons in this toolbox would share the URL specified at the toolbox level.

There are two exceptions.

1. Configuration isn't inherited by children of arbitrary elements.

In this example, neither button would share "http://example.com". The parent div must be an addthis_toolbox.

<div addthis:url="http://example.com">
<a class="addthis_button_email"></a>
<a class="addthis_button_print"></a>
</div>

2. Configuration isn't inherited by regular addthis_buttons.

Because addthis_button is intended to stand alone, it does not inherit from a toolbox parent.

<div class="addthis_toolbox" addthis:url="http://example.com">
<a class="addthis_button"></a>
</div>

Valid XHTML

If you're using XHTML, the custom attributes will not pass validation. To make your XHTML technically valid, you'll need to add a custom namspace declaration to your opening <html> tag. (Note that the W3C validator does not take custom namespaces into account.)

Change

<html xmlns="http://www.w3.org/1999/xhtml">

<html 
    xmlns="http://www.w3.org/1999/xhtml"
    xmlns:addthis="http://www.addthis.com/help/api-spec">

But I really need my documents to validate!

<!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"
[
  <!ATTLIST a addthis:url CDATA #IMPLIED>
  <!ATTLIST a addthis:title CDATA #IMPLIED>
]>

(See this this List Apart article for more discussion of these techniques.)

Events (beta)

Note: The menu events beta is currently unavailable. Check back soon for updates!

When building customized AddThis experiences, or when integrating AddThis with your own web analytics software (like Omniture or Webtrends), it can be useful to know exactly what's happening in the UI. We dispatch key events asynchronously for your consumption. N.B. Events are dispatched globally; we do not currently support distinguishing between multiple menus on a page.

Registering an Event Listener

AddThis events behave much like standard DOM events. To be notified when an event occurs, you must indicate which event you'd like to listen to and provide a callback function for the event itself. Upon the even being fired, the provided function will be called with the event object as its single argument. Any relevant event metadata will be attached to the event object.

addthis.addEventListener(type, listener);

type is a string representing the event type to listen for.
listener is a reference to the function handling this event.

Example:

// Alert a message when the AddThis API is ready
function addthisReady(evt) {
    alert('AddThis API is fully loaded.');
}

// Listen for the ready event
addthis.addEventListener('addthis.ready', addthisReady);

Event Objects

All AddThis event objects have a type and metadata associated with them.

Let's look at the skeleton of the event handler from the example above:

function eventHandler(evt) { 
    // evt is the event object
}

The event object will always have a type property indicating which event was dispatched (so you can use the same handler for multiple events).

function eventHandler(evt) { 
    alert(evt.type); // In the example above, this would alert "addthis.ready"
}

Additionally, the event object may provide an data property with additional information about the event. For example, the "addthis.menu.share" event stores which service the user just shared to:

// Alert a message when the user shares somewhere
function shareEventHandler(evt) { 
    if (evt.type == 'addthis.menu.share') { 
        alert(typeof(evt.data)); // evt.data is an object hash containing all event data
        alert(evt.data.service); // evt.data.service is specific to the "addthis.menu.share" event
    }
}

// Listen for the share event
addthis.addEventListener('addthis.menu.share', shareEventHandler);

Event Types

Event Examples

Putting it all together:

<a class="addthis_button"></a>

<script type="text/javascript">
// Alert a message when the user shares somewhere
function eventHandler(evt) { 
    switch (evt.type) {
        case "addthis.menu.open":
            console.log('menu opened; surface=' + evt.data.pane);
            break;
        case "addthis.menu.close":
            console.log('menu closed; surface=' + evt.data.pane);
            break;
        case "addthis.menu.share":
            console.log('user shared to ' + evt.data.service);
            break;
        default:
            console.log('received an unexpected event', evt);
    }
    
    if (evt.type == 'addthis.menu.share') { 
        alert(typeof(evt.data)); // evt.data is an object hash containing all event data
        alert(evt.data.service); // evt.data.service is specific to the "addthis.menu.share" event
    }
}

// Listen to various events
addthis.addEventListener('addthis.menu.open', eventHandler);
addthis.addEventListener('addthis.menu.close', eventHandler);
addthis.addEventListener('addthis.menu.share', eventHandler);
</script>

User Data (beta)

We expose some of our non-personally-identifying user data for external use, primarily to enable you to create personalized AddThis menus both with link decoration and JavaScript. Since this requires moving data out of our domain and into yours, these API functions are asynchronous.

Like our JavaScript JavaScript rendering methods, the user API methods take the form:

addthis.user.function(callback);

where callback has a single argument for the returned value. For example,

function callback(data) {
    alert(data);
}

Preferred Services

Returns an Array of service IDs in rank order (e.g., ['facebook','myspace','google']) that we've optimized for the viewer. It takes into account the user's own preferences (see below if you just want historical data), language (e.g., Orkut appears high on the list for Portuguese speakers), and overall platform statistics, in that order. As of now, we return up to 11 services if applicable. If we don't have enough data for the user's region, the platform-wide default will be used.

Any services the user has actually shared to will be listed first, in order of use, up to half the length of the total array.

Warning: If services_compact is defined, it overrides our optimized array and is returned instead.

addthis.user.getPreferredServices(callback);

Example:

<script type="text/javascript">
// Call the API, passing a callback function; will create a div 
// listing the best services for the viewer
// Remember! The API is asynchronous!
addthis.user.getPreferredServices(function(services){
    var el = document.createElement('div');
    document.body.appendChild(el);
    
    if (services.length) {
        var h = document.createElement('h2');
        h.innerHTML = 'Best Sharing Services';
        el.appendChild(h);
        
        var list = document.createElement('ol');
        el.appendChild(list);
        
        // Loop over personalization entries
        for (var i=0; i < services.length; i++) {
            var service = services[i],
                item = document.createElement('li');
            item.innerHTML = service;
            list.appendChild(item);
        }
    }
});
</script>

Service Share History

Returns an Array of service IDs (e.g., ['facebook','myspace','google']), ordered by user preference. The array is empty ([]) in all failure cases: browser unsupported for personalization, user has no share history, communication timeout, or other communication failure.

addthis.user.getServiceShareHistory(callback);

Example:

<script type="text/javascript">
// Call the API, passing a callback function; will create a div 
// listing the user's share history on an included page
// Remember! The API is asynchronous!
addthis.user.getServiceShareHistory(function(ssh){
    var el = document.createElement('div');
    document.body.appendChild(el);
    
    // Oh no! No personalization?
    if (ssh.length === 0) {
        var h = document.createElement('h2');
        h.innerHTML = 'No sharing history!';
        el.appendChild(h);
        
    // Phew
    } else {
        var h = document.createElement('h2');
        h.innerHTML = 'Top Sharing Services';
        el.appendChild(h);
        
        var list = document.createElement('ol');
        el.appendChild(list);
        
        // Loop over personalization entries
        for (var i=0; i < ssh.length; i++) {
            var service = ssh[i],
                item = document.createElement('li');
            item.innerHTML = service;
            list.appendChild(item);
        }
    }
});
</script>

Utilities

Service Display Name

Returns a string representing the given service's full name -- when making your own user interface, being able to translate a service code (e.g., 'facebook') into its proper display name (e.g., 'Facebook') can be essential. HTML entity characters may be returned; for example, given the Spanish site 'meneame', we return 'Men&eacute;ame'.

addthis.util.getServiceName(service);

Example:

<script type="text/javascript">
alert(addthis.util.getServiceName('myspace')); // alerts "MySpace"
</script>

If you're interested in learning more about unobtrusive JavaScript, here's a few relevant articles:

• A List Apart on Behavioral Separation
• Ioannis Cherouvim on Unobtrusive JavaScript
• Coding Instinct on Separation Of Concerns

Back to Top