highlight-share

highlight-share
==========

Medium-like text selection sharing without dependencies


> Demo from the HubSpot blog

Purpose

This lightweight library allows to create a simple interface to share selected text in a page, in the form of a small popover over the selected portion of text.

Features:

* customizable sharing channels ("sharers")
* restriction on selected elements
* customizable CSS classes and stylesheets
* hooks on opening and closing the popover, and on sharing action

All in a tiny library (less than 1.8 KB minified and gzipped, plus less than 0.5 KB for the optional provided style sheet and 0.5-1.3 KB for the sample sharers).

Installation

Via npm:

``bash
$ npm install --save highlight-share
`

Usage

After installing, import the library using the module loader of your choice:

`javascript
// CommonJS
const highlightShare = require('highlight-share');

// ES6
import highlightShare from 'highlight-share';

// AMD
define([ 'highlight-share' ], highlightShare => {
// ...
});

// Global
var highlightShare = window.highlightShare;
`

Import any sharers you need:

`javascript
import * as twitterSharer from 'highlight-share/dist/sharers/twitter';
import * as facebookSharer from 'highlight-share/dist/sharers/facebook';
import * as emailSharer from 'highlight-share/dist/sharers/email';
import * as copySharer from 'highlight-share/dist/sharers/copy';
import * as linkedInSharer from 'highlight-share/dist/sharers/linked-in';
import * as facebookMessengerSharer from 'highlight-share/dist/sharers/facebook-messenger';
`

Note that Facebook Messenger also requires a Facebook app ID, for example the abc123 string here:

`javascript
const messengerShare = new facebookMessengerSharer.FacebookMessenger('abc123');
`

Create a variable specifying a DOM element selector and an array of your sharers:

`javascript
const selectionShare = highlightShare({
selector: '#shareable',
sharers: [twitterSharer, facebookSharer, emailSharer, linkedInSharer, messengerShare, copySharer]
});

selectionShare.init();
`

Note: If the sharers array is empty, nothing will happen.

Options

The options for the highlightShare factory include:

* document: the Document object to apply the sharing functionality (default: document);
* popoverClass: the class name (or names) to be used in the root element of the popover (default: highlight-share-popover);
* selector: restricts the shared text to the contents of the elements matching selector (default: "body");
* sharers: an array of sharing channels (Twitter, Facebook, email...); see later for details;
* shareUrl: a reference URL for the shared text (default: the location object of the document property);
* transformer: a function that transforms the extracted selected text (default: a function that trims and collapses whitespaces);
* onOpen: a function that gets called when the sharing popover is opened. The popover's element, the transformed selected text and its original version are passed as arguments;
* onClose: a function that gets called when the sharing popover is closed.

When you're done sharing text, you can call the destroy method;

`javascript
selectionShare.destroy();
`

A destroyed sharing object can not be initialized again.

What is a sharer?

A "sharer" is an object with just one mandatory method: render, that must return the HTML string of the sharing button;
and a name property.

Note that Facebook Messenger also requires a Facebook app ID, for example the abc123 string here:

`javascript
const messengerShare = new facebookMessengerSharer.FacebookMessenger('abc123');
`

$3

$3

This function receives these arguments:

* text: the text that should be shared;
* rawText: the original selected text content (i.e., not mangled by the transformer);
* shareUrl: the reference URL to be shared (see the options).

It must return the HTML of the button/link/element that should provide the required sharing functionality.

$3

A unique string (among the sharers) that identifies the sharer (e.g.: "twitter", "facebook", ...).

$3

This property could actually be a function (with the above signature) or a boolean, stating if the sharer is enabled (true) or not.
If it's a function, it should return a truthy or falsy value, with the same meaning.

$3

A function to be called when the user clicks/taps on the sharing button. The event's default is not prevented. item is the