Implementation of css classes in version 2.x.x

[vegegoku]

Before we explain how CSS classes works in version 2.0.0 I will explain briefly how it used to work in version 1.x.x

1. Version 1.x.x

Well it was very simple, a css class is just a string token same as the name of the CSS class in the style sheet, domino-ui allowed the user to add or remove one or of those strings tokens, there was not so many validations or verification, we would just add/remove from the element class attribute.

Yet as simple as it is it did push any of the custom work to the user, the user needs to track what classes where added/removed, the user needed to come up with their own implementations for different use cases, for example apply a css class only if a boolean value is true, or apply only one css from a set of css classes, or apply two different css classes sets based on different cases...etc. so how domino-ui version 2.x.x left some of that burden from the users ?

2. Version 2.x.x

In version 2.x.x what we had in version 1.x.x is still there, but we added a more flexible implementation and utilities to help the user avoid rewriting a lot of the custom logic for many use cases.

In the new implementation in addition to the string tokens we added the CssClass interface, the interface has few default implemented methods to apply the style, remove the style, check if the style is applied to an element and to check if the style is similar to another CssClass, the implementations will need to override the method getCssClass which should return the String token for css class just like in version 1.x.x, the components are made to accept both, lets take an example :

Assuming we have the css class in the style sheet like this :

.dui-cart-box {
   width: var(--dui-spc-48);
   border: 1px solid var(--dui-clr-black);
}

in domino-ui assuming the cart box components is a simple div we can do this in both versions 1.x.x, and 2.x.x to apply the style :

private static final String dui_cart_box = "dui-cart-box";

DivElement cartBox= div().addCss(dui_cart_box);

or we can just inline the static constant.

But exclusively to version 2.x.x we can do this too :

private static final CssClass dui_cart_box = ()-> "dui-cart-box";
DivElement cartBox =div.addCss(dui_cart_box);

or

DivElement cartBox =div.addCss(()->"dui-cart-box");

Up to this point one might say that this is even more work than using just a simple String token, which is true for such simple case, but now lets say we want to change the border color of the cart box when ever we add/remove items to indicate when total price exceeds as specified limit for example :

so our css in the style sheet might look like this :

.dui-cart-box {
   width: var(--dui-spc-48);
   border: 1px solid var(--dui-clr-black);
}

.dui-cart-box .dui-cart-box-overflow {
   border: 1px solid var(--dui-clr-red);
}

With string tokens we can implement it like this :

import elemental2.dom.HTMLDivElement;
import org.dominokit.domino.ui.elements.DivElement;
import org.dominokit.domino.ui.utils.BaseDominoElement;

import static org.dominokit.domino.ui.utils.Domino.div;

public class CartBox extends BaseDominoElement<HTMLDivElement, CartBox> {

    private static final String dui_cart_box = "dui-cart-box";
    private static final String dui_cart_box_overflow = "dui-cart-box-overflow";

    private final DivElement cart;
    private final double limit = 100.0;

    public CartBox() {
        this.cart = div()
                .addCss(dui_cart_box);
        init(this);
    }

    public void addItem(String id, double price){
        //add item logic
        addRemoveOverflowStyles();
    }

    public void removeItem(String id){
        //remove item logic
        addRemoveOverflowStyles();
    }

    private void addRemoveOverflowStyles() {
        CartBox cartBox = calculateTotalPrice() > limit ?
                this.addCss(dui_cart_box_overflow) :
                this.removeCss(dui_cart_box_overflow);
    }

    public double calculateTotalPrice() {
        double totalPrice = 0;
        //add calculate price logic here;
        return totalPrice;
    }

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

With the new interface we can implement that like this :

import elemental2.dom.HTMLDivElement;
import org.dominokit.domino.ui.elements.DivElement;
import org.dominokit.domino.ui.style.BooleanCssClass;
import org.dominokit.domino.ui.style.CssClass;
import org.dominokit.domino.ui.utils.BaseDominoElement;

import static org.dominokit.domino.ui.utils.Domino.div;

public class CartBox extends BaseDominoElement<HTMLDivElement, CartBox> {

    private static final CssClass dui_cart_box = ()-> "dui-cart-box";
    private static final BooleanCssClass dui_cart_box_overflow = BooleanCssClass.of(()-> "dui-cart-box-overflow");

    private final DivElement cart;
    private final double limit = 100.0;

    public CartBox() {
        this.cart = div()
                .addCss(dui_cart_box);
        init(this);
    }

    public void addItem(String id, double price){
        //add item logic
        dui_cart_box_overflow.apply(this, calculateTotalPrice() > limit);
    }

    public void removeItem(String id){
        //remove item logic
        dui_cart_box_overflow.apply(this, calculateTotalPrice() > limit);
    }

    public double calculateTotalPrice() {
        double totalPrice = 0;
        //add calculate price logic here;
        return totalPrice;
    }

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

Notice that now we are using the BooleanCssClass from domino-ui version 2.x.x, which is as the name suggests takes a css class and apply that class to an element based on a boolean flag, true means add the css class, false means remove the css class, we didnt need the custom logic we added with the string tokens approach.

Now this still looks simple, but it saves repeating the write of that logic in the application for different components, and below we will explain all the available CssClasses in version 2.x.x with custom logic that you can use out of the box :

• BooleanCssClass : Applies a css class based on a boolean flag, true->add, false-> remove
• AutoSwapCssClass : Takes 2 CssClasses When ever apply is called for this css class, it will swap the applied css class with the other, only one of the 2 css classes will be applied to the element at the same time.
• ConditionalCssClass : Similar to the boolean class but instead off taking a boolean as part of the apply method, it takes a condition and when ever apply is called it will evaluate the condition to decide if the css class should be added or removed.
• **LimitOneOfCssClass **: Takes a set of css classes and allow only one of those classes to be applied to element at once, similar to the AutoSwapCssClass but with any number of css classes.
• ReplaceCssClass: Starts with an initial css class and then when ever replaceWith is called a replacement for that css initial style will be set, when the style is applied the original will be replaced with the new replacement, and it will keep track of the original css class.
• **SwapCssClass **: Similar to the AutoSwapCssClass but with manual Swapping. and user can swap the current CssClass with any other CssClass instead of fixed 2 classes.
• ToggleCssClass: Will automatically toggle the existence of the class from the element, whenever apply is called if the class is added it will be removed and if it is not added it will be added to the element.
• CompositeCssClass : Combine as many CssClasses as one class to apply then as if they were a single css class.

Those are few of the new added CssClasses that helps the user not to repeat Css logic in his app, this can be expanded as need by both the user or domino-ui itself to add more utility classes like those above.