Theming FAQ

Frequently asked questions regarding theming in OpenUI5

How can I adapt the visuals of a control?

While there is always the option to create a new Theme, this is overkill for most minor style adaptations. For those minor changes, the recommendation is to include additional CSS into the page which changes the style of the respective tags of the OpenUI5 control. This allows complete, arbitrary changes of the visual design - after all it is the same technology that the UI5 controls use for their styling.

The main options are:

  • Inspect the HTML and CSS of a control and write a similar, but adapted CSS rule for a CSS property you want to override for all controls of a type.
  • Call .addStyleClass("myStyle") on some control instances if you want only those instances to look different than other instances - and then write CSS code that refers to the normal classes/tags AND to this CSS class you just added.
Note
  • With this high degree of power and flexibility comes quite some responsibility. With CSS you are perfectly capable of destroying the functionality of a control. This is no OpenUI5-specific thing, but when you do CSS adaptions, you should always have good knowledge of this open standard.
  • The inner structure of a control, the tag hierarchy, the IDs and CSS classes are NOT part of the public control API that we guarantee to stay stable. This is also the case in other UI libraries which may define some CSS classes as stable, but not everything else. As CSS can refer to the inner structures of a control, you have to accept the risk that your style changes break when we change the inner structure. Changing the inner structure is a freedom we absolutely need to reserve, so we can fix bugs and add features to a control, so this is nothing that can be discussed.
  • When your CSS does not work as expected, use Firebug or the Internet Explorer F12 developer tools or similar tools to inspect the page and check which CSS rules are applied to the respective tag - and which rules may be applied, but overridden by other rules. If your rules are overwritten by other rules, this is probably because of either the order of appearance (last rule wins) or because of the CSS selector specificity (more specific CSS selectors win). If the latter sounds strange to you, look it up in the CSS spec or on Google.
DON'Ts:
  • Do not adapt the style attribute of HTML elements belonging to OpenUI5 controls. When these controls are re-rendered, the changes will be lost.
Why do OpenUI5 controls not have a 'style' property where I can do arbitrary changes?

One tricky thing is that a control usually does not map to ONE HTML element, but to a whole tree of HTML elements. Whatever is set to the 'style' property we would probably add to the root element of this HTML tree – and only there, so you have no 'style' access to inner parts. If you just want to override the height of a button, this would actually work. But as soon as things get more complex, it will not work that easy. And “more complex” already starts with the height of a ComboBox. The outer <div> will get the proper height, yes. And incidentally also the <input> tag inside, as it has 100% height set. But the dropdown arrow and the respective button-kind-of-thing has a fixed height and the whole control will look pretty broken, then.

In other cases, when HTML elements are nested that break the CSS inheritance chain e.g. like a <table> does for font settings, you may change the "style" to a different font and text color, but it will just do nothing.

In general, we try to expose the obvious adaptation stuff in the API, for example the button height. But the less obvious adaptations may require support inside the control to work properly and as we cannot foresee and support everything you can do with a 'style' property, we raise the bar a little bit by requiring you to write CSS (potentially using .addStyleClass(…) on the respective control). With CSS you can do what you cannot do with a 'style' property: tweak the inner HTML components of a control.

Plus: SAP applications (at least the more traditional ones – currently this seems to be less of a rule, but I’m not sure it will stay like this forever) need to conform to some visual design guideline and in general it is not even desired that applications change the TextField height or used font however they like. As you can use CSS, UI5 still supports that, but we shouldn’t make breaking the visual design an option in our official API.

How can I provide additional CSS which is not overwritten by the OpenUI5 CSS?

When OpenUI5 is used "normally" (which means: loaded by a <script> element in the <head> of a page, all libraries declared in the respective attribute of the script tag), it is sufficient to just add the custom CSS at any place after the OpenUI5 <script> element. OpenUI5 will insert its CSS links immediately after the <script> tag, so any later CSS will appear later in the document and can thus overwrite the OpenUI5 CSS.

However, it is important to understand the precedence rules of CSS!

The order of appearance is not the only factor deciding which one of two or more conflicting rules wins. Actually it is only the least important factor. In practice, the most important (and maybe least known) factor is the "specificity" of the selector belonging to a rule.

For example, if one rule says button {color:red;} to make all button texts red and a second rule says div > button {color:green;} to make all texts green in buttons which are direct children of a <div> element, the second rule always wins, if applicable, because it is more specific. The order of appearance in the document does not matter in this case. It would only matter if both rules would start with an equal selector like button{color:***}.

The order of loading is completely irrelevant, only the position in the document counts in this case.

If you load OpenUI5 not with a <script> tag in the <head>, or if you did not specify all used control libraries in the <script> tag, but loaded some later on when the body was already loaded, you can still make sure a custom CSS appears later in the document by loading it with jQuery.sap.includeStyleSheet(stylesheetUrl[, id]) after loading OpenUI5 or the dynamically loaded control library.

More information
I am adding a style class, but it does not work! Why?

If you want to change some styling and use control.addStyleClass(…) to add a CSS class, but it does not seem to work, you first have to understand WHAT is not working:

  • Is the style class not added to the HTML?
  • Or is the style class correctly added, but the style you supplied is not applied by the browser?

You can check this by inspecting the HTML with your browser's developer tools/ web inspector.

  • If the style class is really not added to a control (which is rather unlikely), it would be a bug that needs to be reported and fixed. Note: some entities are not Controls, but only Elements (inherit from sap.ui.core.Element). They only sometimes have support for addStyleClass.
  • If the style class is there in the HTML, the bug is inside the CSS styles you supplied:
    • Are they loaded by the browser?
    • Are the selectors matching the element you want to style? You can again check in the developer tools: they mostly list all styles which would apply, but some are overriding others (those others are usually listed striked-through). If your style is not listed at all, your CSS selector seems to be wrong.
    • If your selector is fine, but other style rules override your styles (potentially those from the original UI5 theme), then the CSS precedence rules decided this. Please read the section "How can I provide additional CSS which is not overwritten by the UI5 CSS?" above and see http://www.w3.org/TR/CSS21/cascade.html#cascading-order for the respective part of the CSS spec and http://www.w3.org/TR/CSS21/cascade.html#specificity for more on specificity.
    • It could also be that your browser does not understand the CSS styles you have written. Some browsers still display them in the developer tools, some don't, so you may want to try changing very common styles like the border to check whether selector and specificity are fine.
When can I use UI Theme Designer and when do I have to do some separate steps?
There is not one single way to create a new theme, but there are several options. Which one to choose depends on several factors:
  • How different is the desired design from an existing theme?
  • Should the theme be used across several applications or just in one?
  • Are sufficient CSS skills available?
  • How much effort can be invested?
  • How structured and clean should the result be?

Depending on the answers it may be that one should not even create a new theme but just adapt an existing one.