From 4167960fe71d0fb82217f41511ed7a35d31f9cdd Mon Sep 17 00:00:00 2001 From: Luke Blevins Date: Sat, 13 May 2023 18:34:26 -0400 Subject: [PATCH 1/5] docs(Nav): Add page navigation to tutorial --- .../Advanced/HowTo-UseNavigationView.md | 89 ++++++++++++++++++- 1 file changed, 86 insertions(+), 3 deletions(-) diff --git a/doc/Learn/Tutorials/Navigation/Advanced/HowTo-UseNavigationView.md b/doc/Learn/Tutorials/Navigation/Advanced/HowTo-UseNavigationView.md index d79ed5a582..c642b97188 100644 --- a/doc/Learn/Tutorials/Navigation/Advanced/HowTo-UseNavigationView.md +++ b/doc/Learn/Tutorials/Navigation/Advanced/HowTo-UseNavigationView.md @@ -163,14 +163,95 @@ Choosing the right control for your navigation needs is important, and one commo ``` -* Observe how the `NavigationView` and the content area are now connected. When you select a `NavigationViewItem`, the corresponding `Grid` will be shown. - * Set the `Visibility` of the `Grid` elements to `Collapsed` to hide the content area's children beforehand: ```xml Visibility="Collapsed" ``` +#### Navigating to Page elements + +* You may want to navigate to a `Page` view element represented by a route name. It is possible to do this without defining the view element alongside the other content areas. For instance, you may need to display a login page `LoginPage` which will be defined in a separate XAML file. + +* Add a new **Page** item to your app called `LoginPage` with the following code: + + ```xml + + + + + + + ``` + +* For the purposes for this tutorial, `LoginPage` will be associated with its own view model `LoginViewModel`. Add a new **Class** item to your app called `LoginViewModel` with the following code: + + ```csharp + namespace UsingNavigationView.ViewModels; + + public class LoginViewModel + { + public LoginViewModel() + { + + } + } + ``` + +* Register `ViewMap` and `RouteMap` instances inside the `RegisterRoutes` method in `AppHead.xaml.cs`. This associates the `LoginPage` described above with `LoginViewModel`, as well as avoiding the use of reflection for route discovery. + + ```csharp + private static void RegisterRoutes(IViewRegistry views, IRouteRegistry routes) + { + views.Register( + new ViewMap(), + new ViewMap(), + new ViewMap() + ); + + routes.Register( + new RouteMap("", View: views.FindByViewModel(), + Nested: new RouteMap[] + { + new RouteMap("Main", View: views.FindByViewModel()), + new RouteMap("Login", View: views.FindByViewModel()) + })); + } + ``` + +* Importantly, the snippet above establishes a route name `Login` for `LoginPage`. We can use this route name to navigate to the `LoginPage` view element. + +* Add a `NavigationViewItem` to the `NavigationView` element with the `uen:Region.Name` attached property set to `Login`. + + ```xml + + + + + + + + ``` + +#### Putting it all together + +* Observe how the `NavigationView` and the content area are now connected. When you select a `NavigationViewItem`, the corresponding `Grid` or `Page` will be shown. + * Now, you have written a UI layout capable of navigating to views with `NavigationView`. Your completed `MainPage.xaml` should look like the code example below. #### Code example @@ -200,6 +281,8 @@ Choosing the right control for your navigation needs is important, and one commo uen:Region.Name="Two" /> + Date: Sat, 13 May 2023 19:16:02 -0400 Subject: [PATCH 2/5] docs(Nav): improve introduction --- .../Advanced/HowTo-AdvancedPageNavigation.md | 15 +++++++-------- .../Navigation/Advanced/HowTo-ResponsiveShell.md | 9 ++++++--- .../Advanced/HowTo-UseContentControl.md | 3 +-- .../Navigation/Advanced/HowTo-UsePanel.md | 1 - .../Navigation/Advanced/HowTo-UseTabBar.md | 5 +---- 5 files changed, 15 insertions(+), 18 deletions(-) diff --git a/doc/Learn/Tutorials/Navigation/Advanced/HowTo-AdvancedPageNavigation.md b/doc/Learn/Tutorials/Navigation/Advanced/HowTo-AdvancedPageNavigation.md index 897c8a7119..00d7a46dc4 100644 --- a/doc/Learn/Tutorials/Navigation/Advanced/HowTo-AdvancedPageNavigation.md +++ b/doc/Learn/Tutorials/Navigation/Advanced/HowTo-AdvancedPageNavigation.md @@ -1,16 +1,15 @@ --- uid: Learn.Tutorials.Navigation.Advanced.PageNavigation --- -# How-To: Advanced Page Navigation +# How-To: Employ Advanced Page Navigation Techniques -Sometimes when you navigate you don't want to leave the current page in the back-stack. For example after signing into an application, you might want to navigate to the main page of the application; you don't want to have the login page still in the back-stack for a user to accidentally to go back to. +When using navigation, you may not want to allow the current page to remain in the back-stack. If you want to navigate to the main page of the application after signing in, there should not be a login page still in the back-stack for a user to accidentally to go back to. -> [!TIP] -> This guide assumes you used the Uno.Extensions `dotnet new unoapp-extensions` template to create the solution. Instructions for creating an application from the template can be found [here](xref:Overview.Extensions) +Using backward/forward navigation in your app requires a degree of extra consideration. Users always expect the back/forward button to take them to a page that is still relevant, yet logically related to the current page and direction. This page contains several concise tutorials about how to implement navigation techniques that address these more advanced problems. -## Step-by-steps +## Techniques -### 1. Navigating to a Page and Clearing Back Stack +### Navigating to a Page and Clearing Back Stack - Add an additional button to `MainPage.xaml` with the `Click` event bound to the `GoToSecondPageClearBackStack` method @@ -37,7 +36,7 @@ Sometimes when you navigate you don't want to leave the current page in the back If you run the application and navigate to the `SecondPage` the back button in the `NavigationBar` isn't visible, since the frame back-stack is empty. -### 2. Navigating to a Page and Removing a Page from Back Stack +### Navigating to a Page and Removing a Page from Back Stack Another common scenario is to navigate to a page and then remove the current page from the back stack. @@ -68,7 +67,7 @@ Another common scenario is to navigate to a page and then remove the current pag The use of `Qualifiers.NavigateBack` will result in the `SecondPage` being removed from the back stack, after navigating forward to the `SamplePage`. -### 3. Navigating to Multiple Pages +### Navigating to Multiple Pages In some cases you may want to navigate forward to a page and inject an additional page into the back stack. This can be done by specifying a multi-section route. diff --git a/doc/Learn/Tutorials/Navigation/Advanced/HowTo-ResponsiveShell.md b/doc/Learn/Tutorials/Navigation/Advanced/HowTo-ResponsiveShell.md index 6033c28f37..933b0f23fc 100644 --- a/doc/Learn/Tutorials/Navigation/Advanced/HowTo-ResponsiveShell.md +++ b/doc/Learn/Tutorials/Navigation/Advanced/HowTo-ResponsiveShell.md @@ -3,8 +3,11 @@ uid: Learn.Tutorials.Navigation.Advanced.ResponsiveShell --- # How-To: Build a Responsive Layout using NavigationView and TabBar -> [!TIP] -> This guide assumes you used the Uno.Extensions `dotnet new unoapp-extensions` template to create the solution. Instructions for creating an application from the template can be found [here](xref:Overview.Extensions) +Apps that scale across multiple devices and form factors need to be able to adapt their layout to the available screen real estate. When your app is running on narrow devices, such as phones, you may want to hide the navigation pane and show a hamburger menu button instead. + +It makes sense to allow `TabBar` to be the dominant navigation surface on these devices. On larger devices, such as tablets and desktops, you may want to show the navigation pane and hide the hamburger menu button. Using the `TabBar` would be a poor choice for navigation on these devices. The platform includes a `VisualStateManger` that allows you to define different visual states for different screen sizes in XAML, showing the navigation pane and hamburger menu button as appropriate. + +This tutorial will show you how to build a responsive layout with multiple navigation controls such as `NavigationView` and the [Uno Toolkit](https://github.com/unoplatform/uno.toolkit.ui) `TabBar` which use the _same_ navigation service behind the scenes. ## Step-by-steps @@ -360,7 +363,7 @@ While the WinUI `NavigationView` control by itself is a good choice for a respon ``` ### 5. Toggle visibility for responsive design -* Finally, specify groups for the VisualStateManager to adjust the Page layout based how close the window size is to a couple of defined breakpoints: +* Finally, specify groups for the `VisualStateManager` to adjust the page layout based on how close the window size is to a couple of defined breakpoints: ```xml diff --git a/doc/Learn/Tutorials/Navigation/Advanced/HowTo-UseContentControl.md b/doc/Learn/Tutorials/Navigation/Advanced/HowTo-UseContentControl.md index c0fcd56bcc..96756b087e 100644 --- a/doc/Learn/Tutorials/Navigation/Advanced/HowTo-UseContentControl.md +++ b/doc/Learn/Tutorials/Navigation/Advanced/HowTo-UseContentControl.md @@ -3,8 +3,7 @@ uid: Learn.Tutorials.Navigation.Advanced.ContentControl --- # How-To: Use a ContentControl to Display a View -> [!TIP] -> This guide assumes you used the Uno.Extensions `dotnet new unoapp-extensions` template to create the solution. Instructions for creating an application from the template can be found [here](xref:Overview.Extensions) +If you want to display a view in a specific location in a page, `ContentControl` is the ideal UI element. For example, you might want to display a view in a `Grid` or `StackPanel` in a specific location. You can use a `ContentControl` to display a view in a specific location. ## Step-by-steps diff --git a/doc/Learn/Tutorials/Navigation/Advanced/HowTo-UsePanel.md b/doc/Learn/Tutorials/Navigation/Advanced/HowTo-UsePanel.md index b25743d479..da2dc35284 100644 --- a/doc/Learn/Tutorials/Navigation/Advanced/HowTo-UsePanel.md +++ b/doc/Learn/Tutorials/Navigation/Advanced/HowTo-UsePanel.md @@ -1,7 +1,6 @@ --- uid: Learn.Tutorials.Navigation.Advanced.Panel --- - # How-To: Use a Panel to Switch Views Sometimes your application may need to switch between multiple views without the overhead of controls like `Frame` which support a navigation stack. In this case, it makes sense to define sectors of potential view content as **regions** and use another control to toggle the `Visibility` of the multiple views directly. This tutorial will show you how to use a `Panel` to switch between views. diff --git a/doc/Learn/Tutorials/Navigation/Advanced/HowTo-UseTabBar.md b/doc/Learn/Tutorials/Navigation/Advanced/HowTo-UseTabBar.md index 49870158b2..634be2d574 100644 --- a/doc/Learn/Tutorials/Navigation/Advanced/HowTo-UseTabBar.md +++ b/doc/Learn/Tutorials/Navigation/Advanced/HowTo-UseTabBar.md @@ -3,13 +3,10 @@ uid: Learn.Tutorials.Navigation.Advanced.TabBar --- # How-To: Use a TabBar to Switch Views -> [!TIP] -> This guide assumes you used the Uno.Extensions `dotnet new unoapp-extensions` template to create the solution. Instructions for creating an application from the template can be found [here](xref:Overview.Extensions) +The navigation capabilities offered by Uno.Extensions include regions. Regions allow you to associate a specific sector of the view with an individual item on a navigation control from the same `Page`. Likewise, the Uno.Extensions library has built-in support for responding to navigation gestures from the [Toolkit](https://github.com/unoplatform/uno.toolkit.ui) `TabBar`. Follow the steps below to define a user interface centered around navigating with this control. ## Step-by-steps -The Navigation capabilities offered by Uno.Extensions include regions. Regions allow you to associate a specific sector of the view with an individual item on a navigation control from the same `Page`. Likewise, the Uno.Extensions library has built-in support for responding to navigation gestures from the [Toolkit](https://github.com/unoplatform/uno.toolkit.ui) `TabBar`. Follow the steps below to define a user interface centered around navigating with this control. - ### 1. Add necessary XAML namespaces * Update the `Page` element in `MainPage.xaml` to include XAML namespace mappings for Navigation and Uno Toolkit: From 0e04bf64330004e83474832a26beabc84967c497 Mon Sep 17 00:00:00 2001 From: Luke Blevins Date: Sat, 13 May 2023 19:36:17 -0400 Subject: [PATCH 3/5] docs(Nav): Update TabBar tutorial --- .../Navigation/Advanced/HowTo-UseTabBar.md | 228 ++++++++++++------ 1 file changed, 157 insertions(+), 71 deletions(-) diff --git a/doc/Learn/Tutorials/Navigation/Advanced/HowTo-UseTabBar.md b/doc/Learn/Tutorials/Navigation/Advanced/HowTo-UseTabBar.md index 634be2d574..b2d75f861f 100644 --- a/doc/Learn/Tutorials/Navigation/Advanced/HowTo-UseTabBar.md +++ b/doc/Learn/Tutorials/Navigation/Advanced/HowTo-UseTabBar.md @@ -11,24 +11,24 @@ The navigation capabilities offered by Uno.Extensions include regions. Regions a * Update the `Page` element in `MainPage.xaml` to include XAML namespace mappings for Navigation and Uno Toolkit: -```xml + ```xml @@ -36,11 +36,11 @@ The navigation capabilities offered by Uno.Extensions include regions. Regions a -``` + ``` * Define initial page and `TabBarItem` content. It's important to make each element that represents a sector of app content have it's `Visibility` explicitly set to `Collapsed`. Uno.Extensions will handle toggling it back to `Visible` when necessary -```xml + ```xml @@ -48,33 +48,33 @@ The navigation capabilities offered by Uno.Extensions include regions. Regions a + Style="{StaticResource MaterialNavigationBarStyle}" /> + FontSize="24" + HorizontalAlignment="Center" + VerticalAlignment="Center" /> + FontSize="24" + HorizontalAlignment="Center" + VerticalAlignment="Center" /> + FontSize="24" + HorizontalAlignment="Center" + VerticalAlignment="Center" /> -``` + ``` -* Add TabBar to the view: +* Add `TabBar` to the view: -```xml + ```xml @@ -82,25 +82,25 @@ The navigation capabilities offered by Uno.Extensions include regions. Regions a + Style="{StaticResource MaterialNavigationBarStyle}" /> + FontSize="24" + HorizontalAlignment="Center" + VerticalAlignment="Center" /> + FontSize="24" + HorizontalAlignment="Center" + VerticalAlignment="Center" /> + FontSize="24" + HorizontalAlignment="Center" + VerticalAlignment="Center" /> -``` + ``` ### 3. Set up regions and specify navigator type @@ -121,7 +121,7 @@ The navigation capabilities offered by Uno.Extensions include regions. Regions a * The containing element of the collapsed content `Grid` definitions * The parent element of both controls -```xml + ```xml @@ -129,26 +129,26 @@ The navigation capabilities offered by Uno.Extensions include regions. Regions a + Style="{StaticResource MaterialNavigationBarStyle}" /> + Grid.Row="1"> + FontSize="24" + HorizontalAlignment="Center" + VerticalAlignment="Center" /> + FontSize="24" + HorizontalAlignment="Center" + VerticalAlignment="Center" /> + FontSize="24" + HorizontalAlignment="Center" + VerticalAlignment="Center" /> -``` + ``` * Name the regions you defined by using the `Region.Name` attached property on both the content itself and associated navigation control item: -```xml + ```xml @@ -173,29 +173,29 @@ The navigation capabilities offered by Uno.Extensions include regions. Regions a + Style="{StaticResource MaterialNavigationBarStyle}" /> + Grid.Row="1"> + Visibility="Collapsed"> + FontSize="24" + HorizontalAlignment="Center" + VerticalAlignment="Center" /> + Visibility="Collapsed"> + FontSize="24" + HorizontalAlignment="Center" + VerticalAlignment="Center" /> + Visibility="Collapsed"> + FontSize="24" + HorizontalAlignment="Center" + VerticalAlignment="Center" /> -``` + ``` * Specify the navigator type as `Visibility` using the `Region.Navigator` attached property on the containing element of your collapsed content `Grid` definitions: -```xml + ```xml -``` + uen:Region.Navigator="Visibility" + Grid.Row="1"> + ``` -* When a `TabBarItem` is selected, the associated content region will now have its `Visibility` toggled to `Visible` +#### Navigating to Page elements + +* You may want to navigate to a `Page` view element represented by a route name. It is possible to do this without defining a view element alongside the other content regions. For instance, you may need to display a subscription sign up page `SignUpPage` which will be defined in a separate XAML file. + +* Add a new **Page** item to your app called `SignUpPage` with the following code: + + ```xml + + + + + +