diff --git a/README.md b/README.md index 6f9be05..3bbbe8d 100644 --- a/README.md +++ b/README.md @@ -19,109 +19,8 @@ The following Blazor Web Apps (Htmxor) are used to test Htmxor and demo the capa - [Htmxor - TestApp](https://github.com/egil/Htmxor/tree/main/test/Htmxor.TestApp) - [Minimal Htmxor App template](https://github.com/egil/Htmxor/tree/main/samples/MinimalHtmxorApp) -## Getting started - -Download the [Minimal Htmxor App template](https://github.com/egil/Htmxor/tree/main/samples/MinimalHtmxorApp) for a complete (but) minimal Blazor + htmx app, with various small examples included. - -Starting fresh, here is what you need to do. - -1. Include the [Htmxor package from NuGet](https://www.nuget.org/packages/Htmxor). - -2. Modify `Program.cs` to look like this: - -```diff - var builder = WebApplication.CreateBuilder(args); - - // Add services to the container. - builder.Services - .AddRazorComponents() -+ .AddHtmx(); - - var app = builder.Build(); - - // Configure the HTTP request pipeline. - if (!app.Environment.IsDevelopment()) - { - app.UseExceptionHandler("/Error", createScopeForErrors: true); - // 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.UseAntiforgery(); -+ app.UseHtmxAntiforgery(); - app.MapRazorComponents() -+ .AddHtmxorComponentEndpoints(app); - - app.Run(); -``` - -Note, there is an overload for `AddHtmx(options => { ... })` that allows you to configure all [htmx's configuration options](https://htmx.org/reference/#config) for your app. - -3. Modify `App.razor` to look like this: - -```diff - - - - - - - - - - - -+ - - - -+ -+ - - -- - - - -``` - -4. Optionally, create a htmx-request specific layout, e.g., `/Components/Layout/HtmxorLayout.razor`: - -```razor -@* -This is a default layout component that is used with htmx requests. -It only includes the which makes it possible to update the -page title during htmx requests by using the component. -*@ -@inherits LayoutComponentBase - -@Body -``` - -5. Optionally, update `_Imports.razor`: - -```diff - @using System.Net.Http - @using System.Net.Http.Json - @using Microsoft.AspNetCore.Components.Forms - @using Microsoft.AspNetCore.Components.Routing - @using Microsoft.AspNetCore.Components.Web - @using static Microsoft.AspNetCore.Components.Web.RenderMode - @using Microsoft.AspNetCore.Components.Web.Virtualization - @using Microsoft.JSInterop -+ @using Htmxor.Components -+ @using Htmxor.Http -+ @using Htmxor - -+ @attribute [HxLayout(typeof(HtmxorLayout))] -``` - -Note that we set up the custom layout for all components by defining the `[HxLayout(typeof(HtmxorLayout))]` attribute in the `_Imports.razor` file. - ## Documentation -- **[Routing in Htmxor](/docs/routing.md)**: Covers how routing works in Htmor, compared to Blazor Static Web apps. +- **[Getting Started](/docs/getting-started.md)** - how to create a new Htmxor/Blazor project. +- **[Routing in Htmxor](/docs/routing.md)** - there are two types of routing in Htmxor, standard and direct. diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 0000000..20ae005 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,109 @@ +# Getting Started + +To create a minimal Blazor + htmx app with various examples, download the [Minimal Htmxor App template](https://github.com/egil/Htmxor/tree/main/samples/MinimalHtmxorApp). + +To start fresh, follow these steps: + +1. **Add the Htmxor Package** + + Install the [Htmxor package from NuGet](https://www.nuget.org/packages/Htmxor). + + +2. **Update `Program.cs`** + + Modify `Program.cs` to include Htmxor services and middleware: + + ```diff + var builder = WebApplication.CreateBuilder(args); + + // Add services to the container. + builder.Services + .AddRazorComponents() + + .AddHtmx(); + + var app = builder.Build(); + + // Configure the HTTP request pipeline. + if (!app.Environment.IsDevelopment()) + { + app.UseExceptionHandler("/Error", createScopeForErrors: true); + app.UseHsts(); + } + + app.UseHttpsRedirection(); + + app.UseStaticFiles(); + app.UseAntiforgery(); + + app.UseHtmxAntiforgery(); + app.MapRazorComponents() + + .AddHtmxorComponentEndpoints(app); + + app.Run(); + ``` + Note: You can use `AddHtmx(options => { ... })` to change [htmx's config](https://htmx.org/reference/#config) for your app. + +3. **Update App.razor** + + Modify `App.razor` to include Htmxor components: + + ```diff + + + + + + + + + + + + + + + + + + + + + + - + + + + ``` + +4. **Create an Optional Direct Request Layout** + + Optionally, create a layout that will be used during [direct routing](routing.md#direct-routing), e.g., `/Components/Layout/HtmxorLayout.razor`: + + ```razor + @inherits HtmxLayoutComponentBase + @Body + ``` + + The `HtmxLayoutComponentBase` includes the `` component. This makes it possible to use the `` component during htmx requests to update the page title. + +5. **Update _Imports.razor (Optional)** + + Modify _Imports.razor to include Htmxor namespaces and set a default layout: + + ```diff + @using System.Net.Http + @using System.Net.Http.Json + @using Microsoft.AspNetCore.Components.Forms + @using Microsoft.AspNetCore.Components.Routing + @using Microsoft.AspNetCore.Components.Web + @using static Microsoft.AspNetCore.Components.Web.RenderMode + @using Microsoft.AspNetCore.Components.Web.Virtualization + @using Microsoft.JSInterop + + @using Htmxor.Components + + @using Htmxor.Http + + @using Htmxor + + + @attribute [HtmxLayout(typeof(HtmxorLayout))] + ``` + + Note that we set up the custom layout for all components by defining the `[HtmxLayout(typeof(HtmxorLayout))]` attribute in the `_Imports.razor` file. diff --git a/docs/routing.md b/docs/routing.md index 4c9f7cc..0716c09 100644 --- a/docs/routing.md +++ b/docs/routing.md @@ -33,7 +33,7 @@ HTTP GET /my-page App -> Routes --> MainLayout --> MyPage ``` -## Direct Routing: +## Direct Routing Direct routing bypasses the root component (`App.razor`) and the standard layout (`MainLayout`). Instead, it routes directly to the component that matches the request.