Feature: Block fragments

[wrapperup]

Since #568 hasn't had an update in a long time, and it is a nice feature, this is a new PR to implement the proposed changes from that discussion.

This adds block fragments/partials as part of the Template derive. Here's an example of how to use it:

#[derive(Template)]
#[template(path = "...", block = "my_block")]
struct MyBlockFragment<'a> {
    name: &'a str,
}

This also properly supports inheritance, nesting, and the super() macro. It does this by abstracting buf_writable in the generator to add the ability to discard output, except for the block that needs to be rendered.

[couchand]

I'm really impressed at how effective the strategy of abstracting the WritableBuffer is. Very nice.

Personally this feature seems a bit odd to me. It feels like its overloading the block inheritance mechanism to do something very different that there's already other ways to do. I did re-read the thread from #568. I wonder if perhaps a more complete motivating example would be helpful, in the tests or the docs or just PR comments?

[wrapperup]

Personally this feature seems a bit odd to me. It feels like its overloading the block inheritance mechanism to do something very different that there's already other ways to do.

I couldn't think of a cleaner way here. Perhaps adding another node to do it, but block ended up being suggested as the preferred way in that thread.

I wonder if perhaps a more complete motivating example would be helpful, in the tests or the docs or just PR comments?

It's very much a convenience feature. There are already ways to do achieve the same result (macros, importing other templates). When using a library like htmx. It's pretty nice to just go slap in a couple of lines in a template file to say "hey, this something that will update", and it can.

It's part of this whole "locality of behavior" idea, where you keep things as close together as possible (ideally, in the same file). htmx, Alpine.js, Tailwindcss, and all of those that are HTML first trend towards this kind of design. This is also a pretty good read: https://htmx.org/essays/template-fragments/

[djc]

The direction here seems like it offers a decent amount of functionality especially relative to the limited complexity cost, so it seems reasonable to me. @vallentin / @Kijewski any thoughts?

[wrapperup]

The parser crate changes had no effect on this PR, which is great. Could I get eyes on these changes again just incase?

[wsantos]

@djc what do we need to merge this? I'm considering using it but since my site is going to be built in htmx this is a requirement, thanks in advance.

[djc]

I'd like a second opinion from one of the other maintainers.

[nathanaelhuffman]

I'm also considering using this with htmx and would love to see this land.

[pbouzakis]

Same here; looking to leverage this in htmx project. Currently, I'm using minijinja and render_block, which is working nicely. Would love to move to Askama if I can, but need this feature.

[teenjuna]

Hey @Kijewski, sorry to bother, but it looks like @djc is looking for your opinion on this. Can you please take a look? 🙏

[djc]

(No is also an okay answer, but would like to have that be made explicit!)

[Kijewski]

Sorry, I won't find the time to wrap my head around this PR for the foreseeable time. At a very (very) quick glance the code looks fine, and the feature seems useful to me.

[James-Rhodes]

Hi all is there any updates on this feature? Very much looking forward to seeing it land :)

[djc]

This is waiting for another round of review from me now that we have some positive acknowledgement from @Kijewski (thanks!) -- I'm having a very busy time so it may take me a bit.

(If this is important to you, maybe consider sponsoring my work on Askama and other projects.)

[GuillaumeGomez]

The feature is pretty nice and code looks good to me! Let's wait for @djc to have time to come back to it.

[djc]

Please just rebase and squash all your changes -- right now "this branch cannot be rebased due to conflicts".

[djc]

(Failing CI now.)

[Kijewski]

I think the error is unrelated to this PR, and it should be fixed in the current main branch. Can you please rebase, @wrapperup?

[wrapperup]

I think the error is unrelated to this PR, and it should be fixed in the current main branch. Can you please rebase, @wrapperup?

Yep! Was just waiting on it to be fixed in main.

[djc]

Thanks, and sorry for the long delays in getting this merged!