Add fluent API for setting options, restore old constructor

ultraq · Jan 27, 2025 · 1b2e00d · 1b2e00d
1 parent 3f43405
commit 1b2e00d
Show file tree

Hide file tree

Showing 3 changed files with 39 additions and 34 deletions.
diff --git a/thymeleaf-layout-dialect-docs/configuration-options.md b/thymeleaf-layout-dialect-docs/configuration-options.md
@@ -17,13 +17,25 @@ On this page
 {:toc}
 
 
+To configure the layout dialect, you have 2 options:
+ - the constructor with arguments, `LayoutDialect(SortingStrategy, boolean)`
+ - the fluent API methods `withAutoHeadMerging`, `withExperimentalTitleTokens`,
+   and `withSortingStrategy`
+
+> Note that the fluent API is currently the only way to enable the `experimentatlTitleTokens`
+> setting.  With the number of options growing, the constructor might be
+> deprecated in favour of the fluent API methods in a future release.
+
+
 `sortingStrategy`
 -----------------
 
 Default: `ApendingStrategy`
 
 ```java
 new LayoutDialect(new AppendingStrategy());
+// or
+new LayoutDialect().withSortingStrategy(new AppendingStrategy());
 ```
 
 Sets how `<head>` elements will be sorted when combined from the layout and
@@ -38,6 +50,8 @@ Default: `true`
 
 ```java
 new LayoutDialect(null, true);
+// or
+new LayoutDialect().withAutoHeadMerging(true);
 ```
 
 Bypass the layout dialect prforming any `<head>` element merging altogether.
@@ -51,13 +65,14 @@ for more details.
 Default: `false`
 
 ```java
-var layoutDialect = new LayoutDialect();
-layoutDialect.setExperimentalTitleTokens(false);
+new LayoutDialect().withExperimentalTitleTokens(false);
 ```
 
 An experimental option added in 3.4.0 to use standard Thymeleaf expression
 syntax for title patterns and to have access to the title parts in templates as
-the variables `layoutDialectLayoutTitle` and `layoutDialectContentTitle`.
+the variables `layoutDialectLayoutTitle` and `layoutDialectContentTitle` (the
+names are pretty verbose but I want to avoid any potential clashes while I
+either come up with new ones or some way to configure the names).
 
 So instead of the example in [Processors > title-pattern]({{ site.baseurl }}{% link processors/title-pattern.md %})
 for setting what the final title will look like:
@@ -69,7 +84,7 @@ for setting what the final title will look like:
 You can do this instead:
 
 ```html
-<title layout:title="|${`layoutDialectLayoutTitle} - ${layoutDialectContentTitle}|">...</title>
+<title layout:title="|${layoutDialectLayoutTitle} - ${layoutDialectContentTitle}|">...</title>
 ```
 
 The title parts will also be made available anywhere in the template as the

diff --git a/thymeleaf-layout-dialect/source/nz/net/ultraq/thymeleaf/layoutdialect/LayoutDialect.groovy b/thymeleaf-layout-dialect/source/nz/net/ultraq/thymeleaf/layoutdialect/LayoutDialect.groovy
@@ -32,67 +32,57 @@ import org.thymeleaf.processor.IProcessor
 import org.thymeleaf.standard.processor.StandardXmlNsTagProcessor
 import org.thymeleaf.templatemode.TemplateMode
 
+import groovy.transform.builder.Builder
+import groovy.transform.builder.SimpleStrategy
+
 /**
  * A dialect for Thymeleaf that lets you build layouts and reusable templates in
- * order to improve code reuse
+ * order to improve code reuse.
+ * <p>
+ * To configure the layout dialect, you have 2 options:
+ * <ul>
+ *   <li>the constructor with arguments {@code LayoutDialect(SortingStrategy, boolean)}</li>
+ *   <li>the fluent API methods {@link #withAutoHeadMerging}, {@link #withExperimentalTitleTokens},
+ *    and {@link #withSortingStrategy}</li>
+ * </ul>
+ * <p>Note that the fluent API is currently the only way to enable the {@code experimentatlTitleTokens}
+ * setting.  With the number of options growing, the constructor might be
+ * deprecated in favour of the fluent API methods.
  *
  * @author Emanuel Rabina
  */
+@Builder(builderStrategy = SimpleStrategy, prefix = 'with')
 class LayoutDialect extends AbstractProcessorDialect {
 
 	static final String DIALECT_NAME = 'Layout'
 	static final String DIALECT_PREFIX = 'layout'
 	static final int DIALECT_PRECEDENCE = 10
 
-	SortingStrategy sortingStrategy = new AppendingStrategy()
+	private SortingStrategy sortingStrategy = new AppendingStrategy()
 
 	/**
 	 * Experimental option, set to {@code false} to skip the automatic merging
 	 * of an HTML {@code <head>} section.
 	 */
-	boolean autoHeadMerging = true
+	private boolean autoHeadMerging = true
 
 	/**
 	 * Experimental option, set to {@code true} to use standard Thymeleaf
 	 * expression syntax for title patterns and to have access to the title parts
 	 * in templates as the variables {@code layoutDialectContentTitle} and
 	 * {@code layoutDialectLayoutTitle}.
 	 */
-	boolean experimentalTitleTokens = false
-
-	/**
-	 * Constructor, create the layout dialect in the default configuration.
-	 */
-	LayoutDialect() {
-
-		this(new AppendingStrategy(), true)
-	}
-
-	/**
-	 * Constructor, create the layout dialect with the specified {@code <head>}
-	 * sorting strategy.
-	 *
-	 * @deprecated
-	 *   Use the appropriate setters to configure the layout dialect instead.
-	 */
-	@Deprecated
-	LayoutDialect(SortingStrategy sortingStrategy) {
-
-		this(sortingStrategy, true)
-	}
+	private boolean experimentalTitleTokens = false
 
 	/**
 	 * Constructor, configure the layout dialect.
 	 *
-	 * @deprecated
-	 *   Use the appropriate setters to configure the layout dialect instead.
 	 * @param sortingStrategy
 	 * @param autoHeadMerging
 	 *   Experimental option, set to {@code false} to skip the automatic merging
 	 *   of an HTML {@code <head>} section.
 	 */
-	@Deprecated
-	LayoutDialect(SortingStrategy sortingStrategy, boolean autoHeadMerging) {
+	LayoutDialect(SortingStrategy sortingStrategy = new AppendingStrategy(), boolean autoHeadMerging = true) {
 
 		super(DIALECT_NAME, DIALECT_PREFIX, DIALECT_PRECEDENCE)
 

diff --git a/...out-dialect/test/nz/net/ultraq/thymeleaf/layoutdialect/decorators/html/TitleTokens.groovy b/...out-dialect/test/nz/net/ultraq/thymeleaf/layoutdialect/decorators/html/TitleTokens.groovy
@@ -48,7 +48,7 @@ class TitleTokens extends Specification {
 		testExecutor.with {
 			dialects = [
 				new StandardDialect(),
-				new LayoutDialect(experimentalTitleTokens: true)
+				new LayoutDialect().withExperimentalTitleTokens(true)
 			]
 			reporter = new JUnitTestReporter(new ConsoleTestReporter())
 		}