There are several things you should keep in mind to ensure that an application can
actually be themed.
General Aspects
Do not hard-code colors and fonts if you want your control or application to be
themable in the theme designer tool.
For example, if you hard-coded the font color to black, this color cannot be adjusted
when you apply a custom theme. This can be problematic if you want to apply a custom
theme with a dark background color because the font color cannot be adjusted to a
light color.
Stable Theme Parameters
- Themes in SAPUI5
are built with the CSS preprocessor “less” and make use of a complex parameter
structure.
- SAPUI5 applications have access
to these parameters at runtime via the API-call
(sap.ui.core.theming.Parameters.get() ). These parameters
not only differ in terms of themes, they are also not necessarily stable across
different versions of SAPUI5. For this
reason, you cannot rely on the complete set of parameters.
- To allow developers to build theme-dependent, custom-styled applications or controls, a
subset of 70 parameters representing colors for different types of usage (such
as Border, Backgrounds, Charts) is available.
- The parameters in this subset can be considered as "stable", in that:
- We will not change naming for these parameters.
- The contrast ratio between foreground- colors like text and the related
background will remain stable.
- Always choose parameters that fit best from a semantic perspective, do
not choose them based on their color value.
- This set is available across the two predefined themes sap_bluecrystal
and sap_hcb and should be handled with care. You should test
your implementations for both themes to ensure the results are as expected.
- We must stress that this approach can only cover the most common use cases. In addition, be
aware that due to parameter value changes with future versions of SAPUI5, it might be
necessary to rework your applications even when using the “stable” theme
parameters described here.
- For charting, two individual sets are available, Chart Accent and Chart Semantic. Both sets
are logically independent. Therefore only one of these sets is to be used
consistently across individual charts.
- You can view the entire set of basic theme
parameters as a sample in the Explored section of the
Demo Kit.
SAPUI5 application developers writing custom HTML should consider the following:
- LESS parameters are not accessible via CSS; only support for standard libraries.
- To ensure theme-dependent styling, only use basic theme parameters.
- Read appropriate parameter values via API and set the elements' CSS properties rather than
hard-coding colors or borrowing arbitrary style classes from control
sets:
jQuery.sap.require("sap.ui.core.theming.Parameters");
var myColor = sap.ui.core.theming.Parameters.get("sapUiDarkBG");
SAPUI5 control developers should consider the following:
- Use the theme LESS parameters in CSS class definitions and rules.
- Use the appropriate level of parameter for the control, creating new ones as appropriate.
For example, do not use color values or quick theming parameters directly in CSS
rules.
- Follow the control parameter hierarchy conventions.