Contacts Control

Contacts Control

Windows Live

Contacts Control

This topic describes the parameters and default values created when you add the Contacts control to enable Windows Live™ Contacts functionality on a Web page.

Syntax

<live:Contacts 
      ID="id" 
      DataDesired="data" 
      Height="height" 
      PrivacyStatementURL="privacy_url" 
      View="view" 
      Width="width" 
/>

Parameters

The parameters shown in the syntax section and in the beginning of the parameters table are the parameters created when dragging the control from the Toolbox and dropping it on a Web page. The default values in the description are also those created when dragging the control from the Toolbox and dropping it on a Web page.

Parameter	Description
ID	Required. The unique identifier for the control on the Web page. The default value is Contacts1.
DataDesired	Optional for List view; ignored otherwise. A comma-separated list of contact information that the control returns. The valid values are name, email, phone, firstname, middlename, lastname, nickname, passportname, emailpersonal, emailbusiness, emailother, phonepersonal, phonebusiness, phonemobile, phonepager, phonefax, phoneother, personalstreet, personalcity, personalstate, personalcountry, personalpostalcode, businessname, businessstreet, businesscity, businessstate, businesscountry, businesspostalcode, websitepersonal, websitebusiness, spacesrssurl, spacesrsscontent. The default value is name,email.
Height	Optional. The height of the control on the Web page. The default value is 500px.
PrivacyStatementURL	Required. A URL to the Web site privacy statement. Dragging the control to a Web page creates an empty privacyPolicy.htm file in your project and sets this parameter to ~/privacyPolicy.htm.
View	Optional. The view presented by the control. The valid values are List, Tile, and TileList. The default value is TileList.
Width	Optional. The width of the control on the Web page. The default value is 250px.
Message	Optional for Tile view; ignored otherwise. A string that is inserted into instant messages and e-mails when in Tile view. If omitted, the control defaults to the URL of the Web site. This parameter can be an empty string ("").
Market	Optional. The market or language requested. The following values are supported: zh-cn (simplified Chinese) nl (Dutch) en (English) fr (French) de (German) it (Italian) ja (Japanese) ko (Korean) sp (Spanish pt-br (Portuguese Brazlian) sv (Swedish) The default value is en (English).
InnerBackgroundColor	Optional. The background color of the inner area of the control. This means you can specify a color name, such as salmon, or a #ffffff value, such as #ff0000 for red. If no color is specified, the default colors apply.
InnerTextColor	Optional. The color of the inner text. See InnerBackgroundColor parameter for values.
OuterBackgroundColor	Optional. The background color of the outer area of the control. See the InnerBackgroundColor parameter for values.
OuterTextColor	Optional. The color of the outer text. See the InnerBackgroundColor parameter for values.
LinkColor	Optional. The color of links in the control. See the InnerBackgroundColor parameter for values.

Note:
As with any control, the Contacts control parameters can be retrieved or set in server-side code and retrieved in client-side code. What makes the Contacts control special is that these parameters also can be set in client-side code. The only additional work required is if you update the look of the control, remember also to update the DOM.

Events

The Contacts control can raise both server and client events. Server events occur after client events and are handled in server-side code that you write for the Web page. Client events are handled in client script, typically ECMAScript (JavaScript), and are raised before server events. The server-side events are triggered even if client-side events are not present.

Event	Designation: Server or Client	Description
OnClientSignIn	Client	Raised when the user signs in.
OnClientSignOut	Client	Raised when the user signs out.
OnClientData	Client	Raised when data about the contact is received.
OnClientCommit	Client	Raised when changes related to a user’s contacts are committed to the contacts store.
OnClientError	Client	Raised when an error is detected.
OnClientLoad	Client	Raised when the control is loaded.
OnServerSignIn	Server	Raised when the user signs in.
OnServerSignOut	Server	Raised when the user signs out.
OnServerData	Server	Raised when data about the contact is received.
OnServerCommit	Server	Raised when changes related to a user’s contacts are committed to the contacts store.
OnServerError	Server	Raised when an error is detected.

OnClientSignIn Event

A client event that is raised when the user signs in.

JavaScript Syntax

function OnClientSignInHandler (sender, args)

Parameters

Parameter	Description
sender	The DOM element raising the event.
args	The event arguments object. This object has the methods `get_cancel` and `set_cancel`.

Remarks

Use the set_cancel method to cancel the execution of the associated server event.

OnClientSignOut Event

A client event that is raised when the user signs out.

JavaScript Syntax

function OnClientSignOutHandler(sender, args)

Parameters

Parameter	Description
sender	The DOM element raising the event.
args	The event arguments object. This object has the methods `get_cancel` and `set_cancel`.

Remarks

Use the set_cancel method to cancel the execution of the associated server event.

OnClientData Event

A client event that is raised when data about the contact is received.

JavaScript Syntax

function OnClientDataHandler(sender, args)

Parameters

Parameter	Description
sender	The DOM element raising the event.
args	The event arguments object. This object has the methods `get_cancel` and `set_cancel`.

Remarks

Use the set_cancel method to cancel the execution of the associated server event. Contact information is provided in the properties of the object, in camel-capped style, first letter lowercase. The contacts object contains only the fields requested in the DataDesired property.

Example

The following example demonstrates how to display the information returned when this event handler is called.

function OnClientData(sender, args)
{
   var c = args.contacts;
   var l = c.length;
   var s = l + " contacts records received\n";

   for(var i = 0; i < l; i++)
   {
      for (var j in c[i])
      {
         s += j + ": " + c[i][j] + "\n";
      }
   }
   
   alert(s);
}

OnClientCommit Event

A client event that is raised when changes related to a user’s contacts are committed to the contacts store.

JavaScript Syntax

function OnClientCommitHandler(sender, args)

Parameters

Parameter	Description
sender	The DOM element raising the event.
args	The event arguments object. This object has the methods `get_cancel`, `get_description`, and `set_cancel`.

Remarks

Use the set_cancel method to cancel the execution of the associated server event. Use the get_description method to access an array of failed contact objects. The returned array has a description of each failed contact, describing what activity failed and the key of the contact object that failed.

OnClientError Event

A client event that is raised when an error is detected.

JavaScript Syntax

function OnClientErrorHandler(sender, args)

Parameters

Parameter	Description
sender	The DOM element raising the event.
args	The event arguments object. This object has the methods `get_cancel` and `set_cancel`.

Remarks

Use the set_cancel method to cancel the execution of the associated server event.

OnClientLoad Event

A client event that is raised when the control is loaded.

JavaScript Syntax

function OnClientLoadHandler(sender, args)

Parameters

Parameter	Description
sender	The DOM element raising the event.
args	The event arguments object. This object has the methods `get_cancel` and `set_cancel`.

Remarks

Use the set_cancel method to cancel the execution of the associated server event.

OnServerSignIn Event

A server event that is raised when the user signs in.

C# Syntax

protected void OnServerSignInHandler(object sender, EventArgs e)

Parameters

Parameter	Description
sender	The Contacts object.
e	The event arguments object.

OnServerSignOut Event

A server event that is raised when the user signs out.

C# Syntax

protected void OnServerSignOutHandler(object sender, EventArgs e)

Parameters

Parameter	Description
sender	The Contacts object.
e	The event arguments object.

OnServerData Event

A server event that is raised when data about the contact is received.

C# Syntax

using Microsoft.Live.ServerControls;
…
protected void OnServerDataHandler(object sender, ServerDataEventArgs e)

Parameters

Parameter	Description
sender	The Contacts object.
e	A ServerDataEventArgs object that contains a collection of Contact objects.

OnServerCommit Event

A server event that is raised when changes related to a user's contacts are committed to the contacts store.

C# Syntax

using Microsoft.Live.ServerControls;
…
protected void OnServerCommitHandler(object sender, ServerCommitEventArgs e)

Parameters

Parameter	Description
sender	The Contacts object.
e	A ServerCommitEventArgs object that contains a collection of ServerCommitError objects.

Remarks

The ServerCommitError object provides information about errors during the commit phase. It has two properties, CommitActivity and CommitError.

CommitActivity can have any of the following values.

Commit means the activity was committed.
Create means the contact was created, but the creation has not yet been committed.
Delete means the contact was deleted, but the deletion has not yet been committed.

CommitError can have any of the following values.

AuthError means that the commit was initiated while the user was not logged in.
UnknownError means that there was a critical failure that was not caused by the data.
DuplicateError means that a contact record already existed for a primary e-mail address in a create operation, or that a delete operation for the same primary e-mail was duplicated.
BadEmailError means that an e-mail address was not well formatted.
ObjectNotFoundError means that a contact record was not found for a primary e-mail address.
InvalidFieldError means that an invalid field was passed in with a contact object.
InvalidOperationError means that more than 30 contacts were passed in a single CreateContacts or DeleteContacts call, or more than 1,000 operations were queued for a single CommitContacts call.
QuotaLimitReachedError means that the number of contacts reached the allowed quota in Windows Live Contacts.
UserRefuse means that the user refused to accept the modifications.

OnServerError Event

A server event that is raised when an error is detected.

C# Syntax

protected void OnServerErrorHandler(object sender, EventArgs e)

Parameters

Parameter	Description
sender	The Contacts object.
e	The event arguments object.

Methods

The Contacts control has the following methods that you can use dynamically to manage contacts for a Web site visitor.

Method	Description
AbortContacts	Aborts any pending changes to the control.
CommitContacts	Commits any changes to the control.
CreateContacts	Adds a collection of contacts to the control.
DeleteContacts	Deletes a collection of contacts from the control.

AbortContacts Method

Aborts any pending changes to the control.

C# Syntax

void ContactControl.AbortContacts();

CommitContacts Method

Commits any changes to the control.

C# Syntax

void ContactControl.CommitContacts();

CreateContacts

Adds a collection of contacts to the control.

C# Syntax

void ContactControl.CreateContacts(contacts);

Parameters

Parameter	Description
contacts	A collection of Contact objects. Up to 30 Contact objects can be added at time.

Exceptions

Exception	Description
ArgumentException	When the collection passed does not contain objects of Contact type.
ArgumentNullException	When the contacts argument is null.
InvalidOperationException	When there are more than 30 Contact objects in the contacts argument.

Remarks

You must call the CommitContacts method to save any changes to the control.

Example

The following example adds a contact with the e-mail address nobody@fabrikam.com to the control Contacts1.

List<Contact> myContacts = new List<Contact>();
Contact myContact = new Contact();
myContact.EmailPersonal = "nobody@fabrikam.com";
myContacts.Add(myContact);
Contacts1.CreateContacts(myContacts);
Contacts1.CommitContacts();

DeleteContacts

Deletes a collection of contacts from the control.

C# Syntax

void ContactControl.DeleteContacts(addresses);

Parameters

Parameter	Description
addresses	A collection of String objects specifying the e-mail addresses of the contacts to delete.

Exceptions

Exception	Description
ArgumentException	When the collection passed does not contain objects of String type.
ArgumentNullException	When the addresses argument is null.
InvalidOperationException	When there are more than 30 String objects in the addresses argument.

Example

The following example deletes a contact with the e-mail address nobody@fabrikam.com from the control Contacts1.

List<String> myContacts = new List<String>();
myContacts.Add("nobody@fabrikam.com");
Contacts1.DeleteContacts(myContacts);
Contacts1.CommitContacts();

Remarks

You must call the CommitContacts method to save any changes to the control.