Apply Custom Themes from the UI Theme Designer to your SAPUI5 App

[former_member724335]

We’ve been working on a project for a client that is partly external and so the client had requested that the App adhere to their internal Style Guide. We previously used the style.css file for this but we often encountered issues:

1. The CSS was very big and hard to maintain.


2. Whenever a new SAPUI5 version was released, some of our styling would break.


3. We were having trouble targeting certain hover states as some of the styles were applied to the child and others applied to the parent.

Obviously, SAP doesn’t recommend overusing the style.css file, and definitely does not recommend utilising it for makeshift theming so we had no right or reason to complain about the issues we faced. One day, after a new SAPUI5 release had broken more of our styles I decided it was time we try-out the UI Theme Designer. It was easy to create the theme and it’s a treat to tweak the style without the need to redeploy the App; the inbuilt support for custom styles meant we had a centralised repository for CSS that we could use across a suite of Apps for our client.

We did have one issue, however… the theme wouldn’t load locally.

It’s too time consuming to redeploy your App every time a modification is made to your code base, particularly if you’re in development. If you are applying a custom theme then for your App to be usable you would have to manually alter the data-sap-ui-theme property in the sap-ui-boostrap script tag of the index.html file to sap_belize (and then you’ve lost your theme and the App on your local machine is not visually reflective of the App deployed to the cloud). We needed a better solution.

I looked through all of the documentation for the AppRouter and the XS-ENV packages but didn’t find any mention of theming. I initially tried to create a destination that pointed to our URL in the cloud, using the default-env.json file to try and intercept requests to the /theme/ endpoint and point them there, however, I quickly learnt that the authentication service didn’t like this at all.

I did see some documentation in the XS-ENV repository that discussed binding services to your localhost instance via the default-env.json file (rather than a destination) to mimic the behaviour in Cloud Foundry, but like I said, there was no mention of theming only common services like hana and connectivity.

Well, even if it’s not documented, I discovered that this does in-fact support theming too! It took a bit of trial and error but I was able to expose our theming service to our local AppRouter instance by including the following in our default-env.json file:

{

	"destinations": [...],

	"VCAP_SERVICES": {

		"theming": [

			{

				"label": "theming",

				"provider": null,

				"plan": "standard",

				"name": <NAME IN CLOUD FOUNDRY>,

				"instance_name": <NAME IN CLOUD FOUNDRY>,

				"tags": [

					"theming"

				],

				"binding_name": null,

				"credentials": {<SERVICE CREDENTIALS OBJECT>},

				"syslog_drain_url": null,

				"volume_mounts": []

			}

		],

	}

}

You’ll need to get your credentials object from the Services and Instances tab in Cloud Foundry.

Once I added this, all I had to do was edit our xs-app.json file to expose this service locally.

{

  "welcomeFile": "/index.html",

  "authenticationMethod": "route",

  "routes": [

    ...

    {

      "source": "^/themes/(.*)$",

      "target": "$1",

      "service": "theming"

    },

    ...

  ]

}

Easy! I restarted the local AppRouter and on load our theme appeared!