{"id":23762404,"url":"https://github.com/thymeleaf/thymeleaf-extras-tiles2","last_synced_at":"2025-09-05T06:31:52.834Z","repository":{"id":3593562,"uuid":"4657431","full_name":"thymeleaf/thymeleaf-extras-tiles2","owner":"thymeleaf","description":"Thymeleaf integration with Apache Tiles 2.x","archived":false,"fork":false,"pushed_at":"2022-12-16T03:02:18.000Z","size":318,"stargazers_count":36,"open_issues_count":18,"forks_count":18,"subscribers_count":8,"default_branch":"2.1-master","last_synced_at":"2025-07-31T17:09:16.309Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://www.thymeleaf.org","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thymeleaf.png","metadata":{"files":{"readme":"README.markdown","changelog":"ChangeLog.txt","contributing":"CONTRIBUTING.markdown","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-06-13T23:45:08.000Z","updated_at":"2024-08-25T01:11:14.000Z","dependencies_parsed_at":"2023-01-13T12:38:20.908Z","dependency_job_id":null,"html_url":"https://github.com/thymeleaf/thymeleaf-extras-tiles2","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/thymeleaf/thymeleaf-extras-tiles2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thymeleaf%2Fthymeleaf-extras-tiles2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thymeleaf%2Fthymeleaf-extras-tiles2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thymeleaf%2Fthymeleaf-extras-tiles2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thymeleaf%2Fthymeleaf-extras-tiles2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thymeleaf","download_url":"https://codeload.github.com/thymeleaf/thymeleaf-extras-tiles2/tar.gz/refs/heads/2.1-master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thymeleaf%2Fthymeleaf-extras-tiles2/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273722729,"owners_count":25156300,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-31T21:19:11.083Z","updated_at":"2025-09-05T06:31:52.287Z","avatar_url":"https://github.com/thymeleaf.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"\nThymeleaf - Tiles 2 integration module\n======================================\n\n------------------------------------------------------------------------------\n\nStatus\n------\n\nThis is a *thymeleaf extras* module, not a part of the Thymeleaf core (and as\nsuch following its own versioning schema), but fully supported by the \nThymeleaf team.\n\nCurrent versions: \n\n  * **Version 2.1.1.RELEASE** - for Thymeleaf 2.1 (requires 2.1.2+)\n\n\nLicense\n-------\n\nThis software is licensed under the [Apache License 2.0]\n(http://www.apache.org/licenses/LICENSE-2.0.html).\n\n\nRequirements\n------------\n\n  *   Thymeleaf **2.1.2+**\n  *   Apache Tiles 2 version **2.2.1+** (**2.2.2** recommended)\n  *   Web environment (Tiles integration cannot work offline)\n\n\nMaven info\n----------\n\n  *   groupId: `org.thymeleaf.extras`   \n  *   artifactId: \n    *   Main package: `thymeleaf-extras-tiles2`\n    *   Spring 3 integration package: `thymeleaf-extras-tiles2-spring3`\n    *   Spring 4 integration package: `thymeleaf-extras-tiles2-spring4`\n\n\nDistribution packages\n---------------------\n\nDistribution packages (binaries + sources + javadoc) can be downloaded from [SourceForge](http://sourceforge.net/projects/thymeleaf/files/thymeleaf-extras-tiles2/).\n\n\nFeatures\n--------\n\n  *   *(Optional)* **Spring MVC 3** integration\n  *   *(Optional)* **Spring Web Flow 2.3** integration, with AJAX fragment \n      rendering support.\n  *   Use Thymeleaf in your **Tiles definitions**:\n    *   Use Thymeleaf templates.\n    *   Include Thymeleaf templates (or fragments of templates) as attributes.\n    *   Compatible with Tiles definition wildcards (Tiles 2.2.2+).\n\t*   Thymeleaf template/attribute definitions can include selectors \n        (similar to `th:include`/`th:replace`):\n\t  *   By fragment name: `\"template :: fragment\"`\n\t  *   By DOM selector: `\"template :: div#content\"`\n\t  *   Can include Standard Expressions: \n\t      `\"${templateName} :: ${conf.fragName}\"`\n  *   New **`tiles` dialect**:\n    *   `tiles:include` / `tiles:replace` for including Tiles attributes.\n\t*   `tiles:fragment` for signaling fragments to be included as attributes.\n\t*   `tiles:string` for inserting String-type Tiles attributes.\n  *   Enable **Natural templating** in your Tiles markup fragments:\n    *   It allows you to use only specific parts of your templates as *Tiles\n\t    attributes*.\n\t*   You can add markup and styling surrounding those *specific parts* for\n        static prototyping purposes.\n  *   **Mix JSPs and Thymeleaf templates** in the same definition, for better\n      legacy integration / migration.\n    *   Thymeleaf fragment templates see variables defined in higher-level \n\t    containing layout templates.\n    *   JSP fragments see variables defined in higher-level containing \n\t    JSP/Thymeleaf templates. And viceversa.\n\n------------------------------------------------------------------------------\n\n\t\nConfiguration with Spring\n-------------------------\n\n*(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.`)*\n\n\nIn order to use Apache Tiles 2 with Thymeleaf in your Spring MVC application,\nwe will first need to configure our application in the usual way for\nSpring + Thymeleaf applications (*TemplateEngine* bean, *template resolvers*, \netc.), and then create an instance of the `ThymeleafTilesConfigurer` (similar\nto the Spring Tiles configurer for JSP), like:\n\n```xml\n    \u003cbean id=\"tilesConfigurer\" class=\"org.thymeleaf.extras.tiles2.spring3.web.configurer.ThymeleafTilesConfigurer\"\u003e\n      \u003cproperty name=\"definitions\"\u003e\n        \u003clist\u003e\n          \u003cvalue\u003e/WEB-INF/tiles-defs.xml\u003c/value\u003e\n        \u003c/list\u003e\n      \u003c/property\u003e\n    \u003c/bean\u003e\n```\n\nAlso, we will need to configure our Thymeleaf *view resolver* in order to\nuse a specialized Thymeleaf-Tiles2 view class:\n\n```xml\n    \u003cbean id=\"tilesViewResolver\" class=\"org.thymeleaf.spring3.view.ThymeleafViewResolver\"\u003e\n      \u003cproperty name=\"viewClass\" value=\"org.thymeleaf.extras.tiles2.spring3.web.view.ThymeleafTilesView\"/\u003e\n      \u003cproperty name=\"templateEngine\" ref=\"templateEngine\" /\u003e\n    \u003c/bean\u003e\n```\n\n...and finally, add the Tiles dialect to our Template Engine so that we\ncan use the `tiles:*` attributes:\n\n```xml\n    \u003cbean id=\"templateEngine\" class=\"org.thymeleaf.spring3.SpringTemplateEngine\"\u003e\n      ...\n      \u003cproperty name=\"additionalDialects\"\u003e\n        \u003cset\u003e\n          \u003cbean class=\"org.thymeleaf.extras.tiles2.dialect.TilesDialect\"/\u003e\n        \u003c/set\u003e\n      \u003c/property\u003e\n\t  ...\n    \u003c/bean\u003e\n```\n\nAnd that's all! Now we can make our controller methods return Tiles \ndefinition names as view names and everything should work fine.\n\n\n\nConfiguration and usage without Spring\n--------------------------------------\n\nFollowing the standard configuration mechanisms in Tiles 2.2, in order to \nuse Thymeleaf + Tiles in a non-Spring application, we should:\n\n  *   Either configure an `org.thymeleaf.extras.tiles2.web.startup.ThymeleafTilesListener`\n      at our `web.xml`\n  *   ...or configure an `org.thymeleaf.extras.tiles2.web.startup.ThymeleafTilesServlet`,\n      also at our `web.xml`.\n\nBoth these artifacts declare and initialize a Thymeleaf-enabled \n`TilesContainer` instance, which we can access with:\n\n```java\n    final TilesContainer tiles = ServletUtil.getContainer(servletContext);\n```\n    \n...and then execute, specifying the definition to be executed and the \nfollowing sequence of *request items*:\n\n  1.   The Thymeleaf *template engine* (`TemplateEngine`)\n  2.   The Thymeleaf *context* (`IContext`)\n  3.   The `HttpServletRequest`\n  4.   The `HttpServletResponse`\n  5.   The `java.io.Writer` the result should be written to (for example, \n       `response.getWriter()`)\n\nPut as code:\n  \n```java\n    tiles.render(\"myDefinition\", templateEngine, ctx, request, response, writer);\n```\n  \n  \nUsing Thymeleaf in our definition files\n---------------------------------------\n\nUsing Thymeleaf in our definition files (usually called something like\n`tiles-defs.xml`) is easy. These are the key points:\n  \n  *   Thymeleaf is now the default *template type*, instead of JSP.\n    *   We can use `templateType=\"thymeleaf\"` or simply omit `teamplateType`\n        for our templates, and `type=\"thymeleaf\"` for attributes.\n\t*   We can use `templateType=\"jsp\"` for our JSP templates\n\t    (`type=\"jsp\"` for our attributes).\n  *   Thymeleaf value syntax is equivalent to that of  `th:include` and\n      `th:replace` attributes:\n\t  `\"TEMPLATESELECTOR (:: FRAGMENTSELECTOR)?\"`\n\t  *   Template Selector:\n\t    *    Understandable by the template resolvers you configured, just as\n             with any other thymeleaf templates.\n\t\t*    Can use Standard Expressions: `${...}`, `*{...}`, literals,\n\t\toperands, etc. (externalized messages and links are *not allowed*).\n\t  *   Fragment Selector (optional): \n\t    *    Can specify fragments by name (using attribute `tiles:fragment`).\n\t\t*    Can specify DOM Selector (`div#content`)\n\t\t*    Can use Standard Expressions: `${...}`, `*{...}`, literals,\n\t\toperands, etc. (externalized messages and links are *not allowed*).\n  * Tiles definition wildcards (from Tiles 2.2.2) can be used.\n\nA quick example:\n\n```xml\n    \u003ctiles-definitions\u003e\n      ...  \n      \u003cdefinition name=\"main\" template=\"basic_layout\"\u003e\n        \u003cput-attribute name=\"content\"\u003e\n          \u003cdefinition template=\"basic_contentlayout :: content\"\u003e\n            \u003cput-attribute name=\"text\" value=\"main :: text\" /\u003e\n          \u003c/definition\u003e\n        \u003c/put-attribute\u003e\n        \u003cput-attribute name=\"side\" value=\"${config.sideColumnTemplate}\" /\u003e\n      \u003c/definition\u003e\n      ...\n    \u003c/tiles-definitions\u003e\n```\n\n  \nInserting attributes\n--------------------\n\nThe new `tiles` dialect allows us to insert Tiles attributes easily,\njust as we'd do with `th:include`:\n\n```xml\n    \u003chtml xmlns:th=\"http://www.thymeleaf.org\" xmlns:tiles=\"http://www.thymeleaf.org\"\u003e\n      ...\n      \u003cbody\u003e\n\t    ...\n\t    \u003cdiv tiles:include=\"side\"\u003e\n\t\t   some prototyping markup over here...\n\t\t\u003c/div\u003e\n\t    ...\n\t  \u003c/body\u003e\n\t\u003c/html\u003e\n```\n\nThat `tiles:include` will work equivalently to the Standard Dialect's\n`th:include`, only inserting a Tiles attribute by its name (as specified\nin the definition file) instead of another template.\n\nAnother possibility, `tiles:replace`:\n\n```xml\n    \u003cdiv tiles:replace=\"side\"\u003e\n\t   some prototyping markup over here...\n\t\u003c/div\u003e\n```\n\n...will work almost exactly as `tiles:include`, but replacing the\ncontaining `\u003cdiv\u003e` tag with the attribute contents, instead of inserting\nthese contents inside it.\n\nWhat about inserting *string* attributes? Easy:\n\n```xml\n    \u003cspan tiles:string=\"some_string_attribute\"\u003eblah blah\u003c/span\u003e\n```\n\nAnd there's one more attribute, which allows us to (optionally) specify \nwhich part of our template we will be using as a fragment. So:\n\n```xml\n    \u003cdiv tiles:fragment=\"text\"\u003e\n\t   lorem ipsum sic dolor amet blah blah...\n\t\u003c/div\u003e\n```\n\n...will specify a fragment we can use in our definitions with:\n  \n```xml\n    \u003cput-attribute name=\"text\" value=\"main :: text\" /\u003e\n```\n\n  \nMixing Thymeleaf and JSP\n------------------------\n\nFor a better legacy integration and a smoother migration of applications,\nThymeleaf templates and JSPs can be mixed together in Tiles definitions, so\nthat Thymeleaf templates can include JSP attributes, and viceversa.\n\nAnd these fragments in different technologies can even *communicate*, so \nthat they can see the variables that the others define:\n\n  *   Thymeleaf attribute included into Thymeleaf template:\n    *   Attribute can see all local variables (e.g. `th:with`) defined in \n        template.\n  *   Thymeleaf attribute included into JSP template:\n    *   Attribute can see all variables defined (e.g. `\u003cc:set.../\u003e`) with\n        at least *request scope* in the JSP.\n  *   JSP attribute included into Thymeleaf template:\n    *   Attribute can see all local variables (e.g. `th:with`) defined in\n        templates as *request attributes*.\n    \n    \n\n  \nUsing Spring Web Flow\n---------------------\n\nIn order to use Thymeleaf + Tiles in our Spring Web Flow applications, we\nwill first need to modify the definition of our *View Resolver*, so that it\nuses thymeleaf's AJAX-enabled implementation configured to create *View*\ninstances that understand the SpringWebFlow-Tiles combination:\n  \n\n```xml\n    \u003cbean id=\"tilesViewResolver\" class=\"org.thymeleaf.spring3.view.AjaxThymeleafViewResolver\"\u003e\n      \u003cproperty name=\"viewClass\" value=\"org.thymeleaf.extras.tiles2.spring3.web.view.FlowAjaxThymeleafTilesView\"/\u003e\n      \u003cproperty name=\"templateEngine\" ref=\"templateEngine\" /\u003e\n    \u003c/bean\u003e\n```\n\n\n### Scenario\n\n\nLet's say we have a Tiles definition like:\n\n```xml\n    ...\n    \u003cdefinition name=\"order_details\" template=\"orderdet\"\u003e\n      \u003cput-attribute name=\"prog_content\" value=\"progress :: progtext\" /\u003e\n    \u003c/definition\u003e\n\t...\n```\n\nWhich references a *template file* called `orderdet`, which will probably be added\na prefix and a suffix by the Thymeleaf *template resolver*, resulting into something\nlike `/WEB-INF/templates/orderdet.html`. \n\nAlso, we can see how `orderdet` includes a fragment (an *attribute* in Tiles jargon)\ncalled `prog_content`, which resolves to a fragment (specified with `tiles:fragment`)\ncalled `progtext` in template `progress` (probably `/WEB-INF/templates/progress.html`).\n\nLet's see how these two template files could look like. First, the relevant parts\nof `orderdet.html`:\n\n```html\n    \u003c!DOCTYPE html\u003e\n\n    \u003chtml xmlns:th=\"http://www.thymeleaf.org\" xmlns:tiles=\"http://www.thymeleaf.org\"\u003e\n    \n      \u003chead\u003e\n        ...\n        \u003cscript type=\"text/javascript\" th:src=\"@{/resources/dojo/dojo.js}\"\u003e\u003c/script\u003e\n        \u003cscript type=\"text/javascript\" th:src=\"@{/resources/spring/Spring.js}\"\u003e\u003c/script\u003e\n        \u003cscript type=\"text/javascript\" th:src=\"@{/resources/spring/Spring-Dojo.js}\"\u003e\u003c/script\u003e\n      \u003c/head\u003e\n    \n      \u003cbody\u003e\n    \n        ...\n        ...\n    \n        \u003cdiv tiles:replace=\"prog_content\"\u003e\n    \t  Progress of your order: GOOD!\n    \t\u003c/div\u003e\n    \t\n        \u003cform id=\"progressForm\" method=\"post\"\u003e\n          \u003cinput type=\"submit\" id=\"progressButton\" name=\"_eventId_checkprogress\" value=\"Update order progress!\" /\u003e\n        \u003c/form\u003e\n    \n    \n        \u003cscript type=\"text/javascript\"\u003e\n            Spring.addDecoration(\n                    new Spring.AjaxEventDecoration(\n                            {\n                             elementId:'progressButton',\n                             event:'onclick',\n                             formId:'progressForm'\n                            }));\n        \u003c/script\u003e\n    \n      \u003c/body\u003e\n      \n    \u003c/html\u003e\n```\n\n\nThere you can see how we added the required JavaScript libraries from the Spring JS project\n(a part of Spring Web Flow), and then linked an AJAX call for Spring Web Flow's\nevent `checkprogress` to our form button.\n\nThe relevant parts of our `progress.html` file could look like:   \n\n\n```html\n    ...\n    \u003cdiv id=\"progressText\" tiles:fragment=\"progtext\"\u003e\n      Progress of your order \u003cspan th:text=\"${order.percentComplete}\"\u003e34\u003c/span\u003e%\n    \u003c/div\u003e\n\t...\n```\n\nNote that, in order for Spring Web Flow to be able to refresh a markup fragment via AJAX, \nthe specific fragment must be completely enclosed in an element specifying an `id` attribute, \nlike the `\u003cdiv id=\"progressText\" ...\u003e` you see above. Also note that in order to preserve \nthat `id` when it renders, we use `tiles:replace` instead of `tiles:include`.\n\n\nOur flow can now define a transition for updating that fragment as a part of \nthe *Order Details* view (`view-state`): \n\n```xml\n    \u003cview-state id=\"orderdetailsview\" view=\"orderdet\"\u003e\n        \u003ctransition on=\"checkprogress\"\u003e\n          \u003crender fragments=\"prog_content\"/\u003e\n        \u003c/transition\u003e\n    \u003c/view-state\u003e\n```\n\nYour AJAX interactions should now work seamlessly.\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthymeleaf%2Fthymeleaf-extras-tiles2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthymeleaf%2Fthymeleaf-extras-tiles2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthymeleaf%2Fthymeleaf-extras-tiles2/lists"}