Alternative approach to rendering

[jwstegemann]

Motivation

• There were three bugs that dealt with rendering problems, so obviously the current solution was not good / mature enough yet:
  • mount-point problems #531
  • nested render on tracker() throws UnsupportedOperationException in Browser #405
  • Missing placeholder when using renderEach() on same level #346
  • Popups do not work in Modals #538
• The code was rather complex
• The mechanism itself was rather cumbersome, as there was some placeholder tag rendered into the DOM, which would be replaced by the actual flow evaluated DOM fragement.

All this was only necessary to enable to mix mount-points with static DOM tags below the same parent node.

→ Optimization only for one edge case! → not a good idea!

New Solution

The new rendering is based upon mount-points, that are always represented by a dedicated tag within the DOM tree! The dynamic content is then rendered below this mount-point-tag. This is true for all render variations, so for render as well as for renderEach variants.

To be more precise, there is one div-tag inserted at the location where the render method is called:

// within some RenderContext
section {
    flowOf("Hello, World!").render {
        span { +it }
    }
}

This will result in the following DOM structure:

<section>
  <div class="mount-point" data-mount-point>
    <span>Hello World</span>
  </div>
</section>

The CSS class mount-point makes the div "invisible" to the client (by display="contents"), the data attribute data-mount-point is primarely added to support readability or debugging.

It is worth to emphasize, that this mount-point-tag remains under full control of the framework. So all rendered tags below this tag, will be cleared out every time a new value appears on the flow. So do not try to use or touch this tag or any child from outside of the render function!

This works similar for dynamic lists:

ul {
    flowOf(listOf("fritz2", "react", "vue", "angular")).renderEach {
        li { +it }
    }
}

Which will result in this DOM structure:

<ul>
  <div class="mount-point" data-mount-point>
    <li>fritz2</li>
    <li>react</li>
    <li>vue</li>
    <li>angular</li>
  </div>
</ul>

Recipe: Mixing dynamic and static content within the same level

If it is absolutely clear that the mount-point will be the only element of some parent tag, then the render methods offer the optional into parameter, which accepts an existing RenderContext as anchor for the mount-point. In this case the rendering engine uses the existing parent node as reference for the mount-point:

render {
    ul { // `this` is <ul>-tag within this scope
        flowOf(listOf("fritz2", "react", "vue", "angular")).renderEach(into = this) {
        //                                                             ^^^^^^^^^^^
        //                                                             define parent node as anchor for mounting    
            li { +it }
        }
    }
}

This will result in the following DOM structure:

<ul data-mount-point> <!-- No more explicit <div> needed! Data attribute gives hint that tag is a mount-point -->
  <li>fritz2</li>
  <li>react</li>
  <li>vue</li>
  <li>angular</li>
</ul>

If you are in a situation where you absolutly have to mix static elements with dynamic (flow based) content within the same DOM level, then the new rendering offers a solution too: Try to integrate the static aspect within a map expression!

Let's consider the following example sketch we would like to achieve:

<ul>
  <!-- static elements within the list items, always on top -->
  <li>fritz2</li>
  <!-- dynamic content from a flow -->
  <li>react</li>
  <li>vue</li>
  <li>angular</li>
</ul>

The simplest solution would be to just call the renderEach method directly within the <ul> context after the static <li> portions. But this would violate the constraint, that all <li> tags must appear on the same DOM level (refer to the first example output to see, that an extra <div> would be insterted after the static portion).

So the correct way is to provide the into = this parameter in order to lift up the dynamic portion into the surrounding <ul> tag and to integrate the static portion within the flow by some map expression:

val frameworks = flowOf(listOf("react", "vue", "angular")) // might be a store in real world applications
ul {
    frameworks
        .map { listOf("fritz2") + it } // prepend the static part to the dynamic list
        .renderEach(into = this) { // do all the rendering in the "dynamic" part of the code
            li { +it }
        }
}

The result is exactly the same as the scetch from above.

You might habe recognized that the into parameter could be omitted, if the extra <div> does not affect the overall structure (in this case all <li> elements would still remain on the same level within the DOM!).

Migration Guide

For the most if not all parts of your application nothing has to be changed!

So first of all please compile and test your application. If there are no compiler errors and the application appears and functions as it did before, do nothing!

There are only few exceptions to this rule:

1. renderElement does not exist anymore. You will get compile errors of course, so this is easy to detect. Change all occurrences to render instead to solve this problem. If needed, apply the next two patterns on top.
2. If the additional mount-point-tag leads to unwanted effects (some styling applied to children won't work for example), just provide the parent tag as mount-point-tag by setting the into = this parameter at the render functions calls.
3. If there are parts of your application where dynamic and static content absolutely needs to coexist within the same DOM level, strive to include the static portion into the flow (for example by using map as shown in the recipe section before).
4. If you use our StackUp or LineUp component with dynamic content, make sure to set the into = this parameter in order to make the spacing property work again.

Further Information

For more details have a look at the documentation

fixes #531
fixes #405
fixes #346
fixes #538

[ghost]

I just added one more issue (#405 ) that should be fixed by this.