Working with PinToStartAction

Last night I released WPUtils 1.1 which brings a PinToStartAction and a demo project. In this post, I’m going to talk about the PinToStartAction.

As its name implies, PinToStartAction is used to enable a control/component to pin a tile to the start screen. Let’s have a look at how it works with Button and app bar button/menu item. If you have a Button like this:

<Button Content="pin" Margin="0,12,0,0"/>

you can attach the PinToStartAction to this Button via EventTrigger:

<Button Content="pin" IsEnabled="{Binding TileAbsent}" Margin="0,12,0,0">
    <i:Interaction.Triggers>
        <i:EventTrigger EventName="Click">
            <WPUtils:PinToStartAction
                NavigationUri="{Binding NavigationUri}"
                BackgroundImage="{Binding BackgroundImage}"
                Title="{Binding TileTitle}"/>
        </i:EventTrigger>
    </i:Interaction.Triggers>
</Button>

Note that I have a view model class behind for data binding. The IsEnabled property is bound to a TileAbsent property of view model class. When the tile already exists in the start screen, the Button will appear disabled. In order to achieve this, you’ll need to add code to check the existence of the tile and set TileAbsent property accordingly in your view model class, and call this code inside OnNavigatedTo method of the page. You shouldn’t rely on the construction point of the page to determine the state of the Button, because the user could switch to Start screen right from this page, remove the tile, and back to this page.

Of couse, this action contains code to check if the tile already exists in case you don’t do the check. This action will just do nothing when the tile exists. But I strongly recommend that you do the check and set the IsEnabled property accordingly so that the users will be aware of what’s happening.

What’s more, if you specify images for background/back background, PinToStartAction will take care of copying them to /Shared/ShellContent folder and reporting the correct URI to the underlying API.

For app bar button, we will need AppBarItemTrigger from AppBarUtils. Once you have that toolkit ready in your project, you can attach PinToStartAction to a app bar button like this:

<phone:PhoneApplicationPage.ApplicationBar>
    <shell:ApplicationBar>
         <shell:ApplicationBarIconButton IconUri="/images/appbar.pin.png" Text="pin"/>
    </shell:ApplicationBar>
</phone:PhoneApplicationPage.ApplicationBar>

<i:Interaction.Triggers>
     <AppBarUtils:AppBarItemTrigger Id="pin" IsEnabled="{Binding TileAbsent}">
         <WPUtils:PinToStartAction
             BackgroundImage="{Binding BackgroundImage}"
             Title="{Binding TileTitle}"
             NavigationUri="{Binding NavigationUri}"/>
     </AppBarUtils:AppBarItemTrigger>
</i:Interaction.Triggers>

AppBarItemTrigger and PinToStartAction are both bound to the same view model class as the above Button, and work the same way as expected.

In Expression Blend, you can just drag and drop it onto a control, set/bind the needed properties, and you’re done. Pretty simple. For app bar item, you will need to drag and drop PinToStartAction onto the page, and change the trigger to AppBarItemTrigger on Properties panel.

Last but not the least, go download the code, run to see how the demo works! Cheers!

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: