# Share widget

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

- The page does not contain useful content (e.g., splash pages)
- The page does not have a unique URL. Sharing the page would send people to a different page if users clicked on the shared link.
- Automatically on every page.

## Working example

- English working examples
- French working examples

## 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 or `window[ "wb-share" ]` 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 or `window[ "wb-share" ]` 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 or `window[ "wb-share" ]` 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 or `window[ "wb-share" ]`. | `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 or `window[ "wb-share" ]`. | `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 or `window[ "wb-share" ]`. | 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 or `window[ "wb-share" ]`. | 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 or `window[ "wb-share" ]`. | 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 or `window[ "wb-share" ]`. | 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 or `window[ "wb-share" ]`. Use the following JavaScript code instead to configure all instances of the plugin: `window[ "wb-share" ] = {"filter": ["site-1", "site-2", ... "site-n"]};`. The following filtering options are available by default: bitly blogger delicious digg diigo email (v4.0.15+) facebook gmail googleplus linkedin myspace pinterest reddit stumbleupon tumblr twitter yahoomail | None (default): Sites are not filtered by default.
1. `sites` | Add one or more sites to the panel. | Add the following to the `data-wb-share` attribute or `window[ "wb-share" ]`:
       "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"
       		}
       	}
       };
3. Create a 32 pixel by 32 pixel image for each site. 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:
  2015-05-27