Skip to content

Commit 1836273

Browse files
pkellnerRick Anderson
pkellner
authored and
Rick Anderson
committed
Ra p kellner built in th (#2785)
* Put in more reasonable cache times for examples. * Added to ImageTagHelper.md a block on the top and guessed at updating assetid by incrementing 1. Renamed all Additional Resources to Resources per @Devguard, fixed incorrect expires-sliding code example, removed warning about Cache NeverRemove. * fixed blank lines below toc entry, made consistent "Additional resources", put back in warning about NeverRemove based on feedback from team: #2698 (comment) * clean up * created Distributed and Environment Tag Helper Doc Pages and worked on environment. * Reworked sections from @Rick-Anderson previous commit and removed review comments. * Updated Anchor Tag Helper's definition of asp-action and asp-controller to be more explicit about defaults as well as say "href" instead of "final URL". * I realized that asp-all-route-data also behaves like asp-route-* with routing parameters so I updated the doc to reflect that. * Updated var-by-route definition following comments from Damien in old github post aspnet/Mvc#1552 * Cleanup of Tag Helper Docs * changed author to pkellner from Peter Kellner per @mairaw * Update AnchorTagHelper.md * Update CacheTagHelper.md * Minor tweaks
1 parent 8e7e564 commit 1836273

File tree

6 files changed

+272
-71
lines changed

6 files changed

+272
-71
lines changed

‎aspnetcore/mvc/views/tag-helpers/built-in/AnchorTagHelper.md

Lines changed: 104 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
1-
---
1+
---
22
title: Anchor Tag Helper | Microsoft Docs
3-
author: Peter Kellner
3+
author: pkellner
44
description: Shows how to work with Anchor Tag Helper
55
keywords: ASP.NET Core,tag helper
66
ms.author: riande
@@ -12,15 +12,13 @@ ms.technology: aspnet
1212
ms.prod: aspnet-core
1313
uid: mvc/views/tag-helpers/builtin-th/AnchorTagHelper
1414
---
15-
1615
# Anchor Tag Helper
1716

1817
By [Peter Kellner](http://peterkellner.net)
1918

19+
The Anchor Tag Helper enhances the HTML anchor (`<a ... ></a>`) tag by adding new attributes. The link generated (on the `href` tag) is created using the new attributes. That URL can include an optional protocol such as https.
2020

21-
The Anchor Tag Helper enhances the html anchor (`<a ... ></a>`) tag. A new set of attributes are defined that work with the anchor tag. The link generated (on the `href` tag) is based on a combination of these new attributes that work together to form the final URL. That URL can include an optional protocol such as https.
22-
23-
The speaker controller used in attribute definitions below is shown here.
21+
The speaker controller below is used in samples in this document.
2422

2523
<br/>
2624
**SpeakerController.cs**
@@ -34,51 +32,126 @@ The speaker controller used in attribute definitions below is shown here.
3432

3533
### asp-controller
3634

37-
`asp-controller` is used to associate which controller will be used to generate the final URL. The only valid choices are controllers that exist in the current project. To get to a list of all speakers specifying `asp-controller="Speaker"` is required. If only the `asp-controller` and no `asp-action` is specified, the default asp-action will be the name of the the controller method calling this view page.
35+
`asp-controller` is used to associate which controller will be used to generate the URL. The controllers specified must exist in the current project. The following code lists all speakers:
36+
37+
```
38+
<a asp-controller="Speaker" asp-action="Index" >All Speakers</a>
39+
```
40+
41+
The generated URL will be:
42+
43+
```
44+
<a href="/Speaker">All Speakers</a>
45+
```
46+
47+
If the `asp-controller` is specified and `asp-action` is not, the default `asp-action` will be the default controller method of the currently executing view. That is, in the above example, if `asp-action` is left out, and this Anchor Tag Helper is generated from *HomeController*'s `Index` view (**/Home**), the generated markup will be:
48+
49+
50+
```html
51+
<a href="/Home">All Speakers</a>
52+
```
3853

3954
- - -
4055

4156
### asp-action
4257

43-
`asp-action` is the name of the method in the controller that will be included in the final URL. That is, in the example, if the route to the Speaker Detail page is wanted, then the attribute should be set to `asp-action=Detail`. You should always set `asp-controller` when specifying `asp-action`. If no `asp-action` is specified then the default `asp-controller` will be the current executing controller.
58+
`asp-action` is the name of the action method in the controller that will be included in the generated `href`. For example, the following code set the generated `href` to point to the speaker detail page:
59+
60+
```html
61+
<a asp-controller="Speaker" asp-action="Detail" >Speaker Detail</a>
62+
```
63+
64+
The generated URL will be:
65+
66+
```html
67+
<a href="/Speaker/Detail">Speaker Detail</a>
68+
```
69+
70+
If no `asp-controller` attribute is specified, the default controller calling the view executing the current view will be used.
71+
72+
If the attribute `asp-action` is `Index`, then no action is appended to the URL, leading to the default `Index` method being called. The action specified (or defaulted), must exist in the controller referenced in `asp-controller`.
4473

4574
- - -
4675

4776
### asp-route-{value}
4877

49-
`asp-route-` is a wild card route prefix. Any value you put after the trailing dash will be interpreted as the parameter to pass into the route. For example, if a tag is created as follows:
78+
`asp-route-` is a wild card route prefix. Any value you put after the trailing dash will be interpreted as a potential route parameter. If a default route is not found, this route prefix will be appended to the generated href as a request parameter and value. Otherwise it will be substituted in the route template.
79+
80+
Assuming you have a controller method defined as follows:
81+
82+
```csharp
83+
public IActionResult AnchorTagHelper(string id)
84+
{
85+
var speaker = new SpeakerData()
86+
{
87+
SpeakerId = 12
88+
};
89+
return View(viewName, speaker);
90+
}
91+
```
92+
93+
And have the default route template defined in your **Startup.cs** as follows:
94+
95+
```csharp
96+
app.UseMvc(routes =>
97+
{
98+
routes.MapRoute(
99+
name: "default",
100+
template: "{controller=Home}/{action=Index}/{id?}");
101+
});
102+
103+
```
50104

51-
`<a asp-controller="Speaker" asp-action="Detail" asp-route-id-="11">Speaker 11</a>`
105+
The **cshtml** file that contains the Anchor Tag Helper necessary to use the **speaker** model parameter passed in from the controller to the view is as follows:
52106

53-
the `href` generated will be
107+
```html
108+
@model SpeakerData
109+
<!DOCTYPE html>
110+
<html><body>
111+
<a asp-controller='Speaker' asp-action='Detail' asp-route-id=@Model.SpeakerId>SpeakerId: @Model.SpeakerId</a>
112+
<body></html>
113+
```
54114

55-
`<a href="/Speaker/11">Speaker 11</a>`
115+
The generated HTML will then be as follows because **id** was found in the default route.
56116

57-
This is because a route was found that matched a single parameter "id" in the ```SpeakerController``` method ```Detail```. If there was no parameter match, say for example you created the tag helper
117+
```html
118+
<a href='/Speaker/Detail/12'>SpeakerId: 12</a>
119+
```
58120

59-
`<a asp-controller="Speaker" asp-action="Detail" asp-route-name-="Ronald">Ronald</a>`
121+
If the route prefix is not part of the routing template found, which is the case with the following **cshtml** file:
60122

61-
you would get generated the html
123+
```html
124+
@model SpeakerData
125+
<!DOCTYPE html>
126+
<html><body>
127+
<a asp-controller='Speaker' asp-action='Detail' asp-route-speakerid=@Model.SpeakerId>SpeakerId: @Model.SpeakerId</a>
128+
<body></html>
129+
```
62130

63-
`<a href="/Speaker/Detail?Name=Ronald">Ronald</a>`
131+
The generated HTML will then be as follows because **speakerid** was not found in the route matched:
64132

65-
This is because there was no route found that matched a controller that had a method named `Detail` with one string parameter titled `name`.
133+
134+
```html
135+
<a href='/Speaker/Detail?speakerid=12'>SpeakerId: 12</a>
136+
```
137+
138+
If either `asp-controller` or `asp-action` are not specified, then the same default processing is followed as is in the `asp-route` attribute.
66139

67140
- - -
68141

69142
### asp-route
70143

71144
`asp-route` provides a way to create a URL that links directly to a named route. Using routing attributes, a route can be named as shown in the `SpeakerController` and used in its `Evaluations` method.
72145

73-
`Name = "speakerevals"` tells the Anchor Tag Helper to generate a route directly to that controller method using the URL `/Speaker/Evaluations`. If `asp-controller` or `asp-action` is specified in addition to `asp-route`, the route generated may not be what you expect. `asp-route` should not be used with either of the attributes `asp-controller` or `asp-action` to avoid a route conflict.
146+
`Name = "speakerevals"` tells the Anchor Tag Helper to generate a route directly to that controller method using the URL `/Speaker/Evaluations`. If `asp-controller` or `asp-action` is specified in addition to `asp-route`, the route generated may not be what you expect. `asp-route` should not be used with either of the attributes `asp-controller` or `asp-action` to avoid a route conflict.
74147

75148
- - -
76149

77150
### asp-all-route-data
78151

79-
`asp-all-route-data` allows creating on a .NET context (that is, the running C# associated with your Razor view) a dictionary of key value pairs where the key is the parameter name and the value is the value associated with that key.
152+
`asp-all-route-data` allows creating a dictionary of key value pairs where the key is the parameter name and the value is the value associated with that key.
80153

81-
As the example below shows, an inline dictionary is created and the data is passed to the razor view. The data could also be passed in with your model to keep the Razor view simpler.
154+
As the example below shows, an inline dictionary is created and the data is passed to the razor view. As an alternative, the data could also be passed in with your model.
82155

83156
```
84157
@{
@@ -93,39 +166,40 @@ As the example below shows, an inline dictionary is created and the data is pass
93166
asp-all-route-data="dict">SpeakerEvals</a>
94167
```
95168

96-
The code that this generates looks as follows:
169+
The code above generates the following HTML:
97170

98171
```
99172
http://localhost/Speaker/EvaluationsCurrent?speakerId=11&currentYear=true
100173
```
101174

102-
When the link is clicked, this will call the controller method `EvaluationsCurrent` because that controller has two string parameters that match what has been created from the `asp-all-route-data` dictionary.
175+
When the link is clicked, the controller method `EvaluationsCurrent` is called. It is called because that controller has two string parameters that match what has been created from the `asp-all-route-data` dictionary.
176+
177+
If any keys in the dictionary match route parameters, those values will be substituted in the route as appropriate and the other non-matching values will be generated as request parameters.
103178

104179
- - -
105180

106181
### asp-fragment
107182

108-
`asp-fragment` defines a URL fragment to append to the URL. The Anchor Tag Helper will add the hash character (#) automatically. If you create a tag:
183+
`asp-fragment` defines a URL fragment to append to the URL. The Anchor Tag Helper will add the hash character (#). If you create a tag:
109184

110185
```
111186
<a asp-action="Evaluations" asp-controller="Speaker"
112187
asp-fragment="SpeakerEvaluations">About Speaker Evals</a>
113188
```
114189

115-
The generated URL will be
116-
190+
The generated URL will be:
117191

118192
```
119193
http://localhost/Speaker/Evaluations#SpeakerEvaluations
120194
```
121195

122-
Hash tags are useful when doing client side applications. They can be used for easy marking and searching in JavaScript for example.
196+
Hash tags are useful when building client-side applications. They can be used for easy marking and searching in JavaScript, for example.
123197

124198
- - -
125199

126200
### asp-area
127201

128-
`asp-area` sets the area name that ASP.NET Core uses to set the appropriate route. Below are examples of how the area attribute causes a remapping of routes. Setting `asp-area` to Blogs prefixes the directory Areas/Blogs to the routes of the associated controllers and views for this anchor tag..
202+
`asp-area` sets the area name that ASP.NET Core uses to set the appropriate route. Below are examples of how the area attribute causes a remapping of routes. Setting `asp-area` to Blogs prefixes the directory `Areas/Blogs` to the routes of the associated controllers and views for this anchor tag.
129203

130204
* Project name
131205

@@ -170,19 +244,19 @@ The generated HTML will include the areas segment and will be as follows:
170244

171245
### asp-protocol
172246

173-
The `asp-protocol` is for specifying a particular protocol (such as `https`) in your URL. An example Anchor Tag Helper that includes the protocol will look as follows.
247+
The `asp-protocol` is for specifying a protocol (such as `https`) in your URL. An example Anchor Tag Helper that includes the protocol will look as follows:
174248

175249
```<a asp-protocol="https" asp-action="About" asp-controller="Home">About</a>```
176250

177-
and will generate HTML as follows.
251+
and will generate HTML as follows:
178252

179253
```<a href="https://localhost/Home/About">About</a>```
180254

181255
The domain in the example is localhost, but the Anchor Tag Helper uses the website's public domain when generating the URL.
182256

183257
- - -
184258

185-
## Additional Resources
259+
## Additional resources
186260

187261
* [Areas](xref:mvc/controllers/areas)
188262

0 commit comments

Comments
 (0)