Pkellner built in th

aspnetcore/mvc/views/tag-helpers/builtin.md

@@ -2,16 +2,16 @@
 
 By [Peter Kellner](http://peterkellner.net) 
 
-Microsoft has included 17 Tag Helpers that can be immediately used in .net Core web projects.  These Tag Helpers are complete and production quality and are recommended to be used in projects where appropriate.  In this section we will outline all the built in Tag Helpers along with a sample of each tag helper in use.
+Microsoft has included multiple Tag Helpers that can be immediately used in .net Core web projects.  These Tag Helpers are complete and production quality and are recommended to be used in projects where appropriate.  In this section we will outline all the built in Tag Helpers along with a sample of each tag helper in use.
 
 > [!NOTE]
 > There are other Tag Helpers built in that are not discussed as they are used internally in the Razor view engine.  This includes a tag helper for the ~ character which expands to the root path of the web site (among others).
 
 ## Built in ASP.NET Core Tag Helpers
 
-**[AnchorTagHelper](builtin/resources/AnchorTagHelper.md)**
+**[Anchor Tag Helper](builtin/resources/AnchorTagHelper.md)**
 
-[comment]: **[CacheTagHelper](builtin/resources/AnchorTagHelper.md)**
+**[Cache Tag Helper](builtin/resources/CacheTagHelper.md)**
 
 [comment]: **[DistributedTagHelper](builtin/resources/AnchorTagHelper.md)**
 
@@ -21,7 +21,7 @@ Microsoft has included 17 Tag Helpers that can be immediately used in .net Core
 
 [comment]: **[FormTagTagHelper](builtin/resources/FormTagHelper.md)**
 
-[comment]: **[ImageTagHelper](builtin/resources/ImageTagHelper.md)**
+**[Image Tag Helper](builtin/resources/ImageTagHelper.md)**
 
 [comment]: **[InputTagHelper](builtin/resources/InputTagHelper.md)**
 
@@ -39,9 +39,9 @@ Microsoft has included 17 Tag Helpers that can be immediately used in .net Core
 
 [comment]: **[ValidationMessageTagHelper](builtin/resources/ValidationMessageTagHelper.md)**
 
-[comment]: **[ValidationSummaryHelper](builtin/resources/ValidationSummaryTagHelper.md)**
-
-<br/>
+[comment]: **[ValidationSummaryTagHelper](builtin/resources/ValidationSummaryTagHelper.md)**  
+  
+  
 
 ## Additional Resources
 

aspnetcore/mvc/views/tag-helpers/builtin/resources/AnchorTagHelper.md

@@ -1,74 +1,72 @@
 [Back To Built In Tag Helpers List](../../builtin.md)
 
 
-# AnchorTagHelper
+# Anchor Tag Helper
 
 By [Peter Kellner](http://peterkellner.net) 
 
 
-The ```AnchorTagHelper``` 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 redirect URL. That URL can include an optional protocol such as https.
+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.
 
-For reference, the following ASP.NET ```startup.cs``` and ```SpeakerController.cs``` are defined as you would expect in a default Visual Studio .Net Core Web Project.
-
-![](../_static/ProjectControllers.png)
-
-**Startup.cs**
-```
-// This method gets called by the runtime. 
-// Use this method to configure the 
-// HTTP request pipeline.
-public void Configure(IApplicationBuilder app, 
-    IHostingEnvironment env, 
-    ILoggerFactory loggerFactory)
-{
-    app.UseMvcWithDefaultRoute();
-    //...
-}  
-```
+The speaker controller used in attribute definitions below is shown here.
 
 <br/>
 **SpeakerController.cs** 
 
 [!code-csharp[SpeakerController](../sample/TagHelpersBuiltInAspNetCore/src/TagHelpersBuiltInAspNetCore/Controllers/SpeakerController.cs)]
 
-<br/>
-These attributes are defined as follows:
 
-## asp-controller
+## Anchor Tag Helper Attributes
+
+- - -
 
-```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. In our case, to get to a list of all speakers or speaker details you would specify ```asp-controller="Speaker"```. If you only specify ```asp-controller``` and no ```asp-action``` the URL will generate without an error but will likely not be what you expect.
+### asp-controller
 
-## asp-action
+`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.
 
-```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 a URL will generate without an error but will likely not be what you expect.
+- - -
+
+### asp-action
 
-## asp-route-
+`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.
 
-```asp-route-``` is basically 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 you create a tag as follows: 
+- - -
+
+### asp-route-{value}
 
-```<a  asp-controller="Speaker" asp-action="Detail" asp-route-id-="11">Speaker 11</a>``` 
+`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: 
 
-the href generated will be 
+`<a  asp-controller="Speaker" asp-action="Detail" asp-route-id-="11">Speaker 11</a>`
 
-```<a href="/Speaker/11">Speaker 11</a>```  
+the `href` generated will be 
+
+`<a href="/Speaker/11">Speaker 11</a>` 
 
 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 
 
-```<a  asp-controller="Speaker" asp-action="Detail" asp-route-name-="Ronald">Ronald</a>```
+`<a  asp-controller="Speaker" asp-action="Detail" asp-route-name-="Ronald">Ronald</a>`
 
 you would get generated the html 
 
-```<a href="/Speaker/Detail?Name=Ronald">Ronald</a>```
+`<a href="/Speaker/Detail?Name=Ronald">Ronald</a>`
+
+This is because there was no route found that matched a controller that had a method named `Detail` with one string parameter titled `name`.
 
-This is because there was no route found that matched a controller that had a method named ```Detail``` with one string parameter titled ```name```.
+- - -
 
-## asp-route
+### asp-route
 
-```asp-route``` provides a way to create a URL that links directly to a named route. Using routing attributes, you can name your routes as shown in the Evaluations method above of the ```SpeakerController```.  ```Name = "speakerevals"``` tells the AnchorTagHelper 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``` then the route generated will 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.
+`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.
 
-## asp-all-route-data
+`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.
 
-```asp-all-route-data``` allows you to create on your current .net context (that is, the running c# associated with your razor page) a dictionary of key value pairs where the key is the parameter name and the value is the value associated with that key. As the example below shows, you can create an inline dictionary on your razor page and then create the ```AnchorTagHelper``` right after that. You could of course pass in the dictionary with your model or as your model. That avoids having extra c# code on your razor page and gives you better control of the data passed to your view.
+- - -
+
+### asp-all-route-data
+
+`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. 
+
+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.
 
 ```
 @{
@@ -89,33 +87,59 @@ The code that this generates looks as follows:
 http://localhost/Speaker/EvaluationsCurrent?speakerId=11&currentYear=true
 ```
 
-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.
+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.
+
+- - -
 
-## asp-fragment
+### asp-fragment
 
-```asp-fragment``` appends after a hash (```#```) tag at the end of the URL whatever the value assigned to it is. That is, if you create a tag
+`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:
 
 ```
 <a asp-action="Evaluations" asp-controller="Speaker"  
    asp-fragment="SpeakerEvaluations">About Speaker Evals</a>
 ```
+
 The generated URL will be
 
+
 ```
 http://localhost/Speaker/Evaluations#SpeakerEvaluations
 ```
+
 Hash tags are useful when doing client side applications. They can be used for easy marking and searching in JavaScript for example.
 
+- - -
 
-## asp-area
+### asp-area
 
-```asp-area``` allows for a razor view area to be associated with the hyperlink URL. That is, if you have a project setup in a similar fashion to the project pictured below, the link generated will include as its first segment the area you mention.
+`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..
 
-![](../_static/ProjectControllersArea.png)
+* Project name
 
-Specifying an area tag that is valid, such as ```area="Blogs"``` when referencing the ```AboutBlog.cshtml``` file will look like the following using the ```AnchorTagHelper```.
+  * *wwwroot*
+
+  * *Areas*
+
+    * *Blogs*
+
+      * *Controllers*
+
+        * *HomeController.cs*
+
+      * *Views*
+
+        * *Home*
+
+          * *Index.cshtml*
+
+          * *AboutBlog.cshtml*
+
+  * *Controllers*
+
+
+
+Specifying an area tag that is valid, such as ```area="Blogs"``` when referencing the ```AboutBlog.cshtml``` file will look like the following using the Anchor Tag Helper.
 
 ```
 <a asp-action="AboutBlog" asp-controller="Home" asp-area="Blogs">Blogs About</a>
@@ -128,20 +152,28 @@ The generated HTML will include the areas segment and will be as follows:
 ```
 
 > [!TIP]
-> For MVC Areas to work in your web application, the route template must include a reference to the area if it exists. That template (which is the second parameter of the ```routes.MapRoute``` method call) will look as follows: ```template: "{area:exists}/{controller=Home}/{action=Index}"```.
-
+> For MVC areas to work in a web application, the route template must include a reference to the area if it exists. That template, which is the second parameter of the `routes.MapRoute` method call, will appear as: template: '"{area:exists}/{controller=Home}/{action=Index}"'
 
+- - -
 
-## asp-protocol
+### asp-protocol
 
-The ```asp-protocol``` is for specifying a particular protocol (such as ```https```) in your URL. An example ```AnchorTagHelper``` that includes the protocol will look as follows.
+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.
 
 ```<a asp-protocol="https" asp-action="About" asp-controller="Home">About</a>```
 
 and will generate HTML as follows.
 
 ```<a href="https://localhost/Home/About">About</a>```
 
-(of course the domain, in the case above is localhost, but this will be substituted for whatever the actual domain hosting the web site is hosted at).
+The domain in the example is localhost, but the Anchor Tag Helper uses the website's public domain when generating the URL.
+
+- - -
+
+## Additional Resources
+
+* [Areas](../../../../controllers/areas.md)
+
+