Sociare

Super simple customizable share buttons with counts.

Installation

Sociare can be installed with npm

$ npm install --save sociare

or with Bower

$ bower install -S sociare

or you can download it directly.

Prerequisites

Sociare comes bundled with only 1 dependency, Babel runtime, which enables key ES6 features that Sociare uses. Once browser support reaches a point where this runtime is no longer needed, it will be removed from the package.

Browser support

• Google Chrome (at least latest 2)
• Safari (at least latest 2)
• Firefox (at least latest 2)
• Edge 12+
• Internet Explorer 9+

Usage Example

var sociare = new Sociare(document.getElementById('share-container'), {
    countUrl: 'http://mysite.com/share-counts',
    buttonClass="btn btn-{network}",
    buttonTemplate: "Share on {network} <span class="count">{count}</span>",
    buttons: [
        'twitter',
        'facebook',
        {
            type: 'pinterest',
            template: 'Pin it! <span class="count">{count}</span>'
        }
    ]
});
 
sociare.render();

API Reference

New instances of Sociare require a DOM element, within which the buttons will be rendered.

var sociare = new Sociare(elem, [config]);

Configuration can be passed in the constructor (like shown above), but also be defined globally, at window.SociareConfig. Configuration inheritance is Global Config > Default Config > Button-Specific Config (See config.options below).

Once an instance has been configured, simply call .render() on it to have it fetch counts (if specified) and render the buttons.

sociare.render();

String Tokens

In any of the button configuration options (both default and button-specific), there are special tokens you can include that will get interpolated when the buttons are rendered. These tokens are:

Name	Description
{network}	Name of the network (facebook, twitter, pinterest, etc)
{count}	# of times URL has been shared on that network

Configuration Parameters

Name	Type	Default	Description
url	String	window.location.href	The URL to share
getCounts	Boolean	true	Indicates whether Sociare should request counts for config.url
countUrl	String		URL to request counts from. Required if config.getCounts is true. See Handling Count Requests for information on what Sociare will expect to be returned
noQueryCount	Boolean	false	If true, adds query string to config.countUrl to indicate that query strings on config.url should be ignored when retrieving counts
buttonTag	String	"a"	Default button tagName
buttonId	String	""	Default button id. If specified here, should use {network} to keep ids unique
buttonClass	String	"sociare sociare-{network}"	Default button classes
buttonAttrs	Object	{}	Additional attributes on button elements. Keys map to attribute names, values to attribute values
buttonTemplate	String	"Share on {network} - {count}"	Default button template
buttonPreHook	Function	undefined	Function to call immediately before opening popup. Is passed a callback, which will prevent popup from opening if called with an error, and the name of the network selected. Async functions run the risk of resulting in a blocked popup.
buttonPostHook	Function	undefined	Function to call immediately after opening popup. Is passed the name of the network selected.
buttons	Array[String/Object]	[]	Buttons to be rendered. Can be a string of the network name to use default configuration, or a button-specific configuration object. Available networks are "facebook", "twitter", "pinterest", "linkedin", and "googleplus"
twitterExtras	Object	{}	Default extra options for Twitter buttons. See Twitter Extras for full list of options.
pinterestExtras	Object	{}	Default extra options for Pinterest buttons. See Pinterest Extras for full list of options.
linkedinExtras	Object	{}	Default extra options for Twitter buttons. See LinkedIn Extras for full list of options.

Button-Specific Configuration

Instead of just passing the network name as a string, you can fine-tune any button made with Sociare by instead passing a configuration object for it in the buttons array. Option names listed below:

Name	Type	Description
url	String	URL to share
type	String	Network type. Available networks are "facebook", "twitter", "pinterest", "linkedin", and "googleplus"
tag	String	Button element tagName
id	String	Button element ID
class	String	Button element classes
attrs	Object	Additional attributes on button element. Keys map to attribute names, values to attribute values
template	String	String template for innerHTML of button element
preHook	Function	Function to call immediately before opening popup. Is passed a callback, which will prevent popup from opening if called with an error. Async functions run the risk of resulting in a blocked popup.
postHook	Function	Function to call immediately after opening popup.
extras	Object	Additional network options (only available in twitter, pinterest, and linkedin types). See Extras

Extras

Some button types (twitter, pinterest, and linkedin) have additional optional configuration that will alter how the URL is shared. See sections below for each networks available extra configuration. All extra values

Twitter Extras

Name	Description
text	Pre-filled tweet text. Users will still have the option to change this before sharing
via	A Twitter username to associate tweet. Will append "via @{username}" to end of tweet.
hashtags	Comma delimited list of hashtags to append to the tweet. Do not include the "#" character

Pinterest Extras

Name	Description
media	URL of image to use when pinned to users boards
description	Caption to be used on pin

LinkedIn Extras

Name	Description
title	Title that will appear on share card
description	Description to appear on share card
source	Source of the content (such as your websites name)

Handling Count Requests

Sociare requires a url to be provided if you would like to use share counts on the buttons it generates. The data returned from this URL should be JSON formatted as network_name: count, for example:

{
    "facebook": 250,
    "twitter": 125
}

When Sociare makes this request, it applies the following query parameters to the URL to assist in determining exactly what data is needed:

• url - URL for which counts should be collected
• networks - Which networks Sociare requires counts from
• omitQuery - Whether query strings on the url should be included when fetching counts

Getting these counts is a real pain, so to make this easier, we've set up a simple NodeJS utility you can use to fetch these counts and output this data.

Contributing

Pull requests for bug-fixes and additions of other services are always welcome! Please be sure to include any tests for new code & follow the current coding style as best you can.

You can run the test suite with the following command:

$ npm test

License

Sociare is distributed under the MIT license.