Template fragment / conditional rendering example

[egil]

This is a small sample inspired by original template fragments article. This could be one way to enable this pattern in Htmxor.

In the example, during a standard request, the full page is rendered. During a hx-patch request, only the content of the <HtmxFragment> where the Match predicate returns true is going output markup.

@inherits ConditionalComponentBase
@page "/examples/archive-toggle"
@attribute [HtmxRoute("/examples/archive-toggle/{id:guid}", Methods = [HttpMethods.Patch])]
@code {
    [Parameter]
    public Guid Id { get; set; } = Guid.Empty;

    private void ToggleArchive()
    {
        Contacts.Data[Id].Archived = !Contacts.Data[Id].Archived;
    }
}
<h1>Edit Row</h1>
<p>This is a Htmxor version of the <a href="https://htmx.org/examples/edit-row/" title="Htmx edit row example">Htmx Edit Row</a> example.</p>
<table class="table">
    <thead>
        <tr>
            <th>First Name</th>
            <th>Last Name</th>
            <th>Email</th>
            <th>Status</th>
        </tr>
    </thead>
    <tbody>
        @foreach (var contact in Contacts.Data.Values.Take(30))
        {
            <tr>
                <td>@contact.FirstName</td>
                <td>@contact.LastName</td>
                <td>@contact.Email</td>
                <td>
                    <HtmxFragment OnStandardRequest=true Match=@(req => req.Path == $"/examples/archive-toggle/{contact.Id}")>
                        <button hx-patch="/examples/archive-toggle/@contact.Id"
                                hx-swap="@SwapStyles.OuterHTML"
                                @onpatch="ToggleArchive">
                            @if (contact.Archived)
                            {
                                <text>Unarchive</text>
                            }
                            else
                            {
                                <text>Archive</text>
                            }
                        </button>
                    </HtmxFragment>
                </td>
            </tr>
        }
    </tbody>
</table>

