sociare

Super simple customizable share buttons with counts.

Usage no npm install needed!

<script type="module">
  import sociare from 'https://cdn.skypack.dev/sociare';
</script>

README

Sociare Build Status Coverage Status

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.