Routing topic (#102)

aspnet · Jun 20, 2018 · e82b688 · e82b688
1 parent ab23417
commit e82b688
Show file tree

Hide file tree

Showing 5 changed files with 70 additions and 3 deletions.
diff --git a/docs/components/index.md b/docs/components/index.md
@@ -380,7 +380,7 @@ Razor directives active with Blazor apps are shown in the following table.
 | [@inherits](https://docs.microsoft.com/aspnet/core/mvc/views/razor#inherits) | Provides full control of the class that the component inherits. |
 | [@inject](https://docs.microsoft.com/aspnet/core/mvc/views/razor#inject) | Enables service injection from the [service container](https://docs.microsoft.com/aspnet/core/fundamentals/dependency-injection). For more information, see [Dependency injection into views](https://docs.microsoft.com/aspnet/core/mvc/views/dependency-injection). |
 | `@layout` | Specifies a layout component. Layout components are used to avoid code duplication and inconsistency. |
-| [@page](https://docs.microsoft.com/aspnet/core/mvc/razor-pages#razor-pages) | Specifies that the component should handle requests directly. The `@page` directive can be specified with a route and optional parameters. Unlike Razor Pages, the `@page` directive doesn't need to be the first directive at the top of the file. |
+| [@page](https://docs.microsoft.com/aspnet/core/mvc/razor-pages#razor-pages) | Specifies that the component should handle requests directly. The `@page` directive can be specified with a route and optional parameters. Unlike Razor Pages, the `@page` directive doesn't need to be the first directive at the top of the file. For more information, see [Routing](xref:client-side/blazor/routing). |
 | [@using](https://docs.microsoft.com/aspnet/core/mvc/views/razor#using) | Adds the C# `using` directive to the generated component class. |
 | [@addTagHelper](https://docs.microsoft.com/aspnet/core/mvc/views/razor#tag-helpers) | Use `@addTagHelper` to use a component in a different assembly than the app's assembly. |
 

diff --git a/docs/dependency-injection.md b/docs/dependency-injection.md
@@ -1,7 +1,7 @@
 ---
 title: Dependency injection in Blazor
 author: rstropek
-description: Learn how Blazor apps can use built-in services by having them injected into components.
+description: See how Blazor apps can use built-in services by having them injected into components.
 manager: wpickett
 ms.author: riande
 ms.custom: mvc

diff --git a/docs/index.md b/docs/index.md
@@ -39,7 +39,10 @@ Create and use Blazor components, the fundamental building blocks of Blazor apps
 Learn how to create reusable layout components for Blazor apps.
 
 [Dependency injection](xref:client-side/blazor/dependency-injection)  
-Learn how Blazor apps can use built-in services by having them injected into components.
+See how Blazor apps can use built-in services by having them injected into components.
+
+[Routing](xref:client-side/blazor/routing)  
+Learn how to route requests in a client-side Blazor app and about the NavLink component.
 
 [JavaScript interop](xref:client-side/blazor/javascript-interop)  
 Learn how to invoke JavaScript functions from .NET and .NET methods from JavaScript.

diff --git a/docs/routing.md b/docs/routing.md
@@ -0,0 +1,63 @@
+---
+title: Blazor routing
+author: guardrex
+description: Learn how to route requests in a client-side Blazor app and about the NavLink component.
+manager: wpickett
+ms.author: riande
+ms.custom: mvc
+ms.date: 05/01/2018
+ms.prod: asp.net-core
+ms.technology: aspnet
+ms.topic: article
+uid: client-side/blazor/routing
+---
+# Blazor routing
+
+By [Luke Latham](https://github.com/guardrex)
+
+[!INCLUDE[](~/includes/blazor-preview-notice.md)]
+
+Learn how to route requests in a client-side Blazor app and about the NavLink component.
+
+[View or download sample code](https://github.com/aspnet/Blazor.Docs/tree/master/docs/components/common/samples/) ([how to download](xref:client-side/blazor/index#view-and-download-samples)). See the [Get started](xref:client-side/blazor/get-started) topic for prerequisites.
+
+## Route templates
+
+The **&lt;Router&gt;** component enables routing, and a route template is provided to each accessible component. The **&lt;Router&gt;** component appears in the *App.cshtml* file:
+
+```cshtml
+<Router AppAssembly=typeof(Program).Assembly />
+```
+
+When a *\*.cshtml* file with an `@page` directive is compiled, the generated class is given a [RouteAttribute](https://docs.microsoft.com/dotnet/api/microsoft.aspnetcore.mvc.routeattribute) specifying the route template. At runtime, the router looks for component classes with a `RouteAttribute` and renders whichever component has a route template that matches the requested URL.
+
+Multiple route templates can be applied to a component. In the [sample app](https://github.com/aspnet/Blazor.Docs/tree/master/docs/components/common/samples/), the following component responds to requests for `/BlazorRoute` and `/DifferentBlazorRoute`.
+
+*Pages/BlazorRoute.cshtml*:
+
+[!code-cshtml[](components/common/samples/2.x/ComponentsSample/Pages/BlazorRoute.cshtml?start=1&end=4)]
+
+## Route parameters
+
+The Blazor client-side router uses route parameters to populate the corresponding component parameters with the same name (case insensitive).
+
+*Pages/RouteParameter.cshtml*:
+
+[!code-cshtml[](components/common/samples/2.x/ComponentsSample/Pages/RouteParameter.cshtml?start=1&end=8)]
+
+Optional parameters aren't supported yet, so two `@page` directives are applied in the example above. The first permits navigation to the component without a parameter. The second `@page` directive takes the `{text}` route parameter and assigns the value to the `Text` property.
+
+## NavLink component
+
+Use a NavLink component in place of HTML **\<a>** elements when creating navigation links. A NavLink component behaves like an **\<a>** element, except it toggles an `active` CSS class based on whether its `href` matches the current URL. The `active` class helps a user understand which page is the active page among the navigation links displayed.
+
+The NavMenu component in the [sample app](https://github.com/aspnet/Blazor.Docs/tree/master/docs/components/common/samples/) creates a [Bootstrap](https://getbootstrap.com/docs/) nav bar that demonstrates how to use NavLink components. The following markup shows the first two NavLinks in the *Shared/NavMenu.cshtml* file.
+
+[!code-cshtml[](components/common/samples/2.x/ComponentsSample/Shared/NavMenu.cshtml?start=13&end=24&highlight=4-6,9-11)]
+
+There are two [NavLinkMatch](/api/Microsoft.AspNetCore.Blazor.Routing.NavLinkMatch.html) options:
+
+* `NavLinkMatch.All` &ndash; Specifies that the NavLink should be active when it matches the entire current URL.
+* `NavLinkMatch.Prefix` &ndash; Specifies that the NavLink should be active when it matches any prefix of the current URL.
+
+In the preceding example, the Home NavLink (`href="/"`) matches all URLs and always receives the `active` CSS class. The second NavLink only receives the `active` class when the user visits the BlazorRoute component (`href="/BlazorRoute"`).
diff --git a/docs/toc.md b/docs/toc.md
@@ -4,6 +4,7 @@
 # [Components](xref:client-side/blazor/components/index)
 # [Layouts](xref:client-side/blazor/layouts)
 # [Dependency injection](xref:client-side/blazor/dependency-injection)
+# [Routing](xref:client-side/blazor/routing)
 # [JavaScript interop](xref:client-side/blazor/javascript-interop)
 # [Host and deploy](xref:client-side/blazor/host-and-deploy/index)
 # [FAQ](xref:client-side/blazor/introduction/faq)