There are 3 primary methods by which you can perform customization:

1. Content Controls: The "start modality" buttons will display the default icon for their respective feature if no content is specified. However, you can provide an arbitrary framework element as the child of one of these controls to modify this behavior.

2. Restyling: Many aspects of the controls styling can be customized simply by changing the corresponding properties on the control. For example, you can change the background color or border thickness by simply specifying a new value.

3. Retemplating: This is the most extreme form of customization, in which you completely replace the user interface of the control with a new template of your choosing. This process is best performed using Microsoft Expression Blend, which facilitates extraction of the existing template to use as a starting point.

We will show simple examples for the first 2 of these techniques in this blog post, and cover advanced retemplating topics in the next post.

Customizing a content control

There are a variety of controls in the Lync SDK which end with the word “Button”:

• StartVideoCallButton
• ScheduleMeetingButton
• StartAudioCallButton
• SendEmailButton
• SendFileButton
• ShareDesktopButton

The naming of these controls is a bit confusing.  The classes themselves don’t actually extend from the Button class.  Instead, the template of each of these controls contains a Button.  And as you may already know, a Button is a ContentControl class.  Elements of this type support a single piece of content which defines their template.  The content you provide can be as simple as a text string, or as complex as a grid containing a rich layout of numerous elements. 

By default, if you do not define any content for these controls, they will render a toolbar-sized icon which matches the corresponding UI element is the Lync client. This is accomplished internally by defining a Binding.TargetNullValue for the Content property of the button.  But you can easily override the default content by specifying any non-null value for the content.  When you do, the UI of the button will be replaced with the framework element of your choosing. 

In some cases, the UI is rendered with a special SplitButton control which shows a drop-down menu on the right side, and a button on the left.  In these situations, the content you provide will be used to define the template of the left-hand-side of the control only.  The drop-down menu functionality will be preserved. 

Here is a simple example of how to customize the display of a StartAudioCallButton using this technique:

<!-- Plain call button -->

<controls:StartAudioCallButton

    Source="sip:schuddle@microsoft.com"/>

<!-- Call button custom content -->

<controls:StartAudioCallButton

    x:Name="callButton"

    Source="sip:schuddle@microsoft.com">

    <StackPanel Orientation="Horizontal">

        <TextBlock Text="Call "/>

        <TextBlock Text="{Binding ElementName=callButton,Path=DisplayName}"/>

    </StackPanel>

</controls:StartAudioCallButton>

As you can see, the first button control is defined with no content.  But the second button defines a StackPanel element with 2 nested TextBlocks as the content of the button class.  When you run this code, the net effect looks something like this:

Restyling a Lync Control

Another really easy way to customize the content of a Lync control is by applying a custom style.  There are many common properties which you can control that are template bound, and do not require any complex configuration to use.  The complete list of properties which support restyling can be found in the SDK documentation, under the topic Properties That Support Restyling.  For a simple example of what you can do with some of these properties, consider the XAML for these two ContactCard controls:

<!-- Plain contact card -->

<controls:ContactCard Margin="10"

    Source="schuddle@microsoft.com" />

<!— Contact card with styles applied -->

<controls:ContactCard Margin="10"

    Source="schuddle@microsoft.com"

    Background="LightSteelBlue"

    BorderBrush="DarkBlue"

    BorderThickness="5"

    FontFamily="Century Schoolbook"

    FontWeight="Bold"

/>

As you can see from these examples, there are many aspects of the control appearance which can be modified without the need for any complex coding at all.

In the next post, we will explore more radical methods for altering the appearance of Lync controls, which permit us to dramatically change their user interface and behavior.

Begin by creating and opening a Visual Studio project using one of the Lync templates which were installed by the SDK installer. Refer to the previous Hello, Lync post for details on how to get started with a new project. Note: In the sample code snippets shown below, we will use the XML namespace “controls” to refer to the Microsoft.Lync.Controls assembly which you must reference at the top of each XAML source file.

Introducing the search controls

The easiest way to add search functionality to your application is by using the ContactSearch control. This control adds a search input box and a search result list as a single unit, arranged vertically just as they are in the Lync user interface. However, you can also add these components separately to your application, and retain control over the layout of the individual components. To add search features to your application search features in this manner, you must use a pair of interrelated controls: ContactSearchInputBox and ContactSearchResultList.

The ContactSearchInputBox control provides a user interface for entering search criteria and executing a search. It provides both name and keyword search features, and is designed to mimic the user interface of Microsoft Lync. The ContactSearchResultList control provides a user interface for displaying the results of your search, as well as metadata about the status of the search operation.

To use these controls, you must first add them to your application. You can place these controls separately anywhere on the window. We will place the results on top in this example:

    <Grid>

        <Grid.RowDefinitions>

            <RowDefinition Height="*"/>

            <RowDefinition Height="Auto"/>

        </Grid.RowDefinitions>

        <controls:ContactSearchResultList Grid.Row="0"/>

        <controls:ContactSearchInputBox Grid.Row="1"/>

    </Grid>

Binding the search controls to each other

We’re not done yet! The above code sample will not work as expected. The reason for this is that the ContactSearchResultList control is not connected to the ContactSearchInputBox control which performs the search operation.

