SAPUI5 Custom control library: Web IDE Development, deployment to HCP, and to on-premise ABAP Repository. Part 1.

Despite the enormous quantity of controls supplied by SAPUI5 framework it is likely that at one or another moment you realise that your end users go whimsical and you face a task of creating another Control successor. Not a big deal actually, just open a corresponding guide and off you go. You implement a new control and use it as a part of an App project. However, sooner or later you will need to use the same control in another project, then in one more, then in yet another, and so forth. If the control is simple enough (just like in this tutorial) you can use old good “copy-paste”, copying the js file into all projects as required, however it is the worst thing to do – keep in mind that you are working in Object-oriented environment and programming language. That’s when you need a library – a functionally close set of reusable code (controls, types, etc.), which you can reuse in multiple projects and probably publish on the Net for other developers.

And at one moment I found myself in such a situation. After quite an hours of practicing trial-and-error technique I found a solution: the library was implemented, deployed to HCP and to on-premise SAP ABAP Repository, and now probably is a good time to share the findings. Unfortunately I cannot guarantee that the technique described below would be applicable to any installations, but hey, we are all developers, and the more challenging task is the more fun to resolve it.

By the time the solution proved to work for me (early December’16) the UI5 version was 1.42.x and SAPUI5 version at on-premise SAP ABAP Repository was 1.38.9. SAP ABAP Repository was of version 7.40/0014.

Implementing Library

A brief review of the necessary steps of library implementation can be found here. Apparently it is not an official documentation, and it’s far from being comprehensive. However, it’s a good starting point. I would also recommend to look through other SAPUI5 libraries within Github OpenUI5 source repository for samples.

To start implementing library in the Web IDE first you have to create a project.
Let’s assume that the name space of the library would be “my.custom.control” and the name of the Web IDE project would be “MyCustomLib”. We also assume that the library will contain a single control ProductRating taken from the OpenUI5 tutorial.

Despite the fact that the guide orders to create a folder hierarchy according to the library namespace, it’s OK to place all the library files into the project root folder.
In comparison to a common SAP UI5 app you have to do some things differently:

• the “type” value of “sap.app” part of the manifest.json file must contain string value “library”
• the “id” value of “sap.app” part of the manifest.json file contains the library name space, “my.custom.control” in our case
• in addition to all your JS files, containing implementation of different controls, project root folder must contain library.js file
• project root folder must also contain .library file.
• if your controls use some specific CSS styles you have to create “themes” folder in the project, and then subfolders for all supported themes. Each subfolder should contain library.css file with your specific CSS-rules.

The key values of the “sap.app” part of the manifest.json would be as follows:

{
	...
	"sap.app": {
		"id": "my.custom.control",
		"type": "library",
	...
}

The resulting Web IDE project root folder should look like this:

And the library.js file should look like this:

/* global my:true */

sap.ui.define([
		"jquery.sap.global",
		"sap/ui/core/library"
	], // library dependency
	function(jQuery) {

		"use strict";

		sap.ui.getCore().initLibrary({
			name: "my.custom.control",
			version: "1.0.0",
			dependencies: ["sap.ui.core"],
			types: [],
			interfaces: [],
			controls: [
				"my.custom.control.ProductRating"
			],
			elements: []
		});

		return my.custom.control;

	}, /* bExport= */ false);

Deployment to SAP HCP

Once you set up the library project and gathered all the necessary files you now want to start developing apps which would use the new library. And here the first problem arises: how exactly you tell your newly app to use the library? And there is virtually no documentation on the matter (I tried different search requests and different sources of information to no avail, my question at stackoverflow remained unanswered until I posted the answer myself – not completely correct though).

The only phrase I could find in the SAP guide was that applications deployed to SAP HCP (HANA Could Platform) can be used for resource sharing. And further work showed it was a correct first step. It’s time to deploy the library project to the HCP. You select your library project in Web IDE, and then select menu option Deploy -> Deploy to SAP HANA Cloud Platform.

In the dialog shown next you will be presented with default values including application public name (copy it for further use) and version as in the following figure:

Most likely you should accept all the default values by pressing “Deploy” button. Immediately after deployment Web IDE will show another dialog box suggesting to register application with HCP Launchpad, however a library cannot be registered and so you have to press “Close” button:

Let’s remember that the deployed application name is “mycustomlib”.
Now that you have your library deployed to HCP it’s time to link your application to it.

Yes, you enter all the necessary dependencies into your JS controller files and appropriate name spaces into XML views, however it appears that Web IDE still does not know of existence of some shareable application where you store your library files.

To resolve this, we need to amend another configuration file found in the project root folder – neo-app.json – a.k.a. Application Descriptor File. Among other things it contains mappings from application specific paths to HCP related paths under the node “routes”.

Normally for a new porject the file neo-app.json looks as follows:

{
	"welcomeFile": "index.html",
	"routes": [{
		"path": "/webapp/resources",
		"target": {
			"type": "service",
			"name": "sapui5",
			"entryPath": "/resources"
		},
		"description": "SAPUI5 Resources"
	}, 
	{
		"path": "/webapp/test-resources",
		"target": {
			"type": "service",
			"name": "sapui5",
			"entryPath": "/test-resources"
		},
		"description": "SAPUI5 Test Resources"
	}, 
	{
		"path": "/destinations/ES4",
		"target": {
			"type": "destination",
			"name": "ES4"
		},
		"description": "ES4 Demo Service"
	}]
}

The first entry in the “routes” mapping array contains the following instruction for the Web IDE run-time: if a running app requests a resources with url starting with /webapp/resources, then the predefined service “sapui5” must be asked to provide the resource from its internal path starting with /resources.

In our case we need to tell a similar thing about our library. When mentioning our ProductRating control from the new library in some controller file the dependency string should be like this: “my/custom/control/ProductRating”. The Web IDE run-time will start searching this resource in its predefined webapp/resources folder, and so we must redirect this search to the deployed library in the HCP. Remember that by this moment we have already deployed the library to HCP under the name “mycustomlib”. Thus, the new entry in the “routes” arrays should look like this:

{
	"path": "/webapp/resources/my/custom/control",
	"target": {
		"type": "application",
		"name": "mycustomlib", 
		"entryPath": "/"
	},
	"description": "Custom control library"
}

As you might recall we stored all the library files in the project root folder and thus the “entryPath” property of the mapping has value “/”. After that you can run the App and it should correctly load resources from the deployed library.

Remember though that once you have changed something in the library files you have to redeploy library again. Next time you deploy the library the Web IDE will suggest the new version of the existing HCP application, so most probably you accept all the default values. There is no need to update App porject using the library as by default Web IDE will load resources from the most recent version of the library.

The next part will be about deployment the library to SAP ABAP Repository and proper theming configuration. Stay tuned.