Odo Share

Share links to social media.

Support

Dependencies

Supported Services

GoTo

The Basics

Quickstart

The very basics to get the OdoShare component up and running.

  • Share the current page with Twitter when the user clicks the button:

    <a href="#" class="odo-share" data-service="twitter">Share on Twitter</a>

    Demo: Share on Twitter

  • Share the current page with Twitter with a default text of I shared the thing! when the user clicks the button:

    <a href="#" class="odo-share" data-service="twitter" data-text="I shared the thing!">Share on Twitter</a>

    Demo: Share on Twitter

  • Share http://odopod.com/ with Facebook when the user clicks the button:

    <a href="#" class="odo-share" data-service="facebook" data-url="http://odopod.com/">Share on Facebook</a>

    Demo: Share on Facebook

  • Immediately invoke a twitter share for the current page. No element necessary, as this is done via javascript:

    OdoShare.share({
  service: 'twitter'
});

Advanced

Dynamic Data

The sharing data is determined on every share, not on page load. So you can continuously change the data being shared from the same OdoShare instance at any time without issue.

Demo: Share it! 
<input id="example-1-url" type="text" placeholder="http://odopod.com/" value="http://odopod.com/"/>

<select id="example-1-service">
  <option value="facebook">Facebook</option>
  <option value="twitter">Twitter</option>
  <option value="googleplus">Google Plus</option>
  <option value="linkedin">LinkedIn</option>
</select>

<a href="#" id="example-1-share">Share it!</a>

const share = document.getElementById('example-1-share');
const urlField = document.getElementById('example-1-url');
const serviceField = document.getElementById('example-1-service');

share.addEventListener('click', (evt) => {
  evt.preventDefault();

  OdoShare.share({
    service: serviceField.value,
    data: {
      url: urlField.value,
    },
  });
});

Interceptors

You can intercept OdoShare from immediately opening a new share window. A practical example of this might be making an ajax request before the sharing can take place. Just return a promise.

Demo: Share after one second 
<a href="#" id="example-2-share" data-service="twitter" data-url="http://www.odopod.com">Share after one second</a>
const share = document.getElementById('example-2-share');

OdoShare.add({
  element: share,
  before(/* output */) {
    // Perform something asynchronous.
    return new Promise((resolve) => {
      setTimeout(resolve, 1000);
    });
  },
});

Data Rewriting

You can modify the data being shared by OdoShare even after the user has clicked the share button. Simply return a new data object back from the before() callback. You might need to do this if you first need to hit an API to get updated share data, but only once the user has attempted to share.

Demo: Share https://google.com! 
<a href="#" id="example-3-share" data-service="twitter" data-url="https://google.com">Share https://google.com!</a>
const share = document.getElementById('example-3-share');

OdoShare.add({
  element: share,
  before(/* output */) {
    // decodeURIComponent(output.params.url) => "http://odopod.com"

    // Rewrite the data before we perform the share.
    return {
      url: 'http://www.odopod.com',
    };
  },
  after(/* output */) {
    // decodeURIComponent(output.params.url) => "http://www.odopod.com"
  },
});

Halt Share Action

You can halt the share action even if the user has started sharing by returning false from the before option. You likely won't ever need to do this, but if you do you have that choice!

Demo: Share with Confirm 
<a href="#" id="example-4-share" data-service="twitter">Share with Confirm</a>
const share = document.getElementById('example-4-share');

OdoShare.add({
  element: share,
  before() {
    if (confirm('Are you sure you want to share this page?')) {
      // Returning null or undefined won't change the original data.
      return null;
    }

    // Halt the share process.
    return false;
  },
});

Caveats

Facebook sharing and query strings

Sharing links with Facebook that contain complex query strings is very complicated. Facebook likes to strip out any spaces (%20) and replace them with plusses (+). To avoid this we need to encode query string text twice, then decode it back on the client side.

var base = 'http://www.greetingcards.com/';
var text = 'Happy Mother\'s Day!';
var textEncoded = encodeURIComponent(text); // Happy%20Mother's%20Day!
var queryString = '?text=' + encodeURIComponent(textEncoded);
var url = base + queryString;

OdoShare.share({
  service: 'facebook',
  data: {
    url: url
  },
  before: function (output) {
    console.log(output.params.u);
    // ->  "http%3A%2F%2Fgreetingcards.com%2F%3Ftext%3DHappy%252520Mother's%252520Day!"
  }
});

The URL that is sent through OdoShare is:

http%3A%2F%2Fgreetingcards.com%2F%3Ftext%3DHappy%252520Mother's%252520Day!

When this url is opened from Facebook, the resulting URL is:

http://greetingcards.com/?text=Happy%2520Mother's%2520Day!

You must decode this url on the client side of your website via

var rewriteBase = '?text=';
var parts = window.location.href.split(rewriteBase);
if (parts.length > 1) {
  var url = parts[0] + rewriteBase + decodeURIComponent(parts[1]);

  // Use pushstate if possible
  if (Modernizr.history) {
    history.pushState({url: url}, '', url);
  } else {
    window.location.href = url;
  }
}

