diff --git a/library/src/main/java/j2html/Config.java b/library/src/main/java/j2html/Config.java index fbac933d..d015a6c4 100644 --- a/library/src/main/java/j2html/Config.java +++ b/library/src/main/java/j2html/Config.java @@ -7,14 +7,14 @@ import j2html.utils.Minifier; import j2html.utils.TextEscaper; -import java.util.Collections; - public class Config { /** * Change this to configure text-escaping * For example, to disable escaping, do {@code Config.textEscaper = text -> text;} + * @deprecated in favor of {@link j2html.rendering.DefaultHtmlBuilder#withTextEscaper(TextEscaper)} */ + @Deprecated public static TextEscaper textEscaper = EscapeUtil::escape; /** * Change this to configure css-minification. @@ -29,14 +29,18 @@ public class Config { /** * Change this to configure enable/disable closing empty tags * The default is to NOT close them + * @deprecated in favor of {@link j2html.rendering.DefaultHtmlBuilder#withEmptyTagsClosed(boolean)} */ + @Deprecated public static boolean closeEmptyTags = false; - private static String FOUR_SPACES = " "; + /** * Change this to configure indentation when rendering formatted html * The default is four spaces + * @deprecated in favor of {@link j2html.rendering.DefaultHtmlBuilder#withIndenter(Indenter)} */ - public static Indenter indenter = (level, text) -> String.join("", Collections.nCopies(level, FOUR_SPACES)) + text; + @Deprecated + public static Indenter indenter = Indenter.defaults(); private TextEscaper _textEscaper; @@ -93,6 +97,10 @@ public Indenter indenter() { return _indenter; } + /** + * @deprecated in favor of {@link j2html.rendering.DefaultHtmlBuilder#withTextEscaper(TextEscaper)} + */ + @Deprecated public Config withTextEscaper(TextEscaper textEscaper){ Config copy = new Config(this); copy._textEscaper = textEscaper; @@ -111,12 +119,20 @@ public Config withJsMinifier(Minifier jsMinifier){ return copy; } + /** + * @deprecated in favor of {@link j2html.rendering.DefaultHtmlBuilder#withEmptyTagsClosed(boolean)} + */ + @Deprecated public Config withEmptyTagsClosed(boolean closeEmptyTags){ Config copy = new Config(this); copy._closeEmptyTags = closeEmptyTags; return copy; } + /** + * @deprecated in favor of {@link j2html.rendering.DefaultHtmlBuilder#withIndenter(Indenter)} + */ + @Deprecated public Config withIndenter(Indenter indenter){ Config copy = new Config(this); copy._indenter = indenter; @@ -128,7 +144,7 @@ public Config withIndenter(Indenter indenter){ CSSMin::compressCss, JSMin::compressJs, false, - (level, text) -> String.join("", Collections.nCopies(level, FOUR_SPACES)) + text + Indenter.defaults() ); public static final Config defaults() { diff --git a/library/src/main/java/j2html/rendering/DefaultHtmlBuilder.java b/library/src/main/java/j2html/rendering/DefaultHtmlBuilder.java new file mode 100644 index 00000000..c98fc35f --- /dev/null +++ b/library/src/main/java/j2html/rendering/DefaultHtmlBuilder.java @@ -0,0 +1,125 @@ +package j2html.rendering; + +import j2html.Config; +import j2html.utils.Indenter; +import j2html.utils.TextEscaper; + +/** + * Default entry point for constructing an {@link HtmlBuilder} instance. + * Examples: + * + * 
+ * HtmlTag html = ...
+ * Appendable out = ...
+ * html.render(DefaultHtmlBuilder.into(out));
+ *
+ * + * will write the HTML into {@code out} without any line breaks or indentation + * using the default settings of {@link Config#defaults()}. + *

+ * + * 

+ * html.render(DefaultHtmlBuilder.indented(true).into(out));
+ *
+ * + * will write the HTML into {@code out} with line breaks and indentation using + * the default settings and the indenter {@link Indenter#defaults()}. + *

+ * + * 

+ * html.render(DefaultHtmlBuilder.indented(true).withIndenter(Indenter.with("\t")).into(out));
+ *
+ * + * will use the tab character {@code \t} for indentation. + *

+ * A different {@link TextEscaper} can be provided using + * {@link #withTextEscaper(TextEscaper)}, a different setting for the closing of + * empty tags can be applied with {@link #withEmptyTagsClosed(boolean)}. + *

+ * There is also a convenience method {@link #inMemory()} for rendering the HTML + * into a String: + * + * 

+ * String text = html.render(DefaultHtmlBuilder.with...().inMemory()).toString();
+ *
+ */ +public class DefaultHtmlBuilder { + + public static HtmlBuilder into(A out) { + return new Configurer().into(out); + } + + public static HtmlBuilder inMemory() { + return into(new StringBuilder()); + } + + public static Configurer indented(boolean indented) { + return new Configurer().indented(indented); + } + + public static Configurer withEmptyTagsClosed(boolean closeTags) { + return new Configurer().withEmptyTagsClosed(closeTags); + } + + public static Configurer withTextEscaper(TextEscaper textEscaper) { + return new Configurer().withTextEscaper(textEscaper); + } + + public static Configurer withIndenter(Indenter indenter) { + return new Configurer().withIndenter(indenter); + } + + /** + * @deprecated will be removed in a future version + */ + @Deprecated + public static Configurer withConfig(Config config) { + return new Configurer(config); + } + + public static class Configurer { + private boolean indented; + private Config config; + + private Configurer() { + this(Config.defaults()); + } + + private Configurer(Config config) { + this.config = config; + this.indented = false; + } + + @SuppressWarnings("deprecation") + public HtmlBuilder into(A out) { + return this.indented ? IndentedHtml.into(out, this.config) : FlatHtml.into(out, this.config); + } + + public HtmlBuilder inMemory() { + return into(new StringBuilder()); + } + + public Configurer indented(boolean indented) { + this.indented = indented; + return this; + } + + @SuppressWarnings("deprecation") + public Configurer withEmptyTagsClosed(boolean closeTags) { + this.config = this.config.withEmptyTagsClosed(closeTags); + return this; + } + + @SuppressWarnings("deprecation") + public Configurer withTextEscaper(TextEscaper textEscaper) { + this.config = this.config.withTextEscaper(textEscaper); + return this; + } + + @SuppressWarnings("deprecation") + public Configurer withIndenter(Indenter indenter) { + this.config = this.config.withIndenter(indenter); + return this; + } + } +} diff --git a/library/src/main/java/j2html/rendering/FlatHtml.java b/library/src/main/java/j2html/rendering/FlatHtml.java index f674d02d..2d815283 100644 --- a/library/src/main/java/j2html/rendering/FlatHtml.java +++ b/library/src/main/java/j2html/rendering/FlatHtml.java @@ -9,7 +9,10 @@ * Composes HTML without any extra line breaks or indentation. * * @param The type of the Appendable to which HTML will be appended. + * + * @deprecated in favor of {@link DefaultHtmlBuilder} */ +// should be made package private in 2.0 public class FlatHtml implements HtmlBuilder { /** @@ -20,6 +23,7 @@ public class FlatHtml implements HtmlBuilder { * @param The type of the Appendable to which HTML will be appended. * @return An HtmlBuilder for flat HTML. */ + @Deprecated public static final FlatHtml into(T out) { return new FlatHtml<>(out, Config.defaults()); } @@ -43,6 +47,7 @@ public static final FlatHtml into(T out, Config config * * @return An HtmlBuilder for flat HTML. */ + @Deprecated public static final FlatHtml inMemory() { return into(new StringBuilder()); } @@ -53,6 +58,7 @@ public static final FlatHtml inMemory() { * @param config The Config which will specify text escapement, tag closing, etc. * @return An HtmlBuilder for flat HTML. */ + @Deprecated public static final FlatHtml inMemory(Config config) { return into(new StringBuilder(), config); } diff --git a/library/src/main/java/j2html/rendering/HtmlBuilder.java b/library/src/main/java/j2html/rendering/HtmlBuilder.java index c1490027..fff2a34f 100644 --- a/library/src/main/java/j2html/rendering/HtmlBuilder.java +++ b/library/src/main/java/j2html/rendering/HtmlBuilder.java @@ -7,6 +7,9 @@ * Appendable, and support appending HTML-specific character * sequences to that Appendable. *

+ * This library provides configurable implementations for flat and + * indented HTML, which can be obtained from the {@link DefaultHtmlBuilder}. + *

* Note: HtmlBuilder extends Appendable for compatibility with * previous version of this library. This extension will probably be * removed in the future, so avoid relying on the deprecated methods diff --git a/library/src/main/java/j2html/rendering/IndentedHtml.java b/library/src/main/java/j2html/rendering/IndentedHtml.java index 53c36f4a..1000dd9b 100644 --- a/library/src/main/java/j2html/rendering/IndentedHtml.java +++ b/library/src/main/java/j2html/rendering/IndentedHtml.java @@ -12,7 +12,10 @@ * Composes HTML with lines breaks and indentation between tags and text. * * @param The type of the Appendable to which HTML will be appended. + * + * @deprecated in favor of {@link DefaultHtmlBuilder} */ +// should be made package private in 2.0 public class IndentedHtml implements HtmlBuilder { /** @@ -23,6 +26,7 @@ public class IndentedHtml implements HtmlBuilder { * @param The type of the Appendable to which HTML will be appended. * @return An HtmlBuilder for indented HTML. */ + @Deprecated public static final IndentedHtml into(T out) { return new IndentedHtml<>(out, Config.defaults()); } @@ -46,6 +50,7 @@ public static final IndentedHtml into(T out, Config co * * @return An HtmlBuilder for indented HTML. */ + @Deprecated public static final IndentedHtml inMemory() { return into(new StringBuilder()); } @@ -57,6 +62,7 @@ public static final IndentedHtml inMemory() { * @param config The Config which will specify indentation, text escapement, tag closing, etc. * @return An HtmlBuilder for indented HTML. */ + @Deprecated public static final IndentedHtml inMemory(Config config) { return into(new StringBuilder(), config); } diff --git a/library/src/main/java/j2html/tags/ContainerTag.java b/library/src/main/java/j2html/tags/ContainerTag.java index 5fc688b0..900d6dae 100644 --- a/library/src/main/java/j2html/tags/ContainerTag.java +++ b/library/src/main/java/j2html/tags/ContainerTag.java @@ -2,11 +2,9 @@ import j2html.Config; import j2html.attributes.Attribute; -import j2html.rendering.TagBuilder; -import j2html.rendering.FlatHtml; +import j2html.rendering.DefaultHtmlBuilder; import j2html.rendering.HtmlBuilder; -import j2html.rendering.IndentedHtml; - +import j2html.rendering.TagBuilder; import java.io.IOException; import java.util.ArrayList; import java.util.List; @@ -145,9 +143,10 @@ public int getNumChildren() { * * @return the rendered and formatted string */ + @SuppressWarnings("deprecation") public String renderFormatted() { try { - return render(IndentedHtml.into(new StringBuilder(), Config.global())).toString(); + return render(DefaultHtmlBuilder.withConfig(Config.global()).indented(true).inMemory()).toString(); }catch (IOException e) { throw new RuntimeException(e.getMessage(), e); } @@ -179,7 +178,7 @@ public A render(HtmlBuilder builder, Object model) thr public void renderModel(Appendable writer, Object model) throws IOException { HtmlBuilder builder = (writer instanceof HtmlBuilder) ? (HtmlBuilder) writer - : FlatHtml.into(writer, Config.global()); + : DefaultHtmlBuilder.withConfig(Config.global()).into(writer); render(builder, model); } diff --git a/library/src/main/java/j2html/tags/EmptyTag.java b/library/src/main/java/j2html/tags/EmptyTag.java index e2b4ed02..eebf81d3 100644 --- a/library/src/main/java/j2html/tags/EmptyTag.java +++ b/library/src/main/java/j2html/tags/EmptyTag.java @@ -2,10 +2,9 @@ import j2html.Config; import j2html.attributes.Attribute; -import j2html.rendering.TagBuilder; -import j2html.rendering.FlatHtml; +import j2html.rendering.DefaultHtmlBuilder; import j2html.rendering.HtmlBuilder; - +import j2html.rendering.TagBuilder; import java.io.IOException; public class EmptyTag> extends Tag { @@ -35,7 +34,7 @@ public A render(HtmlBuilder builder, Object model) thr public void renderModel(Appendable writer, Object model) throws IOException { HtmlBuilder builder = (writer instanceof HtmlBuilder) ? (HtmlBuilder) writer - : FlatHtml.into(writer, Config.global()); + : DefaultHtmlBuilder.withConfig(Config.global()).into(writer); render(builder, model); } diff --git a/library/src/main/java/j2html/tags/Renderable.java b/library/src/main/java/j2html/tags/Renderable.java index 67ea012a..10fd99fe 100644 --- a/library/src/main/java/j2html/tags/Renderable.java +++ b/library/src/main/java/j2html/tags/Renderable.java @@ -1,9 +1,8 @@ package j2html.tags; import j2html.Config; -import j2html.rendering.FlatHtml; +import j2html.rendering.DefaultHtmlBuilder; import j2html.rendering.HtmlBuilder; - import java.io.IOException; import java.io.UncheckedIOException; @@ -42,9 +41,10 @@ default T render(HtmlBuilder builder) throws IOExcepti * Create a StringBuilder and use it to render the Renderable and it's * children */ + @SuppressWarnings("deprecation") default String render() { try { - return render(FlatHtml.into(new StringBuilder(), Config.global())).toString(); + return render(DefaultHtmlBuilder.withConfig(Config.global()).inMemory()).toString(); } catch (IOException e) { throw new UncheckedIOException(e); } @@ -60,7 +60,7 @@ default void render(Appendable writer) throws IOException { if (writer instanceof HtmlBuilder) { render((HtmlBuilder) writer); } else { - render(FlatHtml.into(writer, Config.global())); + render(DefaultHtmlBuilder.withConfig(Config.global()).into(writer)); } } diff --git a/library/src/main/java/j2html/tags/Text.java b/library/src/main/java/j2html/tags/Text.java index 8a512ec4..71a4dfc7 100644 --- a/library/src/main/java/j2html/tags/Text.java +++ b/library/src/main/java/j2html/tags/Text.java @@ -1,9 +1,8 @@ package j2html.tags; import j2html.Config; -import j2html.rendering.FlatHtml; +import j2html.rendering.DefaultHtmlBuilder; import j2html.rendering.HtmlBuilder; - import java.io.IOException; public class Text extends DomContent { @@ -25,7 +24,7 @@ public T render(HtmlBuilder builder, Object model) thr public void renderModel(Appendable writer, Object model) throws IOException { HtmlBuilder builder = (writer instanceof HtmlBuilder) ? (HtmlBuilder) writer - : FlatHtml.into(writer, Config.global()); + : DefaultHtmlBuilder.withConfig(Config.global()).into(writer); render(builder, model); } diff --git a/library/src/main/java/j2html/tags/UnescapedText.java b/library/src/main/java/j2html/tags/UnescapedText.java index 55674f36..5bb8474a 100644 --- a/library/src/main/java/j2html/tags/UnescapedText.java +++ b/library/src/main/java/j2html/tags/UnescapedText.java @@ -1,9 +1,8 @@ package j2html.tags; import j2html.Config; -import j2html.rendering.FlatHtml; +import j2html.rendering.DefaultHtmlBuilder; import j2html.rendering.HtmlBuilder; - import java.io.IOException; public class UnescapedText extends DomContent { @@ -25,7 +24,7 @@ public T render(HtmlBuilder builder, Object model) thr public void renderModel(Appendable writer, Object model) throws IOException { HtmlBuilder builder = (writer instanceof HtmlBuilder) ? (HtmlBuilder) writer - : FlatHtml.into(writer, Config.global()); + : DefaultHtmlBuilder.withConfig(Config.global()).into(writer); render(builder, model); } diff --git a/library/src/main/java/j2html/utils/Indenter.java b/library/src/main/java/j2html/utils/Indenter.java index 379e6e9f..54580967 100644 --- a/library/src/main/java/j2html/utils/Indenter.java +++ b/library/src/main/java/j2html/utils/Indenter.java @@ -1,6 +1,17 @@ package j2html.utils; +import java.util.Collections; + @FunctionalInterface public interface Indenter { + String indent(int level, String text); + + static Indenter with(String indentString) { + return (level, text) -> String.join("", Collections.nCopies(level, indentString)) + text; + } + + static Indenter defaults() { + return with(" "); + } } diff --git a/library/src/test/java/j2html/rendering/RenderingCompatabilityTest.java b/library/src/test/java/j2html/rendering/RenderingCompatabilityTest.java index e8fb5a35..1adcd69c 100644 --- a/library/src/test/java/j2html/rendering/RenderingCompatabilityTest.java +++ b/library/src/test/java/j2html/rendering/RenderingCompatabilityTest.java @@ -68,7 +68,7 @@ public void renderModel(Appendable writer, Object model) throws IOException { // Rendering with an HtmlBuilder defers to the original methods. assertThat( - dom.render(FlatHtml.inMemory(), "success").toString(), + dom.render(DefaultHtmlBuilder.inMemory(), "success").toString(), is("

success
") ); } @@ -85,19 +85,19 @@ public void client_classes_which_implement_attribute_rendering_continue_to_work_ assertThat(stringBuilder.toString(), is(" mock=\"null\"")); assertThat( - mock.render(FlatHtml.inMemory(), "success").toString(), + mock.render(DefaultHtmlBuilder.inMemory(), "success").toString(), is(" mock=\"success\"") ); // In empty tags. assertThat( - input().attr(mock).render(FlatHtml.inMemory(), "success").toString(), + input().attr(mock).render(DefaultHtmlBuilder.inMemory(), "success").toString(), is("") ); // In container tags. assertThat( - div().attr(mock).render(FlatHtml.inMemory(), "success").toString(), + div().attr(mock).render(DefaultHtmlBuilder.inMemory(), "success").toString(), is("
") ); } diff --git a/library/src/test/java/j2html/tags/TextTest.java b/library/src/test/java/j2html/tags/TextTest.java index 359a185a..6b88b150 100644 --- a/library/src/test/java/j2html/tags/TextTest.java +++ b/library/src/test/java/j2html/tags/TextTest.java @@ -1,10 +1,8 @@ package j2html.tags; -import j2html.rendering.FlatHtml; -import j2html.rendering.IndentedHtml; -import org.junit.Test; - +import j2html.rendering.DefaultHtmlBuilder; import java.io.IOException; +import org.junit.Test; import static j2html.TagCreator.rawHtml; import static j2html.TagCreator.text; @@ -15,13 +13,13 @@ public class TextTest { @Test public void null_text_is_rendered_as_a_string_literal() throws IOException { - assertThat(text(null).render(FlatHtml.inMemory()).toString(), is("null")); - assertThat(text(null).render(IndentedHtml.inMemory()).toString(), is("null\n")); + assertThat(text(null).render(DefaultHtmlBuilder.inMemory()).toString(), is("null")); + assertThat(text(null).render(DefaultHtmlBuilder.indented(true).inMemory()).toString(), is("null\n")); } @Test public void null_unescaped_text_is_rendered_as_a_string_literal() throws IOException { - assertThat(rawHtml(null).render(FlatHtml.inMemory()).toString(), is("null")); - assertThat(rawHtml(null).render(IndentedHtml.inMemory()).toString(), is("null\n")); + assertThat(rawHtml(null).render(DefaultHtmlBuilder.inMemory()).toString(), is("null")); + assertThat(rawHtml(null).render(DefaultHtmlBuilder.indented(true).inMemory()).toString(), is("null\n")); } }