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/
So far we have collected more than 20 community libraries and the project has matured quite a bit over the last months. Our initial prototype used grunt and bower to load the UI5 dependencies. Recently, we have switched all UI5Lab repositories to npm modules and the new UI5 tooling. Thanks @mlauffer, @Stermi, @WittmerJ and @Randombyte for the help!
While the old library structure still works ok, we recommend switching to the new tooling for all community libraries. Bower is deprecated and the new UI5 tools are much simpler to use than grunt.
In this guide, I will explain the simple steps to make it work based on my UI5Lab library openui5.parallax. The same code base is also used for the ui5lab.geometry template library.
Assuming you have followed our UI5Lab documentation to create your library only a few steps are required:
Let's go do it step by step...
This step is quite simple:
Package.json
Add the new @openui5 "dependencies" and remove the bower "devDependencies"
Note: If you wish to continue using Grunt, you have to adjust your Gruntfile.js a bit. You can find instructions in this commit. We don't to it here as we switch to the new UI5 tooling immediately.
Now it is time to switch the server and build tools stack as well. We need add the dev dependency to the new UI5 tooling and exchange the start and build scripts. We also add some new ui5lab metadata to the package.json. Finally, we add a ui5.yaml configuration file to the project and adjust the ignore files.
Gruntfile.js
Delete it, we don't need it anymore
Package.json
ui5.yaml
Define a library project for the UI5 tooling, apps would use type "application". This will instruct the tooling to serve resources properly and build a library preload accordingly.
Note: There is additional documentation available on GitHub if you like to do something fancy or need special treatment for your lib. For example, in my libary openui5-parallax i had to define a shim for loading the thirdparty library resources properly. Try the standard way first, if it does not work for your thirdparty dependencies, have a look at my library as a reference.
prepare.js
Add a "prepare.js" file to your root folder - this will enable the new way of loading the UI5Lab browser and fill the libraries.json file automatically with your library namespace once after installation.
.gitignore
Add the line to ignore reference to the UI5Lab browser in your project. If you deliver your library via npm, we recommend to also ignore the dist folder to not clutter your GitHub repo with duplicate files:
.npmignore
Add the lines to not accidentially publish the browser to your npm module
A browser should open with the root folder of your library. Be sure to check the library is shown in the local UI5Lab browser and the samples are working fine by checking all entry points
Browser: http://localhost:8080/test-resources/ui5lab/browser/index.html
Sample: http://localhost:8080/test-resources/openui5/parallax/sample/ParallaxScene.html
index.json
Make sure this file is located in a folder named as your library namespace, in my case "test-resources/openui5/parallax", otherwise the library cannot be displayed in the browser. Later on, we plan to get rid of this metadata file and switch complelety to package.json - but thats another story.
ParallaxScene.html
Make sure the base href is correct. By default, this is 4 times up the folder tree, but it could be different in your library depending on your namespace. This is essential as the central UI5Lab browser switches your samples to load UI5 from the CDN and defines an additional resource path for your library on the fly. If you don't define a proper <base href="...">, the sample will fail in the UI5Lab-central project.
Increase version in the package.json (1.0.x to signalize that you switched to the new tooling and conventions) and run the build on your library to create a library preload and minified files in the "dist" folder
Publish your migrated library to npm
Note: if you wish to check what will be published, run "npm pack" and check the created archive first. Don't forget deleting the generated tgz file before publishing, otherwise the tgz file will also be published 🙂
Push your changes to GitHub. If you chose to not publish to npm don't forget to also push the "dist" folder so that the optimized resources can be loaded in the UI5Lab-central project.
If you publish to npm, you need to edit the package.json in the project UI5Lab-central and update your library to your new version. If you publish to GitHub, just let us know or wait until the next build runs.
package.json
If you want to make sure everything works fine, you can test all changes locally by following the instructions in the README.md in UI5Lab-central.
That's it! Create a pull request, sit back and relax while we review your change.
I hope this guide will help migrating your libraries.
If you have an questions, hop onto Slack channel #ui5lab and let us know.
If you would rather see the delta in the code, check these three commits:
Have fun!
Michael
So far we have collected more than 20 community libraries and the project has matured quite a bit over the last months. Our initial prototype used grunt and bower to load the UI5 dependencies. Recently, we have switched all UI5Lab repositories to npm modules and the new UI5 tooling. Thanks @mlauffer, @Stermi, @WittmerJ and @Randombyte for the help!
While the old library structure still works ok, we recommend switching to the new tooling for all community libraries. Bower is deprecated and the new UI5 tools are much simpler to use than grunt.
In this guide, I will explain the simple steps to make it work based on my UI5Lab library openui5.parallax. The same code base is also used for the ui5lab.geometry template library.
Assuming you have followed our UI5Lab documentation to create your library only a few steps are required:
- Switch from bower to OpenUI5 npm modules
- Switch to the new UI5 build and development tooling
- Test the new setup and check your resource paths
- Publish the new library version to npm or GitHub
- Update the library dependency in UI5Lab-central
Let's go do it step by step...
1. Switch from bower to OpenUI5 npm modules
This step is quite simple:
- Delete the bower.json file
- Modify your package.json file to load the npm modules instead of the deprecated bower modules.
- Update your .gitignore and .npmignore and throw out those bower paths there, too.
- Finally, don't forget to update your documentation - bower install is not needed anymore in the development setup steps.
Package.json
Add the new @openui5 "dependencies" and remove the bower "devDependencies"
"dependencies": {
"@openui5/sap.f": "^1.60.0",
"@openui5/sap.m": "^1.60.0",
"@openui5/sap.ui.core": "^1.60.0",
"@openui5/sap.ui.layout": "^1.60.0",
"@openui5/themelib_sap_belize": "^1.60.0",
"parallax-js": "^3.1.0"
}Note: If you wish to continue using Grunt, you have to adjust your Gruntfile.js a bit. You can find instructions in this commit. We don't to it here as we switch to the new UI5 tooling immediately.
2. Switch to the new UI5 build and development tooling
Now it is time to switch the server and build tools stack as well. We need add the dev dependency to the new UI5 tooling and exchange the start and build scripts. We also add some new ui5lab metadata to the package.json. Finally, we add a ui5.yaml configuration file to the project and adjust the ignore files.
Gruntfile.js
Delete it, we don't need it anymore
Package.json
- Replace the scripts with the commands "ui5 serve" and "ui5 build", add the "prepare" script
- Increase your library version and the ui5lab-browser dependency to 1.0.0
- Add a section "ui5lab" and fill in namespace, icon, and display name (for future innovations)
- add the "@ui5/cli" dev dependency
{
"name": "openui5-parallax",
"version": "1.0.0",
"description": "A library wrapping parallax.js in UI5 controls to create stunning layered effects",
"private": false,
"scripts": {
"test": "echo \"Error: no test specified. Please add some.\" && exit 1",
"prepare": "node prepare",
"start": "ui5 serve -o",
"build": "ui5 build"
},
"ui5lab": {
"namespace": "openui5.parallax",
"icon": "dimension",
"displayName": "Parallax"
},
"dependencies": {
"@openui5/sap.ui.core": "^1.60.0",
"@openui5/sap.m": "^1.60.0",
"@openui5/themelib_sap_belize": "^1.60.0",
"@openui5/sap.ui.layout": "^1.60.0",
"@openui5/sap.f": "^1.60.0",
"parallax-js": "^3.1.0"
},
"devDependencies": {
"ui5lab-browser": "^1.0.0",
"@ui5/cli": "^0.2.3",
"fs-extra": "^3.0.0"
}
}ui5.yaml
Define a library project for the UI5 tooling, apps would use type "application". This will instruct the tooling to serve resources properly and build a library preload accordingly.
specVersion: '0.1'
metadata:
name: openui5-parallax
type: libraryNote: There is additional documentation available on GitHub if you like to do something fancy or need special treatment for your lib. For example, in my libary openui5-parallax i had to define a shim for loading the thirdparty library resources properly. Try the standard way first, if it does not work for your thirdparty dependencies, have a look at my library as a reference.
prepare.js
Add a "prepare.js" file to your root folder - this will enable the new way of loading the UI5Lab browser and fill the libraries.json file automatically with your library namespace once after installation.
var fs = require('fs-extra');
// copy ui5lab browser to the right location for local testing
fs.copySync('./node_modules/ui5lab-browser/dist/', './test/ui5lab/browser');
// read library namespace from package.json
var oPackage = require('./package.json');
var sNamespace = oPackage.ui5lab.namespace || "ui5lab.library";
// add library namespace to browser library list
var sBrowserLibraryFile = './test/ui5lab/browser/libraries.json';
fs.readFile(sBrowserLibraryFile, 'utf8', function (err, data) {
if (err) {
return console.log(err);
}
var result = data.replace(/\[((\r)?\n\t)*\]/m, '[\r\n\t\t"' + sNamespace + '"\r\n\t]');
fs.writeFile(sBrowserLibraryFile, result, 'utf8', function (err) {
if (err) return console.log(err);
});
});
.gitignore
Add the line to ignore reference to the UI5Lab browser in your project. If you deliver your library via npm, we recommend to also ignore the dist folder to not clutter your GitHub repo with duplicate files:
# only for testing, these resources should not be checked in
test/ui5lab/browser/.npmignore
Add the lines to not accidentially publish the browser to your npm module
# only for testing, these resources should not be delivered
test/ui5lab/browser/
dist/test-resources/ui5lab/browser/3. Test the new setup and check your resource paths
- Delete the node_modules folder and the package-lock.json if they exist
- Run "npm install" to get all new modules installed
- Run "npm start"
A browser should open with the root folder of your library. Be sure to check the library is shown in the local UI5Lab browser and the samples are working fine by checking all entry points
Browser: http://localhost:8080/test-resources/ui5lab/browser/index.html
Sample: http://localhost:8080/test-resources/openui5/parallax/sample/ParallaxScene.html
index.json
Make sure this file is located in a folder named as your library namespace, in my case "test-resources/openui5/parallax", otherwise the library cannot be displayed in the browser. Later on, we plan to get rid of this metadata file and switch complelety to package.json - but thats another story.
ParallaxScene.html
Make sure the base href is correct. By default, this is 4 times up the folder tree, but it could be different in your library depending on your namespace. This is essential as the central UI5Lab browser switches your samples to load UI5 from the CDN and defines an additional resource path for your library on the fly. If you don't define a proper <base href="...">, the sample will fail in the UI5Lab-central project.
<!DOCTYPE HTML>
<html>
<head>
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta charset="UTF-8">
<base href="../../../../">
<title>Sample - openui5.parallax.ParallaxScene</title>
<script id="sap-ui-bootstrap"
src="../../../../resources/sap-ui-core.js"
data-sap-ui-libs="openui5.parallax"
data-sap-ui-resourceroots='{
"openui5.parallax.example" : "./test-resources/openui5/parallax/sample"
}'
data-sap-ui-theme="sap_belize">
</script>4. Publish the new library version
Increase version in the package.json (1.0.x to signalize that you switched to the new tooling and conventions) and run the build on your library to create a library preload and minified files in the "dist" folder
ui5 buildPublish your migrated library to npm
npm publishNote: if you wish to check what will be published, run "npm pack" and check the created archive first. Don't forget deleting the generated tgz file before publishing, otherwise the tgz file will also be published 🙂
Push your changes to GitHub. If you chose to not publish to npm don't forget to also push the "dist" folder so that the optimized resources can be loaded in the UI5Lab-central project.
5. Update the library dependency in UI5Lab-central
If you publish to npm, you need to edit the package.json in the project UI5Lab-central and update your library to your new version. If you publish to GitHub, just let us know or wait until the next build runs.
package.json
"dependencies": {
...
"openui5-parallax": "^1.0.0"
},If you want to make sure everything works fine, you can test all changes locally by following the instructions in the README.md in UI5Lab-central.
That's it! Create a pull request, sit back and relax while we review your change.
I hope this guide will help migrating your libraries.
If you have an questions, hop onto Slack channel #ui5lab and let us know.
If you would rather see the delta in the code, check these three commits:
Have fun!
Michael
- SAP Managed Tags:
2 Comments