When decoded, this transforms correctly back into:

http://greetingcards.com/?text=Happy%20Mother's%20Day!

Services API

Facebook

data.url (string)

The URL of the page to share. Default: window.location.href

<a href="#" class="odo-share" data-service="facebook" data-url="{{ data.url }}"></a>

Example(s):

<a href="#" class="odo-share" data-service="facebook" data-url="http://odopod.com/">Share</a>
OdoShare.share({
  service: 'facebook',
  data: {
    url: 'http://odopod.com/'
  }
});

Back to facebook API

Back to Services API

Twitter

data.url (string)

The URL of the page to share. Default: window.location.href

<a href="#" class="odo-share" data-service="twitter" data-url="{{ data.url }}"></a>

Example(s):

<a href="#" class="odo-share" data-service="twitter" data-url="http://odopod.com/">Share</a>
OdoShare.share({
  service: 'twitter',
  data: {
    url: 'http://odopod.com/'
  }
});

Back to Twitter API

data.via (string)

Screen name of the user to attribute the Tweet to. The preceding @ is optional.

<a href="#" class="odo-share" data-service="twitter" data-via="{{ data.via }}"></a>

Example(s):

<a href="#" class="odo-share" data-service="twitter" data-via="@odopod">Share</a>
<a href="#" class="odo-share" data-service="twitter" data-via="odopod">Share</a>
OdoShare.share({
  service: 'twitter',
  data: {
    via: '@odopod'
  }
});

Back to Twitter API

data.text (string)

The default Tweet text.

<a href="#" class="odo-share" data-service="twitter" data-text="{{ data.text }}"></a>

Example(s):

<a href="#" class="odo-share" data-service="twitter" data-text="I shared the thing!">Share</a>
OdoShare.share({
  service: 'twitter',
  data: {
    text: 'I shared the thing!'
  }
});

Back to Twitter API

data.recommend (string or array)

Related accounts. More than one recommend account may be defined if each item is separated by a comma. The preceding @ is optional.

<a href="#" class="odo-share" data-service="twitter" data-recommend="{{ data.recommend[,...] }}"></a>

Example(s):

<a href="#" class="odo-share" data-service="twitter" data-recommend="@odopod">Share</a>
<a href="#" class="odo-share" data-service="twitter" data-recommend="@odopod,@Vestride">Share</a>
OdoShare.share({
  service: 'twitter',
  data: {
    recommend: ['@odopod', '@Vestride']
  }
});

Back to Twitter API

data.language (string)

The language for the tweet sheet. Default: "en"

<a href="#" class="odo-share" data-service="twitter" data-language="{{ data.language }}"></a>

Example(s):

<a href="#" class="odo-share" data-service="twitter" data-language="fr">Partager sur Twitter</a>
OdoShare.share({
  service: 'twitter',
  data: {
    language: 'fr'
  }
});

Back to Twitter API

data.resolvesTo (string)

URL to which your shared URL resolves. This will increase the tweet count for that page; this is especially important for pages that contain query strings or hashes. They should all resolve to the same location.

<a href="#" class="odo-share" data-service="twitter" data-resolves-to="{{ data.resolvesTo }}"></a>

Example(s):

<a href="#" class="odo-share" data-service="twitter" data-url="http://odopod.com/?foo=bar" data-resolves-to="http://odopod.com/">Share</a>
OdoShare.share({
  service: 'twitter',
  data: {
    url: 'http://odopod.com/?foo=bar',
    resolvesTo: 'http://odopod.com/'
  }
});

Back to Twitter API

data.hashtags (string or array)

Hashtags to append to the tweet text. More than one hashtag may be defined if each item is separated by a comma. The # is optional.

<a href="#" class="odo-share" data-service="twitter" data-hashtags="{{ data.hashtags[,...] }}"></a>

Example(s):

<a href="#" class="odo-share" data-service="twitter" data-hashtags="#odoshare">Share</a>
<a href="#" class="odo-share" data-service="twitter" data-hashtags="#winning,#odopod">Share</a>
OdoShare.share({
  service: 'twitter',
  data: {
    hashtags: ['#winning', '#odopod']
  }
});

Back to Twitter API

Back to Services API

Google Plus

data.url (string)

The URL of the page to share. Default: window.location.href

<a href="#" class="odo-share" data-service="googleplus" data-url="{{ data.url }}"></a>

Example(s):

<a href="#" class="odo-share" data-service="googleplus" data-url="http://odopod.com/">Share</a>
OdoShare.share({
  service: 'googleplus',
  data: {
    url: 'http://odopod.com/'
  }
});

Back to Google Plus API

Back to Services API

Tumblr

data.url (string)

The URL of the page to share. Default: window.location.href

<a href="#" class="odo-share" data-service="tumblr" data-url="{{ data.url }}"></a>

Example(s):

