- make sure htmx always run first

- setup engines at startup time

Author: jknack

jooby/src/main/java/io/jooby/TemplateEngine.java

@@ -18,6 +18,8 @@
  * @author edgar
  */
 public interface TemplateEngine extends MessageEncoder {
+  /** Just a template engine that is on top of the stack (run before all other engines). */
+  interface OnTop extends TemplateEngine {}
 
   /** Name of application property that defines the template path. */
   String TEMPLATE_PATH = "templates.path";

jooby/src/main/java/io/jooby/internal/HttpMessageEncoder.java

@@ -30,7 +30,12 @@ public class HttpMessageEncoder implements MessageEncoder {
   public HttpMessageEncoder add(MediaType type, MessageEncoder encoder) {
     if (encoder instanceof TemplateEngine engine) {
       // Media type is ignored for template engines. They have a custom object type
-      templateEngineList.add(engine);
+      if (engine instanceof TemplateEngine.OnTop) {
+        // need to go first
+        templateEngineList.addFirst(engine);
+      } else {
+        templateEngineList.add(engine);
+      }
     } else {
       if (encoders == null) {
         encoders = new LinkedHashMap<>();

modules/jooby-htmx/src/main/java/io/jooby/htmx/HtmxModule.java

@@ -58,7 +58,9 @@ public void install(Jooby app) throws Exception {
     if (errorHandler != null) {
       app.error(errorHandler.toErrorHandler());
     }
-
-    app.encoder(new HtmxTemplateEngine());
+    var htmxEngine = new HtmxTemplateEngine();
+    app.encoder(htmxEngine);
+    // validate and setup engines:
+    app.onStarting(() -> htmxEngine.init(app));
   }
 }

modules/jooby-htmx/src/main/java/io/jooby/htmx/HtmxTemplateEngine.java

@@ -5,6 +5,9 @@
  */
 package io.jooby.htmx;
 
+import java.util.ArrayList;
+import java.util.List;
+
 import org.jspecify.annotations.Nullable;
 
 import io.jooby.*;
@@ -23,12 +26,22 @@
  * @author edgar
  * @since 4.5.0
  */
-public class HtmxTemplateEngine implements TemplateEngine {
+public class HtmxTemplateEngine implements TemplateEngine.OnTop {
+
+  private List<TemplateEngine> engines;
+
+  void init(Jooby app) {
+    engines = new ArrayList<>(app.getRouter().getTemplateEngines());
+    engines.remove(this);
+    if (engines.isEmpty()) {
+      throw new IllegalStateException("No template engines registered");
+    }
+  }
 
   @Override
   public Output render(Context ctx, ModelAndView<?> modelAndView) throws Exception {
     if (modelAndView instanceof HtmxModelAndView<?> htmxView) {
-      var engineEncoder = resolveTemplateEngine(ctx, htmxView);
+      var engineEncoder = resolveTemplateEngine(htmxView);
       if (engineEncoder == null) {
         throw new IllegalStateException(
             "No template engine registered to handle: " + htmxView.getView());
@@ -47,17 +60,16 @@ public Output render(Context ctx, ModelAndView<?> modelAndView) throws Exception
    * ModelAndView}. Iterates through the available template engines in the context, returning the
    * first one that supports the provided model and view.
    *
-   * @param ctx The web context containing the registered resources and state information.
    * @param mv The {@link ModelAndView} to be rendered. The method determines its compatibility with
    *     the available template engines.
    * @return The {@link TemplateEngine} capable of rendering the provided {@link ModelAndView}, or
    *     {@code null} if no suitable engine is found.
    */
-  private @Nullable TemplateEngine resolveTemplateEngine(Context ctx, ModelAndView mv) {
+  private @Nullable TemplateEngine resolveTemplateEngine(ModelAndView mv) {
     // Find the encoder that handles standard ModelAndView
-    for (var templateEngine : ctx.getRouter().getTemplateEngines()) {
-      if (templateEngine != this && templateEngine.supports(mv)) {
-        return templateEngine;
+    for (var engine : engines) {
+      if (engine.supports(mv)) {
+        return engine;
       }
     }
     return null;

modules/jooby-htmx/src/test/java/io/jooby/htmx/HtmxModuleTest.java

@@ -36,6 +36,9 @@ void shouldInstallWithoutErrorHandler() throws Exception {
 
     // Verify the template engine WAS registered
     verify(app).encoder(any(HtmxTemplateEngine.class));
+
+    // Verify the init lifecycle hook was registered
+    verify(app).onStarting(any());
   }
 
   @Test
@@ -54,5 +57,8 @@ void shouldInstallWithErrorHandler() throws Exception {
 
     // 4. Verify the template engine WAS registered
     verify(app).encoder(any(HtmxTemplateEngine.class));
+
+    // 5. Verify the init lifecycle hook was registered
+    verify(app).onStarting(any());
   }
 }

modules/jooby-htmx/src/test/java/io/jooby/htmx/HtmxTemplateEngineTest.java

@@ -23,6 +23,7 @@
 import org.junit.jupiter.api.Test;
 
 import io.jooby.Context;
+import io.jooby.Jooby;
 import io.jooby.ModelAndView;
 import io.jooby.Router;
 import io.jooby.TemplateEngine;
@@ -35,13 +36,29 @@ class HtmxTemplateEngineTest {
   private HtmxTemplateEngine engine;
   private Context ctx;
   private Router router;
+  private Jooby app;
 
   @BeforeEach
   void setUp() {
     engine = new HtmxTemplateEngine();
     ctx = mock(Context.class);
     router = mock(Router.class);
+    app = mock(Jooby.class);
+
     when(ctx.getRouter()).thenReturn(router);
+    when(app.getRouter()).thenReturn(router);
+  }
+
+  // --- Lifecycle / Init Tests ---
+
+  @Test
+  void shouldThrowIllegalStateExceptionWhenNoOtherTemplateEnginesRegistered() {
+    // Router only has the HtmxTemplateEngine registered, no underlying engines like Handlebars
+    when(router.getTemplateEngines()).thenReturn(List.of(engine));
+
+    IllegalStateException ex = assertThrows(IllegalStateException.class, () -> engine.init(app));
+
+    assertEquals("No template engines registered", ex.getMessage());
   }
 
   // --- Supports Tests ---
@@ -68,12 +85,17 @@ void shouldReturnNullForStandardModelAndView() throws Exception {
 
   @Test
   void shouldThrowIllegalStateExceptionWhenNoTemplateEngineFound() {
+    // 1. Setup incompatible engine and initialize the HtmxTemplateEngine
+    TemplateEngine incompatibleEngine = mock(TemplateEngine.class);
+    when(router.getTemplateEngines()).thenReturn(Arrays.asList(engine, incompatibleEngine));
+    engine.init(app); // Cache the engines
+
+    // 2. Setup the HTMX view
     HtmxModelAndView<?> htmxView = mock(HtmxModelAndView.class);
     when(htmxView.getView()).thenReturn("missing.hbs");
+    when(incompatibleEngine.supports(htmxView)).thenReturn(false);
 
-    // Router has no other engines registered
-    when(router.getTemplateEngines()).thenReturn(List.of(engine));
-
+    // 3. Execute and verify
     IllegalStateException ex =
         assertThrows(IllegalStateException.class, () -> engine.render(ctx, htmxView));
 
@@ -90,17 +112,18 @@ void shouldRenderMultipleTemplatesIntoCompositeOutput() throws Exception {
 
     when(htmxView.iterator()).thenReturn(views.iterator());
 
-    // 2. Mock a delegate Template Engine (e.g., Handlebars)
+    // 2. Mock Delegate Engines
     TemplateEngine delegateEngine = mock(TemplateEngine.class);
     when(delegateEngine.supports(htmxView)).thenReturn(true);
 
-    // Mock an incompatible engine to cover the "continue" branch inside resolveTemplateEngine
     TemplateEngine incompatibleEngine = mock(TemplateEngine.class);
     when(incompatibleEngine.supports(htmxView)).thenReturn(false);
 
-    // Register engines. We include `engine` (this) to ensure the `!= this` branch is hit.
+    // Register and initialize engines (HtmxTemplateEngine should remove itself from the cached
+    // list)
     when(router.getTemplateEngines())
         .thenReturn(Arrays.asList(engine, incompatibleEngine, delegateEngine));
+    engine.init(app);
 
     // 3. Mock the Output Pipeline
     OutputFactory outputFactory = mock(OutputFactory.class);