Was this article helpful?

socialize.showFriendSelectorUI

Last modified 11:38, 15 Sep 2014

Description

Displays a "Friends selector" plugin. The plugin presents a list of confirmed friends from which the user can browse and select a group of friends. The selected friends are returned as a Collection of Friend objects as part of the onSelectionDone event data.

Refer to the Events page in the Developer's Guide - to learn more about how to handle events generated by plugins.

Currently the plugin displays by default friends from the following providers: Facebook, TwitterYahoo, Microsoft MessengerLinkedIn, FourSquare, Renren, Kaixin, Vkontakte, mixi, Yahoo Japan.

Plugin's Default Design (popup version):

FriendSelectorUI-html.gif

The plugin's design is customizable through the use of the parameters listed below.
In addition, you may assign CSS style to elements on the plugin that has an ID. You may use Firebug to identify an HTML element on the plugin and assign a new style to it. Please make sure to use the plugin's container <div> ID when assigning style, so it will not affect other elements on the page.
You are welcome to consult Gigya's support team to guide you through advanced UI customizations. You can 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.

 

 

Syntax

gigya.socialize.showFriendSelectorUI(params)

 

Method Parameters

The following table lists the params object members:

Required Name Type Description
Optional width integer Determines the width you desire for the plugin.
  height integer Determines the height you desire for the plugin.

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.
  captionText string Sets the caption text. This parameter is relevant only when the plugin is in a popup mode (i.e. if the containerID/container parameter is not provided). If the plugin is embedded in the page then the caption is not presented.
  context object A reference to a developer created object that will be passed back unchanged to the event handlers of any event triggered as a consequence of using this plugin. The context object will be passed as one of the fields of the eventObj received by the event handler (see extended explanation in the "Plugin Events" and in the "Global Event Triggered" sections below).
  showEditLink Boolean Show or hide the "Edit" link. Clicking the "Edit" link opens a popup dialog that enables the user to edit his connection status to each of the social networks.
  okButtonText string Defines the text that would be presented on the confirmation button of the Friend Selector Plugin. The default text is: "OK".
  enabledProviders string A comma delimited list of providers that should be included in this Plugin. Valid provider names include: 'facebook', 'twitter', 'yahoo', 'messenger', 'linkedin', 'foursquare', 'renren', 'kaixin', 'vkontakte', 'mixi', 'yahoojapan'.
For example, if you would like this Plugin to show friends only from Facebook and Twitter, define: enabledProviders="facebook,twitter".
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 be excluded from this Plugin. Valid provider names include: 'facebook', 'twitter', 'yahoo', 'messenger', 'linkedin', 'foursquare','renren', 'kaixin', 'vkontakte', 'mixi', 'yahoojapan'.
For example, if you would like this Plugin to show all providers 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.
  requiredCapabilities string A comma separated list of any of the following capabilities: Login, Notifications, Actions, Friends, Status, Photos, Contacts. Only providers that are available and support all the required capabilities will be visible.
The default required capability is: 'friends'.
  maxItems integer When the value is greater than 0, defines how many friends can be selected in the UI. The default value is '0', indication that there is no limit.
  minItems integer Defines a minimum number of friends that must be selected. The default value is '1'.
  detailLevel string This field is passed from socialize.getFriendsInfo, and indicates whether to provide basic or extended information about each friend. See the Friend object page for details on which fields are included for each detail level.

Allowed values are:
basic - Basic detail level. This is the default.
extended - Extended detail level.

  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.
 Events Registration Parameters  
  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:
  • If the Plugin is displayed as a popup the event will be fired when the Plugin is closing.
  • If the Plugin is embedded in 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.
      onSelectionDone function ref A reference to an event handler function that will be called when the user has finished selecting friends in the Plugin and clicked the "OK" 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.

 

onClose 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.

 

onSelectionDone 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.
friends Collection A collection of basic? Friend objects, representing the list of the selected friends.
UIDs string A comma separated list of friends' user IDs, representing the list of the selected friends.
Note: The UIDs list is equivalent to the 'friends' Collection field.

 

Global Event Triggered

There are no global events that may be triggered by using this Plugin.

 

Code Sample

var context = {
	msg:'This is my params.context.msg'
};	

var params = { 
    requiredCapabilities: 'notifications',
    context:context
};

params['onSelectionDone'] = function(evt) {            
	var msg = evt.eventName + ' - ' + ' selected: ';
	var friends = evt['friends'];            
	if ( null!=friends) {
	    var friendsArr = friends['arr'];
	    if ( null!=friendsArr && friendsArr.length>0) { 
		    for (var index in friendsArr ) {  
		        var friend = friendsArr[index];
		        var name = ' - Friend\'s Name is :'+friend['name'] + '('+friend['nickname']+')';
		        msg += name + '\n';
		    }
	    }
	    else {
	        msg += ' - Error: Friends list is empty or null';
	    }
	}
	else {
		msg += ' - Error: No friends were returned ';                 
	}            
	alert(msg);
};  

gigya.socialize.showFriendSelectorUI(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 some cases it is necessary to connect/login the user to a provider? prior to calling the API method. You can learn more in the Social Login guide.

Tags

This page has no custom tags.

Comments

You must to post a comment.

Attachments