<a href="#" class="odo-share" data-service="tumblr" data-url="http://odopod.com/">Share</a>
OdoShare.share({
  service: 'tumblr',
  data: {
    url: 'http://odopod.com/'
  }
});

Back to Tumblr API

data.title (string)

The title of the content to share. Default: document.title

<a href="#" class="odo-share" data-service="tumblr" data-title="{{ data.title }}"></a>

Example(s):

<a href="#" class="odo-share" data-service="tumblr" data-title="Odoshare all the things!">Share</a>
OdoShare.share({
  service: 'tumblr',
  data: {
    title: 'Odoshare all the things!'
  }
});

Back to Tumblr API

Back to Services API

LinkedIn

data.url (string)

The URL of the page to share. Default: window.location.href

<a href="#" class="odo-share" data-service="linkedin" data-url="{{ data.url }}"></a>

Example(s):

<a href="#" class="odo-share" data-service="linkedin" data-url="http://odopod.com/">Share</a>
OdoShare.share({
  service: 'linkedin',
  data: {
    url: 'http://odopod.com/'
  }
});

Back to LinkedIn API

data.title (string)

The title of the content to share. Default: document.title

<a href="#" class="odo-share" data-service="linkedin" data-title="{{ data.title }}"></a>

Example(s):

<a href="#" class="odo-share" data-service="linkedin" data-title="Odoshare all the things!">Share</a>
OdoShare.share({
  service: 'linkedin',
  data: {
    title: 'Odoshare all the things!'
  }
});

Back to LinkedIn API

data.mini (boolean)

Use the mini-version of the LinkedIn share plugin*. Default: true

* I'm not actually sure what this does.

<a href="#" class="odo-share" data-service="linkedin" data-mini="{{ data.mini }}"></a>

Example(s):

<a href="#" class="odo-share" data-service="linkedin" data-mini="true">Share</a>
OdoShare.share({
  service: 'linkedin',
  data: {
    mini: true
  }
});

Back to LinkedIn API

data.ro (boolean)

I'll be honest, I have no idea what this does, and couldn't find an documentation on it. Default: false

<a href="#" class="odo-share" data-service="linkedin" data-ro="{{ data.ro }}"></a>

Example(s):

<a href="#" class="odo-share" data-service="linkedin" data-ro="false">Share</a>
OdoShare.share({
  service: 'linkedin',
  data: {
    ro: false
  }
});

Back to LinkedIn API

Back to Services API

Email

data.to (string, array)

Who to send the email to. This may be a single recipient, or an array of recipients. 

<a href="#" class="odo-share" data-service="email" data-to="{{ data.to[,...] }}"></a>

Example(s):

<a href="#" class="odo-share" data-service="email" data-to="foo@odopod.com">Share</a>
<a href="#" class="odo-share" data-service="email" data-to="foo@odopod.com,bar@odopod.com">Share</a>
OdoShare.share({
  service: 'email',
  data: {
    to: ['foo@odopod.com', 'bar@odopod.com']
  }
});

Back to Email API

data.cc (string, array)

Who to CC the email to. This may be a single recipient, or an array of recipients. 

<a href="#" class="odo-share" data-service="email" data-cc="{{ data.cc[,...] }}"></a>

Example(s):

<a href="#" class="odo-share" data-service="email" data-cc="foo@odopod.com">Share</a>
<a href="#" class="odo-share" data-service="email" data-cc="foo@odopod.com,bar@odopod.com">Share</a>
OdoShare.share({
  service: 'email',
  data: {
    cc: ['foo@odopod.com', 'bar@odopod.com']
  }
});

Back to Email API

data.bcc (string, array)

Who to BCC the email to. This may be a single recipient, or an array of recipients. 

<a href="#" class="odo-share" data-service="email" data-bcc="{{ data.bcc[,...] }}"></a>

Example(s):

<a href="#" class="odo-share" data-service="email" data-bcc="foo@odopod.com">Share</a>
<a href="#" class="odo-share" data-service="email" data-bcc="foo@odopod.com,bar@odopod.com">Share</a>
OdoShare.share({
  service: 'email',
  data: {
    bcc: ['foo@odopod.com', 'bar@odopod.com']
  }
});

Back to Email API

data.subject (string)

The subject of the email. Default: document.title 

<a href="#" class="odo-share" data-service="email" data-subject="{{ data.subject }}"></a>

Example(s):

<a href="#" class="odo-share" data-service="email" data-subject="Odopod">Share</a>
OdoShare.share({
  service: 'email',
  data: {
    subject: 'Odopod'
  }
});

Back to Email API

data.body (string)

The body of the email. Default: window.location.href 

<a href="#" class="odo-share" data-service="email" data-body="{{ data.body }}"></a>

Example(s):

<a href="#" class="odo-share" data-service="email" data-body="Check this out!">Share</a>
OdoShare.share({
  service: 'email',
  data: {
    body: "Check this out!"
  }
});

Back to Email API

Back to Services API