Was this article helpful?

socialize.showShareUI

Modified 15:13, 17 Mar 2013 by Tanya

1. Description
2. Syntax
3. Method Parameters
4. Plugin Events
1. 4.1. onLoad Event Data
2. 4.2. onError Event Data
3. 4.3. onClose Event Data
4. 4.4. onSendDone Event Data
5. 4.5. onSendDone Event Data - Email
5. Global Event Triggered
6. Code Sample

Description

Displays a "Share" plugin. The Share plugin is a pop-up dialog, allowing the user to publish a newsfeed to various social networks.

The plugin presents:

An editable text box providing the user with an option to edit his newsfeed message.
An abbreviated preview of the newsfeed to be published.
A list of social networks from which the user can select publishing destinations.
The plugin displays by default the following social networks: Facebook, Twitter, Yahoo,LinkedIn.
You may customize this list using the enabledProviders and disabledProviders parameters. The supported social networks are: Facebook, Twitter, Yahoo, LinkedIn, Myspace, Orkut, Yahoo-Japan, Tencent QQ, Renren, Sina Weibo, and VKontakte* (the plugin may show maximum six network buttons). *Note: the VKontakte application must be whitelisted in order for it to support share.
A "Publish" button. When the user presses the button, Gigya will attempt to publish the newsfeed to each of the social networks that the user selected (on the left hand side of the plugin).

Optional:

A "More" button - The "More" button leads to a screen presenting a selection of additional social destinations. The button is shown by default, you may hide this button using the showMoreButton parameter.
An "Email" button - The "Email" button leads to a screen for sharing via email. The button is hidden by default, you may add this button using the showEmailButton parameter.

Note: If you plan on integrating the Share plugin, we highly recommend reading the Share Plugin page in the Developer's Guide, which is a step-by-step guide for integrating the Share plugin, publishing feed items and also provides advanced customization options.

Syntax

gigya.socialize.showShareUI(params)

Method Parameters

The following table lists the params object members:

Required	Name	Type	Description
Required	userAction	UserAction object	The user action to publish. The UserAction object enfolds the newsfeed data, including text, media, link, etc.
Optional	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: 'multiSelect' (default) - Opens the Share plugin with multi-select options, enabling the user to share on multiple social networks. 'simpleShare' - Opens the Share plugin in the Simple Share mode. 'autoDetect' - Automatically opens the Share plugin according to the user's connection status; if the user is connected the Multi-select mode is displayed, and if the user is not connected the Simple Share mode is displayed.
	snapToElementID	string	The ID of the HTML element that triggers the Share plugin. This element determines where the Simple Share plugin is displayed on the screen. This parameter is relevant only when using the Simple Share mode (only if the operationMode parameter is set to 'simpleShare' or 'autoDetect').
	containerID	string	An ID of a <DIV> element on the page in which you want to display the plugin. If this parameter is not provided then the plugin will be displayed as a popup at the center of the page. Please refer to Dialog or Embedded section for extended explanation.
	enabledProviders	string	A comma delimited list of providers that should be displayed on this plugin. Valid provider names include: 'facebook', 'twitter', 'yahoo', 'linkedin', 'myspace', 'orkut', 'yahoo-japan', 'qq', 'renren', 'sina', 'vknotakte'.* 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', 'linkedin', 'myspace', 'orkut', 'yahoo-japan', 'qq', 'renren', 'sina', 'vkontakte'.* 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. 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 the user clicks the user message input box in the shareUI, the text disappears. The default text is "Write your message...".
	showSuccessMessage	Boolean	Using this parameter, you may add a success message to the share UI, notifying the user of a successful publish. The default value of this parameter is 'true'. If this parameter is set to 'true', when the syndication process completes, a message would appear to the user, saying: "Message posted successfully".
	grayedOutScreenOpacity	integer (0-100)	This parameter allows you to gray-out the screen behind the plugin to emphasize the "modal" environment. 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: 0 - clear (not grayed out). This is the default, if this parameter is not set. 100 - opaque (blacked out). 20 - is our recommended value for gray-out opacity.
	initialView	string	Determines the initial view of the plugin when it loads. There are three options: 'share' (default) - shows the default share view. 'more' - shows the "More" view. This option is only relevant if the showMoreButton parameter (see below) is set to 'true'. To learn more, please read the Adding More Destinations page. 'email' - shows the "Email" view. This option is only relevant if the showEmailButton parameter (see below) is set to 'true'. To learn more, please read the Sharing via Email page.
	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: 'always' - always shorten URLs. 'whenRequired' (default) - shorten URLs when needed - when posting to Twitter, LinkedIn, MySpace and Yahoo where the status update is limited to 140 char. 'never' - never shorten URLs. When Gigya's URL shortening service is active, Gigya tracks all the traffic coming from the distributed URLs. In such cases, 'Referred Traffic' reports will be available to you. 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.
	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: *postShareAction* - accepts two values: "close" (default) and "connect". When "connect" is used, then after the user clicks on a button of a social network that supports authentication, a dialog is displayed, offering to connect the user to your site with the selected social network. *postShareConnectCaptionText* - The text that is displayed as the header of the connect dialog. The default text is "Thanks for sharing!". *postShareConnectBodyText* - The text that is displayed in the body of the connect dialog. The default text is "To make sharing even simpler". This parameter is relevant only when using the Simple Share mode (only if the operationMode parameter (see above) is set to 'simpleShare' or 'autoDetect'). Read more about this feature in the Post Share Connection section.
	deviceType	string	Determines the type of the device on which the Share plugin UI is displayed in Simple Share mode. The parameter supports the following values: desktop (default) - render the share in regular mode mobile - render the share in mobile view mode auto - identify the device (user-agent) and if it is a mobile device, render in the mobile view mode
	shareTimeout	integer	Sets a timeout to the sharing operation. Set this parameter with the maximum number of seconds to wait for 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 mouse hover over a social network icon. The tooltip presents the social network's full name.
	tags	string	A comma separated list of tags that are used to identify the share operation.
	actionAttributes	JSON object	In Gamification your users receive points for actions they perform on your site, in this case sharing 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 performs a share action, 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.: { "<attribute1 name>": ["<attribute1 value1>", "<attribute1 value2>", ...], "<attribute2 name>": "<attribute2 value>", ... } For example: { "tv-show": ["glee", "30rock"], "music": "pop" } In this example the action receives three attributes: {"tv-show":"glee"}, {"tv-show":"30rock"}, and {"music":"pop"}. This parameter may receive a list of up to three sets of key and value entries per call. If more values are entered, only the first three will count and the rest will be ignored. The three sets of key and value can be one key with three values, or three keys with one value each, or two keys, one with two values and the other with one value. You can also choose to input attributes using a generic "Tags" key, with no category name, for example: {"tags": ["glee", "house", "pop"]}. In this case the action receives these three attributes: {"tags":"glee"}, {"tags":"house"}, and {"tags":"pop"}.
	useHTML	Boolean	Deprecated. The plugin is available in both Flash and HTML versions. By default, the HTML version is used. You may override the default behavior. Setting this parameter with the value 'false', will force Gigya to use the Flash version.
	successMessage	Boolean	*Deprecated*. Using this parameter, you may add a success message to the share UI, notifying the user of a successful publication. The default value of this parameter is 'false'. If this parameter is set to 'true', when the syndication process completes, a message would appear to the user, saying: "Message posted successfully".
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).
'More' Screen related Parameters:
	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 to 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.
