OpenUI5 Custom Control: use Javascript and CSS from external NPM library

openui5-flatpickr result

In my latest blog post I explained how to create a Custom Control from 0 to hero.

In all of these examples I always needed to wrap an external library inside a custom control. At first I always copied the latest master version of the library inside my source code and pack it with grunt-openui5.

But I was not satisfied at all. BowerJS and npm exists for a reason, they are a package manager that allow you to easily sync with a specific version of a library and upgrade it with just a command.

That’s why I tried to push grunt-openui5 (kudos to Matthias Oßwal for the huge help) to it’s limit and share with you my work. In this example we will see everything I’ve learned to create “openui5-flatpickr a stunning DatePicker for your SAPUI5 app”.

Configure NPM to install flatpickr

In our case we just have to add (to the other dependencies needed to develop and package the custom library) flatpickr version 3.0.6 (the latest one from the master repository)

Flatpickr will be downloaded and installed inside /node_modules/flatpickr/dist. In particular we are interested in

• /node_modules/flatpickr/dist/flatpickr.min.js
• /node_modules/flatpickr/dist/flatpickr.min.css

Include flatpickr.min.js in your OpenUI5 project

“./3dparty/flatpickr” is the relative path of the flatpickr.js file that will be included inside our library-preload.js file.

Include flatpickr.min.css in your OpenUI5 project

Flatpickr include also it’s own css file to customize and render the DatePicker. This was the trickiest part for me.

All your themes must be defined inside your library root package inside the subfolder themes. In our case we just defined the base theme (used by all others and merged with them).

Here’s the content inside our /themes/base/library.source.less

../../../../../flatpickr/dist/flatpickr.min.css is the relative path to the css file inside our node_modules folder

Pack it all together via grunt-openui5

openui5_theme

Builds a theme and creates the following files in the dest directory of the specified less file:

• library.css (regular css)
• library-RTL.css (mirrored css for right-to-left support)
• library-parameters.json (key-value map of all global less variables)

We’re going to take a better look at some options used in our Gruntfile.js task.

rootPaths: Root paths to use for import directives. It is useful if less files are located in separate folders but referenced as they would all be in one.

In our case we have two different rootPaths:

• src
• node_modules

The node_modules rootPaths allow us to resolve the relative import path that we have defined inside our /themes/base/library.source.less

files: tells the task where you theme files are located. ‘**/themes/*/library.source.less’ allow you to have multiple theme (base, sap_belize, sap_bluecrystal, etc…)

openui5_preload

openui5_preload is the task that allow you to pack all your code inside the library-preload.js file

resources: Resources/files that should be used as source for preload files

• cwd: Base/root directory for finding resources.
• prefix: Directory namespace prefix that should be prepended to all found paths. This is useful if the source folder structure is not the same as the module namespace.
• src: Glob pattern(s) for finding relevant resources insidecwd. If set, the default patterns will be replaced.

In our case we only had 2 resource entity, one for our main src folder (where the library source code is located) and one (more interesting) to include in the library-preload.js the flatpickr source code located inside the node_modules folder:

{ cwd: ‘ node_modules/flatpickr/dist’, src: ‘flatpickr.js’, prefix: ‘it/designfuture/flatpickr/3rdparty’ }

NB: if you take a good look, the prefix has the same path of the resource we included in our FlatDatePicker.js. That’s the trick I was talking about ;)

Grunt build: the output

When, in your terminal, type

grunt build

grunt will execute the following sub tasks (in order):

• clean: clean the distribution folder of the packed custom library
• openui5_theme: collect the custom library theme/css
• openui5_preload: pack theme and library code all toghether
• copy: copy the packed library inside our demo app (maybe I’ll move this sub task inside another task named grunt build-demo)

Below you can see the library-preload.js generated by the openui5_preload subtask.

And here’s the result of our openui5_theme subtask: for each of our openui5 theme we have 3 different compressed files.

That’s all folks!

Hope you have enjoyed this tutorial. As usual feel free to give me some feedback to improve it!