Was this article helpful?

socialize.showReactionsBarUI

Last modified 05:45, 25 Nov 2014

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.

 

 ReactionUI-comments.gif

The Mini Share popup displays, by default, the first 6 providers that support share by default, in this case the following social networks: 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 Messenger, LinkedIn, Tencent QQ, Renren, VKontakte 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.  No more than ten reaction buttons can be displayed.
  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. Limited to 100 characters.
Optional 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. 
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>" }
  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.
  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.
  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.
  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'.
  cid string 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: 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).
  countType string This 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.
  disabledProviders string A comma delimited list of providers that should not be displayed on this plugin. Valid provider names include: 'facebook', 'twitter', 'messenger', '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: the value of this parameter overrides the value of the identical parameter in the global configuration object.
  enabledProviders string A comma delimited list of providers that should be displayed on this plugin. Valid provider names include: 'facebook', 'twitter', 'messenger', '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: 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.
  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.
  layout string Sets the arrangement of buttons in the bar. May be:
  • 'horizontal' (default)
  • 'vertical'
  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).
  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).
  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'.
  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.
  shortURLs string

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 only available for the providers LinkedIn, QQ, Twitter, mixi, and Hatena.
When Gigya's URL shortening service is active, Gigya tracks all the traffic coming from the distributed URLs. In such case, 'Referred Traffic' reportswill be available to you.


Note: the value of this parameter overrides the value of the identical parameter in the global configuration object.
  showCounts string This parameter determines if and where to display the share counts in relation to the reaction button. The options are:
  • 'none' (default)
  • 'top'
  • 'right'
  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: 
  • "Reaction shared successfully"
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:
  • '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.
  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).
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:
  • 'external' (default) - the feed item will be published externally to social networks and will appear on social networks' feed streams (but not on the site's Activity Feed plugin).
  • 'both' - the feed item will be published internally to the site and externally to social networks. The feed item will appear both on social networks' feed streams and on the site's Activity Feed plugin.
  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:
  • 'public' - Public items appear in all tabs with the publisher's identity (user name and image).
  • 'friends' - Friends items appear in the 'Friends' and 'Me' tabs with identity, and anonymously in the 'Everyone' tab.
  • 'private' (default) - Private actions appear in the 'Me' tab, and anonymously in the 'Friends' and 'Everyone' tabs. An exception to this rule: If the item has been shared to social networks, then it will be presented as "identified" (with user name and image) in the 'Friends' tab.
  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. Limited to 100 characters.
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.
sourcestringThe 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.
sourcestringThe 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.
sourcestringThe 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.
sourcestringThe 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.
sourcestringThe 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:
  • provider - the social network provider (string). The optional values are: 'facebook','twitter' or 'messenger'.
  • 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 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. 

Tags

This page has no custom tags.
This page has no classifications.

Comments

You must to post a comment.

Attachments