The Fastest Way to Get Started with UI5 Web Components
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.
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.
<!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-button, ui5-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:
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!
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.
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:
Or try out Hebrew to see RTL being derived from the language:
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.
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.