Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/bootique/bootique-mvc

MVC framework for Bootique and Mustache Template Engine integration
https://github.com/bootique/bootique-mvc

bootique freemarker mustache mvc

Last synced: about 2 months ago
JSON representation

MVC framework for Bootique and Mustache Template Engine integration

Awesome Lists containing this project

README 

        



[![build test deploy](https://github.com/bootique/bootique-mvc/actions/workflows/maven.yml/badge.svg)](https://github.com/bootique/bootique-mvc/actions/workflows/maven.yml)

[![Maven Central](https://img.shields.io/maven-central/v/io.bootique.mvc/bootique-mvc.svg?colorB=brightgreen)](https://search.maven.org/artifact/io.bootique.mvc/bootique-mvc/)



A basic MVC web framework for [Bootique](http://bootique.io) for processing requests and responding with 

template-generated views. Implemented on top of JAX-RS, specifically [bootique-jersey](https://github.com/bootique/bootique-jersey)). 

bootique-mvc can work with multiple template engines, providing integration with [Mustache](https://mustache.github.io/) 

and [FreeMarker](https://freemarker.apache.org) out of the box. 



This framework is suitable for simple HTML UIs, with minimal server-side rendering (e.g. when most of the UI work is 

done on the client with JavaScript). 



Code examples: [bootique-mvc-demo](https://github.com/bootique-examples/bootique-mvc-demo).



## Usage

### Prerequisites

Include ```bootique-bom```:

```xml



    

        

            io.bootique.bom

            bootique-bom

            3.0-M4

            pom

            import

        

    



```



Include the flavor of bootique-mvc you are planning to use, e.g. Jakarta / Mustache:



```xml



	io.bootique.mvc

	bootique-mvc-jakarta-mustache



```



### Create HTML page



Create a "view" class extending `AbstractView`. It performs two functions:



* Defines the location of the page template. Pay attention to the view Java package. Usually template file will be 

located under the path matching the view package (see the next section on template resolving mechanism).

* Serves as a "root context" during template rendering, providing values for the template variables. So the view is 

also a holder of the page "model". 



```java

package org.example.view;



public class SomePageView extends AbstractView {



    private final String firstName;

    private final String lastName;



    public SomePageView(String firstName, String lastName) {

        super("some-page.mustache");



        this.firstName = firstName;

        this.lastName = lastName;

    }

    

    public String getFirstName() {

        return firstName;

    }



    public String getLastName() {

        return lastName;

    }

}

```



Configure the app to resolve templates relative to a folder on a classpath :



```yaml

mvc:

  templateBase: "classpath:templates"

```



Now let's create a Mustache template in the project resources folder under 

`templates/org/example/view/some-page.mustache`.



```



Hi, {{firstName}} {{lastName}}!



```



Finally, create a "controller" class, which is a collection of JAX-RS endpoints that return view instances in response 

to user requests. So a single controller can serve multiple "pages" (e.g. those that share a common URL path prefix).



```java

@Path("/")

@Produces(MediaType.TEXT_HTML)

public static class Pages {



    @GET

    @Path("some-page")

    public SomePageView somePage(

            @QueryParam("fn") String firstName, 

            @QueryParam("ln") String lastName) {

        return new SomePageView(firstName, lastName);

    }

}

```



Now when you hit `/some-page?fn=Joe&ln=Smith`, you'd get a page that says "hi".



### Template Resolving



In the example above we set the template base to be `classpath:templates`. But it can also be set to a filesystem 

directory or a URL on a public web server. The only requirement is that a single base is shared by all templates.

Assuming the base is `classpath:templates`, here are some simple rules for path resolution:



* Template path with no leading forward slash will be prepended with a path corresponding to the view package:

`some-page.mustache` -> `classpath:templates/org/example/view/some-page.mustache`. 

* Template path starting with a forward slash is resolved directly against `templateBase`:

`/some-page.mustache` -> `classpath:templates/some-page.mustache`

* Template path can reference parent directories via `../`:  `../some-page.mustache` -> 

`classpath:templates/org/example/some-page.mustache`. 

* If a parent directory is outside the `templateBase`, an exception is thrown: `../../../../some-page.mustache` -> throws

* Templates can include other templates (such includes are called "partials" in Mustache). The rules for resolving 

includes are the same as for the root templates.



### Template Caching



By default `bootique-mvc` would reload a template on every call. This is great in development mode, but is 

going to result in poor performance in production. To configure template caching, you'll need to set an extra

property in config. E.g.:



```yaml

mvc:

  templateTtl: 1min

```



_TODO: as of Bootique 3.0.M2, this only works for Mustache, and not Freemarker until [this task](https://github.com/bootique/bootique-mvc/issues/27) is complete._