Component Variants

Overview

Variants are Servoy elements with an applied style (so-called Variant). When designing a form, using variants allows you to easily choose the element with the desired look and feel. Variants not only facilitate the development process but also help maintain a consistent and professional visual appearance across all parts of the application.

A variant simply appends a determined list of style classes to the element; therefore, the look & feel of the variant is ultimately determined by the solution's stylesheet ( see CSS/Theme ).

How it works

Variants in Servoy can be applied to buttons and label elements, allowing developers to choose a predefined style for these components. The variant is nothing else than a collection of style classes applied to the element. In the Form Editor, you can pick the label or button with the applied style ( variant ) of your choice by clicking the ... icon.

Variants

You can change the applied variant at any moment later with the "variant" property of the element.

Variant Property

The variants are defined in a JSON object in the variants.json file present in the media folder of the solution ( or it's module ); You can edit the variants.json file to create/remove variants or to modify the style applied to existing variants.

Why using variants ?

Using variants is not the only approach to applying a style to elements; it is also possible to use the element's styleClass instead of the variant to get the desired look and feel. However, this approach has a few disadvantages compared to using variants. To start with, you won't be able to see the resulting look & feel until you have set the element's styleClass. Furthermore, the list of classes you can choose from is extensively long, and often you end up selecting multiple classes to achieve the desired result. This result in a slower an inefficient approach, which is prone to cause inconsitencies in the appereance of the application. Since there is a vast list of classes to choose from, for a large and complex application, is more likely for the developers to apply different style classes to the elements, causing inconsistencies in the appearence.

Using variants, instead, allows you to preview the look & feel of the element before you even place it into the form. The list of variants is considerably shorter compared to the list of style classes, and the user will be able to select only from the style the designer has accounted for. It is responsability of the designer to define the variants that can be used within the application.

In conclusion, using variants eliminates the need to manually select the styleClasses each time a new element is added to the form, saving time and ensuring consistency in the application's appearance.

Can i use the styleClass property with a variant ?

Yes, it is still possible to use the styleClass property of an element together with variant. There are some use cases where you are expected to use the styleClass property on top the variant; for instance in responsive forms, positioning, sizing and margins of the element may vary depending on the context the element is in. Using the element's styleClass you can control the element's dimensions ( position, height, width, margins ) fitting the context they are in.

Aside from positioning & dimensioning, is recommended you avoid altering the look & feel ( colors, fonts, borders ) of the variant by adding additional classes in the element's styleClass property. Doing so may introduce inconsitencies in the global look & feel; if you need a different style perhaps you can consider to create a new variant for it ?

Quick Start

When creating a new solution, a pre-determined set of variants is included by default. The variants are defined in the variants.json file present in the Media node of the solution. You can edit the variants.json file to modify existing variants or to create new variants.

For existing solution instead, you can create the variants.json file in the Media node of your solution ( or module ). Is best to locate the variants.json file in the same module where the solution's theme/stylesheet is located.

Variant JSON

The variant.json structure is the following: each variant has an unique identifier, a category which can be button or label, a display name visible to the user, the list of styleClasses applied to the element.

{
    "VariantUniqueID": {
        "category": "button"|"label", 
        "displayName": "VariantDisplayName",
        "classes": [ "ListOfStyleClasses", "CommaSeparated" ]   
    }
 }
 

Below an example of a button variant and a label variant:

{
    "BtnSuccess": {
        "category": "button", 
        "displayName": "Success",
        "classes": [ "btn", "btn-success", "btn-lg", "font-weight-bold" ]   
    },
    "TxtPrimary": {
        "category": "label", 
        "displayName": "Primary",
        "classes": [ "h3", "text-uppercase", "text-primary" ]   
    }
 }