Design System Class

Official Content
This documentation is valid for:

A class determines a set of design characteristics that you want one or more controls to adopt in the UI at runtime (rendering).

It is declared in the section Design System Styles

Syntax

.class_name  [,.class_namei]...
‘{’
       [@include class_namej ... ;]      
       {property_name: {value[unit]|$token_group.token_name | gx-function}...}; ...
‘}

View Syntax conventions.

Where:

class_name, class_namei: Name given to the class by the developer. This name will be used in the class properties of the controls. You can specify more than one class name if you want them to share the same block of property definitions (currently only for Web). Read the warning about casing in the section on temporary restrictions.

class_namej: Name of a class declared in the same Style whose properties are to be included in this one. If there is no class with that name, it is ignored.

property_name: Valid style property name. Valid properties are both the existing ones for Web platform objects (for example, Web Panel) as well as Native or Angular (for example, Panel). See Design System Class Properties.

value: Valid value for the property property_name.

unit: Valid unit of measurement according to property_name. Some of them are px, dip, em, %.

token_group: Valid Token category. In the Token editor, you can see a combo box with all the possible values (colors, radius, spacing, etc.).

token_name: Name of the Token defined under the token_group category in the Tokens section of the DSO or of a DSO (or Tokens section of a DSO) imported by it (in a sort of "extended DSO" if viewed as an analogy to the concept of an extended table).

gx-function: Function used to return a reference to a KB object as a value. For example, the gx-image function returns a reference to a KB image and is used for properties specifying images. The gx-file function returns a reference to a KB file.

Note: Among other things, CSS also allows you to select HTML tags or identifiers —not only classes— and combine selectors, etc. The Styles section of the DSO allows you to directly import or copy a CSS, and for this reason that syntax should be included here as well. However, it is not explained here because it has a lower level and is not supported for native objects (Panels type). This tutorial can be very helpful to access it.
If there is an Include rule, the property declarations of each of the included classes are taken as if they were written within the class being declared, in that same order. Therefore, they are added to those of the class. If there is overlap, the last one applies.

Example:

For the H1 class, the entire H1_Negative declaration block is valid except for the color declaration; in this case, the declaration explicitly specified in H1 is valid. 

.H1_Negative
{
    color: #FFFFFF;
    font-family: $fonts.Title1;
    font-size: $fontSizes.H1;
    font-weight: bold;
    text-align: center;
    letter-spacing: -1.72px;
    line-height: 75px;
} 
.H1
{
    @include H1_Negative;
    color: $colors.Black;
}

Note that values were used for some properties, while other properties have values with units of measurement or references to Tokens. If this DSO were to be applied to a Panel, then the px unit would be converted to dip (1 to 1 equivalence).

Characteristics of classes

Classes are not specific, meaning that they have no restrictions as to the type of control to which they can be applied. When any of the style declarations of the associated class doesn't make sense for a control type, that declaration (and only that one) will not be taken into account. 

Thus, if a class defines text features such as font size, they will have an effect on Text Block or Attribute/Variable type controls but not on an Image type control. 

There may be classes not associated with any UI control, just as there may be controls that have classes associated with them that are not specified in the DSO (nor in any of the DSOs or Styles of DSOs imported by it). In the latter case, it’s as if they had no associated class.

About properties

Some properties are valid for rendering both Web Panel and Panel controls, but others are specific.

See more in Design System Class Properties

Class structuring in the Styles section

A class can be conditioned so that its declaration is only valid when the condition is met. For now, the condition is only related to the medium, such as screen size, and applies only to the Web.

In addition, the same class can be selected in the same DSO with no condition (or with another condition), or in the Styles of an imported DSO. See Structuring classes in Design System to know what happens in those cases.

See also Rendering precedences for controls with Design System Object.

Temporary restriction on casing of Web class names

A DSO used in a Web application will generate a CSS file with the classes having the same casing as that of the DSO. 

While the DSO is not case-sensitive, nor is CSS, HTML considers selectors to be case-sensitive. So, for a control that has a MyClass class associated with it to take its values from that class in the CSS at runtime, it has to be called MyClass, and not, for example, myclass. 

At the moment (u6), the first time a class name is typed in a DSO and saved, that will be the casing used from then on in the KB; even if the developer modifies it in the DSO, internally the first one will continue to be taken, so it will be the one used by the controls. 

This has some drawbacks:

1.    Suppose you have a DSO where you first declared:

styles MyStyles
{
    .MyClass
    {
        color: brown;
    }
}

When you try to associate this class with a control, you will be offered the MyClass class. When the CSS is generated, it will be generated with the casing of the DSO object, so it will be MyClass. At runtime, the brown color will be displayed correctly.

However, if you change the casing in the DSO (or delete the class and write it again with another casing) and call the class "myclass," when trying to associate that class with a control, even if you type "myclass" in the Class field value, you will see that the IDE will show "MyClass" after losing focus.

The problem is that in the generated CSS the change will be applied —you will see "myclass"— but the HTML tag for the control will read MyClass. So, when you look for that class in the CSS it will not be found and you will not see the brown color at runtime.

2.    The same will happen if you use the same class name in two different DSOs. The internal casing will be the one used the first time it was saved, regardless if it comes from two different DSOs.

Therefore, once you have saved a class with a certain casing, you should always use that exact casing in all DSOs, even if they are independent of each other. No matter what casing you type, the controls will always map to the first one regardless of which DSO they come from. 
The other option is to change something in the name to make it understood that it is another entity.

Note: All that has been said is also valid for Angular applications.

Availabilty

Since GeneXus 17 Upgrade 6.