Windows Phone Toolkit DateTime Converters

published on: 9/13/2011 | Views: N/A | Tags: WP7Toolkit Binding

by WindowsPhoneGeek

In this article I am going to talk about the new DateTime converters that come with the latest update of the Windows Phone Toolkit - August 2011 (7.1 SDK) . Basically, these converters enable developers to display date/time in different formats(including localized strings and information) like "8/21" for short dates or relative times like '21 hour ago'. So, in this post I will explain the basic principles of converters in Windows Phone and will give lots of examples of how to use the different toolkit converters.

What is a Converter?

Silverlight data binding engine allows data to be bound through XAML or programmatically with code. Sometimes you want to databind two properties that have incompatible types. You need some code that converts the value from source to target type and back. This code is called ValueConverter.

Basically a Value Converter is a class, that implements the interface IValueConverter interface.This interface exposes two methods: object Convert(object value)and ConvertBack(object value).

The binding engine calls the Convert and ConvertBack methods if the Converter parameter is defined for the binding. When data is passed from the source, the binding engine calls Convert and passes the returned data to the target. When data is passed from the target, the binding engine calls ConvertBack and passes the returned data to the source. The following example shows how to set the Converter parameter.

Getting Started

Windows Phone Toolkit - August 2011 (7.1 SDK) gives us some very helpful converters which you can use in your application even without writing any custom code. To begin with using them first add a reference to the Microsoft.Phone.Controls.Toolkit.dll assembly in your Windows Phone application project.

NOTE: The Microsoft.Phone.Controls.Toolkit.dll assembly is installed with the toolkit and you can find it in:

For 32-bit systems:

C:\Program Files\Microsoft SDKs\Windows Phone\v7.1\Toolkit\Aug11\Bin\Microsoft.Phone.Controls.Toolkit.dll

For 64-bit systems:

C:\Program Files (x86)\Microsoft SDKs\Windows Phone\v7.1\Toolkit\Aug11\Bin\Microsoft.Phone.Controls.Toolkit.dll

Alternatively you can select it directly from the "...\Silverlight for Windows Phone Toolkit Source & Sample - Aug 2011\Bin\" if you have downloaded the "Silverlight for Windows Phone Toolkit Source & Sample - Aug 2011.zip" instead.

NOTE: If you have installed the toolkit via NuGet then the reference is automatically added to your project.

NOTE: To use DateTimeConverters in XAML you will have to add the following namespace declaration (for example):

xmlns:toolkit="clr-namespace:Microsoft.Phone.Controls;assembly=Microsoft.Phone.Controls.Toolkit"

RelativeTimeConverter

Converts a DateTime object into a string that represents the elapsed time relatively to the present.

Example:

<phone:PhoneApplicationPage.Resources>
        <toolkit:RelativeTimeConverter x:Key="RelativeTimeConverter"/>
</phone:PhoneApplicationPage.Resources>
<!--...-->

<toolkit:DatePicker x:Name="datepicker" Value="8/21/2011" />
<TextBlock Text="RelativeTimeConverter:" />
<TextBlock Text="{Binding ElementName=datepicker, Path=Value, Converter={StaticResource RelativeTimeConverter}}" />

Result:

DailyDateTimeConverter

Converts a DateTime object into a string appropriately formatted for daily feeds.

Example:

<phone:PhoneApplicationPage.Resources>
        <toolkit:DailyDateTimeConverter x:Key="DailyDateTimeConverter"/>
</phone:PhoneApplicationPage.Resources>
<!--...-->

<toolkit:DatePicker x:Name="datepicker" Value="8/21/2011" />
<TextBlock Text="DailyDateTimeConverter:" />
<TextBlock Text="{Binding ElementName=datepicker, Path=Value, Converter={StaticResource DailyDateTimeConverter}}" />

Result:

FullViewDateTimeConverter

Converts a DateTime object into a string appropriately formatted to display full date and time information. This format can usually be found in email.

NOTE: This format never displays the year.

HourlyDateTimeConverter

Converts a DateTime object into a string appropriately formatted for hourly feeds. This format can usually be found in messaging.

Example:

<phone:PhoneApplicationPage.Resources>
        <toolkit:HourlyDateTimeConverter x:Key="HourlyDateTimeConverter"/>
</phone:PhoneApplicationPage.Resources>
<!--...-->

<toolkit:DatePicker x:Name="datepicker" Value="8/21/2011" />
<TextBlock Text="HourlyDateTimeConverter:" />
<TextBlock Text="{Binding ElementName=datepicker, Path=Value, Converter={StaticResource HourlyDateTimeConverter}}" />

Result:

ListViewDateTimeConverter

Converts a DateTime object into a string appropriately formatted for list-views. This format can usually be found in email.

NOTE: This format never displays the year.

<phone:PhoneApplicationPage.Resources>
        <toolkit:ListViewDateTimeConverter x:Key="ListViewDateTimeConverter"/>
</phone:PhoneApplicationPage.Resources>
<!--...-->

<toolkit:DatePicker x:Name="datepicker" Value="8/21/2011" />
<TextBlock Text="ListViewDateTimeConverter:" />
<TextBlock Text="{Binding ElementName=datepicker, Path=Value, Converter={StaticResource ListViewDateTimeConverter}}" />

ThreadDateTimeConverter

Converts a DateTime object into a string appropriately formatted for threads. This format can be found in messaging.

NOTE: This format never displays the year.

<phone:PhoneApplicationPage.Resources>
        <toolkit:ThreadDateTimeConverter x:Key="ThreadDateTimeConverter"/>
</phone:PhoneApplicationPage.Resources>
<!--...-->

<toolkit:DatePicker x:Name="datepicker" Value="8/21/2011" />
<TextBlock Text="ThreadDateTimeConverter:" />
<TextBlock Text="{Binding ElementName=datepicker, Path=Value, Converter={StaticResource ThreadDateTimeConverter}}" />

Result:

That was all about the new "DateTime Converters" from the Windows Phone Toolkit Aug 2011 in depth. Stay tuned for more Windows Phone Toolkit articles. Here is the full source code:

ToolkitConverters

You may also find interesting the following articles:

You can also follow us on Twitter @winphonegeek