(since updated - see https://github.com/egil/Htmxor/blob/examples-project/samples/HtmxorExamples/Components/Pages/Examples/ArchiveToggle/Index.razor).

The HtmxFragment component itself is pretty simple:

Htmxor/samples/HtmxorExamples/Components/HtmxFragment.cs

Lines 1 to 31 in a65d3c9

	using System.Diagnostics.CodeAnalysis;
	using Htmxor.Http;
	using Microsoft.AspNetCore.Components;
	using Microsoft.AspNetCore.Components.Rendering;
	namespace Htmxor.Components;
	public class HtmxFragment : ConditionalComponentBase
	{
	[Parameter, EditorRequired]
	public required RenderFragment ChildContent { get; set; }
	[Parameter]
	public Func<HtmxRequest, bool>? Match { get; set; }
	[Parameter]
	public bool OnStandardRequest { get; set; } = true;
	protected override void BuildRenderTree(RenderTreeBuilder builder)
	{
	if (ShouldOutput(Context, 0, 0))
	{
	builder.AddContent(0, ChildContent);
	}
	}
	public override bool ShouldOutput([NotNull] HtmxContext context, int directConditionalChildren, int conditionalChildren)
	=> (OnStandardRequest && context.Request.RoutingMode is RoutingMode.Standard)
	|| (Match?.Invoke(context.Request) ?? true);
	}

@tanczosm what do you think?

[tanczosm]

I have a couple of thoughts. Nice work. I think it looks better in that it's much easier to reason what is going on under the hood when you can express a matching pattern for the route.

I think there are some things I would still like to see:

1. Lifecycle methods of some type for fragments

2. Direct rendering to output stream of an Htmxor component / fragment by type and fragment name

Fragments are theoretically supposed to be a replacement for extracting code for entire components. With a fragment you have no discernable lifecycle methods.. at least, how can I tell when it's appropriate to load all the data that will be needed for the full page request vs just the data needed for the fragment in the whole page OnInitialized and OnParametersSet methods? The matching approach makes it possible for the fragment to know it needs to render, but how do you discern with the regular component lifecycle methods which is the data you want to load? Could fragments themselves have some event methods that you could hook into in order to load data for that fragment?

I've looked over a few other working implementations of template fragments and there are some commonalities. Most of the template fragment implementations requires explicit names for the template fragment. While you are taking a different approach I could still see points in time where a developer would would want to render fragments by name.

One of the nice things I saw when it comes to other Template fragment implementations is that a common pattern is to load some model data and then directly render a fragment of a page by calling the page and named fragment and passing the model parameter. I think that is a really versatile alternative.

With existing .net technologies I can render a razor component from a minimal api using a RazorComponentResult, which just returns IResult (also used by MVC, RazorPages) Would it be possible to allow Htmxor pages to be rendered to an output stream as well?

Some thoughts. HtmxFragment would need to have a fragment Id. Then expose a public renderer with a method like below akin to HtmlRenderer which is also used by RazorComponentResult I believe:

public Task<HtmxorRootComponent> RenderComponentAsync(Type componentType, string fragmentId, ParameterView parameters)

Not sure if this could make this doable but perhaps add an internal nullable string property called FragmentId to HtmxRequest. When not null, the HtmxFragment Match function on a HtmxFragment is overridden by one that could be set to return true when the fragment id in the fragment matches the FragmentId in the HtmxRequest?

Anyway that's all for now. I need to think about this some more but I think this is closing in on a nice solution.

[egil]

Thank you for your input. Let me address your points in reverse order:

Addressable fragments

What logic would you use in a Minimal API that employs RazorComponentResult to render a component and a specific fragment?

A possible approach is to inspect the HtmxRequest object to identify which ID is in the route, and then address a specific fragment accordingly. The example given code accomplishes this implicitly via a predicate passed to <HtmxFragment>. What advantage do you see in moving the predicate elsewhere and adressing the fragment via an ID?

In frameworks with support for template fragments I've seen define the endpoint in separate files, similar to MVC and Minimal API, and they invoke template engines that generate markup, like RazorComponentResult.I dont see a reason why Htmxor's renderer, with the additional benefit of making fragments addressable, should not work with RazorCompoenntResult, if folks want to go that route.

If you have examples of similar implementations that does something else than this, please share links or snippets!

But what is the advantage of selecting the fragment outside of the component rather than inside it? I personally like that everything is inside a single file/component, and not spread out, with routing/endpoint definition in one place, and template/components in another.

Life cycle methods -- parent knowing when a fragment will or will not render

Your suggestion that parents should avoid loading unnecessary data is valid.

However, additional lifecycle methods may not be required. Fragments are managed by the page component they belong to, which allows data access to be centralized rather than duplicated. Thats one of advantages over moving fragments into their own addressable components.

The page component decides which fragments match a request and can load only the necessary data. Here's an updated example:

Htmxor/samples/HtmxorExamples/Components/Pages/Examples/ArchiveToggle/Index.razor

Lines 1 to 59 in a65d3c9

	@inherits ConditionalComponentBase
	@page "/examples/archive-toggle"
	@attribute [HtmxRoute("/examples/archive-toggle/{id:guid}", Methods = [HttpMethods.Patch])]
	@code {
	private IEnumerable<Contact> data = Enumerable.Empty<Contact>();
	[Parameter]
	public Guid Id { get; set; } = Guid.Empty;
	protected override void OnInitialized()
	{
	data = Id == Guid.Empty
	? Contacts.Data.Values.Take(30)
	: Contacts.Data.Values.Where(c => c.Id == Id);
	}
	private void ToggleArchive()
	{
	Contacts.Data[Id].Archived = !Contacts.Data[Id].Archived;
	}
	}
	<h1>Edit Row</h1>
	<p>This is a Htmxor version of the <a href="https://htmx.org/essays/template-fragments/" title="Template Fragments article">contact archive toggle</a> example in the Template Fragments article.</p>
	<table class="table">
	<thead>
	<tr>
	<th>First Name</th>
	<th>Last Name</th>
	<th>Email</th>
	<th>Status</th>
	</tr>
	</thead>
	<tbody>
	@foreach (var contact in data)
	{
	<tr>
	<td>@contact.FirstName</td>
	<td>@contact.LastName</td>
	<td>@contact.Email</td>
	<td>
	<HtmxFragment>
	<button hx-patch="/examples/archive-toggle/@contact.Id"
	hx-swap="@SwapStyles.OuterHTML"
	@onpatch="ToggleArchive">
	@if (contact.Archived)
	{
	<text>Unarchive</text>
	}
	else
	{
	<text>Archive</text>
	}
	</button>
	</HtmxFragment>
	</td>
	</tr>
	}
	</tbody>
	</table>

With this modification, <HtmxFragment> usage is further simplified, as filtering the data ensures that only the necessary fragment is created:

I pushed the updated code to the branch https://github.com/egil/Htmxor/tree/examples-project.

[tanczosm]

Just to be clear I think that the match approach is fine. I just think that the option to render on the id of the fragment should also exist.

Covering the lifecycle methods for now. I'm going to come up with an example where the data isn't tied into the same feature.

Let's say we have a news page where the main content is a list of latest articles and it has a sidebar with several cards featuring different types of content. As the user scrolls I want to load in additional articles automatically, targeting the end of the main content container. For the sidebar boxes I have one that is a list of latest comments from users and a list of top articles. I also want to place the newest comment in a special box at the top of the page above the article list.

There is also a navbar and other elements that are part of the main template for the site, so this initial page content will typically be loaded via an htmx request and will target a div with id "page_content".

On scroll the last article has hx-trigger="revealed" to make a call to retrieve page 2 of latest articles. Only articles will be updated, so the targeted element will be the main content area after the end. All other parts of the page should remain the same.

Every 30 seconds I will poll for latest comments and refresh the comments box with the latest comments. The special box on top will be updated with the latest comment using an OOB swap.

For this example, we have:
On a full page load refresh to /news:

• api call to a backend to retrieve page 1 of latest articles (let's say this is resource intensive and a relatively longer running call than the rest)
• api call to retrieve latest comments
• api call to retrieve top articles.
• render complete layout, comment special box, latest comments, and top articles

On an htmx request to to /news with target of #page_content

• api call to a backend to retrieve page 1 of latest articles (let's say this is resource intensive and a relatively longer running call than the rest)
• api call to retrieve latest comments
• api call to retrieve top articles.
• render comment special box, latest comments, and top articles

On an htmx request to /news?page=2 with target of #articles and swap method of afterend

• api call to a backend to retrieve page 2 of latest articles (let's say this is resource intensive and a relatively longer running call than the rest)
• do not load latest comments or top articles
• render top articles

On an htmx request to /news/comments with a target of #comments

• api call to retrieve latest comments
• do not load latest articles or top articles
• render latest comments and render comment special box with an oob swap value

How would you approach this example?

[egil]

Just to be clear I think that the match approach is fine. I just think that the option to render on the id of the fragment should also exist.

How do you propose RazorComponentResult or other code indicate which fragment to render?

Could it be surfaced the HtmxRequest type as a property?

Could it be a Htmxor specific http header?

Covering the lifecycle methods for now. I'm going to come up with an example where the data isn't tied into the same feature...

Cool scenario. Let me try this out later tonight.

[egil]

Didn't get to it last night.

@tanczosm it would be helpful if you can provide the HTML part of it, i.e. what hx- attributes you would attach to each element. Then I will try to make the backend handle them.

[tanczosm]

Here is what I think it might look look like if everything is broken into components rather than template fragments. I'm typing this in the github editor so there may be mistakes but this is the gist of it:

For the API calls I'll start with an interface for the service to make it simplified:

public interface INewsService
{
    Task<List<Article>> GetArticlesAsync(int page);
    Task<List<Article>> GetTopNArticlesAsync(int n);
    Task<List<Comment>> GetLatestCommentsAsync();
}

Models could be:

public class Article
{
    public int Id { get; set; }
    public string Headline { get; set; }
    public string AuthorName { get; set; }
    public string Body { get; set; }
}

public class Comment
{
    public int Id { get; set; }
    public string AuthorName { get; set; }
    public string CommentText { get; set; }
}

News page:

@page "/news"
@page "/news/{CurrentPage:int}"
@inject INewsService NewsService

<div class="container">
    <div id="page_content">
        <div class="latestcomment alert alert-info" role="alert">
        </div>
        <div id="articles">
            @for (int i = 0; i < Articles.Count; i++)
            {
                var article = Articles[i];
                <div>
                    <h2>@article.Headline</h2>
                    <p>@article.Body</p>
                    @if (i == Articles.Count - 1)
                    {
                        <div hx-get="@($"/news/{CurrentPage + 1}")" hx-trigger="revealed"></div>
                    }
                </div>
            }
        </div>
    </div>
    <aside>
        <TopArticles />
        <LatestComments />
    </aside>
</div>

@code {
    private List<Article> Articles { get; set; } = new List<Article>();

    [Parameter]
    public int CurrentPage { get; set; } = 1;

    protected override async Task OnParametersSetAsync()
    {
        Articles = await NewsService.GetArticlesAsync(CurrentPage);
    }
}

TopArticles.razor

@inject INewsService NewsService

<h3>Top Articles</h3>
<div>
    @foreach (var article in TopArticles)
    {
        <div>@article.Headline by @article.AuthorName</div>
    }
</div>

@code {
    private List<Article> TopArticles { get; set; } = new List<Article>();

    protected override async Task OnInitializedAsync()
    {
        TopArticles = await NewsService.GetTopNArticles(5);
    }
}

LatestComments.razor

@page "/news/comments"
@inject INewsService NewsService

<div id="comments" hx-get="/news/comments" hx-trigger="every 30s">
<h3>Latest Comments</h3>
@if (Comments != null)
{
    foreach (var comment in Comments)
    {
        <div>@comment.AuthorName says @comment.CommentText</div>
    }
    if (Comments.Count > 0)
    {
        var lastComment = Comments.Last();
        <div hx-swap-oob="innerHTML:.latestcomment">@lastComment.AuthorName says @lastComment.CommentText</div>
    }
}
</div>

@code {
    private List<Comment>? Comments;

    protected override async Task OnInitializedAsync()
    {
            Comments = await NewsService.GetLatestComments();
    }
}

[tanczosm]

I threw this into chatgpt to generate the service implementation:

public class NewsService : INewsService
{
    private static readonly string[] Headlines = new string[]
    {
        ".NET 8 Highlights and Features",
        "Understanding C# 10.0 Innovations",
        "Exploring ASP.NET Core Performance",
        "Entity Framework Core Best Practices",
        "Blazor for Web Development: A Real Game Changer",
        "Migrating from .NET Framework to .NET 8",
        "ASP.NET Core Security Best Practices",
        "An Overview of Microservices in .NET",
        "Using Docker Containers with .NET",
        "Performance Optimization in C# Applications",
        "The Future of .NET Development",
        "Building RESTful APIs with ASP.NET Core",
        "Unit Testing in .NET: Best Tools and Practices",
        "Introduction to Machine Learning with ML.NET",
        "Secure Your .NET Applications from Common Vulnerabilities",
        "C# Functional Programming: Pros and Cons",
        "Deep Dive into C# 10.0 Records",
        "New Features in Entity Framework Core 8",
        "Scaling .NET Applications with Kubernetes",
        "Integrating Azure Services with .NET Applications",
        "SignalR in .NET 8: Real-time Web Functionalities",
        "Effective Error Handling in ASP.NET Core",
        "Best Practices for Logging in .NET Applications",
        "Using .NET MAUI for Cross-Platform Development",
        "Event Sourcing in Microservices with .NET",
        "Understanding Dependency Injection in .NET",
        "ASP.NET Core MVC vs Razor Pages: Which to Choose?",
        "Building Responsive Applications with Blazor",
        "Why Choose .NET for Enterprise Applications?",
        "Improving .NET Application Security"
    };

    private static readonly string[] AuthorNames = new string[]
    {
        "Alex Johnson", "Maria Garcia", "Michael Williams", "Linda Brown",
        "James Davis", "Patricia Miller", "Robert Wilson", "Jennifer Moore",
        "William Taylor", "Elizabeth Anderson", "David Thomas", "Barbara Jackson",
        "Richard White", "Susan Harris", "Joseph Martin", "Jessica Thompson",
        "Charles Lee", "Sarah Lewis", "Thomas Clark", "Lisa Robinson"
    };

    private static readonly string[] CommentContents = new string[]
    {
        "Really informative, thanks for the details!",
        "I disagree with this point, more discussion needed.",
        "Could use more code examples to illustrate.",
        "Perfect explanation on this complex topic.",
        "This article needs an update with the latest version information.",
        "Well written, but lacks depth in some areas.",
        "Great introduction to the topic for beginners.",
        "The concepts were a bit hard to follow.",
        "Excellent coverage of the essentials!",
        "Not what I expected, needs more technical insights.",
        "Brilliantly articulated, looking forward to more posts.",
        "This helped clear up some of my confusion.",
        "Lacks critical analysis of the drawbacks.",
        "Very biased viewpoint, not balanced!",
        "A comprehensive guide, very useful.",
        "Missed out on some newer tools that are better suited.",
        "Wonderful read, very engaging content!",
        "Too lengthy, could be more concise.",
        "Great for my research, thanks for sharing.",
        "Not enough practical advice, too theoretical.",
        "Simplified a complex topic effectively.",
        "Overly simplified, omits important details.",
        "A must-read for anyone starting with .NET.",
        "Good refresher on the basics.",
        "Could benefit from editing for clarity and grammar.",
        "Outdated examples, please revise with current standards.",
        "Enjoyed the writing style, very approachable.",
        "More visuals would greatly help understanding.",
        "Excellent resource for my team's training.",
        "Useful article, added to my bookmarks."
    };

    private static readonly string LoremIpsum = "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.";

    private readonly Random _random = new Random();

    public async Task<List<Article>> GetArticlesAsync(int page)
    {
        await Task.Delay(1000);  // simulate delay

        var articles = Enumerable.Range(1, 10)
            .Select(id => new Article
            {
                Id = id + (page - 1) * 10,
                Headline = Headlines[_random.Next(Headlines.Length)],
                AuthorName = AuthorNames[_random.Next(AuthorNames.Length)],
                Body = LoremIpsum
            })
            .ToList();

        return articles;
    }

    public async Task<List<Article>> GetTopNArticlesAsync(int n)
    {
        await Task.Delay(50);

        var articles = Enumerable.Range(1, n)
            .Select(id => new Article
            {
                Id = id,
                Headline = Headlines[_random.Next(Headlines.Length)],
                AuthorName = AuthorNames[_random.Next(AuthorNames.Length)],
                Body = LoremIpsum
            })
            .ToList();

        return articles;
    }

    public async Task<List<Comment>> GetLatestCommentsAsync()
    {
        await Task.Delay(10);

        var comments = Enumerable.Range(1, 5)
            .Select(id => new Comment
            {
                Id = id,
                AuthorName = AuthorNames[_random.Next(AuthorNames.Length)],
                CommentText = CommentContents[_random.Next(CommentContents.Length)]
            })
            .ToList();

        return comments;
    }
}

[egil]

Here are three new implementations of the https://htmx.org/examples/update-other-content examples from htmx.org.

The expand the target example:

Htmxor/samples/HtmxorExamples/Components/Pages/Examples/UpdatingOtherContent/ExpandTheTarget.razor

Lines 1 to 33 in 0af3d6e

	@inherits ConditionalComponentBase
	@page "/examples/updating-other-content/expand-the-target"
	<PageTitle>Htmxor - Examples - Updating Other Content - Expand the Target</PageTitle>
	<h1>Updating Other Content - Expand the Target</h1>
	<p>This is a Htmxor version of the <a href="https://htmx.org/examples/update-other-content/#expand" title="Updating Other Content article">Updating Other Content - Solution 1: Expand the Target</a> example at htmx.org.</p>
	<HtmxFragmentElement Id="table-and-form" class="d-flex flex-row gap-3">
	<table class="table w-50 border">
	<thead>
	<tr>
	<th>First Name</th>
	<th>Last Name</th>
	<th>Email</th>
	</tr>
	</thead>
	<tbody>
	@foreach (var contact in Contacts.Data.Values.OrderBy(x => x.Modified).Take(20))
	{
	<tr>
	<td>@contact.FirstName</td>
	<td>@contact.LastName</td>
	<td>@contact.Email</td>
	</tr>
	}
	</tbody>
	</table>
	<div class="w-50 p-3 border">
	<h5>Create new contact</h5>
	<ContactEditForm hx-post hx-target="#table-and-form" OnContactSave="() => StateHasChanged()" />
	</div>
	</HtmxFragmentElement>

The OOB example:

Htmxor/samples/HtmxorExamples/Components/Pages/Examples/UpdatingOtherContent/OutOfBandResponses.razor

Lines 1 to 47 in 0af3d6e

	@inherits ConditionalComponentBase
	@page "/examples/updating-other-content/out-of-band-responses"
	@code {
	private Contact? savedContact;
	}
	<PageTitle>Htmxor - Examples - Updating Other Content - Out of Band Responses</PageTitle>
	<h1>Updating Other Content - Out of Band Responses</h1>
	<p>This is a Htmxor version of the <a href="https://htmx.org/examples/update-other-content/#oob" title="Updating Other Content article">Updating Other Content - Solution 2: Out of Band Responses</a> example at htmx.org.</p>
	<div class="d-flex flex-row gap-3">
	<table class="table w-50 border">
	<thead>
	<tr>
	<th>First Name</th>
	<th>Last Name</th>
	<th>Email</th>
	</tr>
	</thead>
	<tbody id="contacts-table">
	@foreach (var contact in Contacts.Data.Values.OrderBy(x => x.Modified).Take(20))
	{
	<tr>
	<td>@contact.FirstName</td>
	<td>@contact.LastName</td>
	<td>@contact.Email</td>
	</tr>
	}
	</tbody>
	</table>
	<div class="w-50 p-3 border">
	<h5>Create new contact</h5>
	<HtmxFragment>
	@if (savedContact is not null)
	{
	<tbody hx-swap-oob="afterbegin:#contacts-table">
	<tr>
	<td>@savedContact.FirstName</td>
	<td>@savedContact.LastName</td>
	<td>@savedContact.Email</td>
	</tr>
	</tbody>
	}
	<ContactEditForm hx-post OnContactSave=@(c => savedContact = c) />
	</HtmxFragment>
	</div>
	</div>

The event triggering example:

Htmxor/samples/HtmxorExamples/Components/Pages/Examples/UpdatingOtherContent/TriggeringEvents.razor

Lines 1 to 39 in 0af3d6e

	@inherits ConditionalComponentBase
	@page "/examples/updating-other-content/triggering-events"
	@code {
	private Contact? savedContact;
	}
	<PageTitle>Htmxor - Examples - Updating Other Content - Triggering Events</PageTitle>
	<h1>Updating Other Content - Triggering Events</h1>
	<p>This is a Htmxor version of the <a href="https://htmx.org/examples/update-other-content/#events" title="Updating Other Content article">Updating Other Content - Solution 3: Triggering Events</a> example at htmx.org.</p>
	<div class="d-flex flex-row gap-3">
	<table class="table w-50 border">
	<thead>
	<tr>
	<th>First Name</th>
	<th>Last Name</th>
	<th>Email</th>
	</tr>
	</thead>
	<HtmxFragment Match=@(req => req.Target == "contacts-table")>
	<tbody id="contacts-table" hx-get hx-trigger="newContact from:body" hx-swap=@SwapStyles.OuterHTML>
	@foreach (var contact in Contacts.Data.Values.OrderBy(x => x.Modified).Take(20))
	{
	<tr>
	<td>@contact.FirstName</td>
	<td>@contact.LastName</td>
	<td>@contact.Email</td>
	</tr>
	}
	</tbody>
	</HtmxFragment>
	</table>
	<div class="w-50 p-3 border">
	<h5>Create new contact</h5>
	<HtmxFragment Match=@(req => req.Method == HttpMethods.Post)>
	<ContactEditForm hx-post OnContactSave=@(() => Context.Response.Trigger("newContact")) />
	</HtmxFragment>
	</div>
	</div>

Let me know what you think!

https://github.com/egil/Htmxor/tree/examples-project/samples/HtmxorExamples/Components/Pages/Examples/UpdatingOtherContent

[tanczosm]

I like the working callbacks. That is really awesome! Match looks pretty flexible as well. I haven't seen HtmxFragmentElement before. What's the difference between HtmxFragment and HtmxFragmentElement in the first example?

[egil]

It's in the samples project too: https://github.com/egil/Htmxor/blob/examples-project/samples/HtmxorExamples/Components/HtmxFragmentElement.cs