RFR: JDK-8240697: convert builders to high-level Content blocks

[Jonathan Gibbons]

Responding to the comment about the conventions for building HTML trees ...

My experience (including in other projects that generate HTML) is that 
the "After:" style you propose works well as long as it is not too 
deeply nested.

It does not work so well when there is conditional content or iterative 
content ... and as much as I have come to appreciate streams, I believe 
they can be over-(ab)used in trying to force everything into a more 
functional paradigm.

When the code pattern does not work well, I find I prefer to make trees 
"bottom up", building the leaf components, before assembling them in a 
single step into a larger component.   This is in comparison to creating 
an empty enclosing component and then building and adding the individual 
child components.

And, all of these are better that some of the weirder patterns that 
exist in the code today.

-- Jon

On 03/09/2020 04:38 AM, Pavel Rappo wrote:
> 2. Is it just me, or it is indeed hard to comprehend the structure of the HTML
> being composed in some of the places? Maybe we could think of slightly bending
> the code formatting rules for the sake of readability where practical?
>
> Before:
>
>      HtmlTree flexHeader = HtmlTree.HEADER()
>              .setStyle(HtmlStyle.flexHeader)
>              .add(header);
>
>      HtmlTree flexContent = HtmlTree.DIV(HtmlStyle.flexContent)
>              .add(HtmlTree.MAIN().add(mainContents))
>              .add(footer);
>
>      return HtmlTree.DIV(HtmlStyle.flexBox)
>              .add(flexHeader)
>              .add(flexContent);
>
> After:
>
>      return DIV(HtmlStyle.flexBox,
>                 HEADER(HtmlStyle.flexHeader
>                     header
>                 ),
>                 DIV(HtmlStyle.flexContent,
>                     MAIN(mainContents),
>                     footer
>                 )
>             );
>
> Before:
>
>      Content li = HtmlTree.LI(HtmlStyle.blockList, table);
>      Content ul = HtmlTree.UL(HtmlStyle.blockList, li);
>      contentTree.add(ul);
>
> After:
>
>      contentTree.add(
>          UL(HtmlStyle.blockList,
>              LI(HtmlStyle.blockList, table)
>          )
>      );
>
> One added benefit of structuring HTML generation like that is that the resulting
> code is less error-prone. When no intermediate reference is created, it is much
> harder to pass a single "Content" into multiple places (which would be a bug).