Inline partial definitions

[infogulch]

The most underrated features of Go's templating system are the define and block directives.

define enables template authors to define new named templates within an existing template file, which is nice for small snippets that are related to the main template but you don't want to put them in their own file. When you render the main template, any inline defines are skipped. Then it can be invoked by name like any other template.

block is like a define + an invocation of the newly defined template in the main template. This is super handy, and allows authors to write up a whole html document in a single file while slicing out sections of it into small reusable snippets.

The combination of these two features pairs surprisingly well with htmx.

---

You can see an example of this use case in xrss, a toy rss reader I built with go templates and htmx.

1. Here's a somewhat large snippet of the project to demonstrate the idea of defining partials inline. I can write the entire page as if it were a single html document, and surround any given section for reuse later.

The nice thing about this is that everything stays in context and isn't unnecessarily broken up across dozens of files.

I'm also doing some other funny things like extracting url params, launching sql queries etc directly in the template, which is... lets say "unconventional". But don't get distracted, I'm talking about partials here. 😆

  {{- block "items-panel" .}}
  {{- $feed_id := int (.Params.ByName "feed_id") }}
  <div id="items-panel" class="md:flex-1 shrink-0 snap-start w-full h-full min-w-0 overflow-y-auto" style="scrollbar-gutter: stable;">
    <div class="sticky top-0 z-20 flex w-full gap-2 p-2 pb-2 bg-white">
      <span
        class="md:hidden h-full p-3 text-lg text-gray-600 bg-gray-100 rounded-lg scale-x-[-1]"
        onclick="document.getElementById('feeds-panel').scrollIntoView({behavior:'smooth'})">&nbsp;⇌&nbsp;</span>
      <span class="p-3 text-lg text-center text-gray-600 bg-gray-100 rounded-lg">
        {{.QueryVal `SELECT COALESCE((SELECT title FROM v_feed WHERE id=$1), 'All Feeds')` $feed_id}}
      </span>
      {{- if ne $feed_id 0}}
      {{- if not .Config.read_only}}
      <a href="" hx-post="/feeds/{{$feed_id}}/refresh" hx-target="#items-panel" hx-swap="outerHTML scroll:top"
        class="p-3 text-lg text-center text-gray-600 bg-gray-100 rounded-lg">⟳</a>
      {{- end}}
      {{- end}}
    </div>
    <ul id="items" class="p-2">
      {{- block "items" .}}
      {{- $feed_id := int (.Params.ByName "feed_id") }}
      {{- $offset := int (.Req.URL.Query.Get "offset") }}
      {{- $count := .QueryVal `SELECT COUNT(*) FROM v_item WHERE feed_id=$1 OR $1=0` $feed_id}}
      {{- range .QueryRows `SELECT feed_id, id, feed_title, title, description, image, author, published FROM v_item WHERE feed_id=$1 OR $1=0 ORDER BY published DESC LIMIT 10 OFFSET $2` $feed_id $offset }}
      {{- block "item" .}}
      <li class="odd:bg-gray-100 max-h-7.5em h-[7.5em] flex flex-row gap-2 p-2 cursor-pointer transition" hx-get="/feeds/{{.feed_id}}/items/{{.id}}/expanded" hx-swap="outerHTML transition:true">
        <div class="flex-none w-[6em] h-[6em] m-1 bg-cover rounded" style="background-image: url('{{.image}}');"></div>
        <div class="items-baseline flow-root overflow-hidden">
          <div class="xl:flex-row flex flex-col">
            <div class="flex-initial pr-2 text-lg font-semibold truncate">{{.title | sanitizeHtml "strict" }}</div>
            <div class="flex flex-row items-baseline flex-none">
              <div class="flex-none pl-1 pr-1 text-sm text-gray-800">{{.feed_title | sanitizeHtml "strict" }}</div>·
              <div class="flex-none pl-1 pr-1 text-sm text-gray-800">{{.author | sanitizeHtml "strict" }}</div>·
              <div class="group/tip relative flex-none pl-1 text-sm text-gray-800">
                <time datetime="{{.published}}">{{.published | humanize "time:2006-01-02T15:04:05Z07:00"}}</time>
                <span class="group-hover/tip:visible left-full top-full mr-[-999px] -translate-x-full absolute invisible p-1 text-gray-200 bg-gray-800 rounded shadow-lg">
                  {{- .published | toDate "2006-01-02T15:04:05Z07:00" | date "Monday, 02 Jan 2006 15:04:05 MST" -}}
                </span>
              </div>
            </div>
          </div>
          <div class="line-clamp-2 xl:line-clamp-3 text-gray-500">{{.description | abbrev 4000 | sanitizeHtml "strict"}}</div>
        </div>
      </li>
      {{- end}}
      {{- end}}
      {{- $next_offset := add $offset 10}}
      {{- if lt $next_offset $count}}
      <li hx-trigger="intersect" hx-swap="outerHTML"
        hx-get="{{if $feed_id }}/feeds/{{$feed_id}}{{end}}/items?offset={{ $next_offset }}">(loading...)</li>
      {{- end}}
      {{- end}}
    </ul>
  </div>
  {{- end}}

Here: https://github.com/infogulch/xrss/blob/caa35cbea98bafff36935e1a53cdb658758f3b54/templates/index.html#L47-L100

