Table of contents
Description
Displays the "Reaction" 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 following social networks: Facebook, Twitter, Yahoo, Messenger, LinkedIn.
You may customize this list using the enabledProviders and disabledProviders parameters. The supported social networks are: Facebook, Twitter, Yahoo, Microsoft Messenger, LinkedIn, Myspace, Orkut, Tencent QQ, Renren, and Sina Weibo (the plugin may show maximum six network buttons).
Syntax
gigya.socialize.showReactionsBarUI(params)
Method Parameters
The following table lists the params object members:
| Required | Name | Type | Description |
| Required | reactions | array | An array of Reaction objects, representing the buttons to display in the reactions bar. |
| 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 publish. The UserAction object enfolds newsfeed data, including text, media, link, etc. | |
| barID | string | A unique identifier that identifies the content item to which the user reacted. This will be used for associating counts with the reaction. | |
| Optional | headerText | string | This text will be presented as the first line of text in the mini-share that pops-up when clicking one of the reaction buttons. |
| bodyText | string | This text will be presented as the second line of text in the mini-share that pops-up when clicking one of the reaction buttons. | |
| multipleReactions | Boolean | This 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 is of this parameter is 'true' (allowing multiple reactions). | |
| cancelReactions | Boolean | This parameter determines whether a user is allowed to cancel a reaction that he previously clicked. The default value is of this parameter is 'true'. | |
| countType | string | This parameter determines the type of the counter. The options are:
| |
| showCounts | string | This parameter determines if and where to display the share counts in relation to the reaction button. The options are:
| |
| promptShare | Boolean | This parameter determines whether the user is prompted to share his reaction to social networks. The default value of this parameter is 'true'. | |
| noButtonBorders | Boolean | This parameter determines whether the reaction is displayed without borders. The default value of this parameter is 'false' (the reaction button is displayed with borders). | |
| layout | string | Sets the arrangement of buttons in the bar. May be:
| |
| buttonTemplate | string (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. | |
| buttonImages | JSON object | Using 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. | |
| enabledProviders | string | A comma delimited list of providers that should be displayed on this plugin. Valid provider names include: 'facebook', 'twitter', 'yahoo', 'messenger', 'linkedin', 'myspace', 'orkut', 'qq', 'renren', 'sina', 'yahoo-japan'. 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. Valid provider names include: 'facebook', 'twitter', 'yahoo', 'messenger', 'linkedin', 'myspace', 'orkut', 'qq', 'renren', 'sina', 'yahoo-japan'. 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. | |
| 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. | |
| 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. | |
| actionAttributes | JSON object | In 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. 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"], | |
| showSuccessMessage | Boolean | Provides 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:
| |
| Auto Share related Parameters: 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 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:
| |
| 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: "Reacted", "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 barID. 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. The autoShareActionDisplay string will be appended to the "Always share" string, i.e. "Always share XXX" where XXX is the autoShareActionDisplay string. The default value of autoShareActionDisplay is the string "this". | |
| Activity Feed Plugin related Parameters: The following parameters are relevant only if you are integrating the Activity Feed Plugin in your site |
|||
| scope | string | When publishing feed items, by default the feed items are published to social networks only and will not appear on the site's Activity Feed plugin. To change this behavior, you must change the publish scope. The optional values for this parameter are:
|
|
| privacy | string | The privacy level determines how the user action is presented in each of the Activity Feed plugin tabs. The optional values for this parameter are:
|
|
| feedID | string | The purpose of this parameter is to support multiple feed streams with different feeds on the same domain. You may give a different feedID to different Activity Feed Plugins in your site. The Activity Feed plugin will show only User Actions that were published with the same feedID (please refer to the same parameter in the showFeedUI method). Using this parameter you may choose to which Activity Feed Plugin on your site this User Action will be published. If this parameter is not set, it will be published on an Activity Feed Plugin that has no feedID (default). |
|
| Events Registration Parameters: | |||
| onReactionClicked | function ref | A reference to an event handler function that will be called when one of the reaction buttons is clicked. | |
| onReactionUnclicked | function ref | A reference to an event handler function that will be called when one of the reaction buttons is unclicked. | |
| onSendDone | function ref | A reference to an event handler function that will be called when the process of publishing the newsfeed to all selected social networks, has finished. | |
| 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. | |
Reaction Object
A JSON-encoded object representing a single button in the reactions bar:
| Required | Field Name | Type | Description |
| Required | ID | string | An identifier for this reaction button. The identifier should be unique within the scope of this method call. |
| Optional | text | string | The text to display on the button. |
| iconImgUp | string | Path to an image file to display on the reaction button. | |
| iconImgOver | string | Path to an image file to display on the reaction button on mouse over. | |
| iconImgDown | string | Path to an image file to display on the reaction button when the button is pressed. | |
| tooltip | string | Tooltip to show when mouse over. | |
| headerText | string | If defined, this parameter overrides the parallel method param for this reaction button. | |
| bodyText | string | If defined, this parameter overrides the parallel method param for this reaction button. | |
| feedMessage | string | If defined, this parameter's value is added to the title of the feed displaying the reaction. | |
| enableCount | Boolean | Allows to enable/disable a counter for a specific reaction. | |
| noButtonBorders | Boolean | If defined, this parameter overrides the parallel method param for this reaction button. | |
| userMessage | string | Deprecated. 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
| 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. |
onReactionClicked 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. |
| reaction | Reaction object | The object representing the reaction button that has been clicked. |
onReactionUnclicked 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. |
| reaction | Reaction object | The object representing the reaction button that has been unclicked. |
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 | A comma separated list of social networks to which the newsfeed was successfully published. |
| userMessage | string | The textual message that the user entered in the editable text box of the Share plugin (see screenshot above). |
| targetURL | string | The URL that was shared. |
| providerPostIDs | array | An array of JSON objects representing the social network's post ID. Each object has the following fields:
|
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 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 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 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.
Comments