socialize.showReactionsBarUI JS

Skip to end of metadata
Go to start of metadata

 

Displays the Reactions plugin, which allows users to react to content in your site and share their reaction to social networks. The Reactions plugin is built out of one or more buttons, arranged horizontally in a bar. Each button represents a "reaction" to the content, such as 'LOL', 'OMG', etc.
Once a user clicks on a reaction button, a mini Share plugin will popup to suggest to him to share his reaction to the social networks.

Note: If you plan on integrating the Reactions plugin, we highly recommend reading the Reactions Plugin in the Developer's Guide, which is a step-by-step guide for integrating the Reactions plugin and also provides a reference and guide for the various customization options.

 

 

The Mini Share popup displays, by default, the first 6 providers that support share by default; in this case: Facebook, Twitter, LinkedIn, Renren, QQ and VKontakte.
You may customize this list using the enabledProviders and disabledProviders parameters. The supported social networks are: Facebook, Twitter, Microsoft, LinkedIn, Tencent QQ, Renren, VKontakte and Sina Weibo (the plugin may show a maximum of six network buttons).

 

Syntax

 

 

Parameters

The following table lists the available parameters:

RequiredNameTypeDescription
reactionsarrayAn array of Reaction objects, representing the buttons to display in the reactions bar.  No more than ten reaction buttons can be displayed.
containerIDstringThe ID of the <div> element in which to display the plugin.
userActionUserAction objectThe user action to publish. The UserAction object enfolds newsfeed data, including text, media, link, etc.
When Twitter is the provider, only the Title and Link Back are posted.
barIDstringA unique identifier that identifies the content item to which the user reacted. This will be used for associating counts with the reaction. Limited to 100 characters.
actionAttributesJSON objectIn Gamification your users receive points for actions they perform on your site, in this case clicking a reaction 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 reaction, 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.
Example:  {"<attribute key1>": ["<attribute value1>", "<attribute value2>"],  "<attribute key2>": "<attribute value3>" }

bodyTextstringThis text will be presented as the second line of text in the mini-share that pops-up when clicking one of the reaction buttons.
buttonImagesJSON objectUsing this object you may override the default design of a reaction button. Specify your alternative button images using the object fields. The following fields are supported:
buttonLeftImgUp, buttonLeftImgDown, buttonLeftImgDisabled, buttonLeftImgOver, buttonCenterBGImgUp, buttonCenterBGImgDown, buttonCenterBGImgDisabled, buttonCenterBGImgOver, buttonRightImgUp, buttonRightImgDown, buttonRightImgDisabled, buttonRightImgOver.
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.
buttonTemplatestring
(HTML)
Using this parameter you may override the default design of a reaction button. Defines an HTML template representing the design of a single button. The HTML template supports the following placeholders: $iconImg, $text, $count, $onClick.
cancelReactionsBooleanThis parameter determines whether a user is allowed to cancel a reaction that he previously clicked. The default value is of this parameter is 'true'.
cidstring
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.

Note: This parameter overrides the value of the identical parameter in Global Conf (the global configuration object). If the parameter is not set for the method, the value from Global Conf is used.

contextobjectA 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).
countTypestringThis parameter determines the type of the counter. The options are:
  • 'number' (default) - the number of times the reaction was clicked.
  • 'percentage' - the percentage of users who clicked on the specific reaction button out of the total clicked on all reaction buttons in the reaction bar.
disabledProvidersstringA comma delimited list of providers that should not be displayed on this plugin. Valid provider names include: 'facebook', 'twitter', 'microsoft', 'linkedin''qq', 'renren', 'sina'. For example, if you would like this plugin to show all providers icons but LinkedIn and Twitter, define: disabledProviders: "linkedin,twitter". (Note: messenger has been replaced by microsoft, however, for backward compatibility, either can be used). 

Note: This parameter overrides the value of the identical parameter in Global Conf (the global configuration object). If the parameter is not set for the method, the value from Global Conf is used.

enabledProvidersstringA comma delimited list of providers that should be displayed on this plugin. Valid provider names include: 'facebook', 'twitter', 'microsoft', 'linkedin', 'qq', 'renren', 'sina'. For example, if you would like this plugin to show only the icons of Facebook and Twitter, define: enabledProviders: "facebook,twitter". (Note: messenger has been replaced by microsoft, however, for backward compatibility, either can be used). 
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: This parameter overrides the value of the identical parameter in Global Conf (the global configuration object). If the parameter is not set for the method, the value from Global Conf is used.

headerTextstringThis text will be presented as the first line of text in the mini-share that pops-up when clicking one of the reaction buttons.
layoutstringSets the arrangement of buttons in the bar. May be:
  • 'horizontal' (default)
  • 'vertical'
multipleReactionsBooleanThis parameter determines whether the user is permitted to click on multiple reaction buttons on the same reaction bar, or click on one reaction button only. If set to false, the user is allowed to click only one button, after which all other buttons are disabled. The default value of this parameter is 'true' (allowing multiple reactions).
noButtonBordersBooleanThis parameter determines whether the reaction is displayed without borders. The default value of this parameter is 'false' (the reaction button is displayed with borders).
promptShareBooleanThis parameter determines whether the user is prompted to share his reaction to social networks. The default value of this parameter is 'true'.
sessionExpirationintegerThis 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.
shortURLsstring
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:
  • 'always' (default): always try to shorten URLs. Where providers permit, URLs are shortened based on the Data Center you are using.
    fw.to for US DC.
    shr.gs   for users of the European data center.
    vst.to for Australian DC.
  • 'whenRequired': URLs longer than 139 characters are shortened in accordance with provider preferences.
  • 'never' - never shorten URLs. Where providers permit, URLs are left untouched.

URL shortening requirements vary between providers and depend on the particular type of action and its content. URL shortening is available for the following providers:

ProviderNote
FacebookN/A
TwitterN/A
LinkedInShortened URL is posted to the social network but traffic reports show abbreviated URL (e.g., http://developers.gigya.com/display/GD/showShareBarUI+JS is abbreviated to developers.gigya.com).
MicrosoftNot for share. (Note: messenger has been replaced by microsoft, however, for backward compatibility, either can be used).
DeliciousShortened URL is posted to the social network but traffic reports show abbreviated URL (e.g., http://developers.gigya.com/display/GD/showShareBarUI+JS is abbreviated to developers.gigya.com).
WhatsAppOnly on mobile.
RedditN/A
GooglePlusN/A
Google BookmarksN/A
VKontakteN/A
nk.plN/A
XingN/A
TuentiN/A
HatenaN/A
PinterestShortened URL is posted to the social network but traffic reports show abbreviated URL (e.g., http://developers.gigya.com/display/GD/showShareBarUI+JS is abbreviated to developers.gigya.com).
BaiduN/A
FriendFeedN/A
TumblrN/A
SinaN/A
mixiN/A

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.

 


Note: This parameter overrides the value of the identical parameter in Global Conf (the global configuration object). If the parameter is not set for the method, the value from Global Conf is used.

showCountsstringThis parameter determines if and where to display the share counts in relation to the reaction button. The options are:
  • 'none' (default)
  • 'top'
  • 'right'
showSuccessMessageBooleanProvides the user with success feedback on sharing. The default value of this parameter is 'false'. When this parameter is set to 'true', a success message is displayed with the following wording: 
  • "Reaction shared successfully"
Auto Share related Parameters:
To learn more about this feature, please read the Automatic Sharing guide.
showAlwaysSharestringThis 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 barID parameter (see above). 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:
  • 'hide' (default) - do not display the "Always share" checkbox.
  • 'checked' - the "Always share" checkbox is displayed and checked by default.
  • 'unchecked' - the "Always share" checkbox is displayed and unchecked by default.
autoShareActionIDstringUse this parameter to specify a unique identifier for the type of action that the user has performed on your site. For example: "Reacted", "Liked", etc.
The user selection (Always Share) will apply only to this ID.
autoShareExpirationstringUsing this parameter, you may assign an expiration date/time for the user selection for the specific barID. The default is never expire. The expected format is the Unix time format (i.e. the number of milliseconds since Jan. 1st 1970).
Events Registration Parameters:  
onReactionClickedfunction refA reference to an event handler function that will be called when one of the reaction buttons is clicked.
onReactionUnclickedfunction refA reference to an event handler function that will be called when one of the reaction buttons is unclicked.
onSendDonefunction refA reference to an event handler function that will be called when the process of publishing the newsfeed to all selected social networks has finished.
onLoadfunction refA reference to an event handler function that will be called when the plugin has finished drawing itself.
onErrorfunction refA reference to an event handler function that will be called when an error occurs.

 

Reaction Object

A JSON-encoded object representing a single button in the reactions bar:

RequiredField NameTypeDescription
IDstringAn identifier for this reaction button. The identifier should be unique within the scope of this method call. Limited to 100 characters.
textstringThe text to display on the button.
iconImgUpstringPath to an image file to display on the reaction button.
iconImgOverstringPath to an image file to display on the reaction button on mouse over.
iconImgDownstringPath to an image file to display on the reaction button when the button is pressed.
tooltipstringTooltip to show when mouse over.
headerTextstringIf defined, this parameter overrides the parallel method param for this reaction button.
bodyTextstringIf defined, this parameter overrides the parallel method param for this reaction button.
feedMessagestringIf defined, this parameter's value is added to the title of the feed displaying the reaction.
enableCountBooleanAllows to enable/disable a counter for a specific reaction.
noButtonBordersBooleanIf defined, this parameter overrides the parallel method param for this reaction button.
userMessagestringDeprecated. If defined, this parameter overrides the userMessage field of the default userAction method param for this reaction button.

  

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

FieldTypeDescription
   
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.
contextobject 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

FieldTypeDescription
   
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.
contextobject The context object passed by the application as parameter to the API method, or null if no context object has been passed.
errorCodeintegerThe 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.
errorMessagestringA short textual description of an error, associated with the errorCode, for logging purposes.
errorDetailsstringThis field will contain the exception info, if available.

onReactionClicked Event Data

FieldTypeDescription
   
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.
contextobject The context object passed by the application as parameter to the API method, or null if no context object has been passed.
reactionReaction objectThe object representing the reaction button that has been clicked.

 

onReactionUnclicked Event Data

FieldTypeDescription
   
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.
contextobject The context object passed by the application as parameter to the API method, or null if no context object has been passed.
reactionReaction objectThe object representing the reaction button that has been unclicked.

 

onSendDone Event Data

FieldTypeDescription
   
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.
contextobject The context object passed by the application as parameter to the API method, or null if no context object has been passed.
providersstringA comma separated list of social networks to which the newsfeed was successfully published.
userMessagestringThe textual message that the user entered in the editable text box of the Share plugin (see screenshot above).
targetURLstringThe URL that was shared.
providerPostIDsarrayAn array of JSON objects representing the social network's post ID. Each object has the following fields:
  • provider - the social network provider (string). The optional values are: 'facebook','twitter' or 'microsoft'. (Note: messenger has been replaced by microsoft, however, for backward compatibility, either can be used). 
  • postID - the unique ID of the post (string).

 

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

var reactions=[
{
        text: 'Recommend', 
        ID: 'Recommend', 
        iconImgUp:'http://cdn.gigya.com/gs/i/reactions/icons/Recommend_Icon_Up.png', 
        iconImgOver:'http://cdn.gigya.com/gs/i/reactions/icons/Recommend_Icon_Down.png', 
        tooltip:'I recommend this item', 
        feedMessage: 'I recommend this!', 
        headerText:'You recommend this post,'
}
,{
        text: 'LOL',
        ID: 'lol',
        feedMessage: 'I LOL this!',
        headerText:'This post made you LOL,'
}];

var defaultUserAction = new gigya.socialize.UserAction();

defaultUserAction.setTitle("This is the post title");
defaultUserAction.setLinkBack("http://www.gigya.com");

var params = 
{
        barID: 'myID',
        containerID:'reactionsDiv',
        reactions:reactions,
        userAction:defaultUserAction,
        bodyText:'Share it with your friends',
        onReactionClicked : function(a){alert("Reaction Clicked!");}
};

// Show the Reactions buttons bar
gigya.socialize.showReactionsBarUI(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 gigya.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 Reactions Plugin demo you will find a complete working example which uses the socialize.showReactionsBarUI method. You may view the code, run it and view the outcome.