Migrating to 2.0
The biggest change between 1.x and 2.x of the layout dialect is that 2.x is a rewrite of the layout dialect to support Thymeleaf 3. Thymeleaf 3 is largely backwards compatible with Thymeleaf 2 templates, and so the layout dialect has gone out of its way to be backwards compatible too.
As such, everything in this guide is completely optional. However, if you want to future-proof your code and keep your logs clean of deprecation warnings, then follow the steps in this guide.
decorator processor renamed to
While the layout dialect does perform decoration as per the decorator pattern, throughout 1.x it incorrectly identified the layout/parent template as the decorator, when instead, according to the design pattern, the extension (content template in this case) is the decorator.
This change is simply a rename of the
data-layout-decorate so that the template being
specified is the one being decorated, not the decorator, plus an overhaul of the
documentation to fix this inconsistency.
$DECORATOR_TITLE renamed to
A consequence of the above is that the special tokens in the
processor were also incorrectly named, and so a new token has been introduced to
Thymeleaf 3 deprecated the
data-th-include processor and
data-th-insert processor as its replacement.
Because the layout dialect patterned the naming of its template inclusion
processors after Thymeleaf, it did the same - deprecating
Thymeleaf 3 fragment processors
In 1.x of the layout dialect, it used the same template/fragment specifiers as
Thymeleaf 2, which was basically string paths with a special
:: separator. In
Thymeleaf 3, these specifiers have been formalized into "fragment expressions",
and have a new syntax which surrounds the old one with
The layout dialect now favours the use of these fragment expressions for all processors that pick a template or fragment.