Share widget

Looking for WET v3.1?

As of September 23, 2014, version 3.1 of the Web Experience Toolkit is no longer supported. The source code and documentation have been moved to the wet-boew-legacy repository.

Questions or comments?

Purpose

Having a share widget on your site enables users to quickly share content with their networks, hence increasing the reach of your website. This increase in reach comes at very minimal cost as all it requires is the inclusion of a share widget somewhere on your page.

Use when

Use on specific content that you want users to share or that users would find useful to share with others via their social media outlets. Use the filtered version if you want to target certain platforms, for example, if your research indicates that your target audience tends to use one or a few platforms over others.

Rather than automatically including the share button on every page of your site, think about users and when and where they may want to take a call to action to digg, share, tweet or follow. A well designed site will facilitate a 'frictionless' experience for the user where they would otherwise have to copy and paste.

Do not use when

Working example

How to implement

  1. Add <div class="wb-share"></div> to the Web page.
  2. Add a unique id for the share panel. 
    <div class="wb-share" data-wb-share='{"pnlId": "pnl1"}'></div>
  3. Optional: Override the default settings using the configuration options.
  4. Optional: Add additional links using the link-only class. 
    <div class="wb-share link-only" data-wb-share='{"pnlId": "pnl1"}'></div>

Configuration options

Option Description How to configure Values
pnlId Unique identifier for the panel. Only required if providing a second link for the same panel (needs to be specified on all wb-share calls for that panel). Add "pnlId": "uniqueId" to the data-wb-share attribute where uniqueId is a valid unique id.
uniqueId:
Valid unique id (e.g., pnl1)
hdLvl Heading level for the share panel. Add "hdLvl": "headingLevel" to the data-wb-share attribute where headingLevel is the heading level. Use the following JavaScript code instead to configure all instances of the plugin: window[ "wb-share" ] = {"hdLvl": "headingLevel"};.
h2 (default):
Heading level 2
h3:
Heading level 3
h4:
Heading level 4
h5:
Heading level 5
h6:
Heading level 6
lnkClass Classes to be applied to the class attribute of the generated link. Add "lnkClass": "class1 class2" to the data-wb-share attribute where class1 class2 are the classes to be added separated by spaces. Use the following JavaScript code instead to configure all instances of the plugin: window[ "wb-share" ] = {"hdLvl": "lnkClass": "class1 class2"};.
  • None (default)
type Type of content to share. Add "type": "value" to the data-wb-share attribute.
page (default):
Shares the current page
video:
Shares the specified video
audio:
Shares the specified audio file
custType Text to use after "Share" on the share button and the panel header (overrides the text associated to the type option). Add "custType": "string" to the data-wb-share attribute.
this page or this video (default):
Default text used for the page and video share types.
title Text to use instead of the page title or the main h1 text. Recommended for the video type if the page title is not the title of the video. Add "title": "Page title" to the data-wb-share attribute.
Page title or the main h1 text (default):
The title of the current page is shared by default.
url URL to use instead of the URL of the current page. Add "url": "newURL" to the data-wb-share attribute.
Page URL (default):
The URL of the current page is shared by default.
desc Optional description of the item to share. Note: A separate description is not supported by all social media sites. Add "desc": "description" to the data-wb-share attribute.
None (default):
A separate description is not shared by default.
img Optional image for the item to share (mainly for Pinterest). Note: Very few social media sites support specifying a separate image through a URL request. Add "img": "imageURL" to the data-wb-share attribute.
None (default):
A separate image is not shared by default.
filter Optional filter for the sites to display in the panel. Only the sites listed in the array will be displayed. If no sites are listed, then all sites will be displayed. Add "filter": ["site-1", "site-2", ... "site-n"] to the data-wb-share attribute. Use the following JavaScript code instead to configure all instances of the plugin: window[ "wb-share" ] = {"filter": ["site-1", "site-2", ... "site-n"]};.
None (default):
Sites are not filtered by default.
sites Add one or more sites to the panel.

  1. Add the following to the data-wb-share attribute:

    "sites": {
	"siteId1": {
		"name": "siteName1",
		"url": "siteUrl1"
	},
	"siteId2": {
		"name": "siteName2",
		"url": "siteUrl2"
	}
}

    For example "siteId1" could be "yahoomail", "name1" could be "Yahoo! Mail" and "url1" could be "http://compose.mail.yahoo.com/?to=&subject={t}&body={u}%0A{d}" where "{u}" is the page URL, "{t}" is the page title, {i} is the image URL, and '{d}' is the description.

    Use the following JavaScript code instead to configure all instances of the plugin:

    window[ "wb-share" ] = {
	"sites": {
		"siteId1": {
			"name": "siteName1",
			"url": "siteUrl1"
		},
		"siteId2": {
			"name": "siteName2",
			"url": "siteUrl2"
		}
	}
};
  2. Create a 32 pixel by 32 pixel image for each site.
  3. Add the following CSS: 
    .wb-share .siteId1:before {
	background: url("../assets/site1.png") no-repeat;
}
.wb-share .siteId2:before {
	background: url("../assets/site2.png") no-repeat;
}
None (default):
Sites are not added this way by default.

Events

Event Trigger What it does
wb-init.wb-share Triggered manually (e.g., $( ".wb-share" ).trigger( "wb-init.wb-share" );). Used to manually initialize the share widget. Note: The share widget will be initialized automatically unless it is added after the page has already loaded.
wb-ready.wb-share (v4.0.5+) Triggered automatically after the Share plugin initializes. Used to identify where the Share plugin was initialized (target of the event). 
$( document ).on( "wb-ready.wb-share", ".wb-share", function( event ) {
});
$( ".wb-share" ).on( "wb-ready.wb-share", function( event ) {
});
wb-ready.wb (v4.0.5+) Triggered automatically when WET has finished loading and executing. Used to identify when all WET plugins and polyfills have finished loading and executing. 
$( document ).on( "wb-ready.wb", function( event ) {
});

Source code

Share widget source code on GitHub

Date modified: