Social Share Privacy ==================== Social Share Privacy is a jQuery plugin that lets you add social share buttons to your website that don't allow the social sites to track your users. The buttons are first disabled and a user needs to click them to enable them. So in order to e.g. like a site on facebook with these social share buttons a user needs to click two times. But in return for this extra click a user can only be tracked be this third party sites when he decides to enable the buttons. Using the settings menu a user can also permanently enable a social share button. Supported share services: * [Buffer](#buffer-options-buffer) * [Delicious](#delicious-options-delicious) * [Disqus](#disqus-options-disqus) * [EMail](#email-options-mail) * [Facebook](#facebook-options-facebook) * [Flattr](#flattr-options-flattr) * [Google+](#google-options-gplus) * [Hacker News](#hacker-news-options-hackernews) * [Linked in](#linked-in-options-linkedin) * [Pinterest](#pinterest-options-pinterest) * [reddit](#reddit-options-reddit) * [Stumble Upon](#stumble-upon-options-stumbleupon) * [Tumblr](#tumblr-options-tumblr) * [Twitter](#twitter-options-twitter) * [XING](#xing-options-xing) Note that Tumblr and email are just normal links and thus always enabled. This is a fork of socialSharePrivacy by Heise. In this fork the service support was made extensible, some services where added and some bugs fixed. It has some incompatible changes, though (consolidated option names, use of the boolean values `true` and `false` instead of the strings `"on"` and `"off"` etc.). The original can be found here: [http://www.heise.de/extras/socialshareprivacy/](http://www.heise.de/extras/socialshareprivacy/) The Delicious support was heavily inspired by the delicious button jQuery plugin: [http://code.google.com/p/delicious-button/](http://code.google.com/p/delicious-button/) The style for this button was atually copied and only slightly adapted from this plugin. Overview -------- * [Dependencies](#dependencies) * [How to use](#how-to-use) * [Methods](#methods) * [Events](#events) * [Options](#options) * [Global Options](#global-options) * [Common Service Options](#common-service-options) * [Custom Services](#custom-services) * [Helper Functions](#helper-functions-jqueryfnsocialshareprivacy) * [Pack.sh](#packsh) * [Known Issues](#known-issues) * [License](#license) Dependencies ------------------------------------------- * [jQuery](http://jquery.com/) * [jQuery cookies plugin](https://github.com/panzi/jQuery-Cookies) (optional) * [uglifyjs](https://npmjs.org/package/uglify-js) (optional) * [uglifycss](https://npmjs.org/package/uglifycss) (optional) The jQuery cookies plugin is needed in order to enable services permanently. However, you can plug in you own replacement to store this options differently (e.g. via ajax in the user profile or in the browsers local store). For an example that stores the perma options in HTML5 local storage instead of cookies see the file [jquery.socialshareprivacy.localstorage.js](https://github.com/panzi/SocialSharePrivacy/blob/master/scripts/jquery.socialshareprivacy.localstorage.js). How to use ---------------------------------------- ```html
… … … … ``` You only need to include the JavaScript files of the services you want to use. I recommend to pack all needed files into one using a JavaScript packer/compressor. The included [pack.sh](#packsh) script can do that for you, if you've got [uglifyjs](https://npmjs.org/package/uglify-js) and [uglifycss](https://npmjs.org/package/uglifycss) installed. However, for your convenience I provide these precompiled versions of the scripts: * [jquery.socialshareprivacy.min.js](http://panzi.github.com/SocialSharePrivacy/javascripts/jquery.socialshareprivacy.min.js) 1 * [jquery.socialshareprivacy.min.autoload.js](http://panzi.github.com/SocialSharePrivacy/javascripts/jquery.socialshareprivacy.min.autoload.js) 2 * [jquery.socialshareprivacy.min.de.js](http://panzi.github.com/SocialSharePrivacy/javascripts/jquery.socialshareprivacy.min.de.js) 3 * [jquery.socialshareprivacy.min.fr.js](http://panzi.github.com/SocialSharePrivacy/javascripts/jquery.socialshareprivacy.min.fr.js) 3 * [jquery.socialshareprivacy.min.nl.js](http://panzi.github.com/SocialSharePrivacy/javascripts/jquery.socialshareprivacy.min.nl.js) 3 * [jquery.socialshareprivacy.min.ru.js](http://panzi.github.com/SocialSharePrivacy/javascripts/jquery.socialshareprivacy.min.ru.js) 3 * [jquery.socialshareprivacy.min.css](http://panzi.github.com/SocialSharePrivacy/stylesheets/jquery.socialshareprivacy.min.css) 1 This file contains all JavaScripts except the `jquery.socialshareprivacy.localstorage.js` module and the translations. 2 This file contains the same as 1, but it also automatically initializes elements with the attribute `data-social-share-privacy="true"` set. 3 These files contain only translation strings and have to be included in addition to `jquery.socialshareprivacy.min.js`. You can also asynchronously load the buttons if you use the `jquery.socialshareprivacy.min.autoload.js` script: ```html … … … … … ``` Methods --------------------------------- ### socialSharePrivacy **Signature:** ```javascript .socialSharePrivacy([options]) ``` Add social share buttons to all elements in the set. Returns `this`. ### destroy **Signature:** ```javascript .socialSharePrivacy("destroy") ``` Remove all social share buttons. This will return all elements in the set back to their pre-init state. Returns `this`. ### disable **Signature:** ```javascript .socialSharePrivacy("disable", [service_name]) ``` Disable the named service or disable all services if no `service_name` is given. Returns `this`. ### enable **Signature:** ```javascript .socialSharePrivacy("enable", [service_name]) ``` Enable the named service or enable all services if no `service_name` is given. Returns `this`. ### option **Signature:** ```javascript .socialSharePrivacy("option", option_name, [value]) ``` Get or set an option. If no `value` is specified it will act as a getter. Returns `this` when acting as setter. ### options **Signature:** ```javascript .socialSharePrivacy("options", [options]) ``` Get or set all options. If no `options` are specified it will act as a getter. Returns `this` when acting as setter. ### toggle **Signature:** ```javascript .socialSharePrivacy("toggle", [service_name]) ``` Toggle the named service or toggle all services if no `service_name` is given. Returns `this`. Events ------------------------------- ### socialshareprivacy:create This event is emitted after the `socialSharePrivacy` method created a Social Share privacy widget. The event object will have an `options` attribute holding the option object of the initialized widget. ### socialshareprivacy:destroy This event is emitted before a Social Share Privacy widget is destroyed. ### socialshareprivacy:disable This event is emitted after a certain service was disabled. The event object will have a `serviceName` property, holding the name of the service that was disabled, and an `isClick` property, wich is `true` if a click by a user caused this event (`false` if it was disabled via JavaScript). ### socialshareprivacy:enable This event is emitted after a certain service was enabled. The event object will have a `serviceName` property, holding the name of the service that was enabled, and an `isClick` property, wich is `true` if a click by a user caused this event (`false` if it was enabled via JavaScript). Options --------------------------------- Options can be set globally via `$.fn.socialSharePrivacy.settings`, via an options object passed to the `socialSharePrivacy` function or via `data-*` attributes of the share element. If options are defined in more than one way the `data-*` attributes will overwrite the options from the passed options object and the options from passed options object will overwrite the globally defined options. ### `data-*` attributes In order to pass the options as `data-*` attributes simply prepend `data-` to all option names. For the language option you can also use the standard `lang` attribute. If you want to set an option of an service just use a `data-*` attribute that includes dots (`.`) as if it where a JavaScript property expression: ```html ``` If you want you can combine all options of a service and pass a JSON string as attribute value: ```html ``` You can also do this for all services: ```html ``` Or even all options at once: ```html ``` Actually these aren't JSON objects but JavaScript expressions. This way you can pass JavaScript code that will evaluate the option values when the `socialSharePrivacy` function is called. You can even pass a whole new service implementation inline, if you want: ```html ``` The main advantage of using the `data-*` attributes is, that you can easily render several *different* share elements on your webserver and then initialize them with one single JavaScript function call (no need for uniqe element IDs and separate JavaScript calls for each element). **NOTE:** When passing service options via `data-*` attributes all option values (except the common service options) are treated as strings. If you need to pass values of other types (numbers, booleans, arrays or functions) you need to use the JavaScript object syntax. ### Global Options Set these options like this: ```javascript $.fn.socialSharePrivacy.settings.title = "Title of the thing to share."; … ``` Or like this: ```html ``` The version using `script` tags uses again JavaScript expressions to enable inline service definitions.Option | Default Value | Description |
---|---|---|
info_link | http://panzi.github.com/SocialSharePrivacy/ | The link of the i-icon that links users to more information about this. |
info_link_target | The target attribute of the info link. Possible values are _blank ,
_self , _parent , _top or a frame name. |
|
txt_settings | Settings | The text of the settings icon. |
txt_help | [Text] | Tooltip text of the settings menu. |
settings_perma | [Text] | Headline of the settings menu. |
layout | line | Possible values: line or box |
set_perma_option | function (service_name, settings) | Function that stores the perma setting of the service specified by service_name. |
del_perma_option | function (service_name, settings) | Function that removes the perma setting of the service specified by service_name. |
get_perma_options | function (settings) | Function that gets the perma setting of all services in an object where the keys are the service names and the values are boolean. Services that are missing are assumed as false. |
get_perma_option | function (service_name, settings) | Function that gets the perma setting of the service specified by service_name.
Returns a boolean value. Only one of the two functions get_perma_options and get_perma_option need to be implemented. In that case the respective other needs to be set to null. |
perma_option | true (if the jQuery cookies plugin is installed) | Give users the posibility to permanently enable services. (Boolean) |
cookie_path | / | |
cookie_domain | document.location.hostname |
|
cookie_expires | 365 | Days until the cookie expires. |
path_prefix | Prefix to all paths (css_path, dummy_line_img, dummy_box_img) | |
css_path | socialshareprivacy/socialshareprivacy.css | |
language | en | |
uri | [Function] | URI of the thing to share that is passed on to the share services. The default function
uses the value of the first link element with the rel attribute
canonical or the first meta element with the property
attribute og:url it can find or location.href if there are no such
elements. (Function or string) |
title | The title to pass to any share service that want's one. | |
description | The description to pass to any share service that want's one. | |
image | Image URL to pass to any share service that want's one. | |
embed | HTML embed code to pass to any share service that want's one. | |
ignore_fragment | true | Ignore the #fragment part of the url. (Boolean) |
Option | Default Value | Description |
---|---|---|
status | true | Enable/disable this service. (Boolean) |
class_name | [service specific] | The HTML class of the share button wrapper. Per default it is the key of the
service as it is registered in jQuery.fn.socialSharePrivacy.settings.services . |
button_class | HTML class of the share button. Per default the same as class_name. | |
dummy_line_img | Placeholder image for deactivated button in line layout. |
|
dummy_box_img | Placeholder image for deactivated button in box layout. |
|
dummy_alt | [Text] | Alt text of the placeholder image. |
txt_info | [Text] | Help text for deactivated button. |
txt_off | [Text] | Status text if button is deactivated. |
txt_on | [Text] | Status text if button is activated. |
perma_option | true | Give users the posibility to permanently enable this service. (Boolean) |
display_name | [Text] | Name of the service. |
referrer_track | A string that is appended to the URI for this service, so you can track from where your users are coming. | |
language | Override the global language just for this service. | |
path_prefix | Override the global path_prefix just for this service. |
Option | Default Value | Description |
---|---|---|
text | jQuery.fn.socialSharePrivacy.getTitle | Tweet text (excluding the URL). It will be truncated to 120 characters, leaving place for 20 characters for the shortened URL. (Function or string) |
via | Twitter username (without the leading @ ). (Function or string) |
|
picture | jQuery.fn.socialSharePrivacy.getImage | URL of image that represents the thing to share. (Function or string) |
Option | Default Value | Description |
---|---|---|
title | jQuery.fn.socialSharePrivacy.getTitle | Title of the new bookmark. (Function or string) |
Option | Default Value | Description |
---|---|---|
shortname | Your Disqus forum shortname. If an empty string is given it tries to use
window.disqus_shortname . (String) |
|
count | comments | What count to show. Possible values: comments or reactions |
onclick | Function to call when the Disqus button was clicked. (Function or String) |
Option | Default Value | Description |
---|---|---|
subject | jQuery.fn.socialSharePrivacy.getTitle | Subject of the new email. (Function or string) |
body | [Function] | Body of the new email. (Function or string) |
Option | Default Value | Description |
---|---|---|
action | like | Possible values: like or recommend |
colorscheme | light | Possible values: light or dark |
font | Possible values: arial , lucida grande , segoe ui , tahoma ,
trebuchet ms or verdana |
Option | Default Value | Description |
---|---|---|
title | jQuery.fn.socialSharePrivacy.getTitle | Title of the thing to share. (Function or string) |
description | jQuery.fn.socialSharePrivacy.getDescription | Description of the thing to share. (Function or string) |
uid | Flattr username. | |
category | Possible values: Text , Images , Video , Software , People or
Other |
|
tags | Multiple tags are seperated by a comma , . Only alpha characters are supported in tags. |
|
popout | When set to 0 no popout will appear when the Flattr button is hovered. |
|
hidden | When set to 1 your content will not be publicly listed on Flattr. |
Option | Default Value | Description |
---|---|---|
title | jQuery.fn.socialSharePrivacy.getTitle | Title of the news to share. (Function or string) |
Option | Default Value | Description |
---|---|---|
title | jQuery.fn.socialSharePrivacy.getTitle | Title of the thing to share. (Function or string) |
description | jQuery.fn.socialSharePrivacy.getDescription | Description of the thing to share. (Function or string) |
media | jQuery.fn.socialSharePrivacy.getImage | URL of image that represents the thing to share. (Function or string) |
Option | Default Value | Description |
---|---|---|
onsuccess | Name of a callback function that shall invoked when the link was successfully shared. The shared url will be passed as a parameter. (String) | |
onerror | Name of a callback function that shall invoked if link sharing failed. The shared url will be passed as a parameter. (String) | |
showzero | false | Even show count and no placeholder if there are zero shares. (Boolean) |
Option | Default Value | Description |
---|---|---|
title | jQuery.fn.socialSharePrivacy.getTitle | Title of the thing to share. (Function or string) |
target | A cummunity to target. | |
newwindow | 1 | Opens reddit in a new window when set to 1 . Set this option to an empty string or
anything that evaluates to false to open reddit in the same window. |
bgcolor | transparent | HTML color. |
bordercolor | HTML color. |
Option | Default Value | Description |
---|---|---|
type | link | Possible values: link , quote , photo or video |
name | jQuery.fn.socialSharePrivacy.getTitle | Title of the thing to share. (Function or string) This option is only defined for the type link . |
description | jQuery.fn.socialSharePrivacy.getDescription | Description of the thing to share. (Function or string) This option is only defined for the type link . |
quote | [Function] | Quote to share. (Function or string) This option is only defined for the type quote . |
photo | jQuery.fn.socialSharePrivacy.getImage | Image URL of the thing to share. (Function or string) This option is only defined for the type photo . |
clickthrou | [Function] | The URL to where you get when you click the image. Per default it's the
shared URI including the referrer_track. (Function or string) This option is only defined for the type photo . |
embed | jQuery.fn.socialSharePrivacy.getEmbed | Embed code of the thing to share. (Function or string) This option is only defined for the type video . |
caption | jQuery.fn.socialSharePrivacy.getDescription | Caption of the thing to share. (Function or string) This option is only defined for the types photo and video . |
Option | Default Value | Description |
---|---|---|
text | jQuery.fn.socialSharePrivacy.getTitle | Tweet text (excluding the URL). It will be truncated to 120 characters, leaving place for 20 characters for the shortened URL. (Function or string) |
via | Twitter username (without the leading @ ). |
|
related | Twitter username (without the leading @ ). |
|
hashtags | Hashtag to add to the tweet (without the leading # ). |
|
dnt | true | Do not tailor. |
Character | Replacement |
---|---|
< |
< |
> |
> |
& |
& |
" |
" |
' |
' |