Step 14: Custom CSS and Theme Colors

Sometimes we need to define some more fine-granular layouts and this is when we can use the flexibility of CSS by adding custom style classes to controls and style them as we like.

Preview
Figure 1: The space between the button and the input field is now smaller and the output text is blue
Caution

As stated in the Compatibility Rules, the HTML and CSS generated by SAPUI5 is not part of the public API and may change in patch and minor releases. If you decide to override styles, you have the obligation to test and update your modifications each time SAPUI5 is updated. A prerequisite for this is that you have control over the version of SAPUI5 being used, for example in a standalone scenario. This is not possible when running your app in the SAP Fiori launchpad where SAPUI5 is centrally loaded for all apps. As such, SAP Fiori launchpad apps should not override styles.

Coding

You can view and download all files in the Explored app in the Demo Kit at Walkthrough - Step 14.

webapp/css/style.css (New)
#!css.myAppDemoWT .myCustomButton.sapMBtn {
  margin-right: 0.125rem
}

html[dir="rtl"] .myAppDemoWT .myCustomButton.sapMBtn {
  margin-left: 0.125rem;
  margin-right: 0 
}
.myAppDemoWT .myCustomText {
  font-weight: bold;
}

We create a folder css which will contain our CSS files. In a new style definition file inside the css folder we create our custom classes combined with a custom namespace class. This makes sure that the styles will only be applied on controls that are used within our app.

For the button, a custom margin of 2px (or 0.125rem calculated relatively to the default font size of 16px) is added with the style class myCustomButton. We also add the base CSS class sapMBtn to make our selector more specific- the button has a default margin of 0 that we want to override.

For right-to-left (rtl) languages, like Arabic, you set the left margin and reset the right margin as the app display is inverted. If you only use standard SAPUI5 controls, you don't need to care about this, in this case where we use custom CSS, you have to add this information.

In an additional class myCustomText we define a bold text. This time we just define our custom class without any additional selectors.

webapp/manifest.json
#!js{
	sap.ui5: {
		"models" : {
			...
		},
		"resources": {
		  "css": [
			{
			  "uri": "css/style.css"
			}
		  ]
		}
	}
}

In the resources section of the sap.ui5 namespace, additional resources for the app can be loaded. We load the CSS styles by defining a URI relative to the component. This information is added to the header of the HTML page and loaded by the browser automatically. In traditional Web pages this is done using a <link> tag.

webapp/view/App.view.xml
#!xml<mvc:View
   controllerName="sap.ui.demo.wt.controller.App"
   xmlns="sap.m"
   xmlns:mvc="sap.ui.core.mvc"
   displayBlock="true">
   <App class="myAppDemoWT">
      <pages>
         <Page title="{i18n>homePageTitle}">
            <content>
               <Panel
                  headerText="{i18n>helloPanelTitle}"
                  class="sapUiResponsiveMargin"
                  width="auto">
                  <content>
                     <Button
                        text="{i18n>showHelloButtonText}"
                        press="onShowHello"
                        class="myCustomButton"/>
                     <Input
                        value="{/recipient/name}"
                        valueLiveUpdate="true"
                        width="60%"/>
				 <Text
                        text="Hello {/recipient/name}"
                        class ="sapUiSmallMargin sapThemeHighlight-asColor myCustomText"/>
                  </content>
               </Panel>
            </content>
         </Page>
      </pages>
   </App>
</mvc:View>

The app control is configured with the namespace class myAppDemoWT. This class has no styling rules set and is used in the definition of the CSS rules to define CSS classes that are only valid for this app.

We add our custom CSS class to the button to precisely define the space between the button and the input field. Now we have a pixel-perfect design for the panel content.

To highlight the output text we add a theme-dependent CSS class that will put blue color on the text. For other themes, the color might be different, but we will always have a semantic color set on the text. If we would have done this with custom CSS, the color might not fit to the current theme and the text could even be unreadable.

Finally, we add myCustomText to the text control to make the text bold because the text control does not provide such an API property.

Conventions
  • Do not specify colors in custom CSS but use the standard theme-dependent classes instead.