diff --git a/README.md b/README.md index 408c297..6762cd1 100644 --- a/README.md +++ b/README.md @@ -15,73 +15,97 @@ This package will generate a template class for every `.cshtml` file in your pro The generated classes will inherit from `RazorBlade.HtmlTemplate` by default, though it is advised to specify the base class explicitly to get the best IDE experience: -````Razor + + +```cshtml @inherits RazorBlade.HtmlTemplate -```` +``` +snippet source | anchor + -A version with a model is also available for convenience. The following will add a `Model` property and a constructor with a `TModel` parameter: +A version with a model is also available for convenience. The following will add a `Model` property and a constructor with a `ModelType` parameter: -```Razor -@inherits RazorBlade.HtmlTemplate + + +```cshtml +@inherits RazorBlade.HtmlTemplate ``` +snippet source | anchor + Further [documentation](#Documentation) is provided below. ## Example -The following template, in the `TestTemplate.cshtml` file: +The following template, in the `ExampleTemplate.cshtml` file: -```Razor + + +```cshtml @inherits RazorBlade.HtmlTemplate Hello, @Name! @functions { - public string? Name { get; set; } + public string? Name { get; init; } } ``` +snippet source | anchor + Will generate the following class in your project: -```C# -internal partial class TestTemplate : RazorBlade.HtmlTemplate +```cs +internal partial class ExampleTemplate : RazorBlade.HtmlTemplate { // ... - public string? Name { get; set; } + public string? Name { get; init; } // ... } ``` That you can use like the following: -```C# -var template = new TestTemplate + + +```cs +var template = new ExampleTemplate { Name = "World" }; var result = template.Render(); ``` +snippet source | anchor + ### With a model A similar template with a model would be: -```Razor -@using MyApplication.Models + + +```cshtml +@using MyApplication @inherits RazorBlade.HtmlTemplate Hello, @Model.Name! ``` +snippet source | anchor + Instantiating the generated class requires a model argument: -```C# + + +```cs var model = new GreetingModel { Name = "World" }; -var template = new TestTemplate(model); +var template = new TemplateWithModel(model); var result = template.Render(); ``` +snippet source | anchor + ## Documentation @@ -116,11 +140,15 @@ Layout templates may be written by inheriting from the `RazorBlade.HtmlLayout` c The layout to use can be specified through the `Layout` property of `RazorBlade.HtmlTemplate`. Given that all Razor templates are stateful and not thread-safe, always create a new instance of the layout page to use: -```Razor + + +```cshtml @{ Layout = new LayoutToUse(); } ``` +snippet source | anchor + Layout pages can be nested, and can use sections. Unlike in ASP.NET, RazorBlade does not verify if the body and all sections have been used. Sections may also be executed multiple times. diff --git a/src/RazorBlade.IntegrationTest/Examples/EmptyTemplate.cshtml b/src/RazorBlade.IntegrationTest/Examples/EmptyTemplate.cshtml new file mode 100644 index 0000000..9dbb1d7 --- /dev/null +++ b/src/RazorBlade.IntegrationTest/Examples/EmptyTemplate.cshtml @@ -0,0 +1 @@ +@inherits RazorBlade.HtmlTemplate diff --git a/src/RazorBlade.IntegrationTest/Examples/EmptyTemplateWithModel.cshtml b/src/RazorBlade.IntegrationTest/Examples/EmptyTemplateWithModel.cshtml new file mode 100644 index 0000000..f758e1b --- /dev/null +++ b/src/RazorBlade.IntegrationTest/Examples/EmptyTemplateWithModel.cshtml @@ -0,0 +1 @@ +@inherits RazorBlade.HtmlTemplate diff --git a/src/RazorBlade.IntegrationTest/Examples/ExampleTemplate.cshtml b/src/RazorBlade.IntegrationTest/Examples/ExampleTemplate.cshtml new file mode 100644 index 0000000..77d1a74 --- /dev/null +++ b/src/RazorBlade.IntegrationTest/Examples/ExampleTemplate.cshtml @@ -0,0 +1,8 @@ +@inherits RazorBlade.HtmlTemplate + +Hello, @Name! + +@functions +{ + public string? Name { get; init; } +} diff --git a/src/RazorBlade.IntegrationTest/Examples/Examples.cs b/src/RazorBlade.IntegrationTest/Examples/Examples.cs new file mode 100644 index 0000000..d77bf9e --- /dev/null +++ b/src/RazorBlade.IntegrationTest/Examples/Examples.cs @@ -0,0 +1,46 @@ +using System.Diagnostics.CodeAnalysis; +using JetBrains.Annotations; +using MyApplication; + +namespace RazorBlade.IntegrationTest.Examples +{ + [SuppressMessage("ReSharper", "UnusedVariable")] + [UsedImplicitly(ImplicitUseTargetFlags.WithMembers)] + internal class Examples + { + public static void ExampleTemplateUsage() + { + #region ExampleTemplate.Usage + + var template = new ExampleTemplate + { + Name = "World" + }; + + var result = template.Render(); + + #endregion + } + + public static void TemplateWithModelUsage() + { + #region TemplateWithModel.Usage + + var model = new GreetingModel { Name = "World" }; + var template = new TemplateWithModel(model); + var result = template.Render(); + + #endregion + } + } +} + +namespace MyApplication +{ + public class GreetingModel + { + public required string Name { get; init; } + } + + public class ModelType; +} diff --git a/src/RazorBlade.IntegrationTest/Examples/LayoutToUse.cshtml b/src/RazorBlade.IntegrationTest/Examples/LayoutToUse.cshtml new file mode 100644 index 0000000..c619f6b --- /dev/null +++ b/src/RazorBlade.IntegrationTest/Examples/LayoutToUse.cshtml @@ -0,0 +1,3 @@ +@inherits RazorBlade.HtmlLayout + +@RenderBody() diff --git a/src/RazorBlade.IntegrationTest/Examples/TemplateWithLayout.cshtml b/src/RazorBlade.IntegrationTest/Examples/TemplateWithLayout.cshtml new file mode 100644 index 0000000..c794da2 --- /dev/null +++ b/src/RazorBlade.IntegrationTest/Examples/TemplateWithLayout.cshtml @@ -0,0 +1,6 @@ +@inherits RazorBlade.HtmlTemplate +@* begin-snippet: TemplateWithLayout.Usage *@ +@{ + Layout = new LayoutToUse(); +} +@* end-snippet *@ diff --git a/src/RazorBlade.IntegrationTest/Examples/TemplateWithModel.cshtml b/src/RazorBlade.IntegrationTest/Examples/TemplateWithModel.cshtml new file mode 100644 index 0000000..8b7df47 --- /dev/null +++ b/src/RazorBlade.IntegrationTest/Examples/TemplateWithModel.cshtml @@ -0,0 +1,4 @@ +@using MyApplication +@inherits RazorBlade.HtmlTemplate + +Hello, @Model.Name! diff --git a/src/RazorBlade.IntegrationTest/RazorBlade.IntegrationTest.csproj b/src/RazorBlade.IntegrationTest/RazorBlade.IntegrationTest.csproj index 66cf96b..adc0880 100644 --- a/src/RazorBlade.IntegrationTest/RazorBlade.IntegrationTest.csproj +++ b/src/RazorBlade.IntegrationTest/RazorBlade.IntegrationTest.csproj @@ -11,6 +11,10 @@ + + + + diff --git a/src/RazorBlade.sln b/src/RazorBlade.sln index c1465e1..dfccb1a 100644 --- a/src/RazorBlade.sln +++ b/src/RazorBlade.sln @@ -11,6 +11,7 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Build", "Build", "{12E535CC ..\README.md = ..\README.md NuGetReadme.md = NuGetReadme.md ..\.github\workflows\build.yml = ..\.github\workflows\build.yml + mdsnippets.json = mdsnippets.json EndProjectSection EndProject Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "RazorBlade.IntegrationTest", "RazorBlade.IntegrationTest\RazorBlade.IntegrationTest.csproj", "{2FE5A803-86C8-42D2-A0DB-61D156DB6EB9}" diff --git a/src/mdsnippets.json b/src/mdsnippets.json new file mode 100644 index 0000000..83b9804 --- /dev/null +++ b/src/mdsnippets.json @@ -0,0 +1,7 @@ +{ + "$schema": "https://raw.githubusercontent.com/SimonCropp/MarkdownSnippets/master/schema.json", + "Convention": "InPlaceOverwrite", + "ExcludeDirectories": [ + "lib" + ] +}