This method displays the Share Bar plugin, which consists of one or more share buttons arranged in a horizontal or vertical bar. The buttons can be direct bookmark buttons, a general share button, or an email button. Certain bookmark buttons including the general share button can display a counter representing the number of shares. For more information regarding counters, refer to the socialize.getProviderShareCounts API method.
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 plugin will pop up, enabling your user to share and bookmark content and site activities to a selected social destinations.
The following table lists the available parameters:
| ||shareButtons||string or an array of objects|
An array of ShareButton objects or a string containing a comma-separated list of providers, representing the buttons to display in the share bar. When passing a comma-separated list, the plugin behaves as if an array of ShareButton objects was passed, where the only value in each object is the provider name.
Valid provider names include:
(Note: messenger has been replaced by microsoft, however, for backward compatibility, either can be used).
In addition to the provider names listed above, the comma-separated string containing the provider list may also include these reserved names, that implement the provider's own (native) button:
*** The Googleplus button is unable to display share counts because Google does not have an API that returns share counts.
|||containerID||string||An ID of a <div> element on the page in which you want to display the plugin.|
|||userAction||UserAction object||The user action to share. The UserAction object enfolds newsfeed data, including text, media, link, etc., and is used to construct the newsfeed item for all networks except Facebook, Twitter and Google, which use Open Graph (OG) tags instead. For more information on using OG tags, see Sharing Content.|
The title property is required when sharing to Sina Weibo (sina); You do not need to include a title separately if you include it within a UserAction object.
|||actionAttributes||JSON object||In Gamification your users receive points for actions they perform on your site, in this case clicking a share button grants the user points. Action Attributes may be used to annotate actions with additional information, such as the section of the website that generated the action. If you set here the actionAttributes, each time a user clicks a share button, the action also receives an attribute, for example "tv-show":"glee", which can mean that the action was performed on the "Glee" page of the site. |
actionAttributes contain a JSON object comprised of a series of attribute keys (categories) with associated values. You can also use a generic "tags" key.
No more than three values can be given, they can be with a single key or each have their own key.
For more information see Variants and Action Attributes. Action attributes are later used to filter GM Plugins by a certain attribute.
|||buttonImages||JSON object||Using this object you may override the default design of a share button. Specify your alternative button images using the object fields. The following fields are supported:|
Read more in the Applying a New Button Design guide.
|This parameter enables you to override the default design of the buttons in the Share Bar that do not include a counter, such as the "Print" and "Email" buttons. The parameter defines an HTML template representing the appearance of each button. The HTML template supports the placeholders $iconImg, $text, $onClick. See Using Button Templates for information and examples.|
|||buttonWithCountTemplate||string (HTML)||This parameter enables you to override the default design of the buttons in the Share Bar that include a counter, such as the general "Share" button. The parameter defines an HTML template representing the appearance of each button. The HTML template supports the following placeholders: $iconImg, $text, $onClick, $count. See Using Button Templates for information and examples.|
A string of maximum 100 characters length. The CID sets categories for transactions that can be used later for filtering reports generated by Gigya in the "Context ID" combo box. The CID allows you to associate the report information with your own internal data. For example, to identify a specific widget or page on your site/application. You should not define more than 100 different context IDs.
|||context||object||A reference to a developer created object that will be passed back unchanged to the event handlers as one of the fields of the eventObj (see extended explanation in the "Plugin Events" section below).|
|||countURL||URL||Allows to specify a canonical URL and counts are then retrieved from this URL. The countURL ensures that the counts are incremented properly, and tracks counts against the canonical URL. To count Facebook's native buttons you must Enable Native SDK Capabilities (see the shareButtons parameter for native button details). Other native buttons will not be counted.|
|||deviceType||string||Determines the type of the device on which the Share Bar UI is displayed. The parameter supports the following values:|
When the Share Bar is set to deviceType mobile or auto (on mobile), clicking the email share will open the mail client rather than the Gigya share bar UI.
|||displayCountThreshold||integer||The threshold of the counter to be displayed, i.e. each button in the share bar will display its counter only once it reaches this number. If the counter has not reached this threshold, the counter will not be displayed for the provider. The default value is 0. |
This parameter does not apply to the Facebook Like/Send and Twitter buttons.
|||facebookDialogType||string||Applicable only for sharing through Facebook. This parameter determines which Facebook dialog will appear when clicking the share button. Options are:|
When using the 'share' dialog, it is required to implement open graph tags on your page, since Facebook's 'share' as well as other major social networks, use open graph tags to get the news feed item data for the shared item, rather than using data from the 'user action object'.
|This parameter allows you to gray-out the screen behind the plugin to emphasize the "modal" environment in Multiple Selection Share mode. Graying-out covers the entire page behind the plugin with a gray transparent layer. Using this parameter you can define the opacity of the gray layer. The value of this parameter should be a number between 0-100, where:|
|||iconsOnly||Boolean||This parameter determines whether the share bar buttons are displayed as icons only, without text and borders. The default value of this parameter is 'false'.|
|||initialView||string||Determines the initial view of the plugin when it loads in Multiple Selection Share mode. There are three options:|
|||Key||string||Using this parameter, you can specify all the API keys of the social networks that require an API key, e.g. 'mixiKey'.|
|||layout||string||Sets the arrangement of buttons in the bar. May be:|
|||noButtonBorders||Boolean||This parameter determines whether the share bar buttons are displayed without borders. The default value of this parameter is 'false' (the buttons are displayed with borders). This parameter is only applicable if iconsOnly is false.|
|||shareCountCacheTimeout||integer||This parameter defines how long the share counts data will be stored in local cache. The default value of this parameter is 300,000 milliseconds. The share counts data will not be refreshed within this interval, for better performance.|
|||shareTimeout||integer||Sets a timeout to the sharing operation in Multiple Selection Share mode. Set this parameter with the maximum number of seconds to wait for the sharing operation to be completed. If a timeout occurs, the Share plugin will close and an onError event will be fired with errorCode=504001 and errorMessage="Share request timeout".|
Using this parameter you may determine whether to use Gigya's URL shortening service for URLs passed in the status parameter. The optional values for this parameter are:
To determine your data center see Finding Your Data Center.
When Gigya's URL shortening service is active, Gigya tracks all the traffic coming from the distributed URLs. In such case, 'Referred Traffic' reports will be available to you.
|||showCounts||string||This parameter determines if and where to display the share counts in relation to the share button. The options are:|
The following providers support counters: 'facebook' , 'stumbleupon', 'linkedin', 'vkontakte', 'facebook-like', 'facebook-share', 'facebook-send', 'twitter-tweet', 'google-plusone', 'moshare-sms', 'share', 'comments', 'pinterest', 'pinterest-pinit', 'hatena-bookmark'. Note: for provider='moshare-sms' the counters can be either right or none, if top is defined, the moshare button will not display counters.
Shares posted using the generic +Share button will not be counted as shares made by the other buttons.
In addition, showCounts will only work when the shareButtons parameter (see above) is a string.
|||showTooltips||Boolean||This parameter's default value is 'false'. If set to 'true', a tooltip will be displayed when the mouse hovers over a social network icon. The tooltip presents the social network's full name. This parameter is relevant only in Multiple Selection Share mode.|
|||tags||string||A comma separated list of tags that are used to identify the share operation.|
|||<socialNetworkName>UserAction||UserAction object||It is possible to specify different content to publish for each social network in Multiple Selection Share mode. For this purpose, the method supports a set of parameters with the same name format: (i.e., facebook, twitter, googleplus, etc.) followed by "UserAction". For example: twitterUserAction - specifies the content to be used specifically when publishing to Twitter.|
Each of these optional parameters accepts a UserAction object and if specified override the userAction parameter when posting to that provider. In other words, the userAction parameter (see above) specifies the default content to be used for all social networks and UserAction specifies the content to be used for the specific network.
|||userMessagePlaceholder||string||Text that appears as a placeholder for the user message in the shareUI when in multiselect mode. When the user clicks the user message input box in the shareUI, the text disappears.|
|||wrap||Boolean||Indicates whether to "wrap" the buttons in the Share Bar plugin. The default is 'false', and when set to 'true' the share bar's buttons will be automatically wrapped to the next line if the current line isn't wide enough to display all the buttons.|
|||facebookLikeButton||JSON object|| Deprecated . Please use the shareButtons parameter instead, along with the 'facebook-like' value.|
This parameter adds the Facebook Like button to the share bar.
'Share' button related Parameters:
The following parameters are relevant only if you are in Multiple Selection Share mode and using the Simple Share dialog (enabled by creating a generic "Share" button). By default the Share button opens a provider selection box, in which the last option is a "More" button which opens a second box showing all available providers. Gigya offers tens of additional destinations for social sharing. To learn more about this feature, please read the More Networks Screen page in the Developer's Guide.
|||showMoreButton||Boolean||Gigya offers tens of additional destinations for social sharing. The additional destination are provided through a "More" button on the Share Plugin. Using this parameter you can show/hide the "More" button. The default value is of this parameter is 'true' (button is shown). To learn more about this feature, see Adding More Destinations.|
Using these pair of parameters you may define which destination sites buttons will be displayed on the "More" screen, and also determine the order. In Simple Share mode, these are the providers that are displayed (not the enabledProviders ). Each parameter is set with a comma separated string of destination names. These pair of parameters have similar logic to the enabledProviders and disabledProviders pair of parameters (see above). Valid destinations for the "More" screen include:
To learn more about this feature, see Adding More Destinations.
|'Email' button related Parameters:|
|||showEmailButton||Boolean||Gigya offers an option of sharing the user action via email. Sharing via email is provided through the enabling of a "Email" button on the Share Plugin. To enable the "Email" button, set this parameter to 'true' (The default value is 'false'). To learn more about this feature, see Sharing via Email.|
|||emailBody||string (HTML)||This parameter is only relevant if the showEmailButton parameter (see above) is set to 'true'. Using the "Email" screen of the Share plugin, users may send emails to selected email contacts. Gigya defines a default email body structure which is based on the User Action fields, and the message entered by the user in the Share Plugin. You may define an alternative email body, using the emailBody parameter. The email body should be defined in HTML format, and may include the following replacement strings: $sender$, $URL$, $userMsg$, $title$, $description$, and $actionLinkTitle$.|
To learn more about this feature, see Sharing via Email.
|||dontSendEmail||Boolean||This parameter is only relevant if the showEmailButton parameter (see above) is set to 'true'. Setting this parameter to 'true' instructs Gigya to not actually send an email when the user chooses to send one. You can use this parameter along with the onSendDone event data to send the actual email from your own servers. The default value is 'false' (Gigya server will send the email).|
To learn more about this feature, see Sharing via Email.
|||emailProviders||string||A comma delimited list of email providers that should be displayed on the email screen for importing contacts. Valid provider names include: 'yahoo', 'googleplus'. When emailProviders=' ' , the Import Contacts header in the Share UI for share via email is hidden.|
| Auto Share related Parameters: |
The following parameters are relevant only if you are in Multiple Selection Share mode. To learn more about this feature, please read the Automatic Sharing guide.
|||showAlwaysShare||string||This parameter determines whether to show an "Always share" checkbox at the bottom of the Share Plugin. If the user checks this checkbox and presses "Publish", Gigya will turn on an automatic share for this user. Each time this user repeats the same type of action, Gigya will automatically share the action without prompting the user with the Share Plugin. The type of action is determined using the autoShareActionID parameter (see below). The action will be shared on the Social Networks which the user selected when he checked the "Always share" checkbox. If a Network is no longer connected, the share will fail without notifying the user.|
The optional values for this parameter are:
|||autoShareActionID||string||Use this parameter to specify a unique identifier for the type of action that the user has performed on your site. For example: "Commented", "Rated", "Replied", "Liked", etc.|
The user selection (Always Share) will apply only to this ID.
|||autoShareExpiration||string||Using this parameter, you may assign an expiration date/time for the user selection for the specific autoShareActionID. The default is never expire. The expected format is the Unix time format (i.e. the number of milliseconds since Jan. 1st 1970).|
|||autoShareActionDisplay||string||Using this parameter, you may change the default text shown next to the "Always share" checkbox and the "Never share" link. The autoShareActionDisplay string will be appended to the "Always share" and "Never share" strings, i.e., "Always share XXX" and "Never share XXX", where XXX is the autoShareActionDisplay string. The default value of autoShareActionDisplay is the string "this".|
|Events Registration Parameters:|
|||onSendDone||function ref||A reference to an event handler function that will be called when the process of sharing to the selected social network has finished. This does not include submitting comments; for comments use onShareButtonClicked .|
Note that in some instances share actions fire OnSendDone before they have completed: for bookmark providers and emails onSendDone will fire immediately, and for other providers it will fire after the share is complete.
|||onShareButtonClicked||function ref||A reference to an event handler function that will be called when one of the plugin's buttons is clicked. To register a click on a provider's (native) button, use onSendDone.|
|||onLoad||function ref||A reference to an event handler function that will be called when the plugin has finished drawing itself.|
|||onError||function ref||A reference to an event handler function that will be called when an error occurs.|
The single argument, eventObj, contains information about the event and has different fields for different events.
The following tables specify the list of fields available in the eventObj for each event:
onLoad Event Data
onError Event Data
|errorCode||integer||The result code of the operation. Code '0' indicates success, any other number indicates failure. For a complete list of error codes, see the Error Codes table.|
|errorMessage||string||A short textual description of an error, associated with the errorCode, for logging purposes.|
|errorDetails||string||This field will contain the exception info, if available.|
|providers||string||The name of the sharing target (e.g., 'twitter', 'email'). Pinterest does not fire this event.|
|userMessage||string||The textual message that the user entered in the editable text box of the Share Plugin.|
|targetURL||string||The URL that was shared.|
When a user chooses to share via email, he will use the plugin's email screen and press the 'Send' button. In this situation, Gigya fires an onSendDone event with the providers field set to 'email' and with extra email related fields.
|userMessage||string||The user custom message.|
|recipients||array||An array of objects that each has a name property and an email property corresponding to the recipients of the email that has been sent.|
|sender||string||The name or email of the sender.|
To learn more about using this event, please read Sharing via Email.
onShareButtonClicked Event Data
|shareItem||ShareButton object||The object representing the share button that has been clicked. Note: Pinterest does not fire this event.|
Global Event Triggered
By using this Plugin, the following global event may be triggered: onConnectionAdded .
To register an event handler use the socialize.addEventHandlers API method. Refer to the onConnectionAdded event data. Refer to Events to learn more about how to handle events generated by the Gigya service.
Code Sample (using the comments provider with showCommentsUI)
When using the Share Bar Comments provider in conjunction with the Comments plugin (comments.showCommentsUI), you need to capture the Comments button click event in order to send the user to the Comments box on the page. This can be done as follows:
In the ShareBar Plugin demo you will find a complete working example, which uses the socialize.showShareBarUI method. You may view the code, run it and view the outcome.