proposal: render individual template fragments #914

a-h · 2024-09-11T07:25:24Z

a-h
Sep 11, 2024
Maintainer

In this tweet, Carson highlights the capability of Laravel's template engine to render a specific section of an overall template. https://x.com/htmx_org/status/1833450920438272462

This is interesting for HTMX, because with HTMX, you sometimes only want a part of the HTML stream to be returned to the client.

In templ, this could look like:

@Fragment("name") {
  <div>This is a named template fragment.</div>
}

At the moment, you'd have to make a separate templ component for that:

templ named() {
  <div>This is a named template fragment.</div>
}

And then call it - works well, but have to do some refactoring if you're adding this to existing code.

To write out only the fragment without separating the contents into another templ component, the context could be used to trigger the behaviour.

package main

import (
	"context"
	"fmt"
	"io"
	"net/http"
	"slices"
)

type fragmentComponent struct {
	name string
}

func (f fragmentComponent) Render(ctx context.Context, w io.Writer) error {
	// Get children.
	children := templ.GetChildren(ctx)
	ctx = templ.ClearChildren(ctx)
	if children == nil {
		return nil
	}
	// Render children.
	fw, ok := GetFragmentWriter(ctx, f.name)
	if ok {
		w = fw
	}
	return children.Render(ctx, w)
}

type fragmentContextKey struct{}
type fragmentContextValue struct {
	w     io.Writer
	names []string
}

func WithFragment(ctx context.Context, w io.Writer, names ...string) context.Context {
	return context.WithValue(ctx, fragmentContextKey{}, fragmentContextValue{w: w, names: names})
}

func GetFragmentWriter(ctx context.Context, name string) (w io.Writer, ok bool) {
	val, ok := ctx.Value(fragmentContextKey{}).(fragmentContextValue)
	if !ok {
		return nil, false
	}
	if len(val.names) > 0 && !slices.Contains(val.names, name) {
		return nil, false
	}
	return val.w, true
}

func Fragment(name string) templ.Component {
	return fragmentComponent{name: name}
}

templ Page(count int) {
	<!DOCTYPE html>
	<head>
		<title>My Page</title>
		<script src="https://unpkg.com/[email protected]" integrity="sha384-Y7hw+L/jvKeWIRRkqWYfPcvVxHzVzn5REgzbawhxAuQGwX1XWe70vji+VSeHOThJ" crossorigin="anonymous"></script>
	</head>
	<body>
		<h1>My Page</h1>
		<p>This is my page</p>
		@Fragment("count") {
			<div id="count">Count: { fmt.Sprintf("%d", count) }</div>
		}
		<!-- We no longer need to select #count because only the fragment is returned -->
		<button hx-post="/" hx-target="#count">Increment</button>
	</body>
}

func main() {
	var count int
	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		if r.Method == http.MethodPost {
			count++
		}
		c := Page(count)
		if r.Method == http.MethodPost && r.Header.Get("HX-Request") == "true" {
			r = r.WithContext(WithFragment(r.Context(), w, "count"))
			c.Render(r.Context(), io.Discard)
			return
		}
		c.Render(r.Context(), w)
	})

	fmt.Println("Server running on http://127.0.0.1:8080")
	http.ListenAndServe("127.0.0.1:8080", nil)
}

In this example, the GET request returns the whole page:

<!doctype html>
<head>
    <title>My Page</title>
    <script src="https://unpkg.com/[email protected]" integrity="sha384-Y7hw+L/jvKeWIRRkqWYfPcvVxHzVzn5REgzbawhxAuQGwX1XWe70vji+VSeHOThJ" crossorigin="anonymous"></script>
</head>
<body>
    <h1>My Page</h1>
    <p>This is my page</p>
    <div id="count">Count: 0</div>
    <!-- We don't need to select #count because only the fragment is returned -->
    <button hx-post="/" hx-target="#count">Increment</button>
</body>

But the HTMX response returns just the "count" fragment.

<div id="count">Count: 1</div>

I don't like how this design doesn't use the io.Writer that's passed in, using a writer from the context instead, but it does work.

if r.Method == http.MethodPost && r.Header.Get("HX-Request") == "true" {
	r = r.WithContext(WithFragment(r.Context(), w, "count"))
	c.Render(r.Context(), io.Discard)
	return
}

That design is partly because that's all that's possible with the current generated code.

templ's generator currently generates code that creates a buffer from the incoming io.Writer, but I'm not sure it should. Maybe this would be better done at the HTTP handler level, and we keep the rendering code really simple.

