easySocial

Making Social Sharing super-easy with one simple function call.

What's that?

Simple - this is a tiny JavaScript library (if we call it that), consisting of just one function - easySocial. It does not do anything fancy, it just gets you back the HTML code for the buttons with the URLs properly set. It is your choice how to style those and how to insert them into your page. There are no dependencies (jQuery or similar libraries are not used at all) and no CSS and custom styles to apply.

Why?

I needed something very simple for my website to add social buttons, but I did not need the "extras" most libraries seemed to come with: CSS styles, images, animations, inserting buttons into page, etc. Basically I might just want a simple list of links sometimes. This is why.

How?

The usage is pretty straigthforward.

• Add it:

  <script src="/easySocial.min.js"></script>

• Call it:

  var buttons = easySocial({
    url:          "http://mysite.url/",
    caption:      "Share this on",
    title:        "Check this site!",
    description:  "This is my site description",
    buttons:      [ "facebook", "twitter", "linkedin", "vk", "email", "whatsapp", "telegram" ],
  });
  

• Use it:

  $('.share').html(buttons); // It doesn't have to be jQuery.

Supported social sites or other sharing methods

Tag	Official resource name	Type
digg	Digg	Link to website
email	Email	Mailto protocol link
facebook	Facebook	Link to website
googleplus	Google+	Link to website
hackernews	HackerNews	Link to website
linkedin	LinkedIn	Link to website
reddit	Reddit	Link to website
stumbleupon	StumbleUpon	Link to website
telegram	Telegram	Telegram protocol link
twitter	Twitter	Link to website
vk	VK	Link to website
whatsapp	WhatsApp	WhatsApp protocol link

Parameters

Name	Type	Meaning	Has default value
url	Str	Your site url	N
title	Str	Your site title	N
description	Str	Your site description	N
caption	Str	Prepended to "Official resource name" to use in template	Y
tpl	Str	Template for each button element	Y
wrap	Str	Template for all buttons or group of buttons	N
after	Int	How many buttons are considered a group	N
buttons	Array	Which social buttons to use	N
icons	Object	Allows overriding %icon% substitutions with custom values	N

Templates

Button template

HTML for each button is produced based on a template. By default the template value is:

<a href="%url%" title="%caption%" target="_blank">%social-name%</a>

You can use the following substitutions in the button template:

Code	Meaning
%url%	Resulting URL for sharing
%social%	Social tag ('facebook, 'twitter', 'linkedin', etc)
%social-name%	Official resource name ('Facebook', 'Twitter', 'LinkedIn', etc)
%icon%	Font Awesome icon name for the resource ('twitter', 'hacker-news', 'google-plus', etc)
%caption%	String that combines the value of a caption parameter and the social name

You can provide a different template using the tpl parameter.

Wrapping template

You can optionally wrap HTML code of each or all buttons (or even groups of buttons) into some other code, which you can define in wrap parameter. The only substitution that is accepted there is %content%. You choose how many elements at once should be wrapped by using the after parameter:

Value for after parameter	Meaning
Not set or set to 0	All produced buttons are wrapped as one element
Set to 1	Each produced button is wrapped
Set to any other value	That many buttons are wrapped as one element

This can be handy if you are setting your bittons in rows for example.

Template usage examples

Say you want to just create sharing links as a elements and you want every 2 buttons to be set in a row:

var buttons = easySocial({
  tpl:          '<a href="%url%">%social-name%</a>',
  wrap:         '<div class="row">%content%</div>',
  after:        2,
  ...
  buttons:      [ "facebook", "twitter", "linkedin", "email" ],
});

This will produce a code like this (actual URLs are not given):

<div class="row"><a href="...">Facebook</a><a href="...">Twitter</a></div>
<div class="row"><a href="...">LinkedIn</a><a href="...">Email</a></div>

If you change the after to 1, then HTML will be:

<div class="row"><a href="...">Facebook</a></div>
<div class="row"><a href="...">Twitter</a></div>
<div class="row"><a href="...">LinkedIn</a></div>
<div class="row"><a href="...">Email</a></div>

And finally if you change after to 0 or remove it (while keeping the wrap parameter), then HTML will be:

<div class="row">
<a href="...">Facebook</a>
<a href="...">Twitter</a>
<a href="...">LinkedIn</a>
<a href="...">Email</a>
</div>

Icons

The %icon% substitution is useful if you want to add not only the name of the social sharing resource, but also an appropriate icon. By default is is set to be used with Font Awesome icons. For example, if you are normally displaying icons with a code similar to:

<i class="icon fa-twitter"></i>

Then you could use something like below in your button template:

<i class="icon fa-%icon%"></i>

As a result, appropriate icon will be displayed. You can override the substitutions for all or some icons, by using the icon parameter like below:

var buttons = easySocial({
  icons:        { facebook: 'myfbicon' },
  ...
  buttons:      [ "facebook", "twitter", "linkedin", "email" ],
});

Then, instead of getting <i class="icon fa-facebook"></i> code, you will be getting <i class="icon fa-myfbicon"></i>.

This is basically it.