Ra/js/collocation/2 (#33697)

* Add example for configuring JS collocation in _Layout.cshtml

This advice should work for Razor pages and for MVC views. I'm not sure about scripts provided by Razor class libraries, I don't use them personally.

* Update aspnetcore/includes/js-collocation.md

Co-authored-by: Rick Anderson <[email protected]>

* Add ScriptTagHelper sample with collocated JS files

* Escape Razor syntax

* Fix typo in ommitted->omitted

* Fix sample mistakes here and there

* Update aspnetcore/includes/js-collocation.md

* JS colloc /2

* JS colloc /2

* JS colloc /2

* JS colloc /2

* JS colloc /2

* JS colloc /2

* JS colloc /2

* JS colloc /2

---------

Co-authored-by: Steven <[email protected]>

aspnetcore/includes/js-collocation.md

@@ -26,6 +26,12 @@ Collocated JS files are publicly addressable using the ***path to the file in th
   }
   ```
 
+The default layout `Pages/Shared/_Layout.cshtml` can be configured to include collocated JS files, eliminating the need to configure each page individually:
+
+:::code language="razor" source="~/mvc/views/tag-helpers/built-in/samples/ScriptTagHelper/Pages/Shared/_Layout.cshtml"  range="54-54":::
+
+The [sample download](https://github.com/dotnet/AspNetCore.Docs/tree/main/aspnetcore/mvc/views/tag-helpers/built-in/samples/ScriptTagHelper) uses the preceding code snippet to include collocated JS files in the default layout.
+
   When the app is published, the framework automatically moves the script to the web root. In the preceding example, the script is moved to `bin\Release\{TARGET FRAMEWORK MONIKER}\publish\wwwroot\Pages\Index.cshtml.js`, where the `{TARGET FRAMEWORK MONIKER}` placeholder is the [Target Framework Moniker (TFM)](/dotnet/standard/frameworks). No change is required to the script's relative URL in the `Index` page.
 
   When the app is published, the framework automatically moves the script to the web root. In the preceding example, the script is moved to `bin\Release\{TARGET FRAMEWORK MONIKER}\publish\wwwroot\Components\Pages\Index.razor.js`, where the `{TARGET FRAMEWORK MONIKER}` placeholder is the [Target Framework Moniker (TFM)](/dotnet/standard/frameworks). No change is required to the script's relative URL in the `Index` component.

aspnetcore/mvc/views/tag-helpers/built-in/samples/ScriptTagHelper/Pages/CollocatedScript.cshtml

@@ -0,0 +1,34 @@
+@page
+@model CollocatedScriptModel
+@{
+    ViewData["Title"] = "Collocated JS script";
+}
+<h1>@ViewData["Title"]</h1>
+
+<p>This page consists of 3 files:</p>
+
+<ol>
+    <li>CollocatedScript.cshtml</li>
+    <li>CollocatedScript.cshtml.cs</li>
+    <li>CollocatedScript.cshtml.js</li>
+</ol>
+
+<p>JavaScript code can be added to "Collocated.cshtml.js". This file is included in the page by a ScriptTagHelper in "/Pages/Shared/_Layout.cshtml":</p>
+
+<code>
+    <pre>
+    &lt;!-- in /Pages/Shared/_Layout.cshtml --&gt;
+    &lt;script asp-src-include="@@(ViewContext.View.Path).js"&gt;&lt;/script&gt;
+    </pre>
+</code>
+
+<p>The <code>asp-src-include</code> attribute is used to dynamically include collocated JS files. When a page has a matching JS file, a script tag is rendered.</p>
+
+<code>
+    <pre>
+    &lt;!-- Rendered markup --&gt;
+    &lt;script src="/Pages/CollocatedScript.cshtml.js"&gt;&lt;/script&gt;
+    </pre>
+</code>
+
+<p>On the other hand, if there is no matching JS file, the script tag is removed.</p>

aspnetcore/mvc/views/tag-helpers/built-in/samples/ScriptTagHelper/Pages/CollocatedScript.cshtml.cs

@@ -0,0 +1,18 @@
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.RazorPages;
+
+namespace ScriptTagHelper.Pages;
+
+public class CollocatedScriptModel : PageModel
+{
+    private readonly ILogger<CollocatedScriptModel> _logger;
+
+    public CollocatedScriptModel(ILogger<CollocatedScriptModel> logger)
+    {
+        _logger = logger;
+    }
+
+    public void OnGet()
+    {
+    }
+}

aspnetcore/mvc/views/tag-helpers/built-in/samples/ScriptTagHelper/Pages/CollocatedScript.cshtml.js

@@ -0,0 +1,2 @@
+// This script is included in the page by a ScriptTagHelper in /Pages/Shared/_Layout.cshtml
+alert('Hello from CollocatedScript.cshtml.js');

aspnetcore/mvc/views/tag-helpers/built-in/samples/ScriptTagHelper/Pages/Error.cshtml

@@ -0,0 +1,26 @@
+@page
+@model ErrorModel
+@{
+    ViewData["Title"] = "Error";
+}
+
+<h1 class="text-danger">Error.</h1>
+<h2 class="text-danger">An error occurred while processing your request.</h2>
+
+@if (Model.ShowRequestId)
+{
+    <p>
+        <strong>Request ID:</strong> <code>@Model.RequestId</code>
+    </p>
+}
+
+<h3>Development Mode</h3>
+<p>
+    Swapping to the <strong>Development</strong> environment displays detailed information about the error that occurred.
+</p>
+<p>
+    <strong>The Development environment shouldn't be enabled for deployed applications.</strong>
+    It can result in displaying sensitive information from exceptions to end users.
+    For local debugging, enable the <strong>Development</strong> environment by setting the <strong>ASPNETCORE_ENVIRONMENT</strong> environment variable to <strong>Development</strong>
+    and restarting the app.
+</p>

aspnetcore/mvc/views/tag-helpers/built-in/samples/ScriptTagHelper/Pages/Error.cshtml.cs

@@ -0,0 +1,27 @@
+using System.Diagnostics;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.RazorPages;
+
+namespace ScriptTagHelper.Pages;
+
+[ResponseCache(Duration = 0, Location = ResponseCacheLocation.None, NoStore = true)]
+[IgnoreAntiforgeryToken]
+public class ErrorModel : PageModel
+{
+    public string? RequestId { get; set; }
+
+    public bool ShowRequestId => !string.IsNullOrEmpty(RequestId);
+
+    private readonly ILogger<ErrorModel> _logger;
+
+    public ErrorModel(ILogger<ErrorModel> logger)
+    {
+        _logger = logger;
+    }
+
+    public void OnGet()
+    {
+        RequestId = Activity.Current?.Id ?? HttpContext.TraceIdentifier;
+    }
+}
+

aspnetcore/mvc/views/tag-helpers/built-in/samples/ScriptTagHelper/Pages/Index.cshtml

@@ -0,0 +1,10 @@
+@page
+@model IndexModel
+@{
+    ViewData["Title"] = "Home page";
+}
+
+<div class="text-center">
+    <h1 class="display-4">Welcome</h1>
+    <p>Check out the links at the top for ScriptTagHelper samples.</p>
+</div>

aspnetcore/mvc/views/tag-helpers/built-in/samples/ScriptTagHelper/Pages/Index.cshtml.cs

@@ -0,0 +1,19 @@
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.RazorPages;
+
+namespace ScriptTagHelper.Pages;
+
+public class IndexModel : PageModel
+{
+    private readonly ILogger<IndexModel> _logger;
+
+    public IndexModel(ILogger<IndexModel> logger)
+    {
+        _logger = logger;
+    }
+
+    public void OnGet()
+    {
+
+    }
+}

aspnetcore/mvc/views/tag-helpers/built-in/samples/ScriptTagHelper/Pages/NoScript.cshtml

@@ -0,0 +1,15 @@
+@page
+@model NoScriptModel
+@{
+    ViewData["Title"] = "No JS script";
+}
+<h1>@ViewData["Title"]</h1>
+
+<p>This page consists of 2 files:</p>
+
+<ol>
+    <li>NoScript.cshtml</li>
+    <li>NoScript.cshtml.cs</li>
+</ol>
+
+<p>This page doesn't contain any JavaScript code of its own. Note that the ScriptTagHelper has omitted the script tag for <code>NoScript.cshtml.js</code>, because that file does not exist.</p>

aspnetcore/mvc/views/tag-helpers/built-in/samples/ScriptTagHelper/Pages/NoScript.cshtml.cs

@@ -0,0 +1,18 @@
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.AspNetCore.Mvc.RazorPages;
+
+namespace ScriptTagHelper.Pages;
+
+public class NoScriptModel : PageModel
+{
+    private readonly ILogger<NoScriptModel> _logger;
+
+    public NoScriptModel(ILogger<NoScriptModel> logger)
+    {
+        _logger = logger;
+    }
+
+    public void OnGet()
+    {
+    }
+}

aspnetcore/mvc/views/tag-helpers/built-in/samples/ScriptTagHelper/Pages/Shared/_Layout.cshtml

@@ -0,0 +1,58 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>@ViewData["Title"] - ScriptTagHelper</title>
+    <link rel="stylesheet" href="~/lib/bootstrap/dist/css/bootstrap.min.css" />
+    <link rel="stylesheet" href="~/css/site.css" asp-append-version="true" />
+    <link rel="stylesheet" href="~/ScriptTagHelper.styles.css" asp-append-version="true" />
+</head>
+<body>
+    <header>
+        <nav class="navbar navbar-expand-sm navbar-toggleable-sm navbar-light bg-white border-bottom box-shadow mb-3">
+            <div class="container">
+                <a class="navbar-brand" asp-area="" asp-page="/Index">ScriptTagHelper</a>
+                <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target=".navbar-collapse" aria-controls="navbarSupportedContent"
+                        aria-expanded="false" aria-label="Toggle navigation">
+                    <span class="navbar-toggler-icon"></span>
+                </button>
+                <div class="navbar-collapse collapse d-sm-inline-flex justify-content-between">
+                    <ul class="navbar-nav flex-grow-1">
+                        <li class="nav-item">
+                            <a class="nav-link text-dark" asp-area="" asp-page="/Index">Home</a>
+                        </li>
+                        <li class="nav-item">
+                            <a class="nav-link text-dark" asp-area="" asp-page="/CollocatedScript">Collocated JS</a>
+                        </li>
+                        <li class="nav-item">
+                            <a class="nav-link text-dark" asp-area="" asp-page="/NoScript">No JavaScript</a>
+                        </li>
+                    </ul>
+                </div>
+            </div>
+        </nav>
+    </header>
+    <div class="container">
+        <main role="main" class="pb-3">
+            @RenderBody()
+        </main>
+    </div>
+
+    <footer class="border-top footer text-muted">
+        <div class="container">
+            &copy; 2024 - ScriptTagHelper
+        </div>
+    </footer>
+
+    <script src="~/lib/jquery/dist/jquery.min.js"></script>
+    <script src="~/lib/bootstrap/dist/js/bootstrap.bundle.min.js"></script>
+    <script src="~/js/site.js" asp-append-version="true"></script>
+
+    @* Include collocated JS files *@
+
+    <script asp-src-include="@(ViewContext.View.Path).js"></script>
+
+    @await RenderSectionAsync("Scripts", required: false)
+</body>
+</html>

aspnetcore/mvc/views/tag-helpers/built-in/samples/ScriptTagHelper/Pages/Shared/_Layout.cshtml.css

@@ -0,0 +1,48 @@
+/* Please see documentation at https://learn.microsoft.com/aspnet/core/client-side/bundling-and-minification
+for details on configuring this project to bundle and minify static web assets. */
+
+a.navbar-brand {
+  white-space: normal;
+  text-align: center;
+  word-break: break-all;
+}
+
+a {
+  color: #0077cc;
+}
+
+.btn-primary {
+  color: #fff;
+  background-color: #1b6ec2;
+  border-color: #1861ac;
+}
+
+.nav-pills .nav-link.active, .nav-pills .show > .nav-link {
+  color: #fff;
+  background-color: #1b6ec2;
+  border-color: #1861ac;
+}
+
+.border-top {
+  border-top: 1px solid #e5e5e5;
+}
+.border-bottom {
+  border-bottom: 1px solid #e5e5e5;
+}
+
+.box-shadow {
+  box-shadow: 0 .25rem .75rem rgba(0, 0, 0, .05);
+}
+
+button.accept-policy {
+  font-size: 1rem;
+  line-height: inherit;
+}
+
+.footer {
+  position: absolute;
+  bottom: 0;
+  width: 100%;
+  white-space: nowrap;
+  line-height: 60px;
+}

aspnetcore/mvc/views/tag-helpers/built-in/samples/ScriptTagHelper/Pages/Shared/_ValidationScriptsPartial.cshtml

@@ -0,0 +1,2 @@
+<script src="~/lib/jquery-validation/dist/jquery.validate.min.js"></script>
+<script src="~/lib/jquery-validation-unobtrusive/jquery.validate.unobtrusive.min.js"></script>

aspnetcore/mvc/views/tag-helpers/built-in/samples/ScriptTagHelper/Pages/_ViewImports.cshtml

@@ -0,0 +1,3 @@
+@using ScriptTagHelper
+@namespace ScriptTagHelper.Pages
+@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers

aspnetcore/mvc/views/tag-helpers/built-in/samples/ScriptTagHelper/Pages/_ViewStart.cshtml

@@ -0,0 +1,3 @@
+@{
+    Layout = "_Layout";
+}

aspnetcore/mvc/views/tag-helpers/built-in/samples/ScriptTagHelper/Program.cs

@@ -0,0 +1,25 @@
+var builder = WebApplication.CreateBuilder(args);
+
+// Add services to the container.
+builder.Services.AddRazorPages();
+
+var app = builder.Build();
+
+// Configure the HTTP request pipeline.
+if (!app.Environment.IsDevelopment())
+{
+    app.UseExceptionHandler("/Error");
+    // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
+    app.UseHsts();
+}
+
+app.UseHttpsRedirection();
+app.UseStaticFiles();
+
+app.UseRouting();
+
+app.UseAuthorization();
+
+app.MapRazorPages();
+
+app.Run();

aspnetcore/mvc/views/tag-helpers/built-in/samples/ScriptTagHelper/ScriptTagHelper.csproj

@@ -0,0 +1,9 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <TargetFramework>net8.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+</Project>

aspnetcore/mvc/views/tag-helpers/built-in/samples/ScriptTagHelper/appsettings.Development.json

@@ -0,0 +1,9 @@
+{
+  "DetailedErrors": true,
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}

aspnetcore/mvc/views/tag-helpers/built-in/samples/ScriptTagHelper/appsettings.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "AllowedHosts": "*"
+}

aspnetcore/mvc/views/tag-helpers/built-in/samples/ScriptTagHelper/wwwroot/css/site.css

@@ -0,0 +1,22 @@
+html {
+  font-size: 14px;
+}
+
+@media (min-width: 768px) {
+  html {
+    font-size: 16px;
+  }
+}
+
+.btn:focus, .btn:active:focus, .btn-link.nav-link:focus, .form-control:focus, .form-check-input:focus {
+  box-shadow: 0 0 0 0.1rem white, 0 0 0 0.25rem #258cfb;
+}
+
+html {
+  position: relative;
+  min-height: 100%;
+}
+
+body {
+  margin-bottom: 60px;
+}

aspnetcore/mvc/views/tag-helpers/built-in/samples/ScriptTagHelper/wwwroot/js/site.js

@@ -0,0 +1,4 @@
+// Please see documentation at https://learn.microsoft.com/aspnet/core/client-side/bundling-and-minification
+// for details on configuring this project to bundle and minify static web assets.
+
+// Write your JavaScript code.