If we didn't wrap it, we could check (within the Fragment templ component) to see whether the io.Writer is actually a FragmentWriter that only writes the specified fragments and its children, discarding all other writes.

Alternatively, the templ runtime.Buffer type could have this smartness built in.

All of the template is computed, it's simply that only part of the HTML output is returned. I don't think that it's possible (or maybe desirable) to skip computing non-visible parts of the template.

Another design might be even simpler (just pseudocode for now), writing out a comment to start and the fragment.

type fragmentComponent struct {
	id string
	name string
}

func (f fragmentComponent) Render(ctx context.Context, w io.Writer) error {
	// Get children.
	children := templ.GetChildren(ctx)
	ctx = templ.ClearChildren(ctx)
	if children == nil {
		return nil
	}
        // Render prefix.
       io.WriteString(w, "<!-- templ_fragment_start: " + f.id + "-->")
	// Render children.
       err := children.Render(ctx, w)
       io.WriteString(w, "<!-- templ_fragment_end: " + f.id + "-->")
       return err
}

func Fragment(name string) templ.Component {
        id := randomString(name)
	return fragmentComponent{id: id, name: name}
}

templ Page(count int) {
	<!DOCTYPE html>
	<head>
		<title>My Page</title>
		<script src="https://unpkg.com/[email protected]" integrity="sha384-Y7hw+L/jvKeWIRRkqWYfPcvVxHzVzn5REgzbawhxAuQGwX1XWe70vji+VSeHOThJ" crossorigin="anonymous"></script>
	</head>
	<body>
		<h1>My Page</h1>
		<p>This is my page</p>
		@Fragment("count") {
			<div id="count">Count: { fmt.Sprintf("%d", count) }</div>
		}
		<!-- We no longer need to select #count because only the fragment is returned -->
		<button hx-post="/" hx-target="#count">Increment</button>
	</body>
}

Then, a custom writer could discard writes that aren't between the expected comments. templ could provide a custom HTTP response writer too: https://gist.github.com/prakashpandey/f8fe3e8f3d446cd3426ac67ac21172f7

if r.Method == http.MethodPost && r.Header.Get("HX-Request") == "true" {
        w := templ.NewResponseWriter(w, WithRenderFragments("count"))
	c.Render(r.Context(), w)
	return
}

I think that implementing some sort of FragmentWriter interface in both the templ buffer, and a templ.ResponseWriter might work.

Thoughts? Worth doing?

joerdav · 2024-09-11T10:27:06Z

joerdav
Sep 11, 2024
Collaborator

I think that the internal implementation you outlined in the first proposed design makes the most sense. I think utilizing context makes sense here too, but I don't think that this fact should be exposed to the user, I would recommend an abstraction here:

func RenderFragment(ctx context.Context, c Component, w io.Writer, name string) error {
	return c.Render(WithFragment(ctx, w, name), io.Discard)
}

This way the dev experience is a bit more intuitive:

http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		if r.Method == http.MethodPost {
			count++
		}
		c := Page(count)
		if r.Method == http.MethodPost && r.Header.Get("HX-Request") == "true" {
			templ.RenderFragment(r.Context(), c, w, "count")
			return
		}
		c.Render(r.Context(), w)
	})

0 replies

Riu · 2024-09-23T22:56:10Z

Riu
Sep 23, 2024

I have another approach. It treats the component (fragment, partial) like an endpoint (/partial/{component-id}, which has its states depending on the HTTP method used. I can return the rendered html by passing data in the template (initial GET state based on URL), or in the endpoint. Example: take a look at how the navigation works in the mobile version for hanariu.dev - there is an animation like in the SPA app (no page reload effect) because it loads the fragment (endpoint) thanks to HTMX.

This has three main advantages for me:

better documentation of the endpoint and business logic of the component;
easier development of isolated components/fragments (potentially good for microfrontends);
reusability;

For small components and changing only data, HTMX alone + e.g. Alpine js is enough.

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

proposal: render individual template fragments #914

{{title}}

Replies: 2 comments

{{title}}

{{title}}

Select a reply

proposal: render individual template fragments #914

a-h Sep 11, 2024 Maintainer

Replies: 2 comments

joerdav Sep 11, 2024 Collaborator

Riu Sep 23, 2024

a-h
Sep 11, 2024
Maintainer

joerdav
Sep 11, 2024
Collaborator

Riu
Sep 23, 2024