Table of contents
Description
Displays the Share Bar plugin, which is comprised 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 and the general share button can display a counter representing the number of shares. For more information regarding the counters, refer to the socialize.getProviderShareCounts API method.
Once a user clicks on a direct bookmark button, the window of the provider will be opened for direct bookmarking. Once a user clicks on the general share button, the Simple Share mode of the Share plugin will popup, enabling your user to share and bookmark content and site activities to a selected social destinations.
Note: If you plan on integrating the Share Bar plugin, we highly recommend reading the Share Bar plugin in the Developer's Guide, which is a step-by-step guide for integrating the Share Bar plugin and also provides a reference and guide for the various customization options.
Syntax
gigya.socialize.showShareBarUI(params)
Method Parameters
The following table lists the params object members:
| Required | Name | Type | Description | |
| Required | shareButtons | array or string | An array of ShareButton objects or 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: Facebook, Twitter, LinkedIn, Messenger, Myspace, Delicious, Reddit, Google Bookmarks, VKontakte, Spiceworks, Viadeo, nk.pl, Xing, Tuenti, Pinterest*, MyAOL, Baidu, FriendFeed, Tumblr, Stumbleupon, Orkut, Skyrock, QQ, Sina, mixi**, Kaixin, VZnet. In addition to provider names, the provider list may include these reserved names:
| |
| 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. | ||
| Optional | layout | string | Sets the arrangement of buttons in the bar. May be:
| |
| showCounts | string | This parameter determines if and where to display the share counts in relation to the share button. The options are:
| ||
| 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). | ||
| 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'. | ||
| buttonTemplate | string (HTML) | Using this parameter you may override the default design of a single button. Defines an HTML template representing the design of a single button. The HTML template supports the following placeholders: $iconImg, $text, $onClick. | ||
| buttonWithCountTemplate | string (HTML) | Using this parameter you may override the default design of a single button with counter. Defines an HTML template representing the design of a single button with counter. The HTML template supports the following placeholders: $iconImg, $text, $onClick, $count. | ||
| 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: buttonLeftImgUp, buttonLeftImgOver, buttonCenterBGImgUp, buttonCenterBGImgOver, buttonRightImgUp, buttonRightImgOver, countBGImg. Read more in the Applying a New Button Design guide. Note: The images are specified separately from the buttonTemplate in order to be pre-loaded. If pre-loading is not required the images may also be specified directly in the buttonTemplate. | ||
| operationMode | string | Using this parameter determines which Share Plugin mode is displayed; either the Multiple Selection Share mode or the Simple Share mode. Please refer to the Simple Share section for an extended explanation. The optional values for this parameter are:
| ||
| deviceType | string | Determines the type of the device on which the Share Bar UI is displayed. The parameter supports the following values:
| ||
| 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. Note: This parameter does not apply to the Facebook Like/Send and Twitter buttons. | ||
| 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). | ||
| cid | string | A string of maximum 100 characters length. This string is associated with each transaction and will later appear on 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. The "Context ID" combo box lets you filter the report data by site/application context. Note: the value of this parameter overrides the value of the identical parameter in the global configuration object. | ||
| shortURLs | string | Using this parameter you may determine whether to use Gigya's URL shortening service for URLs, which are published through this method. This includes URLs inserted by the user as part of their edited text message. The optional values for this parameter are:
Note: the value of this parameter overrides the value of the identical parameter in the global configuration object. | ||
| showSuccessMessage | Boolean | Provides the user with success feedback on sharing or sending an email. The default value of this parameter is 'false'. When this parameter is set to 'true', a success message is displayed with the following wording:
| ||
| enabledProviders | string | A comma delimited list of providers that should be displayed on this plugin in Multiple Selection Share mode. Valid provider names include: 'facebook', 'twitter', 'yahoo', 'messenger', 'linkedin', 'myspace', 'orkut', 'yahoojapan'. For example, if you would like this plugin to show only the icons of Facebook and Twitter, define: enabledProviders="facebook,twitter". Note: the Share plugin may show up to six social network buttons on its main screen (more social destinations may be shown in the "More" screen). Note: the value of this parameter overrides the value of the identical parameter in the global configuration object. | ||
| disabledProviders | string | A comma delimited list of providers that should not be displayed on this plugin in Multiple Selection Share mode. Valid provider names include: 'facebook', 'twitter', 'yahoo', 'messenger', 'linkedin', 'myspace', 'orkut', 'yahoojapan'. For example, if you would like this plugin to show all providers icons but LinkedIn and Twitter, define: disabledProviders="linkedin,twitter". Note: the value of this parameter overrides the value of the identical parameter in the global configuration object. | ||
| <provider-name>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: <provider-name> (i.e. facebook, twitter, yahoo, 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 <provider-name>UserAction specifies the content to be used for the specific network. | ||
| <provider-name>Key | string | Using this parameter, you can specify all the API keys of the social networks that require an API key, e.g. 'mixiKey'. | ||
| 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. | ||
| grayedOutScreenOpacity | integer (0-100) | 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:
| ||
| initialView | string | Determines the initial view of the plugin when it loads in Multiple Selection Share mode. There are three options:
| ||
| sessionExpiration | integer | This parameter defines the time in seconds that Gigya should keep the social network session valid for the user. To end the session when the browser closes, please assign the value '0'. If this parameter is not specified, the session will be valid forever. | ||
| simpleShareConfig | JSON object | In Simple Share mode, when the user selects a social network for sharing, this parameter enables you to add an option to display a dialog offering to connect the user to your site through the selected social network. The simpleShareConfig parameter accepts a JSON object with the following optional members:
Read more about this feature in the Post Share Connection section. | ||
| 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". | ||
| 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. | ||
| 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. | ||
| 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 web site 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. These action attributes are later used to display the GM Plugins filtered according to a certain attribute. For example, you can show the Leaderboard plugin only for top users on the "Glee" page. This parameter receives a JSON object, comprised of a set or sets of a key (category) and a value or values, i.e.: "tv-show": ["glee", "30rock"], | ||
| tags | string | A comma separated list of tags that are used to identify the share operation. | ||
| Email Button related Parameters: | ||||
| showEmailButton | Boolean | Gigya offers an option of sharing the user action via email. Sharing via email is provided through the "Email" button on the Share Bar, or by enabling of an "Email" button on the Share Plugin when in Multiple Selection Share mode. To enable the "Email" button, set this parameter to 'true' (The default value is 'false'). To learn more about this feature, please read the Sharing via Email page in the Developer's Guide. | ||
| useEmailCaptcha | Boolean | Indicates whether to use a CAPTCHA mechanism when sending emails. When CAPTCHA is used, emails that are sent through Gigya share arrive at their destination and not a spam folder. The default value is 'false'. When set to 'true', a captcha is presented before sending the 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$ and $userMsg$. To learn more about this feature, please read the Sharing via Email page in the Developer's Guide. | ||
| 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, please read the Sharing via Email page in the Developer's Guide. | ||
| 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', 'google'. | ||
| 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". | ||
| 'More' Screen related Parameters: | ||||
| The following parameters are relevant only if you are in Multiple Selection Share mode. | ||||
| 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, please read the Adding More Destinations page in the Developer's Guide. | ||
| moreEnabledProviders, moreDisabledProviders | string | Using these pair of parameters you may define which destination sites buttons will be displayed on the "More" screen, and also determine the order. 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: delicious, digg, friendfeed, googlebookmarks, messenger, myaol, stumbleupon, orkut, skyrock, qq, sina, kaixin, renren, vznet, vkontakte, spiceworks, viadeo, nkpl, xing, tuenti, technorati, plaxo, reddit, formspring, tumblr, faves, newsvine, fark, mixx, bit.ly, misterwong, ask, amazon, gmail, baidu, box.net, netlog, evernote, aolmail, currenttv, yardbarker, blinklist, diigo, backflip, dropjack, segnalo, linkagogo, kaboodle, skimbit, hyves, facebook, twitter, googleplus, yahoobookmarks, linkedin, pinterest, mixi. To learn more about this feature, please read the Adding More Destinations page in the Developer's Guide. Note: These pair of parameters are not relevant if the showMoreButton parameter (see above) is set to 'false'. Note: In addition tho the above automatic destinations, Gigya supports 150 more destinations. These destinations should be explicitly requested. Please contact us by filling in a support form on our site. You can also access the support page by clicking "Support" on the upper menu of Gigya's site. Check out the list of additional destinations here. | ||
| 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. | ||
| onShareButtonClicked | function ref | A reference to an event handler function that will be called when one of the plugin's buttons is clicked. This does not include clicking on 3rd-party buttons, for 3rd-party buttons, 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. | ||
| onClose | function ref | A reference to an event handler function that will be called in one of the following scenarios:
| ||
| Deprecated: | ||||
| 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. | ||
ShareButton Object
A JSON-encoded object representing a single button in the share bar:
| Required | Field Name | Type | Description | |
| Required | provider | string | The label to display on the button and the provider name. Can be a bookmark destination, 'facebook-like', 'facebook-send', 'facebook-subscribe', 'twitter-tweet', 'twitter-hashtag', 'twitter-mention', 'google-plusone', 'googleplus-share', 'moshare-sms', 'foursquare', 'foursquare-save', 'share', 'email', 'comments', 'pinterest-pinit', or 'print'. | |
| Optional | iconImgUp | string | Path to an image file to display on the share button. | |
| iconImgOver | string | Path to an image file to display on the share button, on mouse over. | ||
| tooltip | string | Tooltip to show when mouse over. | ||
| userAction | UserAction object | If defined, this parameter overrides the user action to share. The UserAction object enfolds newsfeed data, including text, media, link, etc. | ||
| userMessage | string | If defined, this parameter overrides the userMessage field of the default userAction method param for this share button. | ||
| enableCount | Boolean | If 'true', displays the counter. Can be overriden per provider. The default value is 'true'. | ||
| iconOnly | Boolean | If 'true', displays the icon only, not the text and borders of the button. | ||
| url | string | If defined, this parameter overrides the share button's value of the URL to be shared. Read more about the how the Share Button's URL is determined. | ||
| These following fields are relevant only if provider='facebook-like': | ||||
| action | string | Defines the verb to display on the button, maps to the Facebook 'action' parameter. Accepts two values: "like" (default) or "recommend". | ||
| colorscheme | string | Defines the color-schemes of the button background. Accepts two values: "light" (default) or "dark". | ||
| font | string | Defines the font of the text on the button. Accepts the following values: "tahoma", "verdana", "arial", "lucida grande", "segoe ui", "trebuchet ms". | ||
| width | integer | Defines the width of the button. | ||
| These following fields are relevant only if provider='facebook-send': | ||||
| colorscheme | string | Defines the color-schemes of the button background. Accepts two values: "light" (default) or "dark". | ||
| font | string | Defines the font of the text on the button. Accepts the following values: "tahoma", "verdana", "arial", "lucida grande", "segoe ui", "trebuchet ms". | ||
| These following fields are relevant only if provider='facebook-subscribe': | ||||
| colorscheme | string | Defines the color-schemes of the button background. Accepts two values: "light" (default) or "dark". | ||
| font | string | Defines the font of the text on the button. Accepts the following values: "tahoma", "verdana", "arial", "lucida grande", "segoe ui", "trebuchet ms". | ||
| These following fields are relevant only if provider='twitter-tweet': | ||||
| via | string | The screen name of the user to whom to attribute the Tweet. | ||
| defaultText | string | If defined, this parameter overrides the default text to include in the Tweet when sharing from the site. The default text to be overwritten is the page title. | ||
| countURL | string | The URL to which your shared URL resolves. | ||
| lang | string | The language for the Tweet button. | ||
| related | string | Related accounts to suggest to the user. Using this field you can suggest accounts for a user to follow once they have sent a Tweet using your Tweet Button. | ||
| These following fields are relevant only if provider='twitter-hashtag': | ||||
| hashtag | string | The hashtag to associate with this button. | ||
| defaultText | string | If defined, this parameter overrides the default text to include in the Tweet when sharing from the site. | ||
| lang | string | The language for the Tweet button. | ||
| related | string | Related accounts to suggest to the user. Using this field you can suggest accounts for a user to follow once they have sent a Tweet using your Tweet Button. | ||
| These following fields are relevant only if provider='twitter-mention': | ||||
| mention | string | The user to mention in this Tweet, e.g. @gigya. | ||
| defaultText | string | If defined, this parameter overrides the default text to include in the Tweet when sharing from the site. | ||
| lang | string | The language for the Tweet button. | ||
| related | string | Related accounts to suggest to the user. Using this field you can suggest accounts for a user to follow once they have sent a Tweet using your Tweet Button. | ||
| These following fields are relevant only if provider='comments': | ||||
| categoryID | string | The identifier of the Comments category for which the comments button is displayed. This field, with the streamID field, must be set in the ShareButton object of the comments button for the counter to be displayed. | ||
| streamID | string | The identifier of the Comments stream for which the comments button is displayed. his field, with the categoryID field, must be set in the ShareButton object of the comments button for the counter to be displayed. | ||
| These following fields are relevant only if provider='google-plusone': | ||||
| size | string | The size of the Google +1 button. Accepts the following values: "small", "medium" (default if not set), "standard", "tall". | ||
| These following fields are relevant only if provider='googleplus-share': | ||||
| width | integer | Defines the width of the button. | ||
| height | integer | Defines the height of the button. | ||
| annotation | string | The annotation to display next to the button. This parameter overrides the showCounts parameter. Accepts the following values:
| ||
| These following fields are relevant only if provider='moshare-sms': | ||||
| iconsOnly | Boolean | This parameter determines whether the moShare button is displayed as icon only, without text and borders. The default value of this parameter is 'false'. | ||
| These following fields are relevant only if provider='foursquare-save': | ||||
| vid | string | A foursquare venue ID. | ||
| variant | string | The button size to render. Can be either undefined or "wide". | ||
| hideTooltip | Boolean | The default value is "false". When set to "true" shows description tooltip on hover. | ||
Plugin Events
An Event Handler is a JavaScript function with the following signature:
functionName(eventObj)
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
| Field | Type | Description |
| eventName | string | The name of the event. |
| source | string | The source plugin that generated this event. The value of this field is the name of the plugin's API method, e.g. 'showLoginUI', 'showCommentsUI', etc. |
| context | object | The context object passed by the application as parameter to the API method, or null if no context object has been passed. |
onError Event Data
| Field | Type | Description |
| eventName | string | The name of the event. |
| source | string | The source plugin that generated this event. The value of this field is the name of the plugin's API method, e.g. 'showLoginUI', 'showCommentsUI', etc. |
| context | object | The context object passed by the application as parameter to the API method, or null if no context object has been passed. |
| 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. |
onClose Event Data
| Field | Type | Description |
| eventName | string | The name of the event. |
| source | string | The source plugin that generated this event. The value of this field is the name of the plugin's API method, e.g. 'showLoginUI', 'showCommentsUI', etc. |
| context | object | The context object passed by the application as parameter to the API method, or null if no context object has been passed. |
onSendDone Event Data
| Field | Type | Description |
| eventName | string | The name of the event. |
| source | string | The source plugin that generated this event. The value of this field is the name of the plugin's API method, e.g. 'showLoginUI', 'showCommentsUI', etc. |
| context | object | The context object passed by the application as parameter to the API method, or null if no context object has been passed. |
| providers | string | The name of the sharing target (i.e. 'twitter', 'email', etc.) |
| 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. |
onSendDone Event Data - Email
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.
| Field | Type | Description |
| eventName | string | The name of the event. |
| source | string | The source plugin that generated this event. The value of this field is the name of the plugin's API method, e.g. 'showLoginUI', 'showCommentsUI', etc. |
| context | object | The context object passed by the application as parameter to the API method, or null if no context object has been passed. |
| providers | string | 'email' |
| 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 the Sharing via Email page in the Developer's Guide.
onShareButtonClicked Event Data
| Field | Type | Description |
| eventName | string | The name of the event. |
| source | string | The source plugin that generated this event. The value of this field is the name of the plugin's API method, e.g. 'showLoginUI', 'showCommentsUI', etc. |
| context | object | The context object passed by the application as parameter to the API method, or null if no context object has been passed. |
| shareItem | ShareButton object | The object representing the share button that has been clicked. |
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 the Events page in the Developer Guide - to learn more about how to handle events generated by the Gigya service.
Code Sample
var ua = new gigya.socialize.UserAction();
ua.setLinkBack("http://www.youtube.com/watch?v=jqxENMKaeCU");
ua.setTitle("Adobe Gets Into Widget Distribution And Advertising With Help From Gigya");
var params ={
userAction:ua,
shareButtons: "facebook-like,google-plusone,share,twitter-tweet,email",
containerID: 'divButtons' // The ID of the <DIV> element on the page in which the plugin is displayed
}
// Show the share bar
gigya.socialize.showShareBarUI(params); Notes:
- This sample is not meant to be fully functional code. For brevity's sake, only the code required for demonstrating the API call itself is presented.
- To run the code on your own domain, add your Gigya API key to the socialize.js URL. A Gigya API key can be obtained on the Site Dashboard page on Gigya's website. Please make sure that the domain from which you are loading the page is the same domain name that you used for generating the API key.
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.
Comments