Email Screen 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, 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$, $userMsg$, $title$, $description$, and $actionLinkTitle$. 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'. When emailProviders=' ', the Import Contacts header in the Share UI for share via email is hidden.
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 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: '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. Note: to apply this feature, you must set both showAlwaysShare and the autoShareActionID parameters.
	showNeverShare	Boolean	This parameter determines whether to show a "Never share" link at the bottom of the Share plugin. If the user clicks this link, the Share plugin will close and Gigya will never prompt the Share plugin when this user repeats the same type of action. The type of action is determined using the autoShareActionID parameter (see below). Note: to apply this feature, you must set both showNeverShare and the autoShareActionID parameters.
	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", etc. The user selection (Always/Never 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". Note: this field can be no longer than 12 characters.
Events Registration Parameters:
	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.
	onClose	function ref	A reference to an event handler function that will be called in one of the following scenarios: If the plugin is displayed as a popup the event will be fired when the plugin closes. If the plugin is embedded in the page the event will be fired when the user clicks a button that indicates the dialog should be closed. In this case the dialog will not hide itself automatically.
	onError	function ref	A reference to an event handler function that will be called when an error occurs.
	onSend	function ref	Deprecated. Please use the onSendDone event instead.

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	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', 'yahoo'. postID - the unique ID of the post (string).

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.

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

// Constructing a UserAction Object
var act = new gigya.socialize.UserAction();

act.setTitle("This is my title");  // Setting the Title
act.setLinkBack("http://www.gigya.com/site/content/socialize.aspx");  // Setting the Link Back
act.setDescription("This is my Description");   // Setting Description
act.addActionLink("Read More", "http://www.gigya.com/site/content/socialize.aspx");  // Adding Action Link
// Adding a Media (image)
act.addMediaItem( { type: 'image', src: 'http://gigya.com/site/images/bsAPI/gs_logo.jpg', href: 'http://www.gigya.com/site/content/socialize.aspx' });
			
var params = 
{
    userAction:act
    ,showMoreButton: true // Enable the "More" button and screen
    ,showEmailButton: true // Enable the "Email" button and screen
};

// Show the "Share" dialog
gigya.socialize.showShareUI(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 Share plugin demo you will find a complete working example that uses the socialize.showShareUI method. You may view the code, run it and view the outcome.

Table of contents

socialize.showShareUI

Table of contents

Description

Syntax

Method Parameters

Plugin Events

onLoad Event Data

onError Event Data

onClose Event Data

onSendDone Event Data

onSendDone Event Data - Email

Global Event Triggered

Code Sample

Tags

Comments

Attachments

Table of contents