2. Then later I reuse the partials in other routes defined inline:

Go doesn't combine templates and routing, so this {{define "<url pattern>"}} is my own addition that exploits the fact that the names of inline definitions can be arbitrary strings; on load I search all the defined templates for those with names that are a valid url path pattern and add it to the router. (We can talk about this later, one thing at a time. 😉)

This is also nice because it means I can have all the html for a given page and dozens of little http path handlers needed to make htmx work all defined in ONE file with only a few lines each and zero boilerplate.

{{- define "GET /feeds/:feed_id/"}}
{{- if (.Req.Header.Get "HX-Request")}}
{{- template "items-panel" .}}
{{- else}}
{{- template "/index.html" .}}
{{- end}}
{{- end}}

{{- define "GET /feeds/:feed_id/items"}}
{{- template "items" .}}
{{- template "perf" .}}
{{- end}}

{{- define "GET /feeds/:feed_id/items/:item_id/"}}
{{- $item := .QueryRow `SELECT feed_id, id, feed_title, title, description, image, author, published FROM v_item WHERE feed_id=$1 AND id=$2` (.Params.ByName "feed_id") (.Params.ByName "item_id") }}
{{- template "item" $item}}
{{- end}}

Here: https://github.com/infogulch/xrss/blob/caa35cbea98bafff36935e1a53cdb658758f3b54/templates/index.html#L108-L124

---

Would you consider adding something akin to go templates' define and block in zmpl?

[Cohors1316]

We have blocks in zmpl, not sure if they're well documented, but they do allow for reuse. I don't think define is something I'd personally want to tackle at this point, maybe later after I iron out the wrinkles in jetzig proper.

[infogulch]

Ah I didn't see blocks, thanks for pointing them out.

What happens if you have

hello.zmpl:

<p>Hello World!</p>

@block hellob {
  <p>Hello George</p>
}

And then you request at /hello ? Which does it render like?

a. <p>Hello World!</p><p>Hello George</p>
b. <p>Hello World!</p>

[Cohors1316]

The best example is probably from the tests, with blocks.zmpl we have

@block head {
    @zig {
        for (0..9) |_| {
            <link rel="stylesheet" href="https://www.example.com/styles.css" />
        }
    }
}

and in blocks_layout.zmpl where it gets called we have

<html>
    <head>
        @blocks head
    </head>
</html>

Which generates

<html>
    <head>            <link rel="stylesheet" href="https://www.example.com/styles.css" />            <link rel="stylesheet" href="https://www.example.com/styles.css" />            <link rel="stylesheet" href="https://www.example.com/styles.css" />            <link rel="stylesheet" href="https://www.example.com/styles.css" />            <link rel="stylesheet" href="https://www.example.com/styles.css" />            <link rel="stylesheet" href="https://www.example.com/styles.css" />            <link rel="stylesheet" href="https://www.example.com/styles.css" />            <link rel="stylesheet" href="https://www.example.com/styles.css" />            <link rel="stylesheet" href="https://www.example.com/styles.css" />    </head>
</html>

In you're example it would just render as <p>Hello World!</p> unless you also called @block head later in the template. I'm trying to find where we tested that exact thing but failing to see it. Personally I generally use @partial, as it can be used as a basic block, or you can pass arguments to it.

I thought we had a test that declared and used a block in the same template, but maybe not. I'll have to make one and double check, but from a technical standpoint blocks are accessed independently from the rest of the template.

[infogulch]

Great, thank you for explaining. I also found that example and my question was designed to tease out the difference. In this case I think zmpl's block is more like Go's define, though your point that blocks and partials live in a different namespace and only partials take arguments is a significant difference. My understanding is that @partial invokes an existing partial, and the only way to define a new partial is to create a new file that starts with an underscore.

This request is for the ability to define new partials inline, inside any other file. Like blocks, but in the partials namespace.

For example, _thing.zmpl file could be removed and instead defined inline in some other template file like this:

<!-- foo.zmpl -->
<p>Hello</p>

@define thing {
  @args foo: []const u8, bar: []const u8
  {{foo}}: {{bar}}
}

<!-- alternative syntax? -->

@define thing(foo: []const u8, bar: []const u8) {
  {{foo}}: {{bar}}
}

It's not clear why one might want to do that in this case, but it can be quite useful for partials that are reused multiple times in the same file.

I could go on with my thoughts on other changes like a combined define/render like go's block and others but maybe it would be better to focus this discussion on @define...

[Cohors1316]

I think we could use @define to allow inline partials pretty easily. We could parse the file at comptime and split out any definition into it's own file, so @define thing would compile to _thing.zig in templates. If we go that route then I'd probably turn @block into an alias for @partial. I can't say it will happen soon but I'll add it to the list of things to explore.

[infogulch]

That makes a lot of sense to me. I agree that would make @blocks redundant and could alias @partial. @block would also be redundant, but I might selfishly wish it could be redefined as "define and invoke" to match Go's semantics. i.e. @block B(x: u8)(225) { x } = @define B(x: u8) { x } @partial B(225).

In any case, would you be interested in reviewing a patch that implements this? I might take a crack at it myself, though it would be my first foray into zig. 👶