sociare v0.3.1

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:

Configuration Parameters

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:

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

Pinterest Extras

LinkedIn Extras

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.