Technology Blogs by SAP
Learn how to extend and personalize SAP applications. Follow the SAP technology blog for insights into SAP BTP, ABAP, SAP Analytics Cloud, SAP HANA, and more.
cancel
Showing results for 
Search instead for 
Did you mean: 
10,648
2021 Update: Check out the newer blog post for an even faster way to start with UI5 Web Components - featuring automatic project creation and a production build with the same effortless development workflow.

It has been almost two months since the initial release of UI5 Web Components and the amount of positive feedback and interest has been phenomenal. There were however questions on how to most easily try out the brand new web components. It is not quite obvious how to consume a client side library from NPM and what setup is needed, especially for people with openui5 background where a CDN hosted version is available. People have been asking if there is a CDN based version of the web components and where to find it for a simple jquery-like usage.



A goal from the start of the project has been to follow modern best practices in shipping code and the UI5 web components are published as ES6 modules on NPM. The intention is for everyone who wants to use them to create their own bundle. This way, each application will get an optimal bundle containing only the web components that it uses. Compare this to a huge bundle containing all web components hosted on CDN, where most applications only use a small fraction (or even just one) of all web components in such a bundle. This is a big performance anti-pattern, but the usage via NPM is still non-intuitive for newcomers. This blog post aims to give you the easiest way for getting started with UI5 web components locally.

Prerequisites


You will need to download and install Node.js for all commands in this article.

Creating the project structure


Start up a terminal or command prompt and enter the following commands:
$ mkdir ui5-webcomponents-starter
$ cd ui5-webcomponents-starter
$ npm init -y

This will create an empty Node.js package that can consume the UI5 Web Components.
Next, add an html and javascript file containing the code for using UI5 Web Components.

src/index.html
<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
</head>
<body>
<ui5-button>Hello World</ui5-button><br><br>
<ui5-textarea placeholder="Type some text" max-length="8" show-exceeded-text></ui5-textarea><br><br>
<ui5-datepicker style="width: 180px"></ui5-datepicker><br><br>

<script src="./main.js"></script>
</body>
</html>

In this file, we are using the ui5-buttonui5-textarea and ui5-datepicker to highlight four specific functionalities (described later) that you get for free when using UI5 web components. We also include a script tag for main.js which contains our application with the following content:

src/main.js
import "@ui5/webcomponents/dist/Button";
import "@ui5/webcomponents/dist/TextArea";
import "@ui5/webcomponents/dist/DatePicker";

To get the code of UI5 Web Components included in our project, we add ES6 Module import statements as described in the documentation of each component.



Installing UI5 Web Components as a project dependency


$ npm install @ui5/webcomponents --save

This command will download the source code of @ui5/webcomponents which are distributed as a Node.js package, and put it in the node_modules folder which will be necessary for the next step.

Starting a development server


By far the easiest way to start a development server is using the zero-configuration bundler Parcel.


You can install parcel globally (you only need to do this once).



$ npm install -g parcel

Then simply run parcel by pointing it to HTML file and voilà - open the URL shown in the output to see your first app running.



$ parcel src/index.html
Server running at http:// localhost:1234
Built in 3.84s.


What happens under the hood is that parcel finds the main.js file included from our index.html, then follows the import statements it finds there and looks up the actual code of the UI5 web components from the node_modules folder. Then a single JS bundle is created (similar to a openui5 CDN hosted bundle) and a static web server is started so this dynamically generated bundle is served to the browser locally.


And that's it. You can now import any UI5 web component like the <ui5-input> by following the instructions on its documentation page: ui5-input sample and API documentation. Just add the import inside src/main.js and use it either declaratively in index.html or programatically via the DOM APIs inside src/main.js. What is cool about using Parcel as a development server, is that it watches the source files for changes, automatically recreates the bundle and reloads the page on any change. You don't event need to hit refresh in the browser.



Things to try out


All UI5 web components implement the standard themes supported by SAP products. The default theme is Fiori 3 (technical name sap_fiori_3), but you can also try out Belize and High Contrast Black by using a URL parameter:




Note: URLs work only if you are following the examples locally!



Belize: http://localhost:1234?sap-ui-theme=sap_belize



High Contrast Black: http://localhost:1234?sap-ui-theme=sap_belize_hcb




Note: The application is responsible for setting the background color of the document for HCB, so it can look as in the image above.


The other cool feature that is supported by all web components is internationalisation (or i18n). Any web component that shows text (like the "8 characters remaining" text of the `<ui5-textarea>`) or the day and month names of the date picker can also be changed by URL parameter. Go ahead and try German:





Next up, as part of the enterprise readiness of the web components, there is full support for right to left languages. You can try it out either by parameter, or automatically for languages that are RTL. Go ahead and open the datepicker in RTL mode:


http://localhost:1234/?sap-ui-rtl=true


Or try out Hebrew to see RTL being derived from the language:


http://localhost:1234/?sap-ui-language=he





Finally, there is a global configuration setting that makes the components appear more compact. This is good for desktop based applications that contain a lot of data on the screen, vs the default cozy appearance which is suitable for both mobile and desktop.


http://localhost:1234/?sap-ui-compactSize=true




What's next


In a future blog post, we will explore how to create a production-ready bundle out of this starter project.


So stay tuned and happy coding. Don't forget to check out the other available web components in the playground. Also give the project a star on github if you'd like to show your appreciation for our work so far. Feel free to open an issue on github for any problems, suggestions or improvements you might want to see.

14 Comments