Domino-ui 2.x.x migration tips

[vegegoku]

Add your feedback and hints to help others who are migrating from 1.x.x to 2.x.x

[FrankHossfeld]

As a early adapter, I switch form Domino-UI v1 to v2 last summer. I am happy that I did the switch and it was really easy. At that time a flex layout was created only with CSS and even that was no problem. Today, compared to last summer, many bugs are fixed, the doc is much better, so, don't wait to upgrade ... :-)

[vegegoku]

Migrating FlexLayout and FlexItem :

Even thought the same syntax is preserved between the two versions to make migration easier, it is recommended to move to the new syntax when possible, users of the library can move to the new syntax gradually, the new syntax has some advantages over the old one, I will try to demonstrate that with few examples :

• Shorter syntax :

In version 1.x.x we can do this

FlexLayout.create()
    .setJustifyContent(FlexJustifyContent.SPACE_AROUND)
    .appendChild(FlexItem.create()
        .css(Styles.align_center)
        .appendChild(prevButton
            .addClickListener(evt -> {
              // go previous
            })
        )
    )
    .appendChild(FlexItem.create()
        .css(Styles.align_center)
        .appendChild(finishButton
            .addClickListener(evt -> {
              //do finish
            }))
    )
    .appendChild(FlexItem.create()
        .css(Styles.align_center)
        .appendChild(nextButton
            .addClickListener(evt -> {
              //go next
            }))
    )

in version 2.x.x

div().addCss(dui_flex, dui_justify_around)
        .appendChild(div().addCss(dui_center)
                .appendChild(prevButton.addClickListener(evt-> {
                    // go previous
                }))
        )
        .appendChild(div().addCss(dui_center)
                .appendChild(finishButton.addClickListener(evt-> {
                    // do finish
                }))
        )
        .appendChild(div().addCss(dui_center)
                .appendChild(nextButton.addClickListener(evt-> {
                    // go next
                }))
        );

FlexLayout not always a div:

In version 1.x.x FlexLayout was always a div, but in v 2.x.x you can apply Flex styles to any type of elements.

Creating your custom layout and reuse them :

With the introduction of the new css style interfaces in v2 it is now easier to create your custom flex layout and reuse them. for example if I want to make a vertical layout with specific gap between the items and align the items to the left, then reuse that in multiple places in my app

In version 1.x.x you would make a custom component like this

import elemental2.dom.HTMLDivElement;
import org.dominokit.domino.ui.shaded.grid.flex.FlexDirection;
import org.dominokit.domino.ui.shaded.grid.flex.FlexJustifyContent;
import org.dominokit.domino.ui.shaded.grid.flex.FlexLayout;
import org.dominokit.domino.ui.shaded.utils.BaseDominoElement;

public class VerticalLayout extends BaseDominoElement<HTMLDivElement, VerticalLayout> {

  private FlexLayout layout;

  public static VerticalLayout create() {
    return new VerticalLayout();
  }

  public VerticalLayout() {
    this.layout = FlexLayout.create()
        .setDirection(FlexDirection.TOP_TO_BOTTOM)
        .setGap("10px")
        .setJustifyContent(FlexJustifyContent.START);
    init(this);
  }

  @Override
  public HTMLDivElement element() {
    return this.layout.element();
  }
}

or you would introduce a static factory :

  public static FlexLayout verticalLayout() {
    return FlexLayout.create()
        .setDirection(FlexDirection.TOP_TO_BOTTOM)
        .setGap("16px")
        .setJustifyContent(FlexJustifyContent.START);
  }

But in version 2.x.x you can use the composite css to achieve the same result way easier and way less code
You just need to define a composite css class somewhere in your app like this

public static CssClass vertical_layout = CompositeCssClass.of(dui_flex, dui_flex_col, dui_justify_start, dui_gap_4);

then just use it anywhere with any kind of element

div().addCss(vertical_layout);

No need for FlexItem

In version 1.x.x any element or node that needs to be appended to a flex layout needed to be wrapped as a FlexItem, but this is no longer needed in version 2.x.x you can just use any element and you can use any element and append it directly to the flex element.

Example :

In version 1.x.x

FlexLayout.create()
        .setDirection(FlexDirection.TOP_TO_BOTTOM)
        .setGap("10px")
        .setJustifyContent(FlexJustifyContent.START)
        .appendChild(FlexItem.create()
            .appendChild(div().textContent("first child"))
        )
        .appendChild(FlexItem.create()
            .appendChild(div().textContent("2nd child"))
        );

In version 2.x.x

div().addCss(dui_flex, dui_flex_col, dui_justify_start, dui_gap_4)
                .appendChild(div().textContent("first child"))
                .appendChild(div().textContent("2nd child"));

These are some of the good qualities that are brought to the Flexlayout in version 2.x.x, some users might even find more advantages in the new syntax as it is extremely flexible and works well for building dynamic and complex layout, the only advantage of the old syntax over the new one could be the fact that the styles using enums and specific method for each might be easier, but this advantage starts to fade as you get used to the new syntax.