Social bookmarking

Social Bookmarks were introduced in Firefox 27.

A service provider may choose to provide a Social Bookmarking button that users can use to save content from the current browser tab for later use.  Social Bookmarks differs from Share in that the url is only sent to the provider.  This functionality can handle use cases such as Facebook Like, Google +1, Pocket, Delicio.us or other save-for-later features.  When a user bookmarks a page (or links and images within a page), the url is sent to the provider.  Each provider has their own button for this functionality, and may have differing functionality or use cases.

The Social Bookmarking button works exactly like the Firefox Bookmark "star" button.  The first click "marks" the page, and the second click will show a panel containing a page loaded from the provider.  That page can contain additional functionality as well as an "unmark" or cancel button.  If the user bookmarks using the context menu, the panel is shown immediately, since the mark may not be the page itself but something contained in the page.

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

A provider implementing support for Social Bookmarking 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 marked page.  In some circumstances, such as marking 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 Social Bookmarking

SocialAPI content works different than typical web pages.  The panels 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 bookmark panel is unique and you will need to take into account how a user should experience your bookmark 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

Bookmark URL Template

While we prefer the use of the DOM event, many sites have existing endpoints that allow users to mark 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 markURL in this format:

"markURL": "https://yoursite.com/mark?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 bookmark endpoint.

• url: The URL to the page, link, image or video being marked
• medium: The media type being marked
• source: The media url being marked if a video is being marked
• 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 marked by the user.

How to properly size your bookmark panel

Your bookmark 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>