Quickstart: Using a hub
[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]
Create an entry page to your app using the Hub control. The Hub control displays content in a rich, panning view that lets users get a glimpse of what's new and exciting, and then dig deeper into your app's content.
Prerequisites
- Review and understand the Windows Navigation patterns.
- Review and understand the Guidelines for the Hub control.
- We assume that you can add controls to a basic Windows Store app using C++, C#, or Visual Basic. To learn how to add a control, see Quickstart: Adding controls and handling events.
What is the Hub control?
Hub pages are the user's entry point to your app. They give users a compelling way to see what's new and exciting, and then dig deeper into your app's content. The hub displays different categories of content, each of which maps to your app's section pages. Ideally, each section bubbles up content or functionality. The hub then, offers a lot of visual variety, engages users, and draws them in to different parts of the app.
Here's an example of a nature app that uses the basic hub template from Microsoft Visual Studio.
.png)
The Extensible Application Markup Language (XAML) Hub control provides a framework to help you more easily implement the hub design pattern for your app. You can use any XAML to create a visually rich hub page, so you have the flexibility to customize your app to fit your brand. Unlike a GridView or ListView control that displays data from a single source, each hub section can display data from a different source.
The elements you can use to create a hub page are the Hub control, a hero tile, HubSection controls, and headers for the Hub and HubSections.
.png)
Add the Hub control
The Hub control typically takes up the full page, and all the page elements, like the header, are incorporated into the Hub. Add a header to the Hub to let users know its context. This is often the name of your app. You can use a simple text header, or define a HeaderTemplate that uses any XAML content. The header remains fixed in position and doesn't scroll with the hub sections.
.gif)
To add a Hub control
There are several ways to add a hub page to your app.
Start a new project using the "Hub App" template.
To get started quickly creating a new app with a hub page, use the Hub App project template in Microsoft Visual Studio 2013. (See C#, VB, and C++ project templates.)
Add a hub page to an existing project using the Hub Page item template. (See C#, VB, and C++ item templates.)
Add a Hub control to an existing page. The next step shows the XAML for a Hub in a Page.
To add a simple text header, set the Header property to a string value.
<Page x:Name="pageRoot" x:Class="HubApp1.HubPage1" xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml" xmlns:d="https://schemas.microsoft.com/expression/blend/2008" xmlns:mc="https://schemas.openxmlformats.org/markup-compatibility/2006" mc:Ignorable="d"> <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}"> <Hub Header="Field Guide"> <!-- Hub sections --> </Hub> </Grid> </Page>To include additional XAML elements or styles in your header, assign a DataTemplate to the HeaderTemplate property. Here, a back button is included in the header.
It's important to remember that, although you can use arbitrary content in the header, the height of the header affects the amount of vertical space available for your hub section content.
Note
If you add a Hub control to a page that uses the "Basic Page" template, add the Hub to the root Grid. Then, move the Grid containing the back button and page title to the Hub.HeaderTemplate, as shown here.
<Page x:Name="pageRoot" x:Class="HubApp1.HubPage1" xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml" xmlns:d="https://schemas.microsoft.com/expression/blend/2008" xmlns:mc="https://schemas.openxmlformats.org/markup-compatibility/2006" mc:Ignorable="d"> <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}"> <Hub> <Hub.HeaderTemplate> <DataTemplate> <!-- Back button and page title --> <Grid Margin="0,20,0,0"> <Grid.ColumnDefinitions> <ColumnDefinition Width="80"/> <ColumnDefinition Width="*"/> </Grid.ColumnDefinitions> <AppBarButton x:Name="backButton" Icon="Back" Margin="-30,-14,0,0" Click="backButton_Click"/> <TextBlock x:Name="pageTitle" Text="Field Guide" VerticalAlignment="Top" Style="{StaticResource HeaderTextBlockStyle}" Grid.Column="1" IsHitTestVisible="false" TextWrapping="NoWrap"/> </Grid> </DataTemplate> </Hub.HeaderTemplate> <!-- Hub sections --> </Hub> </Grid> </Page>
Add sections to the hub
You put the content of your Hub in various HubSection controls. Hub sections typically correspond to your app's section pages. You don't add content directly to a HubSection; instead, you define the content of your HubSection in a DataTemplate object. Any valid XAML can be used in the DataTemplate for a hub section.
Like the Hub, each HubSection has a Header and HeaderTemplate property that you can use to set an optional header for the section.
To add a section to a hub
You can define your HubSection content in the XAML for your Hub by adding a DataTemplate, as shown here.
<Hub Header="Field Guide"> <!-- Hub sections --> <HubSection Width="500" Header="Featured"> <DataTemplate> <Grid> <Grid.RowDefinitions> <RowDefinition Height="Auto" /> <RowDefinition Height="Auto" /> <RowDefinition Height="Auto" /> <RowDefinition Height="*" /> </Grid.RowDefinitions> <Image Stretch="Fill" Width="420" Height="280" Source="Assets/LightGray.png"/> <TextBlock Style="{StaticResource SubheaderTextBlockStyle}" Grid.Row="1" Margin="0,10,0,0" TextWrapping="Wrap" Text="Lorem ipsum dolor sit nonumy sed consectetuer ising elit, sed diam"/> <TextBlock Style="{StaticResource TitleTextBlockStyle}" Grid.Row="2" Margin="0,10,0,0" Text="Description text:"/> <TextBlock Style="{StaticResource BodyTextBlockStyle}" Grid.Row="3" Text="Lorem ipsum dolor sit amet, consectetuer ising elit... "/> </Grid> </DataTemplate> </HubSection> <!-- More sections... --> </Hub>To use a DataTemplate resource as the content of a HubSection, assign it to the ContentTemplate property, like this:
ContentTemplate="{StaticResource FeaturedSectionTemplate}".See ResourceDictionary and XAML resource references for more info about using StaticResources.
<Page x:Name="pageRoot" x:Class="HubApp1.HubPage1" xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml" xmlns:d="https://schemas.microsoft.com/expression/blend/2008" xmlns:mc="https://schemas.openxmlformats.org/markup-compatibility/2006" mc:Ignorable="d"> <Page.Resources> <DataTemplate x:Key="FeaturedSectionTemplate"> <Grid> <Grid.RowDefinitions> <RowDefinition Height="Auto" /> <RowDefinition Height="Auto" /> <RowDefinition Height="Auto" /> <RowDefinition Height="*" /> </Grid.RowDefinitions> <Image Stretch="Fill" Width="420" Height="280" Source="Assets/LightGray.png"/> <TextBlock Style="{StaticResource SubheaderTextBlockStyle}" Grid.Row="1" Margin="0,10,0,0" TextWrapping="Wrap" Text="Lorem ipsum dolor sit nonumy sed consectetuer ising elit, sed diam"/> <TextBlock Style="{StaticResource TitleTextBlockStyle}" Grid.Row="2" Margin="0,10,0,0" Text="Description text:"/> <TextBlock Style="{StaticResource BodyTextBlockStyle}" Grid.Row="3" Text="Lorem ipsum dolor sit amet, consectetuer ising elit... "/> </Grid> </DataTemplate> </Page.Resources> <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}"> <Hub Header="Field Guide"> <!-- Hub sections --> <HubSection Width="500" Header="Featured" ContentTemplate="{StaticResource FeaturedSectionTemplate}"/> <!-- More Sections... --> </Hub> </Grid> </Page>
Add interactive section headers for navigation
You can make section headers interactive. Typically, the user can click an interactive header to go to the corresponding app section page. When its IsHeaderInteractive property is true, the default header includes a chevron glyph, and "Hover" and "Pressed" visual states.
To make a section header interactive
Set the HubHeader.IsHeaderInteractive property to true.
Add an event handler for the Hub.SectionHeaderClick event.
The section headers don't have separate Click event handlers. Each interactive header in the Hub causes the Hub's SectionHeaderClick event to occur when it's clicked.
Add code that determines which header is clicked and performs an action for that header. Typically, you add code to navigate to the appropriate section page.
Use the Section property of the HubSectionHeaderClickEventArgs to determine which header is clicked.
Here, the header of the "Featured" hub section is interactive.
<Hub Header="Field Guide" SectionHeaderClick="Hub_SectionHeaderClick">
<!-- Hub sections -->
<HubSection x:Name="Featured" Width="500" Header="Featured" ContentTemplate="{StaticResource FeaturedSectionTemplate}" IsHeaderInteractive="True"/>
<!-- More Sections... -->
</Hub>
When a header is clicked, you use the Name property to determine which header is clicked, and navigate to the appropriate section page.
private void Hub_SectionHeaderClick(object sender, HubSectionHeaderClickEventArgs e)
{
switch (e.Section.Name)
{
case "Featured":
this.Frame.Navigate(typeof(FeaturedPage));
break;
case "Seasonal":
this.Frame.Navigate(typeof(SeasonalPage));
break;
case "FloraAndFauna":
this.Frame.Navigate(typeof(FloraAndFaunaPage));
break;
default:
break;
}
}
Add a hero tile to the hub
You can use a hero image or content for the first hub section to quickly get a user's interest. The hero tile typically has a background image that covers the full height of the screen (or width if the Orientation is Vertical).
To add a hero tile
Use an ImageBrush as the Background of the first HubSection.
Use a large image for the hero that can be cropped both vertically and horizontally without losing the center of interest. You can optionally add content that overlays the background image. You will typically not add a section header because it will conflict with the Hub header.
<Hub Header="Field Guide">
<!-- Hero tile -->
<HubSection Width="780" Margin="0,0,80,0">
<HubSection.Background>
<ImageBrush ImageSource="Assets/DarkGray.png" Stretch="UniformToFill"/>
</HubSection.Background>
</HubSection>
<HubSection Width="500" Header="Featured">
<!-- ... -->
</HubSection>
<!-- More sections... -->
</Hub>
Use a vertical hub in a narrow app
By default, the hub pans horizontally. If your app supports narrow views, you can make the hub pan vertically, as shown here.
.png)
To use a vertically panning hub
In a narrow app, set the Orientation property to Vertical.
<Hub Header="Field Guide" Orientation="Vertical"> <!-- Hub sections --> </Hub>
Use a SemanticZoom view with the hub
If you have a lot of sections in your Hub, consider adding a SemanticZoom control to let users navigate through the sections more quickly. For more info about SemanticZoom, see Guidelines for semantic zoom.
To use SemanticZoom with a hub
Add your Hub as the ZoomedInView of the SemanticZoom control.
Add a ListView (or GridView) as the ZoomedOutView of the SemanticZoom control.
For more info about using the SemanticZoom control, see Quickstart: Adding SemanticZoom controls.
Give the ListView an appropriate header for your app. In the following example, you make the page header a reusable resource and share it between the Hub and the ListView.
Because the page header is incorporated into the Hub control, it won't be visible when the user changes the SemanticZoom to the ZoomedOutView. Add a header to the ListView for the ZoomedOutView.
Bind the ListView's ItemsSource property to the Hub's SectionHeaders property, like this:
ItemsSource="{Binding SectionHeaders, ElementName=FieldGuideHub}".If the HubSection.Header is not set to a string value (if you use a HeaderTemplate, for example), set the x:Uid directive to a string resource, like this:
<HubSection x:Uid="SeasonalSectionHeader" Width="520">. Otherwise, the ListView will show a blank item for that section.The value of
SeasonalSectionHeaderis defined in the resources.resw file. See Quickstart: Using string resources for more info.To make a section header show in the ListView, but not in the Hub, set the x:Uid directive and define an empty HubSection.HeaderTemplate.
<!-- Hero tile --> <HubSection Width="780" Margin="0,0,80,0" x:Uid="HeroTileHeader"> <HubSection.HeaderTemplate> <DataTemplate/> </HubSection.HeaderTemplate> <HubSection.Background> <ImageBrush ImageSource="Assets/DarkGray.png" Stretch="UniformToFill"/> </HubSection.Background> </HubSection>
Here's a hub page that uses a SemanticZoom control with a Hub and a ListView to let the user quicky navigate to different hub sections. This XAML is simplified to show only the relevant elements. HubSection content is not shown, for example.
<Page
x:Name="pageRoot"
x:Class="HubApp1.HubPage1"
xmlns="https://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="https://schemas.microsoft.com/winfx/2006/xaml"
xmlns:d="https://schemas.microsoft.com/expression/blend/2008"
xmlns:mc="https://schemas.openxmlformats.org/markup-compatibility/2006"
mc:Ignorable="d">
<Page.Resources>
<x:String x:Key="AppName">Field Guide</x:String>
<DataTemplate x:Key="PageHeaderTemplate">
<!--Back button and page title-->
<Grid>
<Grid.ColumnDefinitions>
<ColumnDefinition Width="80"/>
<ColumnDefinition Width="*"/>
</Grid.ColumnDefinitions>
<Button x:Name="backButton" Style="{StaticResource NavigationBackButtonNormalStyle}"
Margin="-1,-1,39,0"
VerticalAlignment="Top"
Command="{Binding NavigationHelper.GoBackCommand, ElementName=pageRoot}"
AutomationProperties.Name="Back"
AutomationProperties.AutomationId="BackButton"
AutomationProperties.ItemType="Navigation Button"/>
<TextBlock x:Name="pageTitle" Text="{StaticResource AppName}"
Style="{StaticResource HeaderTextBlockStyle}" Grid.Column="1"
VerticalAlignment="Top" IsHitTestVisible="false" TextWrapping="NoWrap" />
</Grid>
</DataTemplate>
</Page.Resources>
<!--
This grid acts as a root panel for the page.
-->
<Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
<SemanticZoom>
<SemanticZoom.ZoomedInView>
<Hub x:Name="FieldGuideHub" HeaderTemplate="{StaticResource PageHeaderTemplate}"
SectionHeaderClick="Hub_SectionHeaderClick">
<!-- Hero tile -->
<HubSection Width="780" Margin="0,0,80,0" x:Uid="HeroTileHeader">
<HubSection.HeaderTemplate>
<DataTemplate/>
</HubSection.HeaderTemplate>
<HubSection.Background>
<ImageBrush ImageSource="Assets/DarkGray.png" Stretch="UniformToFill"/>
</HubSection.Background>
</HubSection>
<!-- Hub sections -->
<HubSection Header="Featured" Width="500">
<!-- Hub content -->
</HubSection>
<HubSection x:Uid="SeasonalSectionHeader" Width="520">
<HubSection.HeaderTemplate>
<DataTemplate>
<StackPanel Orientation="Horizontal">
<Image Source="Assets/StoreLogo.png"/>
<TextBlock Text="Seasonal"/>
</StackPanel>
</DataTemplate>
</HubSection.HeaderTemplate>
<!-- Hub content -->
</HubSection>
<HubSection Header="Flora & Fauna">
<!-- Hub content -->
</HubSection>
<HubSection Header="Video">
<!-- Hub content -->
</HubSection>
<!-- More sections... -->
</Hub>
</SemanticZoom.ZoomedInView>
<SemanticZoom.ZoomedOutView>
<ListView ItemsSource="{Binding SectionHeaders, ElementName=FieldGuideHub}"
HeaderTemplate="{StaticResource PageHeaderTemplate}"
Padding="40,60,40,0">
<ListView.ItemContainerStyle>
<Style TargetType="ListViewItem">
<Setter Property="HorizontalAlignment" Value="Center"/>
<Setter Property="Margin" Value="0,20"/>
</Style>
</ListView.ItemContainerStyle>
</ListView>
</SemanticZoom.ZoomedOutView>
</SemanticZoom>
</Grid>
</Page>
Summary and next steps
You learned how to use a Hub control to create an entry page for your app.
For more code examples that show the Hub control, see these samples:
- XAML Hub control sample
- the Hub App project template in Visual Studio 2013.