How do I do framgments with JStachio?

[hrstoyanov]

I just discovered JStachio, and I really like what I see so far! However, one important feature for me is "fragments". This seems the opposite of "layouts" (that I see in the docs), and will allow you buddy, the web designer (who knows nothing about Java/JStachio) to author your html/css templates and work in parallel with you, the web java developer. Not only this leads to a nice separation of labour, but more importantly - helps you avoid growing many small templates into a pile of incomprehensible, interconnected mess.

The "fragments" feature is explained here and is present in both Qute and Thymeleaf

So, how do I do "fragments" in JStachio?

[agentgt]

I haven't done or seen this technique for awhile. I believe PJAX (the precursor to libraries like htmx and unpoly) had this technique and that was the last time I did something like this.

Because you can't send URI fragments as parameters the Javascript frameworks like htmx usually send HTTP headers or query parameters then the web frameworks and or templating languages have to do special stuff to render only the fragment. This is because on regular non ajax web 1.0 style page request you need to deliver the entire HTML page.

What I recommend is to just send the entire page back on every request and let htmx pull a <div> with specific id wrapping the fragment content out which I am 100% sure it can do.

This isn't obvious and you might not believe me but is often more efficient to always send the entire page because you only have to cache the entire page instead of the page and a fragment. Even if you don't do caching with things like gzip and http2 it really isn't that much faster sending a fragment of html vs an entire html page (especially compared to assets). Browsers are very fast at parsing HTML.

Furthermore sending a fragment of HTML is not proper HTML and it is disingenuous if the server sends "Content-Type: text/html" which it will and very much anti hypermedia which I find ironic given htmx stand on this. Imagine sending a fragment of JSON like that. That is why streaming JSON has its own MediaType instead of "application/json". Some solutions ( I think rails?) will wrap fragments with html/body tags to get around this problem but at some point it isn't worth it.

That being said I can see how it is easier to debug if you are using browsers developer tools you would just see the response of the fragment and the htmx code is also easier as well as you just say swap everything.

Regardless the hack implementation of this is basically just having a flag to tell the outputstream to ignore content. So you can do this across the board in many templating languages including jstachio by using a custom outputstream and then getting access to that stream to tell it its "on" or "off". You can do this with some threadlocal magic. Let me see if I can pump out a hack to show this technique this weekend.

And of course you could always do the incredibly naive and simple solution of just using header footer conditions but I'm sure that is not desirable.

Anyway thanks for the great question and I hope soon to find a good solution for you!

[agentgt]

I see now I understand. I was hoping to do this at runtime but this is more like a compiler preprocessor. Like from JStachio point of view this would have to pull out the section at compile time.

The major problem is the context stack nature of mustache.

If you have a template (lets ignore html/head/body for brevity) we will call it base. In JStachio the base template has a model that has a child object called someChild.

