UI5Lab is a community driven project to establish a repository for UI5 Custom Control Libraries. It is meant to gather forces throughout the community and enable everyone to use UI5 Custom Controls easily. More information about UI5Lab can be found here: http://ui5lab.io/
In this community driven project everyone can share his own UI5 custom controls. To do this, you need to wrap your UI5 control in a library. You can do this by following the following steps.
I will use webstorm to create my library, but you can use your own IDE.
You can always use this Github repository as a base for you UI5Lab Library: https://github.com/UI5Lab/UI5Lab-library-simple
The result of this blog can be found here: https://github.com/lemaiwo/UI5Lab-library-space
When you finished this part, you can share your UI5 Library to UI5Lab: https://blogs.sap.com/2018/03/02/add-your-ui5-library-to-ui5lab/
Let’s start!
Create a new project and give it a name/location. I will call my library: “UILab-library-space”. I use the same name for my project.
The created project is completly empty, so let’s create a first folder. Your UI5 control should be placed in a “src” folder. Be aware that the folder structure should be aligned with your namespace. For example, I want to use the namespace “ui5lab.wl.space” for my control, then I need the folder structure “ui5lab/wl/space” in the “src” folder. “src” is in this case the root folder.
You should have something like this:
Inside the lowest folder (“space”), I can now create my own UI5 Control:
This is how my UI5 control looks like with the metadata and all the functions. I’m using a setter for each property, so the control wouldn’t rerender after one of these properties changes.
Also create a file for the renderer in the same folder. The renderer should have the same name as the UI5 control but with “Renderer” behind it.
In the renderer, you can use JavaScript to write html to the DOM, you can find the complete code here: https://github.com/lemaiwo/UI5Lab-library-space/blob/master/src/ui5lab/wl/space/IntroRenderer.js
If you need to add css to your control, then you must add it into the css files for each theme. Create a themes folder with a subfolder for each SAPUI5 theme (that you want to support) in the same location as your control. Add a “library.source.less” file for each theme.
I’ll use one and the same less file for the css of my UI5 control. I created a less file in the folder “themes” and will include this less file in the library less files.
In the library “less” file of the base theme I include the less file of my own UI5 control “Intro.less”. Also for every theme, you must include the original SAPUI5 less files. Look out for the “../” before the path. This depends on how long your namespace/folder structure is. It should go up till the root folder “src”.
I’m using images in my UI5 control, therefore I’ve created a folder images which I can access from in my less file.
You can find the less files here: https://github.com/lemaiwo/UI5Lab-library-space/tree/master/src/ui5lab/wl/space/themes
For making this control accessible as part of a library, we need to add the following two files:
In “library.js” we list all the controls that are part of the library and return the name of the library.
You can copy the code from here: https://github.com/lemaiwo/UI5Lab-library-space/blob/master/src/ui5lab/wl/space/library.js
The “.library” files is need to make it function as a library. Define the dependencies and the name of the library.
Code: https://github.com/lemaiwo/UI5Lab-library-space/blob/master/src/ui5lab/wl/space/.library
We would also like to see if the control works. Therefore, you must create a “test” folder. Start with adding a file “library.json” to this folder. In this file, you must enter the name of your library.
In the test folder you must create the same folder structure as in your library and add an additional folder “sample”. In my example I added a folder images to store images that I’m using in my example. In the “sample” folder we can create our example, in my case “SpaceIntro.html”
The complete code of my example: https://github.com/lemaiwo/UI5Lab-library-space/blob/master/test/ui5lab/wl/space/sample/SpaceIntro.h...
In the example you have two possibilities. You can either choose to add a base href so you don’t have to add “../” before the “sap-ui-core.js” in the bootstrap code. In my example I don’t use the base because I want use “getModulePath” to fetch my image. Otherwise, I would have the wrong url for my image.
Here I just add my control to the content to show that it works.
We have created our control, added it into a library and created a test script. Now we just have to add configuration files to build the library. Therefor we add the follwing files:
Your project should look like this:
Copy Gruntfile from the central simple example and change library name:
https://github.com/UI5Lab/UI5Lab-library-simple/blob/master/Gruntfile.js
Always start from the files in the Simple example, this will most likely contain the latest updates regarding UI5Lab.
I disabled the “lint” task in grunt because it gave me some warnings that blocked the Grunt process. If it doesn’t give you any warning/error, you can skip this step.
Copy package.json and change library name:
https://github.com/UI5Lab/UI5Lab-library-simple/blob/master/package.json
Copy bower file and change library name:
https://github.com/UI5Lab/UI5Lab-library-simple/blob/master/bower.json
From the moment that you have create the package.json, you’ll get this message in Webstorm. (that’s why I prefer webstorm). You can now click on it and it will run the command “npm install”.
If you missed the message or you’re using another ide, you can still start this command via command line. In Webstorm, you can just open the run view and just click run. (Again one of the reasons that I prefer Webstorm)
After npm has installed all the requires packages, go to the “Terminal” view and run the command “npm start”, this will start the default grunt task (this action is defined in the package.json). This can alse be done from another command line tool:
Now we can test our UI5 control with the test page:
http://localhost:8080/test-resources/ui5lab/wl/space/sample/SpaceIntro.html
http://localhost:8080/test-resources/<namespace>/sample/<demopage>.html
For sharing the UI5 library with UI5Lab we need to add it to Github. Create a new Github repository
Give it the same name as the name of the library. Also add readme and a preferred license.
Go back to your IDE (Webstorm in my case) and add the file “.gitignore” with the following lines in it:
After that, push your project to the repository that you just created in Github.
Follow the steps https://help.github.com/articles/adding-an-existing-project-to-github-using-the-command-line/ here to add your project to Github but do a pull like this before the push:
git pull origin master --allow-unrelated-histories
If you go back to github, your repository will look like this:
Now we can update the git url in the package.json. The name that we use in the “package.json” will be used to add the library to UI5Lab later.
And add the index.json for npm
We need the “index.json” to configure our example in the UI5Lab browser. Use the same name as the name of your library, give it an icon, name, description, … pretty straightforward. Just be aware that the “id” of the sample should be the same as the filename of the example.
Code: https://github.com/lemaiwo/UI5Lab-library-space/blob/master/test/ui5lab/wl/space/index.json
Run the command “Grunt build”, this will update the “dist” folder. You could also run “npm start” again, but that will also start a local webhost which we don’t need.
In the end, your project will look like this:
Commit and push the last changes to git and you’re done!
You just created a UI5 library that is ready to share with UI5Lab.
In this community driven project everyone can share his own UI5 custom controls. To do this, you need to wrap your UI5 control in a library. You can do this by following the following steps.
I will use webstorm to create my library, but you can use your own IDE.
You can always use this Github repository as a base for you UI5Lab Library: https://github.com/UI5Lab/UI5Lab-library-simple
The result of this blog can be found here: https://github.com/lemaiwo/UI5Lab-library-space
When you finished this part, you can share your UI5 Library to UI5Lab: https://blogs.sap.com/2018/03/02/add-your-ui5-library-to-ui5lab/
Let’s start!
Create a new project
Create a new project and give it a name/location. I will call my library: “UILab-library-space”. I use the same name for my project.
Create your control
The created project is completly empty, so let’s create a first folder. Your UI5 control should be placed in a “src” folder. Be aware that the folder structure should be aligned with your namespace. For example, I want to use the namespace “ui5lab.wl.space” for my control, then I need the folder structure “ui5lab/wl/space” in the “src” folder. “src” is in this case the root folder.
You should have something like this:
Inside the lowest folder (“space”), I can now create my own UI5 Control:
This is how my UI5 control looks like with the metadata and all the functions. I’m using a setter for each property, so the control wouldn’t rerender after one of these properties changes.
sap.ui.define(['sap/ui/core/Control', './library'],
function(Control, library ) {
"use strict";
var oIntro = Control.extend("ui5lab.wl.space.Intro", {
metadata: {
library : "ui5lab.wl.space",
properties: {
intro: "string",
title: "string",
text: "string",
logo: "string"
},
events: {}
},
init: function () {
},
onAfterRendering: function(evt) {},
setIntro: function(value) {
this.setProperty("intro", value, true);
return this;
},
setTitle: function(value) {
this.setProperty("title", value, true);
return this;
},
setText: function(value) {
this.setProperty("text", value, true);
return this;
},
setLogo: function(value) {
this.setProperty("logo", value, true);
return this;
}
});
return oIntro;
});Also create a file for the renderer in the same folder. The renderer should have the same name as the UI5 control but with “Renderer” behind it.
In the renderer, you can use JavaScript to write html to the DOM, you can find the complete code here: https://github.com/lemaiwo/UI5Lab-library-space/blob/master/src/ui5lab/wl/space/IntroRenderer.js
Add theming to your control
If you need to add css to your control, then you must add it into the css files for each theme. Create a themes folder with a subfolder for each SAPUI5 theme (that you want to support) in the same location as your control. Add a “library.source.less” file for each theme.
I’ll use one and the same less file for the css of my UI5 control. I created a less file in the folder “themes” and will include this less file in the library less files.
In the library “less” file of the base theme I include the less file of my own UI5 control “Intro.less”. Also for every theme, you must include the original SAPUI5 less files. Look out for the “../” before the path. This depends on how long your namespace/folder structure is. It should go up till the root folder “src”.
I’m using images in my UI5 control, therefore I’ve created a folder images which I can access from in my less file.
You can find the less files here: https://github.com/lemaiwo/UI5Lab-library-space/tree/master/src/ui5lab/wl/space/themes
Make it function as a Library
For making this control accessible as part of a library, we need to add the following two files:
- .library
- js
In “library.js” we list all the controls that are part of the library and return the name of the library.
You can copy the code from here: https://github.com/lemaiwo/UI5Lab-library-space/blob/master/src/ui5lab/wl/space/library.js
The “.library” files is need to make it function as a library. Define the dependencies and the name of the library.
Code: https://github.com/lemaiwo/UI5Lab-library-space/blob/master/src/ui5lab/wl/space/.library
Create an example to test your Control
We would also like to see if the control works. Therefore, you must create a “test” folder. Start with adding a file “library.json” to this folder. In this file, you must enter the name of your library.
In the test folder you must create the same folder structure as in your library and add an additional folder “sample”. In my example I added a folder images to store images that I’m using in my example. In the “sample” folder we can create our example, in my case “SpaceIntro.html”
The complete code of my example: https://github.com/lemaiwo/UI5Lab-library-space/blob/master/test/ui5lab/wl/space/sample/SpaceIntro.h...
In the example you have two possibilities. You can either choose to add a base href so you don’t have to add “../” before the “sap-ui-core.js” in the bootstrap code. In my example I don’t use the base because I want use “getModulePath” to fetch my image. Otherwise, I would have the wrong url for my image.
Here I just add my control to the content to show that it works.
Configure the library build process
We have created our control, added it into a library and created a test script. Now we just have to add configuration files to build the library. Therefor we add the follwing files:
- json
- bower is a package manager for web application. This will load the openui5 libraries that we need in our library or test script
- https://bower.io/
- js
- Grunt is a task runner that we use to create productive version of the library. It will, for example, create a preload version of the complete library.
- https://gruntjs.com/
- json
- This file contains the configuration that we need for NPM. NPM will install all the packages/tools that we need in our project, like bower and grunt.
- https://docs.npmjs.com/getting-started/using-a-package.json
Your project should look like this:
Copy Gruntfile from the central simple example and change library name:
https://github.com/UI5Lab/UI5Lab-library-simple/blob/master/Gruntfile.js
Always start from the files in the Simple example, this will most likely contain the latest updates regarding UI5Lab.
I disabled the “lint” task in grunt because it gave me some warnings that blocked the Grunt process. If it doesn’t give you any warning/error, you can skip this step.
Copy package.json and change library name:
https://github.com/UI5Lab/UI5Lab-library-simple/blob/master/package.json
Copy bower file and change library name:
https://github.com/UI5Lab/UI5Lab-library-simple/blob/master/bower.json
From the moment that you have create the package.json, you’ll get this message in Webstorm. (that’s why I prefer webstorm). You can now click on it and it will run the command “npm install”.
If you missed the message or you’re using another ide, you can still start this command via command line. In Webstorm, you can just open the run view and just click run. (Again one of the reasons that I prefer Webstorm)
Test your library
After npm has installed all the requires packages, go to the “Terminal” view and run the command “npm start”, this will start the default grunt task (this action is defined in the package.json). This can alse be done from another command line tool:
Now we can test our UI5 control with the test page:
http://localhost:8080/test-resources/ui5lab/wl/space/sample/SpaceIntro.html
http://localhost:8080/test-resources/<namespace>/sample/<demopage>.html
Share it on Github
For sharing the UI5 library with UI5Lab we need to add it to Github. Create a new Github repository
Give it the same name as the name of the library. Also add readme and a preferred license.
Go back to your IDE (Webstorm in my case) and add the file “.gitignore” with the following lines in it:
After that, push your project to the repository that you just created in Github.
Follow the steps https://help.github.com/articles/adding-an-existing-project-to-github-using-the-command-line/ here to add your project to Github but do a pull like this before the push:
git pull origin master --allow-unrelated-histories
If you go back to github, your repository will look like this:
Configure your Library for UI5Lab
Now we can update the git url in the package.json. The name that we use in the “package.json” will be used to add the library to UI5Lab later.
And add the index.json for npm
We need the “index.json” to configure our example in the UI5Lab browser. Use the same name as the name of your library, give it an icon, name, description, … pretty straightforward. Just be aware that the “id” of the sample should be the same as the filename of the example.
Code: https://github.com/lemaiwo/UI5Lab-library-space/blob/master/test/ui5lab/wl/space/index.json
Run the command “Grunt build”, this will update the “dist” folder. You could also run “npm start” again, but that will also start a local webhost which we don’t need.
In the end, your project will look like this:
Commit and push the last changes to git and you’re done!
You just created a UI5 library that is ready to share with UI5Lab.
- SAP Managed Tags:
1 Comment