In order to make them work together, we will need to add a little bit more code. The ContactSearchInputBox control has a dependency property called Results which contains the output of the search operation. It also supports a dependency property called SearchState which provides feedback on the status of the search operation. To make the ContactSearchResultList control display this output, we must bind the two controls together. The full code looks something like this:

    <Grid>

        <Grid.RowDefinitions>

            <RowDefinition Height="*"/>

            <RowDefinition Height="Auto"/>

        </Grid.RowDefinitions>

        <controls:ContactSearchResultList Grid.Row="0"

           ItemsSource="{Binding Results, ElementName=searchInput, Mode=OneWay}"

           ResultsState="{Binding SearchState, ElementName=searchInput, Mode=OneWay}"

           />

        <controls:ContactSearchInputBox Grid.Row="1" x:Name="searchInput"/>

    </Grid>

If you run the code now, you will see a familiar interface which provides a rich set of search features to your application.

In our next post, we will explore how to customize the display of search results by retemplating a control.

Creating your first Lync Controls project

We’ll use the WPF application libraries in this sample.

1. To begin, you must first install and sign in to Microsoft Lync.  All Lync controls require a running instance of Microsoft Lync to function properly.

2. Next, be sure you have installed the Lync Client Platform SDK.

3. Open Visual Studio, and create a new project using the template Lync WPF Application

4. Open the file Window1.xaml

The template already includes some very basic XAML which instantiates a PresenceIndicator control and a TextBlock:

<!--

    Show the presence indicator. Hover over the icon to see the contact card.

    Set Source to a valid SIP URI in your organization.

-->

<controls:PresenceIndicator

    x:Name="Presence"

    Source="sip:john@contoso.com"

    PhotoDisplayMode="Large"

/>

<!-- Use the DisplayName property from PresenceIndicator to show the user's name -->

<TextBlock

    Text="{Binding DisplayName, ElementName=Presence}"

    Margin="4,0,0,0"

    VerticalAlignment="Center"

/>

If you run the application at this point, you are very likely to see the result “Unknown Contact” in the text block, along with the default silhouette image and grey presence bar.  This is because we have not yet selected a valid contact.

Connecting your control to a source of data

All Lync Controls which operate on a single contact support a property called Source which is used to tell the control which contact should be displayed. The Source property accepts any string, and the control will search for a contact matching that string. While this behavior is very robust, it tends to yield inconsistent results. A search for a string such as “Joe” or “Mary” in an organization of any non-trivial size is likely to return more than one result, and the one which gets returned first is the one which your control will display.

You can make the control behave in a more deterministic fashion by giving it more specific source criteria. One option is to use the Lync API to find a Contact object which meets your needs, and pass that object to the Source of your control in the code-behind; but using that API adds some complexity to your code which isn’t necessary for most applications. A simpler option, which works very well, is to specify the SIP URI value for the contact you wish to use. In fact, if you provide a SIP URI and be sure to prefix it with the string sip:, the Lync Control will load your contact much more quickly, because it does not perform a search. Instead, it simply asks the server for the specific contact you are requesting, based on an exact match of the specified SIP URI.

You can easily view a user’s SIP URI in Lync by simply unchecking the option “Show Friendly Name” in the contact list options menu which appears on the right hand side of the contact list toolbar. Once you know the SIP URI of the contact you wish to display, you can wire up your application:

6. Edit the XAML for your new window, and edit the Source property on your presence indicator. For this example, use your own SIP URI.  The XAML will look something like this:

<controls:PresenceIndicator

    x:Name="Presence"

    Source="sip:schuddle@microsoft.com"

    PhotoDisplayMode="Large"

/>

Despite having assigned a valid SIP URI, the TextBlock still shows the value “Unknown Contact” in the design-time preview.  Not to worry, we can leave this value alone, and let the magic of binding take care of that problem.  As you can see, the Text property of our TextBlock is bound to the DisplayName of the presence control.  This setting will automatically update at runtime when the PresenceIndicator control resolves to our selected contact.

Try running your application now.  You should see something like this:

And, you’re done! Congratulations, you have just created your first application using the new Lync Client Platform SDK.

As you have seen, it is really very simple to add Unified Communications functionality into your applications. But there is much more you can do with these controls once you are familiar with the basic interface they support. In our next post, we will explore the contact search controls, and how they can be used to integrate Lync’s powerful search feature into your application.

The controls ship with a default look-and-feel which emulates the behavior of the Lync desktop client, but like any other WPF or Silverlight control, they can be customized extensively by either restyling or retemplating.  We’ll discuss the customization of these controls more in a future post, but lets begin by introducing the controls:

As you can see, the Lync controls enable a wide range of ready-to-use features that make it very easy for developers to integrate collaboration functionality directly within their business applications and websites.  In our next post, we will present a “Hello World” sample application that demonstrates just how easy this is.

• A .NET API which enables a wide variety of scenarios, including audio/video/IM conversations, contact management, presence subscriptions & publication, UI automation, and UI extensibility.
• A rich set of customizable  UI controls for both WPF and Silverlight which give developers the ability to easily integrate Microsoft Lync functionality into their applications.

The addition of this compelling new SDK to the already powerful set of managed API’s included with Lync is fantastic news for developers.  This blog will be dedicated to helping developers make the most of these API’s, and the next several posts will be focused on the many new features introduced by the Lync Client Platform SDK.

You can download the Lync SDK from Microsoft at the following URL:

https://www.microsoft.com/downloads/en/details.aspx?FamilyID=d98f0bf7-c82c-47f5-9f73-be3edbf30438