{{! base.mustache big major template with fragments }}
{{#someChild}} {{! open context of someChild }}

<!-- My fragment start -->
someChild is now appears to be the root here
<!-- My fragment end -->

{{/someChild}}

See the fragment is not expecting the same object as the base template.

The way I was going to implement it was to rerun the entire template with base model object and just omit output for when it is not in the fragment.

[hrstoyanov]

Btw, I noticed that you might have some misconceptions around what HTMX is, web 1.0, need for whole page refresh, etc.

I highly recommend this YouTube intro to HTMX released just yesterday. For deeper introduction, this is a good one.

HTMX allows java developers to build modern interactive web apps without resorting to JS/JSON API/React/Angular. And here lies the opportunities for jStachio!

[agentgt]

I'm very much aware of how and what HTMX does. UnPoly and hotwired as well.

The reason it works for things like Thymeleaf and probably Qute is that the model is not coupled with the template. They also use Map<String,Object> as their model. So as long as the Map has something like:

model.put("someChild", ...)

Thymeleaf and Qute will work but not JStachio.

In JStachio the model is tightly coupled with the template and has a specific type and not a Map.

So we really need the entire model regardless if we only want a subset.

[hrstoyanov]

My concern is that what I want maybe incompatible with the "logic-less" approach of JStachio (which I like), so I have to accept some compromises here...

I see the author of HTMX tried to develop yet another templating engine, Chil Script, but it is just like qute/thymeleaf.

[agentgt]

I completely understand the need and desire for a single template that acts like many templates. I think it is highly desirable as I agree nobody wants fuck tons of partials (mustache partial templates are basically just includes). Otherwise I would completely dismiss this request :)

There are basically two options (ignoring what is actually easily available but what is possible in the context of JStachio's model):

Option 1

We allow reference to a subset of a template:

@JStache(path = "base.mustache#my-fragment")
public record SomeChild(){};

@JStache(path = "base.mustache")
public record Base(SomeChild someChild){};

But then in your request handling you would have to know to use SomeChild and fill it instead of Base.

So there is not just integration with JStachio but the web framework as well assuming you want the same endpoint to generate the full content (that was my web 1.0 argument).

Option 2

You always use and render base:

@JStache(path = "base.mustache")
public record Base(SomeChild someChild, SomeFragmentChoiceThing fragment){};

And then just tell it to omit output when not in the fragment. This is doable today but with lots of ceremony and hacks.

[agentgt]

Copied previous reply here so it is top level:

I completely understand the need and desire for a single template that acts like many templates. I think it is highly desirable as I agree nobody wants fuck tons of partials (mustache partial templates are basically just includes). Otherwise I would completely dismiss this request :)

There are basically two options (ignoring what is actually easily available but what is possible in the context of JStachio's model):

Option 1

We allow reference to a subset of a template:

@JStache(path = "base.mustache#my-fragment")
public record SomeChild(){};

@JStache(path = "base.mustache")
public record Base(SomeChild someChild){};

But then in your request handling you would have to know to use SomeChild and fill it instead of Base.

So there is not just integration with JStachio but the web framework as well assuming you want the same endpoint to generate the full content (that was my web 1.0 argument).

Option 2

You always use and render base:

@JStache(path = "base.mustache")
public record Base(SomeChild someChild, SomeFragmentChoiceThing fragment){};

And then just tell it to omit output when not in the fragment. This is doable today but with lots of ceremony and hacks.

Anyway I can put together a solution using JStachio today for option 2.

[hrstoyanov]

I was thinking of something like Option 1. Don't worry about any particular web framework.

[agentgt]

I guess my question is do you want the same endpoint to generate the full HTML or a subset or do you really just want a way to reference a subset of a template as though it were a regular template file?

[hrstoyanov]

The second option - i just want to carve out a subset of the template, render it as a string. jStachio should not worry what happens next.

[agentgt]

Option 2 and just sending the entire HTML response every time is super easy just using enums as fragments.

Let us use htmx example of /contacts/details.html which presumably has a GET endpoint of /contacts/{id}.

In JStachio you would make one class for all /contacts/*:

@JStache("/contacts/details.html")
public record ContactDetails(Contact contact, @Nullable Fragment fragment){} // I'm just using records for brevity.

public enum Fragment {
  ARCHIVE_UI,
  SOME_OTHER_FRAGMENT,
  UNARCHIVE_UI;
}

details.html as mustache:

{{^fragment}} {{! I don't recommend this but if you really want to limit output }}
<html>
    <body>
{{/fragment}}
        <div hx-target="#archive-ui"> <!-- we change the target here -->
          {{#fragment.ARCHIVE_UI}}
            <div id="archive-ui"> <!-- this id is important -->
            {{#contact.archived}}
            <button hx-patch="/contacts/${contact.id}/unarchive">Unarchive</button>
            {{/contact.archived}}
            {{^contact.archived}}
            <button hx-delete="/contacts/${contact.id}">Archive</button>
            {{/contact.archived}}
            </div>
         {{/fragment.ARCHIVE_UI}}
        </div>
        <h3>Contact</h3>
        <p>${contact.email}</p>
{{^fragment}}
    </body>
</html>
{{/fragment}}

The above is assuming you largely generate the same HTML as /contacts/{id} and /contacts/${contact.id}/unarchive which in my experience is highly likely and you will in general use the same details.html template for both of those endpoints.

For /contacts/${contact.id}/unarchive we use the enum value of UNARCHIVE_UI for when it renders details.html.

You can think of Fragments in this case as "mode" or "sub template".

[hrstoyanov]

well, not sure i quite like option 2, but I understand it is easier today. The template can become huge as the web app adds more UI stuff. I know HTMX has a way of extracting what it need (e.g. element id and everything under it) from the incoming html payload...

[agentgt]

Also, JSR-430 can do "layout" or basically "composition" too, but cannot offer "fragments" either (unlike Qute and Thymeleaf!). So, without "fragments extraction from a large template", jStachio is like JSR-430, except that It trades compile time code generation (like JSP) for the price of running annotation processor phase during build.

BTW I'm curious where you saw JEP 430 doing layout other than you know just manually doing it with Java? It is interpolation and not full templating. I'm fairly sure JEP 430 cannot loop through items nor does it have conditions. If it does can you show me an example. I have been meaning to play with it more but haven't had the time.

[hrstoyanov]

... yeah what I meant was manually assembling a response in JSR-430. The result is the same as "layout-ing" though - you can only see the final result after you run the web app (Spring or Quarkus or whatever), and you buddy, the web designer, cannot help you. But I do not think this scales the template organization with bigger apps, which is the main problem - you can get yourself in a hot mess of partials, etc. I think this is the reason why the creator of HTMX, @1cg singled out this feature in many template engines, in the essay I posted above.

Honestly, I was considering ditching both Qute and Tymeleaf and just use JSR-430 in Java 21, but the above problem gave me a pause, and runtime rendering (interpolation) is not the best. I also considered just olde JSP, mainly because I like the static compile a lot!, but with all JSP includes, etc. this still cannot be previewed in chrome without the whole build/run cycle.

jStachio checks all boxes for me - java-centric, compile time (=huge performance gain!), not assuming Spring or Microprofile, doing one thing and one thing only well... I just dream of something like Option 1, if possible of course.

[agentgt]

OK I am putting in fragment support and I think you will like how it works. I think will be surprisingly elegant. #193

Let us say we have a template like /contacts/details.mustache:

<html>
    <body>
        <div hx-target="this">
          {{#archive-ui}}
            {{#contact.archived}}
            <button hx-patch="/contacts/${contact.id}/unarchive">Unarchive</button>
            {{/contact.archived}}
            {{^contact.archived}}
            <button hx-delete="/contacts/${contact.id}">Archive</button>
            {{/contact.archived}}
          {{/archive-ui}}
        </div>
        <h3>Contact</h3>
        <p>${contact.email}</p>
    </body>
</html>

You can now do:

@JStache("/contacts/details.mustache#archive-ui")
public record ContactDetails(Contact contact){}

JStachio will see the template as:

            {{#contact.archived}}
            <button hx-patch="/contacts/${contact.id}/unarchive">Unarchive</button>
            {{/contact.archived}}
            {{^contact.archived}}
            <button hx-delete="/contacts/${contact.id}">Archive</button>
            {{/contact.archived}}

I love the happy coincidence that sections have # as their delimiter and we can easily parse for it.

The question is if we should support fragments within fragments.

/contacts/details.mustache#archive-ui#contacts.archived

I'm inclined to say no and just pick the first section with name of the fragment.

Thoughts?

Thank you so much for bringing this up. I think it will be kick ass and I see lots of interesting use cases with Lambdas as snippet/partial context is a pain point.

[hrstoyanov]

Thank you! I will test it as soon as it is available! I think one-level fragments is fine for now, nesting can come later, if needed. The sample above looks good (watch out for things that can turn the template into invalid html, but so far you are good)

[agentgt]

Sort of tangental but what is your preferred web framework?

I saw you said micronaut? Would you like micronaut support?

Never mind I must have mixed up microprofile with micronaut. I'm still looking into how I can do quarkus.

[hrstoyanov]

@agentgt
I split time between quarkus and Spring. Maybe after the fragments feature, I can help with promoting jStachio for both, writing drop-in extensions, listing them on the official sites, etc. You should definitely promote jStachio on the htmx-java discord channel (or I can do on your behalf)

I think HTMX is catching fire fast in the java community - just today Josh Long, a Spring evangelist did a show with HTMX in Spring boot. Expect massive interest from spring developers to follow soon! I also saw a couple of talks at European dev conferences as well.

@1cg see above !

[1cg]

fwiw, I think that is a great syntax for both declaration and use of fragments

one argument for supporting nested fragments is situations like this:

Say you have a table and that table can be refreshed for some reason (e.g. sorting by clicking on the header), but then, within that table, you have a row-specific operation (e.g. inline editing) that targets only the row. In that case it would be nice to declare an outer section for the table and an inner section for the row.

Not a major use case, but wanted to give you one to think about based on my experience w/ htmx

hope that's useful, and great job on this feature!

[agentgt]

@1cg and @hrstoyanov Fragments are in 1.2.0

I actually do some unique whitespace handling to follow Mustache whitespace philosophy.

https://jstach.io/jstachio/io.jstach.jstache/io/jstach/jstache/JStache.html#_fragments

@jgonggrijp might find this whole fragments thing interesting. I'm not sure its worthy of adding to the spec but nonetheless it is great how well it appears to work for Mustache syntax.

[hrstoyanov]

Thank you @agentgt! Will test soon!

[jgonggrijp]

Yes, I find it interesting, thanks for drawing my attention to it!

For what it's worth, I don't have a strong opinion on whether fragments should be in the Mustache spec or not.

[dsyer]

I think I might like some kind of nesting. Not sure how this plays out because my example has an iterable in it, whereas the examples above don't.

E.g. suppose I'm rendering a list of "todos":

<!-- index.mustache -->
<html>
<body>
<ul>
  {{#todos}}{{<todo}}{{/todo}}{{/todos}}
</ul>
</body>
</html>

I want to re-use the entire <ul>...</ul> and it seems like to do that I have to introduce a "fake" model property like

<!-- index.mustache -->
<html>
<body>
{{#hasTodos}}
<ul>
  {{#todos}}{{<todo}}{{/todo}}{{/todos}}
</ul>
{{/hasTodos}}
</body>
</html>

with a main model

@JStache(path = "index")
record Page(TodosContainer hasTodos) {}

@JStache(path = "index#hasTodos")
record TodosContainer(List<Todo> todos) {}

Then I can render a TodosContainer independently of the page, which I like. But ideally I want to put the {{<todo}}{{/todo}} inline in index.mustache as well, and re-use it as a fragment, e.g.

<!-- index.mustache -->
<html>
<body>
{{#hasTodos}}
<ul>
  {{#todos}}<li id="{{id}}">{{title}}</li>{{/todos}}
</ul>
{{/hasTodos}}
</body>
</html>

So I would need something like

@JStache(path = "index#hasTodos#todos")
record Todo(String id, String title) {}

Does that make sense? Could it ever work, given that "todos" is iterable?

[agentgt]

Yes but in the parent template “index” you can define hasTodos…

Basically $ tags get removed but not the inside content.

[agentgt]

https://github.com/mustache/spec/blob/5d3b58ea35ae309c40d7a8111bfedc4c5bcd43a6/specs/~inheritance.yml#L47

[agentgt]

Here is our doc on it which is poorly written and several typos I need to fix: https://jstach.io/doc/jstachio/current/apidocs/#mustache_fragments

The key is you can use any section like tags.

[dsyer]

Didn't work for me so I must still be misunderstanding. An example in the docs would help.

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.11.0:compile (default-compile) on project htmx-spring-boot-example-todowebflux: Compilation failure
[ERROR] /home/dsyer/dev/scratch/todojstachio/src/main/java/example/todomvc/web/TemplateModel.java:[161,16] java.nio.file.NoSuchFileException: /home/dsyer/dev/scratch/todojstachio/src/main/resources/templates/index$hasTodos.mustache

the line with the error is

@JStache(path = "index$hasTodos")
public record TodosDto(List<TodoDto> todos, String action) {...}

UPDATE: the fragment name is index#hasTodos even though the section is a $hasTodos. So it works, I think, but kind of confusing.

[agentgt]

Yes it just happens to be a happy coincidence that fragment URI uses "#" and section blocks "#". Regardless of the type of section-like block it can only be referenced with URI fragment notation.