Thursday, 16 January 2014

Adding items to the Settings pane using Prism for the Windows Runtime for Windows 8.1

Previously I’ve written about using Prism for the Windows Runtime for Windows 8.0 to add an item to the Settings pane. The item was a privacy policy as an example. Prism’s SettingsCharmActionItem class was used to define a Settings pane item and the action that was performed when the item is selected. When the privacy policy was selected Prism’s FlyoutService was used to display the PrivacyPolicyFlyout view.

In Prism for Windows 8.1 the SettingsCharmActionItem and FlyoutService classes have been deprecated. Therefore the purpose of this blog post is to show how to add a privacy policy to an app using Prism for Windows 8.1.

If an app has the ability to transmit data, it must contain a privacy policy. For more info see Windows 8 app certification requirements. While the example app does not transmit data, a privacy policy makes a suitable example to showcase how to add an item to the Settings pane using Prism for the Windows Runtime, When the user invokes the Settings pane from any page of the app they will see an item named Privacy Policy. Selecting this item will display a Flyout that displays the app’s privacy policy.


Creating the Flyout view

A SettingsFlyout view is required to display the app’s privacy policy. However, it does not require an associated view model as the view does not need to bind to any data in a view model, instead displaying embedded text. Please note that in a real app a view model would most likely be required in order to handle user acknowledgement of the privacy policy, and to obtain the localized version of the privacy policy from a resource file.

The sample app defines a SettingsFlyout named PrivacyPolicyFlyout which simply includes a TextBlock to display the text of the privacy policy.

    Background="{StaticResource SettingsFlyoutBackgroundThemeBrush}"
    Title="Privacy Policy"
    <StackPanel x:Name="FlyoutContent">
        <TextBlock Style="{StaticResource BasicTextStyle}"
                   Text="Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum." 

Adding an item to the Settings pane

The PrivacyPolicyFlyout can be displayed by the Settings pane by overriding the GetSettingsCommands method from the MvvmAppBase class in your App class and adding code to add the item to the Settings pane.

protected override IList<SettingsCommand> GetSettingsCommands()
    var settingsCommands = new List<SettingsCommand>();
    settingsCommands.Add(new SettingsCommand(Guid.NewGuid().ToString(), "Privacy Policy", (c) => new PrivacyPolicyFlyout().Show()));
    return settingsCommands;

In this method a new SettingsCommand is created and added to a list of SettingsCommand. The SettingsCommand takes three parameters – a unique id, the text to show in the Settings pane, and the event handler that is called when the user selects the command in the Settings pane. So here, when the user selects the Privacy Policy text in the Settings pane, the PrivacyPolicyFlyout will be displayed by invoking the Show method of the SettingsFlyout class.


In this blog post I’ve extended the sample app so that the Settings pane contains a Privacy Policy item. Prism’s GetSettingsCommands method is overriden to add a SettingsCommand to the Settings pane. When the privacy policy text is selected the Show method of the SettingsFlyout class is used to display the PrivacyPolicyFlyout.

The sample app can be downloaded here.

No comments:

Post a Comment