The ShareThis API (STAPI) is for advanced implementations

So if you're looking to share something more than just a web page (e.g. image, video, etc.), to change the default object properties or to share multiple objects on a single web page then you.re in the right spot.

The ShareThis API (STAPI) is for advanced use when you plan to:

  • Share something more than just a web page (e.g. image, video, etc.).
  • Change the default object properties.
  • Share multiple objects on a single web page.

If you do not need these advanced capabilities, we suggest you use the standard website customizing tool.

Installation

  • Get the ShareThis widget javascript code from the customizing tool.
  • Place this javascript code between the <head> and </head> tags within your site.
  • This script creates the ShareThis object and the API functions are contained within this object so there is no need to worry about namespace collisions.

Creating a Share Object

  • Create a ShareThis object by calling the SHARETHIS.addEntry(propertyList,flags) function.
  • The first argument is a javascript property list containing the attributes of the object you are sharing. This is the information that will be sent to people on a share event (see Object Properties for a complete list user assignable properties).
  • The second argument is a javascript property list that contains control directives for the API. Currently, the only supported property is showButton which instructs the script to (or not to) display the button. If no flags are passed, showButton will default to true.
  • Modify the code below and put it where you want the ShareThis button to display.
			
				<script language="javascript" type="text/javascript">
					SHARETHIS.addEntry({
						title:'Share me',
						summary:'Sharing is good for the soul.',
						icon: 'http://path.to/icon'
					}, {button:true} );
				</script>

Note: You can have as many script blocks as you have things to share. This is great for a blog archive page or hit lists.

Object Properties

Shared objects closely follow the structure of the Entry element as specified by the hAtom microformat (see http://microformats.org/wiki/hatom for more information). Shared objects, like feeds, are often viewed without the context of a web page, so be descriptive.

Since we don't know the encoding of your web page, we have to ask that all strings be encoded in utf-8. Here is a script to make your strings utf-8 safe (http://ecmanaut.blogspot.com/2006/07/encoding-decoding-utf8-in-javascript.html).

Below is the supported list of user assignable properties for a shared object.

  • title: (required) utf-8 string, defaults to document.title
  • url: (optional) fully qualified URL, defaults to document.URL
  • summary: (optional) utf-8 string, defaults to null
  • content: (optional) utf-8 string, defaults to null
  • icon: (optional) fully qualified URL, defaults to Alexa thumbnail of url
  • updated: (optional) ISO 8601 date, defaults to document.lastModified
  • published: (optional) ISO 8601 date, defaults to null
  • author: currently not implemented
  • category: currently not implemented

Note: The content attribute is embedded in share messages where possible (i.e. email, web page). If you use this attribute make sure it is embeddable.

JavaScript Elements

JavaScript array elements are used to provide greater control of the behavior of the button and/or widget. The elements must placed in brackets immediately after the object definition (see "button:" example in the sample code above).

The following are the available ShareThis JavaScript elements:

  • button: create a customized ShareThis button and/or label for any object or page to be shared
  • popup: launches the widget in a new window rather than an iFrame
  • embeds: allows embedded elements to be seen while iFrame is loading
  • onclick: allows for execution of a custom function when button is clicked
  • offsetTop: changes the vertical positioning of the ShareThis widget in relation to the button link
  • offsetLeft: changes the horizontal positiong of the ShareThis widget in relation to the button link

Developers