The Share Bar add-on allows you to easily place in your site a bar with different buttons for sharing content to social destinations. The Share Bar add-on is built out of one or more buttons, arranged horizontally. Each button represents a direct bookmark destination, a general share button, or an email button.
Once a user clicks a direct bookmark button, the window of the provider will be opened for direct bookmarking. Once a user clicks the general share button, the Simple Share mode of the Share add-on will popup, enabling your user to share and bookmark content and site activities to selected social destinations.
The Share Bar buttons may be displayed with or without counters, representing the number of shares.
For more information regarding the counters, refer to the socialize.getProviderShareCounts API method.
You can use the Share Bar Wizard to customize the visual aspects of the Share Bar add-on design, view, and grab the customized code.
What's in this Guide
This document is a step-by-step guide for integrating the Share Bar add-on and also provides a reference and guide for the various customization options. For convenience, we have divided this document into levels of complexity:
- Quick Start Implementation - learn how to quickly integrate the Share Bar add-on, and share to the various social networks.
- Changing to Multiple Selection Share - learn how to change the default share display.
- Share Bar add-on Customization - learn how to customize the default design of the buttons in the share bar.
Quick Start Implementation
Adding the Share Bar add-on is simple, and involves only adding a few lines of code:
- Step 1: Define the action fields for the share item. The newsfeed item that is published to the social networks is constructed from the fields of this object.
This can be done either by constructing a UserAction object, or by adding Open graph meta-tags to your HTML, though it is recommended to implement both.
- Step 2: Define the Share Bar add-on's params object, including a comma-separated list of providers, representing the buttons to display in the share bar.
Add the following code snip to the of your page to activate the Share Bar add-on that is presented in the screenshot above:
Step 1: Construct a UserAction object and fill it with data
The UserAction object represents a User Action. We use the UserAction object constructor for this purpose:
After you have constructed the object, you can use the various UserAction member methods to set the object's properties. For example:
The UserAction's object properties represent the various items of which a User Action may consist: Title, Description etc.
Step 2: Define the Share Bar add-on's parameters
The Share Bar add-on has three required parameters:
- containerID - The identifier of the DIV element, where the Share Bar add-on should be embedded.
- shareButtons- The list of providers.
- userAction - The userAction object that we have created in Step 1.
- facebookDialogType - Options are: 'share' (default) or 'feed'. The 'share' dialog will scrape the post data from the open graph tags defined on the page, while the 'feed' dialog will use data from the 'user action object'.
In this example the ShareButtons parameter is comprised of a list of providers. Instead, you may define an array of ShareButton objects:
The add-on has additional optional parameters you can use. Please refer to the method's parameters table for the entire list of optional parameters.
Step 3: Invoke the Share Bar add-on
Call the socialize.showShareBarUI API method:
A Working Example
In the Share Bar add-on demo you may find a complete working example of a share bar that is used to publish user actions. You may view the code, run it and view the outcome.
How the URL to be Shared is Determined
The share buttons are used to share content, and more specifically share a URL. The URL to be shared is determined according to a certain logic. The following list shows the order in which Gigya checks whether a URL exists, and if it does, this is the URL used for sharing:
- The ShareButton object's 'url' field
- The linkback field of the ShareButton object's userAction
- The linkback field of the UserAction
- The Open Graph URL tag (og:url tag)
- The canonical meta tag* (if defined)
- The URL of the current page
When sharing or shortening URLs via any Gigya Add-ons, APIs, or methods, the URL being used must be a publicly accessible URI. If the URI is behind a firewall, an HTTP Auth, or does not respond within 5 seconds of a request to retrieve the URL of the page, even if the URL is within a whitelisted domain, Gigya will respond with errorCode 400120 - Invalid Site Domain, and the request will fail.
*Defining a canonical meta tag is done by adding a rel="canonical" link to the section of the non-canonical version of each HTML page. To specify a canonical link to the page http://www.example.com/product.php?item=swedish-fish, create a element as follows:
Changing to Multiple Selection Share
When using the general share button in the Share Bar add-on, the default Share dialog that is displayed is the Simple Share dialog. You can change this to the multiple selection share, which is the more elaborate Share add-on.
Change the simple share to multiple selection share by adding the optional operationMode parameter to the Share Bar parameters, with the value 'multiSelect':
The general share button will now trigger the full Share add-on:
You can now use the Share Bar add-on with the full Share add-on capabilities. Please refer to the Share add-on Guide for further reading.
Share Bar UI in Mobile View
When the socialize.showShareBarUI deviceType parameter is set to mobile, the share bar UI is displayed in the mobile mode, with the share bar either in vertical presentation, or horizontal presentation:
Adding a Comments Counter
You can add a Comments button to your Share Bar, with a counter indicating the number of comments made in that specific comments stream. The comments stream is identified by its unique categoryID and streamID.
In order to display the Comments button with a counter, define a ShareButton object with 'comments' as the provider, and the categoryID and streamID that identify the comments stream:
The Share Bar that is displayed for this code is:
Localization for Facebook Like Button
In order to display the Facebook Like button, define a ShareButton object or string with 'facebook-like' as the provider. If you wish to display the button in a different language, the language needs to be set in the socialize JS URL before the add-on is loaded. Learn about this in Localization Support for 3rd Party add-ons.
Twitter Tweet Button
Special Twitter Button Parameters
You can configure the Twitter Tweet button so that:
- After tweeting, you can suggest to the user to follow related accounts, by using the 'related' parameter.
- You can assign the screen name of the user to whom to attribute the Tweet, by using the 'via' parameter.
Define a ShareButton object with 'provider', 'related', and 'via' fields:
The following Twitter window includes the screen name of the user to whom to attribute the Tweet, i.e. @etayg, and two recommended related accounts:
Google +1 Supported Browsers
In order to display the Google +1 button, define a ShareButton object or string with 'google-plusone' as the provider. There are few browsers in which the Google +1 button is not supported. Please refer to the Supported browsers for the updated list by Google.
Google+ Interactive Post
Google+ provides an interactive post feature. Using this feature users can post shares to G+ with a special call-to-action button, and have a deep link to their mobile apps.
Generally, the interactive button allows a post to appear in Google+ with a special "call to action" link, which is displayed in addition to the standard "content" link. For example, "goodsongs" can set an interactive Google+ button, so that whenever users share songs from goodsongs.com, in Google+, each shared song will have a "Listen" button next to it ("call to action") and not just a standard link to the song ("content" link).
In addition, the feature allows configuring "deep links" to be used in mobile apps, so the shared song will not just open the "goodsongs" app (when accessed through a mobile platform), but also directs it to the right place where this song can be played.
Add the Google+ Interactive Post by defining a ShareButton object with provider "googleplus-interactive" and the button's fields:
Sharing via Text Message
In order to share via text message, define a ShareButton object or string with 'moshare-sms' as the provider. moShare cannot be used over https.
When you click on the moShare icon, the following window will open:
Send to Kindle
In order to send to Kindle using the Share Bar, define a ShareButton object or string with 'kindle' as the provider.
Marking the title, author, and publication date on your pages can be done using the following methods: Custom CSS Selectors, Facebook's Open Graph, schema.org, hNews, and Blogger / Blogspot. In the same manner, you can mark the main body of content on your pages using Custom CSS Selectors, schema.org, hNews, and Blogger / Blogspot
- Custom Css Selectors - you can mark the title, author, and publication date on your pages using Custom CSS Selectors. Read about the possible CSS Selectors in the socialize.showShareBarUI method.
- Facebook's Open Graph meta tags allow you to define the title, author, page name and publication date. An example of markup metadata with the Open Graph specification:
- schema.org is a standard to provide information about a website for search engines, it allows them to identify the relevant metadata of the page. An example of markup metadata with the schema.org specification:
- hNews is an open standard for news content, it allows you to describe journalistic work. AN example of markup metadata with the hNews specification:
- Blogger / Blogspot - Using the send to Kindle button with Blogger / Blogspot - select this option if you are using a "Classic" Blogger template.
Since mixi is a provider that requires an API key in order to work, you must add a parameter called mixiKey with the mixi API key to the showShareBarUI parameters:
Read more about adding media items to the UserAction object.
Share Bar add-on Customization
The Share Bar design can be customized using:
You can customize the Share Bar add-on using the following socialize.showShareBarUI method parameters:
- layout - using this parameter you can arrange the buttons in a vertical bar instead of a horizontal bar
- showCounts - using this parameter you can display the counters above the corresponding buttons instead of on their right, or choose to display the bar with no counters
- noButtonBorders - using this parameter you can display buttons without borders
To arrange the buttons in a vertical bar instead of a horizontal bar, add the layout parameter to the Share Bar add-on's parameters, with the value 'vertical':
Counters on Top
To display the counters above the corresponding buttons instead of on their right, add the showCounts parameter to the Share Baradd-on's parameters, with the value 'top':
In the same manner you can display the Share Bar without counters, by adding the showCounts parameter to the Share Bar add-on's parameters, with the value 'none'.
No Button Borders
To arrange the buttons without button borders, add the noButtonBorders parameter to the Share Bar add-on's parameters, with the value 'true':
Applying a New Button Design
It is possible to customize any non-native share button in the Share Bar. Applying a new design can be done categorically for all non-native buttons by applying image URLs to the buttonImages parameter of the socialize.showShareBarUI method, or specifically to a single button by supplying an image URL to the iconImgUp Paramter within the shareButton object.
The following are the categorical customization fields:
- buttonLeftImgUp - An image for the left part of the button
- buttonCenterBGImgUp - An image for the center part of the button
- buttonRightImgUp - An image for the right part of the button
To replace the default button images with your alternative images, set these fields with URLs to the corresponding images.
Add the buttonImages parameter to the Share Bar parameters with your own button images:
You may also define images to the 'Disabled' 'Mouse over' and 'Down' states of the button, using the corresponding fields of the buttonImages parameter:
- buttonLeftImgDisabled, buttonCenterBGImgDisabled, buttonRightImgDisabled - Images for Disabled button (left, center and right).
- buttonLeftImgOver, buttonCenterBGImgOver, buttonRightImgOver - Images for Mouse Over state (left, center and right).
- buttonLeftImgDown, buttonCenterBGImgDown, buttonRightImgDown - Images for Down state (left, center and right).
Customizing a Specific Button
Share buttons are defined via the shareButtons parameter of the socialize.showShareBarUI method. While button images are obtained by default according to the provider of each button, they can also be customized.
To specify an image for a single, specific button (e.g altering the Facebook share button image), set the iconImgUp parameter, within the button object you want to change, to the image URL you would like to set as the share button.
HTML Elements Style (CSS) Classes
Any elements on the add-on that has an ID can be overridden with supported style attributes. You may use Firebug to identify an HTML element on the add-on and assign a new style to it. Please make sure to use the add-on's container ID when assigning style, so it will not affect other elements on the page.
There are five classes that you can use to customize your buttons, overriding the default design:
- gig-share-button-container - overrides the default design of a button and counter
- gig-share-button - overrides the default design of a single button
- gig-share-button-text - overrides the default design of a button's label
- gig-share-counter - overrides the default design of a single counter
- gig-share-counter-text - overrides the default design of a counter's value
The following examples demonstrate how to change the default background color of each class specified here. You may change the font size, font color, border, etc. In order to more
Button and Counter
To design a button and counter with a yellow background, add the following to the section of your page:
To design a button with a green background, add the following to the section of your page:
In this example, the button is without borders to allow the green background to be more visible.
To design a button label with a red background, add the following to the section of your page:
To design a button counter with a purple background, add the following to the section of your page:
To design a counter value with a blue background, add the following to the section of your page:
In addition, you can further customize your share bar buttons using the following classes:
For example, add the following to the section of your page to change the button text to yellow when the button is disabled:
Using Button Templates
The buttonTemplate and buttonWithCountTemplate parameters of the socialize.showShareBarUI method enables you to override the default design of buttons in the Share Bar by defining an HTML template representing the appearance of each button. Within the template, you may use CSS attributes to style the button.
- The buttonTemplate parameter affects the design of buttons that do not include a counter, such as "Print" and "Email". The HTML template supports the placeholders $iconImg, $text, $onClick.
- The buttonWithCountTemplate parameter affects the design of buttons with counters, such as the simple "Share" button. The HTML template supports the placeholders $iconImg, $text, $onClick, $count.
For example, here is a simple bar with no buttonTemplate parameter defined:
The following picture shows the same bar with the following line added to the parameters of the method:
Note that the Share button is not affected, because it is a button with a counter. To apply a template to the Share button, add a buttonWithCountTemplate parameter as well, e.g.: