Skip to content

Commit 1b2e00d

Browse files
ultraqultraq
committed
Add fluent API for setting options, restore old constructor
1 parent 3f43405 commit 1b2e00d

3 files changed

Lines changed: 39 additions & 34 deletions

File tree

‎thymeleaf-layout-dialect-docs/configuration-options.md‎

Lines changed: 19 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,13 +17,25 @@ On this page
1717
{:toc}
1818

1919

20+
To configure the layout dialect, you have 2 options:
21+
- the constructor with arguments, `LayoutDialect(SortingStrategy, boolean)`
22+
- the fluent API methods `withAutoHeadMerging`, `withExperimentalTitleTokens`,
23+
and `withSortingStrategy`
24+
25+
> Note that the fluent API is currently the only way to enable the `experimentatlTitleTokens`
26+
> setting. With the number of options growing, the constructor might be
27+
> deprecated in favour of the fluent API methods in a future release.
28+
29+
2030
`sortingStrategy`
2131
-----------------
2232

2333
Default: `ApendingStrategy`
2434

2535
```java
2636
new LayoutDialect(new AppendingStrategy());
37+
// or
38+
new LayoutDialect().withSortingStrategy(new AppendingStrategy());
2739
```
2840

2941
Sets how `<head>` elements will be sorted when combined from the layout and
@@ -38,6 +50,8 @@ Default: `true`
3850

3951
```java
4052
new LayoutDialect(null, true);
53+
// or
54+
new LayoutDialect().withAutoHeadMerging(true);
4155
```
4256

4357
Bypass the layout dialect prforming any `<head>` element merging altogether.
@@ -51,13 +65,14 @@ for more details.
5165
Default: `false`
5266

5367
```java
54-
var layoutDialect = new LayoutDialect();
55-
layoutDialect.setExperimentalTitleTokens(false);
68+
new LayoutDialect().withExperimentalTitleTokens(false);
5669
```
5770

5871
An experimental option added in 3.4.0 to use standard Thymeleaf expression
5972
syntax for title patterns and to have access to the title parts in templates as
60-
the variables `layoutDialectLayoutTitle` and `layoutDialectContentTitle`.
73+
the variables `layoutDialectLayoutTitle` and `layoutDialectContentTitle` (the
74+
names are pretty verbose but I want to avoid any potential clashes while I
75+
either come up with new ones or some way to configure the names).
6176

6277
So instead of the example in [Processors > title-pattern]({{ site.baseurl }}{% link processors/title-pattern.md %})
6378
for setting what the final title will look like:
@@ -69,7 +84,7 @@ for setting what the final title will look like:
6984
You can do this instead:
7085

7186
```html
72-
<title layout:title="|${`layoutDialectLayoutTitle} - ${layoutDialectContentTitle}|">...</title>
87+
<title layout:title="|${layoutDialectLayoutTitle} - ${layoutDialectContentTitle}|">...</title>
7388
```
7489

7590
The title parts will also be made available anywhere in the template as the

‎thymeleaf-layout-dialect/source/nz/net/ultraq/thymeleaf/layoutdialect/LayoutDialect.groovy‎

Lines changed: 19 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -32,67 +32,57 @@ import org.thymeleaf.processor.IProcessor
3232
import org.thymeleaf.standard.processor.StandardXmlNsTagProcessor
3333
import org.thymeleaf.templatemode.TemplateMode
3434

35+
import groovy.transform.builder.Builder
36+
import groovy.transform.builder.SimpleStrategy
37+
3538
/**
3639
* A dialect for Thymeleaf that lets you build layouts and reusable templates in
37-
* order to improve code reuse
40+
* order to improve code reuse.
41+
* <p>
42+
* To configure the layout dialect, you have 2 options:
43+
* <ul>
44+
* <li>the constructor with arguments {@code LayoutDialect(SortingStrategy, boolean)}</li>
45+
* <li>the fluent API methods {@link #withAutoHeadMerging}, {@link #withExperimentalTitleTokens},
46+
* and {@link #withSortingStrategy}</li>
47+
* </ul>
48+
* <p>Note that the fluent API is currently the only way to enable the {@code experimentatlTitleTokens}
49+
* setting. With the number of options growing, the constructor might be
50+
* deprecated in favour of the fluent API methods.
3851
*
3952
* @author Emanuel Rabina
4053
*/
54+
@Builder(builderStrategy = SimpleStrategy, prefix = 'with')
4155
class LayoutDialect extends AbstractProcessorDialect {
4256

4357
static final String DIALECT_NAME = 'Layout'
4458
static final String DIALECT_PREFIX = 'layout'
4559
static final int DIALECT_PRECEDENCE = 10
4660

47-
SortingStrategy sortingStrategy = new AppendingStrategy()
61+
private SortingStrategy sortingStrategy = new AppendingStrategy()
4862

4963
/**
5064
* Experimental option, set to {@code false} to skip the automatic merging
5165
* of an HTML {@code <head>} section.
5266
*/
53-
boolean autoHeadMerging = true
67+
private boolean autoHeadMerging = true
5468

5569
/**
5670
* Experimental option, set to {@code true} to use standard Thymeleaf
5771
* expression syntax for title patterns and to have access to the title parts
5872
* in templates as the variables {@code layoutDialectContentTitle} and
5973
* {@code layoutDialectLayoutTitle}.
6074
*/
61-
boolean experimentalTitleTokens = false
62-
63-
/**
64-
* Constructor, create the layout dialect in the default configuration.
65-
*/
66-
LayoutDialect() {
67-
68-
this(new AppendingStrategy(), true)
69-
}
70-
71-
/**
72-
* Constructor, create the layout dialect with the specified {@code <head>}
73-
* sorting strategy.
74-
*
75-
* @deprecated
76-
* Use the appropriate setters to configure the layout dialect instead.
77-
*/
78-
@Deprecated
79-
LayoutDialect(SortingStrategy sortingStrategy) {
80-
81-
this(sortingStrategy, true)
82-
}
75+
private boolean experimentalTitleTokens = false
8376

8477
/**
8578
* Constructor, configure the layout dialect.
8679
*
87-
* @deprecated
88-
* Use the appropriate setters to configure the layout dialect instead.
8980
* @param sortingStrategy
9081
* @param autoHeadMerging
9182
* Experimental option, set to {@code false} to skip the automatic merging
9283
* of an HTML {@code <head>} section.
9384
*/
94-
@Deprecated
95-
LayoutDialect(SortingStrategy sortingStrategy, boolean autoHeadMerging) {
85+
LayoutDialect(SortingStrategy sortingStrategy = new AppendingStrategy(), boolean autoHeadMerging = true) {
9686

9787
super(DIALECT_NAME, DIALECT_PREFIX, DIALECT_PRECEDENCE)
9888

‎thymeleaf-layout-dialect/test/nz/net/ultraq/thymeleaf/layoutdialect/decorators/html/TitleTokens.groovy‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ class TitleTokens extends Specification {
4848
testExecutor.with {
4949
dialects = [
5050
new StandardDialect(),
51-
new LayoutDialect(experimentalTitleTokens: true)
51+
new LayoutDialect().withExperimentalTitleTokens(true)
5252
]
5353
reporter = new JUnitTestReporter(new ConsoleTestReporter())
5454
}

0 commit comments

Comments
 (0)