Wp7nl Utilities Contribution

When building apps for Windows Phone, I use my own library. I’m a “lazy” developer and don’t like writing code twice. So I place a lot of code that can be reused, like behaviors, converters and extension methods, in my library. For I while, I’ve been thinking about sharing the library as an open source project on Codeplex, but in the end decided to contribute to the Wp7nl Utilities project of Joost van Schaik. The first bunch of utilities are added. I will continue to add more and describe those on my blog too.

Actions for Launchers

I often have simple trigger actions that need to be executed in my apps. For example, opening a URL in Internet Explorer or sending an email. Because I use Blend a lot (and I’m lazy ;) ), I just like to drag and drop an action to a button or text block and be done with it. The great thing about actions and behaviors is that you can bind the properties which makes them very useful in templates.

At this point, only a few of the possible Windows Phone Launchers are available as trigger actions, but I’m sure the list will grow over time. If you would like one added, just let me know and I’ll see what I can do.

NavigateToUrlAction

Using these actions is very simple. The code surrounding the action is pretty much the same for all actions, only the event name might change. The NavigateToUrlAction performs a WebBrowserTask. It opens up the Url property so you can bind to it. As a small extra feature, it checks if a network connection is available and shows a message if there isn’t. This message can be customized as well.

<Button Content="Wp7nl" HorizontalAlignment="Left" VerticalAlignment="Top">
    <i:Interaction.Triggers>
        <i:EventTrigger EventName="Tap">
            <behaviors:NavigateToUrlAction Url="http://wp7nl.codeplex.com"/>
        </i:EventTrigger>
    </i:Interaction.Triggers>
</Button>

SendEmailAction

This action executes the EmailComposeTask. The “To”, “Subject” and “Body” properties can be bound to.

NavigatieToMarketplaceDetailAction

This action executes the MarketPlaceDetailTask. It opens up the marketplace and shows the details of your app.

NavigatieToReviewAction

Getting people to review your apps is crucial for a successful app. This action executes the MarketplaceReviewTask and makes it very easy for users to review.

ShareLinkAction

Sharing links is a very common task in apps. This action executes the ShareLinkTask. So you can use the native sharing features of the phone. The “LinkUri”, “Message” and “Title” properties can be bound to.

Limit TextBox Behavior

I ran into cases where I wanted to limit the number of characters a user can enter. This behavior an only be used with a TextBox element. You can set the maximum number characters that can be entered in the “MaxChars” property. As a bonus feature, you can have the phone vibrate a little when the maximum number of characters is reached.

<TextBox x:Name="LimitedTextbox">
    <i:Interaction.Behaviors>
        <behaviors:LimitTextBoxBehavior MaxChars="25" Vibrate="True"/>
    </i:Interaction.Behaviors>
</TextBox>

Visible On Locale Behavior

The VisibleOnLocaleBehavior sets the attached element to visible if the current UI language of the phone matches the specified two letter ISO language name and hides it when it doesn’t. The behavior can be used if you have certain element, like images, that are language specific.

<TextBlock Text="English" >
    <i:Interaction.Behaviors>
        <behaviors:VisibleOnLocaleBehavior LanguageCode="en"/>
    </i:Interaction.Behaviors>
</TextBlock>
<TextBlock Text="Nederlands">
    <i:Interaction.Behaviors>
        <behaviors:VisibleOnLocaleBehavior LanguageCode="nl"/>
    </i:Interaction.Behaviors>
</TextBlock>

Visibility In Trial Behavior

The VisibilityInTrialBehavior sets the attached element to visible or collapsed if the app is in trial mode. Whether the attached element should be visible or collapsed is determined by the “Visibility” property.

<TextBlock Text="Not in trial mode">
    <i:Interaction.Behaviors>
        <behaviors:VisibilityInTrialBehavior Visibility="Collapsed"/>
    </i:Interaction.Behaviors>
</TextBlock>

This behavior makes use of the TrialHelper. This helper is used to see if your app is running in trial mode. To be able to run your application in trial mode, you can add “TRIAL” as a conditional compilation symbol to fake it when debugging.

Converters

I’ve added a couple of converters to the Wp7nl library. Most of which are very simple.

ObjectToStringValueConverter

Let’s start with the one that needs the most explanation. The ObjectToStringConverter is used to create a nicer representation of an object. Add properties of the bound object between { } to the converter parameters.

Take, for example, a Person class.

public class Person
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

Whenever you would like to have a textblock show the last name and the first name separated with a comma, you could just add that to the converter parameter.

For this example, I’ve set the datacontext of the mainpage to a new instance of the person class directly in the constructor. You wouldn’t do that in a real application of course, but you’ll get the idea.

public MainPage()
{
    InitializeComponent();
    DataContext = new Person{FirstName = "Larry", LastName = "Laffer"};
}

Then, I’ve added a databinding to the textblock.

<TextBlock Text="{Binding ConverterParameter=\{LastName\}\, \{FirstName\}, 
   Converter={StaticResource ObjectToStringValueConverter}}"/>

When creating the binding in Blend, you don’t have to escape the curly brackets, as shown in the image below:

NullToCollapsedConverter

Returns Visibility.Collapsed for any value that is null, empty, only whitespaces or an empty guid. Very useful to hide empty stuff. You don’t want to show a navigate to URL button if the URL is empty, for example.

StripHtmlValueConverter

Removes all HTML from a string and decodes ‘&XXXX’ to regular chars. Often when data is requested from external services like Twitter or Facebook, it contains HTML at some point. This HTML has to be converted to either a regular string or to some sort of rich text block. This converter does the first, removing all HTML. <BR /> tags are changed to new lines.

ToLowerValueConverter

Converts a string to all lowercase characters. Useful for headers.

ToUpperValueConverter

Converts a string to all uppercase characters. Useful for titles.