Enhanced Theming Concepts

SAPUI5 uses the popular CSS preprocessor LESS. This tool introduces several features, including CSS variables - a concept which also has been heavily demanded by the CSS community: in any UI5-controlled CSS file, variables can be defined and can then be referenced anywhere in the CSS code of the same library. These variables are mainly used for colors. All CSS variables are global. The CSS variable concept contributes to a consistent way in implementing and changing the styles.

LESS adds more features like color calculations, mixins and CSS selector nesting. The color calculations are used in SAPUI5 to derive many different color shades from just a few variables.

Here is the syntax:

@sapUiText: #000000; /* define the text color as 'black' */

button {
   color: @sapUiText; /* buttons will automatically have the current text color, which is '#000000' right now */
    [...]
}

The SAPUI5 theme generator then takes care of substituting all references to a CSS variable by the current value of this variable. This happens during the build of the control library.

Additionally, a specific theme can modify the CSS parameter values given by the base theme. So a control can just define its text color to use sapUiText by default which will automatically take care of applying the correct color for every theme or user modification: The theme generation will create one CSS file per theme, and the substitution of the CSS parameter references will always take the theme-dependent value into account. So a visually very different theme can be easily created by just changing a couple of colors.

While every library and control can introduce their own CSS variables, those defined in global.css are most important. Optimally, they should be few and simple enough to be understood by many end-users (similar to what the Windows operating system offers to end-users), but still cover enough aspects of the visual appearance to make them sufficient for many customer-required theme modifications.

Additional benefits of CSS variables are for example:

• They can be used to generically build simple styling tools that allow a limited degree of freedom (=changing the CSS parameter values). The UI theme designer is an example for such a tool.
• They can also be linked to metadata like what group of colors they belong to, to which colors they need to have some visual contrast, etc.

SAPUI5 CSS generation does not only substitute the CSS variable values but also takes care of bringing all CSS files from a control library into one file to be loaded at runtime, this increases the performance. The reasons to not have all styles defined within one file at development time are for example:

• Less collisions and merging when different developers edit the styles of their controls.
• Clear separation between the styles for different controls (this helps greatly with estimating/testing the impact of a CSS modification)
• Keeping the door open for future optimizations regarding runtime performance and data transfer by tailoring CSS files on server-side that only contain the CSS required on the current application page.

For performance reasons, the SAPUI5 CSS generation can optionally remove all comments and unnecessary whitespace and can collapse verbose declarations into a more compact format.

In all SAPUI5 application pages, the HTML root tag of the document gets the additional attribute data-sap-ui-browser where the value is the type and the current browser version. When browser-specific CSS needs to be written, this attribute can be used in CSS selectors.

html[data-sap-ui-browser="ie8"] button {  /* this rule will only be applied if the current browser is Internet Explorer 8 */
   margin-top: 0px;
}

html[data-sap-ui-browser*="ie"] button {  /* this rule will only be applied if the current browser is ANY version of IE */
   padding-top: 0px;
}

While some of the style and layout applied using CSS is clearly depending on the current theme - and customers are likely to modify such style rules - there are other style rules that are required for a control to work properly and unlikely to differ for different themes. Examples are: the overflow behavior, positioning of popup elements, the mouse cursor type, the display mode and others more.

SAPUI5 promotes and supports keeping those style definitions in the so-called base theme, which serves as a common base for all themes.

Themes are built upon this base style, defining their specific visual design by applying colors and images, sizes and fonts. SAPUI5 theme generation takes care of combining the base theme with the specific theme for each generated theme CSS file. Because the specific CSS is appended to the base theme, a specific theme can always override styles defined in the base theme. If this step is required often, the respective style declaration probably should not be located in the base theme.

Any style declarations which are referencing CSS variables (at least those common ones defined in the base theme) can also be done in the base theme, and it is sufficient to do it only there: The CSS generation will apply the correct value for each respective theme. So this split between base theme and specific themes avoids double creation and maintenance of CSS parts which are common for all themes and keeps the CSS files smaller that need to be written for any new theme.

For certain countries, right-to-left (RTL) text mode needs to be supported. In order to avoid the need to create a completely new set of CSS files for those countries, SAPUI5 supports generic RTL generation. Basically, this involves switching the right and left margins and mirroring everything else (including CSS3 rotations, and so on).

Everything else that is not covered by this automatic transformation can be fixed by using style rules that are only applied in the RTL case.

If you override RTL-specific attributes like text-alignment, positioning and so on, you have to write the RTL equivalent into your application CSS. The attributes below are critical for RTL support:

• float
• clear
• text-align

The following attributes require attention:

• margins
• paddings
• borders
• background-position
• position (right/left)
• text-indent

Depending on the values, these latter attributes may also need to be mirrored. As applications running in RTL-mode add a dir attribute to the HTML tag in the DOM, custom styles that have to be written can use the following selector to handle RTL-specific styling:

html[dir="rtl"]  .myselector{
}