Description
Displays a "Friends selector" Widget. The Widget 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 Widgets.
Currently the Widget displays, by default, friends from the following providers: Facebook, Myspace, Twitter, Yahoo, LinkedIn.
Syntax
gigya.services.socialize.showFriendSelectorUI(conf,params)
Method parameters
conf object
Please refer to the Conf object page for full specifications.
params object members
| Required | Name | Type | Description |
| Optional |
width |
integer |
Determines the width you desire for the Widget. |
| |
height |
integer |
Determines the height you desire for the Widget. |
|
containerID |
string |
Supported in JavaScript only (In ActionScript use the container parameter instead).
An ID of a <DIV> element on the page in which you want to display the Widget.
If this parameter is not provided then the Widget will be displayed as a popup at the center of the page. |
| |
container |
object reference |
Supported in ActionScript only (In JavaScript use the containerID parameter instead).
Reference of a container object (e.g. Canvas) in which you want to display the Widget. If this parameter is not provided then the Widget will be displayed as a popup at the center of the application. |
| |
showCaption |
boolean |
By default the Widget shows a caption when in dialog mode and does not show one when displayed inside a div (when a containerID was provided). This allows you to override this default behavior. |
| |
captionText |
string |
Sets the caption text. This parameter is relevant only if a caption is shown (see the showCaption parameter above). |
|
showTermsLink |
boolean |
Show or hide the "Terms" link. Clicking the "Terms" link opens Gigya's Legal Notices 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 "Widget Events" section below). |
| |
UIConfig |
string (XML) |
An XML string describing changes to the default design of the Widget. |
| |
useFacebookConnect |
boolean |
Assigning "true" to this parameter, will cause Gigya Socialize to pop-up Facebook Connect UI when connecting to the user's Facebook account (i.e. when the user presses the Facebook button of the Connect UI). You may find more information about the subject in Using Facebook Connect section in the Developer Guide.
Note: this parameter is not supported in ActionScript environment.
|
| | 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 widget. The default text is: "OK". When the Friend Selector is used in the Inviting Friends flow, the default button text is "Invite Friends". |
| | limit | integer | Sets the maximum number of friends that can be selected by the user. |
| enabledProviders | string | A comma delimited list of providers that should be included in this widget. Valid provider names include: 'facebook', 'myspace', 'twitter', 'yahoo', 'linkedin'. For example, if you would like this widget 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 Conf object. |
| | disabledProviders | string | A comma delimited list of providers that should be excluded from this widget. Valid provider names include: 'facebook', 'myspace', 'twitter', 'yahoo', 'linkedin'. For example, if you would like this widget 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 Conf object. |
| | cid | string | A string of maximum 100 characters length. This string will be 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 Conf object. |
| Events Registration Parameters | |
| | onSelectionDone | function ref | A reference to an event handler function that will be called when the user has finished selecting friends in the Widget and clicked the "OK" button. |
| | onLoad | function ref | A reference to an event handler function that will be called when the Widget 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 Widget is displayed as a popup the event will be fired when the Widget is closing.
- If the Widget 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.
|
| | onError | function ref | A reference to an event handler function that will be called when an error occurs. |
Widget 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. |
| context | object | The context object passed by the application as parameter to the API method, or null if no context object has been passed. |
onClose event data
| Field | Type | Description |
| |
| eventName | string | The name of the event. |
| 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. |
| 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. |
onSelectionDone event data
| Field | Type | Description |
| |
| eventName | string | The name of the event. |
| 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 Widget.
Code Sample
var conf = {
APIKey:'2_fA4cZD0cEmxKUjDdNai8hyK4fZ-Jq7w4qm1x-pkS-7E6NDm90gAmrdcugVoaewUS'
};
var context = {
msg:'This is my params.context.msg'
};
var params = {
showCaption:true,
captionText:'This is my caption text',
showTermsLink:false,
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.services.socialize.showFriendSelectorUI(conf,params);
function showFriendSelectorUI():void {
var conf:Object = {
mcRoot:this.root,
APIKey:'2_fA4cZD0cEmxKUjDdNai8hyK4fZ-Jq7w4qm1x-pkS-7E6NDm90gAmrdcugVoaewUS'
};
var context:Object = {
msg:'This is my params.context.msg'
};
var params:Object = {
showCaption:true,
captionText:'This is my caption text',
showTermsLink:false,
context:context
};
params['onSelectionDone'] = function(evt:Object):void {
var msg:String = evt.eventName + ' - ' + ' selected: ';
var friends:Object = evt['friends'];
if ( null!=friends) {
var friendsArr:Array = friends['arr'];
if ( null!=friendsArr && friendsArr.length>0) {
for (var index:Object in friendsArr ) {
var friend:Object = friendsArr[index];
var name:String = ' - 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 ';
}
trace(msg);
};
gigya.services.socialize.showFriendSelectorUI(conf,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.
- The API key in the sample will only work on http://localhost/...
- To run the code on your own domain, modify the API key in the example to your own API key. A Gigya API Key can be obtained on the Site Setup page on Gigya's website. Please make sure that the domain you are loading the page from is the same domain name that you used for generating the API Key.
- In some cases it is necessary to connect the user to a provider? prior to calling the API method. For connecting the user to a provider, you may use the Connect API method call or the pre-built Connect Widget.
- Best practice is, to define one global conf object and use it throughout the application.