https://github.com/thymeleaf/thymeleaf-extras-tiles2
Thymeleaf integration with Apache Tiles 2.x
https://github.com/thymeleaf/thymeleaf-extras-tiles2
Last synced: 6 months ago
JSON representation
Thymeleaf integration with Apache Tiles 2.x
- Host: GitHub
- URL: https://github.com/thymeleaf/thymeleaf-extras-tiles2
- Owner: thymeleaf
- Created: 2012-06-13T23:45:08.000Z (over 13 years ago)
- Default Branch: 2.1-master
- Last Pushed: 2022-12-16T03:02:18.000Z (about 3 years ago)
- Last Synced: 2025-07-31T17:09:16.309Z (7 months ago)
- Language: Java
- Homepage: http://www.thymeleaf.org
- Size: 311 KB
- Stars: 36
- Watchers: 8
- Forks: 18
- Open Issues: 18
-
Metadata Files:
- Readme: README.markdown
- Changelog: ChangeLog.txt
- Contributing: CONTRIBUTING.markdown
Awesome Lists containing this project
README
Thymeleaf - Tiles 2 integration module
======================================
------------------------------------------------------------------------------
Status
------
This is a *thymeleaf extras* module, not a part of the Thymeleaf core (and as
such following its own versioning schema), but fully supported by the
Thymeleaf team.
Current versions:
* **Version 2.1.1.RELEASE** - for Thymeleaf 2.1 (requires 2.1.2+)
License
-------
This software is licensed under the [Apache License 2.0]
(http://www.apache.org/licenses/LICENSE-2.0.html).
Requirements
------------
* Thymeleaf **2.1.2+**
* Apache Tiles 2 version **2.2.1+** (**2.2.2** recommended)
* Web environment (Tiles integration cannot work offline)
Maven info
----------
* groupId: `org.thymeleaf.extras`
* artifactId:
* Main package: `thymeleaf-extras-tiles2`
* Spring 3 integration package: `thymeleaf-extras-tiles2-spring3`
* Spring 4 integration package: `thymeleaf-extras-tiles2-spring4`
Distribution packages
---------------------
Distribution packages (binaries + sources + javadoc) can be downloaded from [SourceForge](http://sourceforge.net/projects/thymeleaf/files/thymeleaf-extras-tiles2/).
Features
--------
* *(Optional)* **Spring MVC 3** integration
* *(Optional)* **Spring Web Flow 2.3** integration, with AJAX fragment
rendering support.
* Use Thymeleaf in your **Tiles definitions**:
* Use Thymeleaf templates.
* Include Thymeleaf templates (or fragments of templates) as attributes.
* Compatible with Tiles definition wildcards (Tiles 2.2.2+).
* Thymeleaf template/attribute definitions can include selectors
(similar to `th:include`/`th:replace`):
* By fragment name: `"template :: fragment"`
* By DOM selector: `"template :: div#content"`
* Can include Standard Expressions:
`"${templateName} :: ${conf.fragName}"`
* New **`tiles` dialect**:
* `tiles:include` / `tiles:replace` for including Tiles attributes.
* `tiles:fragment` for signaling fragments to be included as attributes.
* `tiles:string` for inserting String-type Tiles attributes.
* Enable **Natural templating** in your Tiles markup fragments:
* It allows you to use only specific parts of your templates as *Tiles
attributes*.
* You can add markup and styling surrounding those *specific parts* for
static prototyping purposes.
* **Mix JSPs and Thymeleaf templates** in the same definition, for better
legacy integration / migration.
* Thymeleaf fragment templates see variables defined in higher-level
containing layout templates.
* JSP fragments see variables defined in higher-level containing
JSP/Thymeleaf templates. And viceversa.
------------------------------------------------------------------------------
Configuration with Spring
-------------------------
*(Note: the following code examples use Spring 3.x package naming (`.spring3.`). If you are using the `thymeleaf-extras-tiles2-spring4` package for integration with Spring 4 instead, you should replace `.spring3.` with `.spring4.`)*
In order to use Apache Tiles 2 with Thymeleaf in your Spring MVC application,
we will first need to configure our application in the usual way for
Spring + Thymeleaf applications (*TemplateEngine* bean, *template resolvers*,
etc.), and then create an instance of the `ThymeleafTilesConfigurer` (similar
to the Spring Tiles configurer for JSP), like:
```xml
/WEB-INF/tiles-defs.xml
```
Also, we will need to configure our Thymeleaf *view resolver* in order to
use a specialized Thymeleaf-Tiles2 view class:
```xml
```
...and finally, add the Tiles dialect to our Template Engine so that we
can use the `tiles:*` attributes:
```xml
...
...
```
And that's all! Now we can make our controller methods return Tiles
definition names as view names and everything should work fine.
Configuration and usage without Spring
--------------------------------------
Following the standard configuration mechanisms in Tiles 2.2, in order to
use Thymeleaf + Tiles in a non-Spring application, we should:
* Either configure an `org.thymeleaf.extras.tiles2.web.startup.ThymeleafTilesListener`
at our `web.xml`
* ...or configure an `org.thymeleaf.extras.tiles2.web.startup.ThymeleafTilesServlet`,
also at our `web.xml`.
Both these artifacts declare and initialize a Thymeleaf-enabled
`TilesContainer` instance, which we can access with:
```java
final TilesContainer tiles = ServletUtil.getContainer(servletContext);
```
...and then execute, specifying the definition to be executed and the
following sequence of *request items*:
1. The Thymeleaf *template engine* (`TemplateEngine`)
2. The Thymeleaf *context* (`IContext`)
3. The `HttpServletRequest`
4. The `HttpServletResponse`
5. The `java.io.Writer` the result should be written to (for example,
`response.getWriter()`)
Put as code:
```java
tiles.render("myDefinition", templateEngine, ctx, request, response, writer);
```
Using Thymeleaf in our definition files
---------------------------------------
Using Thymeleaf in our definition files (usually called something like
`tiles-defs.xml`) is easy. These are the key points:
* Thymeleaf is now the default *template type*, instead of JSP.
* We can use `templateType="thymeleaf"` or simply omit `teamplateType`
for our templates, and `type="thymeleaf"` for attributes.
* We can use `templateType="jsp"` for our JSP templates
(`type="jsp"` for our attributes).
* Thymeleaf value syntax is equivalent to that of `th:include` and
`th:replace` attributes:
`"TEMPLATESELECTOR (:: FRAGMENTSELECTOR)?"`
* Template Selector:
* Understandable by the template resolvers you configured, just as
with any other thymeleaf templates.
* Can use Standard Expressions: `${...}`, `*{...}`, literals,
operands, etc. (externalized messages and links are *not allowed*).
* Fragment Selector (optional):
* Can specify fragments by name (using attribute `tiles:fragment`).
* Can specify DOM Selector (`div#content`)
* Can use Standard Expressions: `${...}`, `*{...}`, literals,
operands, etc. (externalized messages and links are *not allowed*).
* Tiles definition wildcards (from Tiles 2.2.2) can be used.
A quick example:
```xml
...
...
```
Inserting attributes
--------------------
The new `tiles` dialect allows us to insert Tiles attributes easily,
just as we'd do with `th:include`:
```xml
...
...
some prototyping markup over here...
...
```
That `tiles:include` will work equivalently to the Standard Dialect's
`th:include`, only inserting a Tiles attribute by its name (as specified
in the definition file) instead of another template.
Another possibility, `tiles:replace`:
```xml
some prototyping markup over here...
```
...will work almost exactly as `tiles:include`, but replacing the
containing `
` tag with the attribute contents, instead of inserting
these contents inside it.
What about inserting *string* attributes? Easy:
```xml
blah blah
```
And there's one more attribute, which allows us to (optionally) specify
which part of our template we will be using as a fragment. So:
```xml
lorem ipsum sic dolor amet blah blah...
```
...will specify a fragment we can use in our definitions with:
```xml
```
Mixing Thymeleaf and JSP
------------------------
For a better legacy integration and a smoother migration of applications,
Thymeleaf templates and JSPs can be mixed together in Tiles definitions, so
that Thymeleaf templates can include JSP attributes, and viceversa.
And these fragments in different technologies can even *communicate*, so
that they can see the variables that the others define:
* Thymeleaf attribute included into Thymeleaf template:
* Attribute can see all local variables (e.g. `th:with`) defined in
template.
* Thymeleaf attribute included into JSP template:
* Attribute can see all variables defined (e.g. ``) with
at least *request scope* in the JSP.
* JSP attribute included into Thymeleaf template:
* Attribute can see all local variables (e.g. `th:with`) defined in
templates as *request attributes*.
Using Spring Web Flow
---------------------
In order to use Thymeleaf + Tiles in our Spring Web Flow applications, we
will first need to modify the definition of our *View Resolver*, so that it
uses thymeleaf's AJAX-enabled implementation configured to create *View*
instances that understand the SpringWebFlow-Tiles combination:
```xml
```
### Scenario
Let's say we have a Tiles definition like:
```xml
...
...
```
Which references a *template file* called `orderdet`, which will probably be added
a prefix and a suffix by the Thymeleaf *template resolver*, resulting into something
like `/WEB-INF/templates/orderdet.html`.
Also, we can see how `orderdet` includes a fragment (an *attribute* in Tiles jargon)
called `prog_content`, which resolves to a fragment (specified with `tiles:fragment`)
called `progtext` in template `progress` (probably `/WEB-INF/templates/progress.html`).
Let's see how these two template files could look like. First, the relevant parts
of `orderdet.html`:
```html
...
...
...
Progress of your order: GOOD!
Spring.addDecoration(
new Spring.AjaxEventDecoration(
{
elementId:'progressButton',
event:'onclick',
formId:'progressForm'
}));
```
There you can see how we added the required JavaScript libraries from the Spring JS project
(a part of Spring Web Flow), and then linked an AJAX call for Spring Web Flow's
event `checkprogress` to our form button.
The relevant parts of our `progress.html` file could look like:
```html
...
Progress of your order 34%
...
```
Note that, in order for Spring Web Flow to be able to refresh a markup fragment via AJAX,
the specific fragment must be completely enclosed in an element specifying an `id` attribute,
like the `
` you see above. Also note that in order to preserve
that `id` when it renders, we use `tiles:replace` instead of `tiles:include`.
Our flow can now define a transition for updating that fragment as a part of
the *Order Details* view (`view-state`):
```xml
```
Your AJAX interactions should now work seamlessly.