Why do we use builder/Fluent style API in domino-ui?

[vegegoku]

In order to answer this question we need to think of HTML before we think of the domino-ui java code we write , so lets start with simple example :

<div class="card">
    <div class="header" aria-expanded="true">
        <div class="flex-layout">
            <div class="flex-item logo" d-collapsed="true" aria-expanded="false"
                 style="display: none; align-self: center;"></div>
            <div class="flex-item" style="align-self: center; flex-grow: 1;">
                <h2>LOGIN<small></small></h2>
            </div>
            <div class="flex-item">
                <ul class="header-actions"></ul>
            </div>
        </div>
    </div>
    <div class="body height-collapsed-overflow height-collapsed-trans-200">
        <div class="field-group lined">
            <div class="field-cntr">
                <div class="flex-layout">
                    <div class="flex-item field-input-cntr" style="flex-grow: 1;">
                        <label class="field-label" for="id-188"><span>User name</span>* </label>
                        <input type="text" domino-uuid="id-188" id="id-188" spellcheck="true">
                    </div>
                </div>
            </div>
        </div>
        <div class="field-group lined">
            <div class="field-cntr">
                <div class="flex-layout">
                    <div class="flex-item field-input-cntr" style="flex-grow: 1;">
                        <label class="field-label" for="id-189"><span>Password</span>* </label>
                        <input type="password" domino-uuid="id-189" id="id-189" spellcheck="true">
                    </div>
                </div>
            </div>
        </div>
        <button class="btn md waves-effect elevation-1 bg-theme btn-block"><i
                class="material-icons btn-icon">lock_open</i><span>Login</span></button>
    </div>
</div>

Which would look like this in the browser

HTML is structured in hierarchical style, it is elements inside elements inside elements...

this structure allows you to locate the elements inside the page, and domino-ui with the builder/fluent api like
so lets compare the following code sample that builds the above card.

Card card = new Card();
card.setTitle("LOGIN");

TextBox userName = new TextBox("User name");
userName.setRequired(true);
userName.setAutoValidation(true);

card.appendChild(userName);

TextBox password = new TextBox("password", "Password");
password.setRequired(true);
password.setAutoValidation(true);

card.appendChild(password);

Button button = new Button();
button.setIcon(Icons.ALL.lock_open());
button.setBackground(Color.THEME);
button.setContent("Login");
button.setBlock(true);
        
card.appendChild(button);

        Card.create("LOGIN")
                .appendChild(TextBox.create("User name")
                                .setRequired(true)
                                .setAutoValidation(true)
                )
                .appendChild(TextBox.password("Password")
                                .setRequired(true)
                                .setAutoValidation(true)
                )
                .appendChild(Button.create(Icons.ALL.lock_open())
                                .setBackground(Color.THEME)
                                .setContent("Login")
                                .block()
                );

It is completely valid to write domino-ui code using style 1. but for my own preference there is a lot of extra typing and it does not reflect the structure and the hierarchy of the html, even in this very simple sample it is still hard to tell what goes into what and for something bigger it can be easily turn into a mess over time.

In the style 2. it looks simpler with less typing and it does reflect the structure and it is somehow much easier to locate the components inside each other and it is a lot easier to move components and relocate them inside this structure. but if it is a very big tree this will be a little overkill, specially if each component initialization took a lot more than few lines of code or even had it is own nesting, lambdas or loops..etc. also this style impose debugging issue when we set breakpoints.

So in a real project we adopted a middle ground style as we actually initialize the component outside the structure and append the components using style 2.

        TextBox userName = TextBox.create("User name")
                .setRequired(true)
                .setAutoValidation(true);

        TextBox password = TextBox.password("Password")
                .setRequired(true)
                .setAutoValidation(true);

        Button login = Button.create(Icons.ALL.lock_open())
                .setBackground(Color.THEME)
                .setContent("Login")
                .block();

        Card.create("LOGIN")
                .appendChild(userName)
                .appendChild(password)
                .appendChild(login);

With this style achieved less typing, separate initialization, and structured components, we have less debugging issues and easier refactor.

So in fact anyone can use the style they prefer and even come with their own preferred style.