Skip to Content
Author's profile photo Sergei Korolev

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.

Assigned Tags

      19 Comments
      You must be Logged on to comment or reply to a post.
      Author's profile photo Andreas Kunz
      Andreas Kunz

      Nice! Great to see you got it working based on the very limited documentation!

      You wondered why it's ok to use the root folder of your project instead of establishing a folder structure that reflects the control namespace. I think this is due to your new entry in the neo-app.json file: it maps this deep folder structure where UI5 is looking for your control to the root folder in your new "library app".
      An alternative would be to use "registerModulePath" for your library namespace or Core.loadLibrary(...) to do the same mapping within the app(s) using the library (= tell UI5, where this library/namespace can be found).

      Author's profile photo Sergei Korolev
      Sergei Korolev
      Blog Post Author

      Hi Andreas,
      Thanks for commenting. Actually Web IDE works fine if you create the folder hierarchy according to the library name space and then change respective entryPath in the neo-app.json. It was a problem with SAP ABAP Repository deployment which made me put all the library files into the root folder. Will show this in the next part.

      Author's profile photo Pierre Dominique
      Pierre Dominique

      Great post Sergey! I was actually looking for a good way to achieve this. I started playing with git submodules for our library but I quickly realized that the Web IDE doesn't support them.

      @Andreas > could you update the official documentation with the steps we should follow to properly develop, publish and then use a custom control library?

      Author's profile photo Sergei Korolev
      Sergei Korolev
      Blog Post Author

      Thanks Pierre!

      Author's profile photo Helmut Tammen
      Helmut Tammen

      Thanks Sergey for this great insight.

      I have one additional question though. The routing to another deployed app works on HCP by means of neo-app.json. Which is the corresponding descriptor on an ABAP system?
      I would like to deploy and reuse my own library in several Fiori apps on an ABAP Frontend server.

      Author's profile photo Sergei Korolev
      Sergei Korolev
      Blog Post Author

      Hi Helmut,

      I just published the Part 2 of the adventure, which is about my exercises with SAP ABAP server.

      Author's profile photo Helmut Tammen
      Helmut Tammen

      Thanks Sergey. I already noticed it and will have a look at it soon.

      Author's profile photo Mudit Kumar
      Mudit Kumar

      Hello,

      Can we deploy this library to fiori launch pad

      Author's profile photo Sergei Korolev
      Sergei Korolev
      Blog Post Author

      Hello Mudit,

      To my understanding Fiori launchpad is a facility to start an application of virtually any kind accessible through a URL. Library is not an app, it cannot be "started", it's just a set of objects which can be used by various apps. So, I am afraid I don't quite understand what you need.

      Author's profile photo Mudit Kumar
      Mudit Kumar

      Hello Sergey,

      Actually I have developed an application in webide which is referring to a library which we have developed in webide only. Now I have to deploy my application to HCP and later register this application in Fiori Launch Pad. I deployed my consumer App to HCp. I deployed my library to HCP . What changes do i need to do in configuration files of consumer App so that it can access library deployed in HCP.

      Same requirement is for FLP. What changes needed to be done in Conusmer App(like adding destionations or path) so that it can consume Librray deployed to FLP. Again how to deploy a library to FLP. I assume we would be needing component.js file to deploy a library to flp.

       

       

       

       

      My requirement is that I need to have some library which can be integrated to the Apps running on Firoi Launch Pad.

      Author's profile photo Sergei Korolev
      Sergei Korolev
      Blog Post Author

      Hi Mudit,

      Did you try amending "routes" node of neo-app.json file of your app as suggested in the "Deployment to HCP" part (see above)? Actually I only worked with on-premise deplyment and checked HCP deployment only while developing and testing app in the Web IDE. I did not try to deploy my app to HCP.

      Author's profile photo Mudit Kumar
      Mudit Kumar

       

      Hi Sergey,

      Yes I tried amending routes node of neo -app.json file.  Actually when I try to deploy the Library created in Web ide it says some Error and says to Build the Library using Maven and then deploy to HCP.

      I am stuck at how to deploy the library to HCP.

      Author's profile photo Mudit Kumar
      Mudit Kumar

      How will an Application which is deployed to HCP, can consume the library deployed to HCP ?

      Author's profile photo Mudit Kumar
      Mudit Kumar

      Hello Sergey,

      I got a way to deploy the Library to HCP.

      How are you accessing ProductRating from your Library in Consuming application. Can you please tell me the syntax to do it.

       

      Author's profile photo Sergei Korolev
      Sergei Korolev
      Blog Post Author

      Hi Mudit,

      Good to know.  To use your newly deployed library you should add en entry into “routes” array into neo-app.json file. The entry looks like this:

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

      here “path” is the path you use in the dependency definition of your controller JS file. “name” in “target” clause contains the name under which you deployed the library into HCP. See in the text above the paragraph starting with “In our case we need…

      Author's profile photo Mudit Kumar
      Mudit Kumar

      Hi  Sergey,

      I was able to access the library from HCP.

      However I am not able to access the library when I deploy the consuming application to FLP launchpad. It gives some error. Can you tell me how to make this thing work for applications deployed to FLP

      Author's profile photo Dashrath Singh
      Dashrath Singh

      Hi Sergey,

      It's really a great blog. Thanks for sharing your knowledge with us.

      But I got stuck in initial configuration. I couldn't get how did you create your project. Did you create it using standard templates like SAP UI5 application or did you just create a folder and inside that you created all these files(eg:manifest.json, project.json etc.)?

      It would be better if you can share your code with me. If not possible, please share .project.json file code.

      Thanks a lot.

      Dashrath 

      Author's profile photo Sergei Korolev
      Sergei Korolev
      Blog Post Author

      Hi Dashrath,

      I did not use any template. I created a new project and placed all the library files into the project root folder.

      You can right-click on the Workplace in the left pane of the Web IDE and then select New -> Folder.

      Next you can right-click on the new folder and enter a Project settings. As soon as you save the settings the Web IDE would create some project files (rudimentary though).

      After that you should create manifest.json file. The one I use in my library looks as follows:

      {
      	"_version": "1.4.0",
      	"sap.app": {
      		"id": "you-library-name like com.mylib",
      		"type": "library",
      		"title": "{{appTitle}}",
      		"description": "{{appDescription}}",
      		"applicationVersion": {
      			"version": "1.0.0"
      		},
      		"_version": "1.4.0",
      		"ach": "MY-UI5-CON"
      	},
      	"sap.ui": {
      		"_version": "1.4.0",
      		"technology": "UI5",
      		"deviceTypes": {
      			"desktop": true,
      			"tablet": true,
      			"phone": true
      		},
      		"supportedThemes": ["sap_hcb", "sap_bluecrystal", "sap_belize"]
      	},
      	"sap.ui5": {
      		"resources": {
      			"css": []
      		},
      		"dependencies": {
      			"minUI5Version": "1.38.9",
      			"libs": {
      				"sap.m": {
      					"minVersion": "1.38.9"
      				},
      				"sap.ui.core": {
      					"minVersion": "1.38.9"
      				}
      			}
      		},
      		"contentDensities": {
      			"compact": true,
      			"cozy": true
      		}
      	}
      }
      Author's profile photo Dashrath Singh
      Dashrath Singh

      Hi Sergey,

      It's working perfectly fine. I am calling this library in another project and it is fabulous.

      Thanks a lot.

      Keep posting.

      Regards,
      Dashrath