Share

This is preliminary documentation and is subject to change.  Share is available from [TBD: Firefox 23]

A service provider may choose to provide a Share panel that users can use to share content from the current browser tab with their friends.  The Share panel is slightly different from other Social UI in the browser.  The Share panel itself contains a list of providers that support the share functionality.  When a user shares a page, they can choose which provider they want to share with.  Each provider may have differing functionality, such as simply providing a comment box to extensive functionlality allowing for image selection and more.

Share is initiated by the user either through the share button in the toolbar or a context menu.  The user can select an image or text in a page to be shared, or share the page itself.  Links within a page may also be shared without visiting the link.

A provider implementing support for share may choose to use a URL template that is compatible with OExchange, however the browser also sends a DOM event to the page after load containing details of the share.  In some circumstances, such as sharing a link on the page, the browser will not have detailed information.  Using the DOM event allows the provider to display information about the page being shared without needing to fetch it themselves and parse the page for information.  The browser includes certain META tags, including OpenGraph tags in the event data.

A User Experience Flow for Share

SocialAPI content works different than typical web pages.  The are presented as primary UI in the browser, and may be confined in size, live longer than a browser tab, and more.  How your user will interact with your share panel is unique and you will need to take into account how a user should experience your share panel.

[TODO: describe the expected flow here]

OpenGraphData DOM Event

The share page can listen for the OpenGraphData DOM Event.

addEventListener("OpenGraphData", function(e) {
  var shareData = JSON.parse(e.detail);
  $("#shared").text(shareData.url);
})

Attributes

The event detail can contain the following attributes which are retreived from META tags and other tags within HEAD, such as the TITLE tag:

• url: The URL to the page, link, image or video being shared
• medium: The media type being shared
• source: The media url being shared if a video is being shared
• sitename: The site name
• title: The title of the page
• description: The description of the page
• text: The selected text that the user is sharing
• previews: A list of images available as page previews

Share URL Template

While we prefer the use of the DOM event, many sites have existing endpoints that allow users to share to that site.  SocialAPI supports using a URL template to make implementation easy for sites that already have this functionality.  In your manifest, you can define your shareURL in this format:

"shareURL": "https://yoursite.com/share?u=%{url}&t=%{title}

The %{name} values will be replaced with the following attributes if available.  Otherwise that parameter is removed from the final url used to load your share endpoint.

• url: The URL to the page, link, image or video being shared
• medium: The media type being shared
• source: The media url being shared if a video is being shared
• sitename: The site name
• title: The title of the page
• description: The description of the page
• text: The selected text that the user is sharing
• image: A URL to an image to use as a preview, or the image shared by the user.

How to properly size your share panel

Your share panel is presented in a door hanger from the browser toolbar.  While it can be flexible in size, there is a minimum and a maximum size that the panel will allow.  You also need to implement a couple items to help the browser identify the size you need for your panel.  There are a few ways you can define the proper size for your panel, here are some examples:

Styling the BODY element

By default the browser will look at the body.style.width and body.style.height, also taking into account the margin.  It will try to size the panel to show your full page.

<html>
<body style="width: 300px; height: 400px">
</body>
</html>

Identifying a content element

The browser will also look to see if you have defined a primary content element.  If you have, then it will use the width and height styles from that element to size the panel.  You will need to make sure that your content element is properly placed.

<html>
<body contentid="content">
<div id="content" style="width: 300px; height: 400px; top: 0; left: 0;"/>
</body>
</html>