Skip to content

Latest commit

 

History

History
126 lines (80 loc) · 9.15 KB

readme.md

File metadata and controls

126 lines (80 loc) · 9.15 KB
Raw

UI5 Library Playground

This is a playground repository for learning (learning-by-doing) and understanding UI5 libraries. To be more specific custom UI5 control and theme libraries.

When creating this monorepository I have looked through several resources mainly @vobus ui5-webcomponent-showcase. As this is the first real monorepository of mine it was a bit of a learning curve but I enjoyed it.

In a few examples from @vobu or @matz3 you can see them use yarn (for workspace linking) and it works quite well. If you're unsure whether or not the UI5 tooling is picking up on your dependencies, execute the ui5 tree command and check if your dependency gets picked up.

I'm well aware that it does look a bit like a copy of @vobus showcase repository (it isn't, I actually created the files myself 👀). I used it as main example and wanted to learn not only yarn but also rollup.js and the combination of ui5 webcomponents with ui5 custom controls and ui5 custom libraries. Of course ... mainly the library part but it was the mixture of everything combined that made it enjoyable to learn. In addition to that it was the first time using "basic" things like npm-watch. Sounds basic? What can I say, I didn't know it exists and mainly develop in ABAP during the daytime. 😂

Other ways of getting external resources working in your application

  • For example using the resourceRoots attribute within the manifest.json or index.html file. This is especially then useful when you added the external library/dependency as actual files into your application folder (e.g. actually creating a thirdparty folder and putting the files in there).

  • Another option of adding external (non-UI5, 3rd party) dependencies would be via the usage of Project-Shims in tandem to adding the dependencies to the package.json as seen in this example in addition to the usage of the sap.ui.loader.config to provide a Runtime-Shim before your actual sap.ui.require statement (to not pollute global scope at dev-time)as seen here or here.

Best Practices

This repository does not necessarily include all the latest best practices. I strongly recommend visiting the UI5 Community Org. on github for current and up to date best practice examples/showcases and templates aswell as the recommended documentation. Check out an example Library here.

Using this Repository

Initialize the Repository

The wrapper commands mentioned here are all to be run within the root of the repository. Alternatively you can of course directly run the wrapped commands each inside their respective project folders.

# Setup the repository within the root and do all the dependency linking.

$> yarn

Building the Library Resources

# The UI5 application pulls the library resources from the `dist` folder.
# In order to make that work, we first need to build our resources.
# To do so execute the following scripts:

$> yarn ctrllib:build 

# or

$> yarn themelib:build

Developing a Library

# In order to not have to manually rebuild the libraries after each change use:

$> yarn ctrllib:dev

# or

$> yarn themelib:dev

Starting or Building the UI5 Application

# The UI5 applications helps to demonstrate the consumption of the libraries.
# You can either run it in development mode or build it and run it from the `dist` folder. 
# Either way, make sure to have the libraries it consumes built first.

# To just start the application use:
$> yarn ui:start:dev

# To build both libraries and start the application use:
$> yarn ui:init:start:dev

# Run the build process of both libraries and the aplication & start the built application:
$> yarn ui:init:start:build

Question & Answer

Q: Why are there different .yaml files in the folders?

The ui5.yaml is the file that gets pulled in (read) by the UI5 tooling. In there we specify which resources we want the UI5 tooling to use. Those are the final, built resources (the ones you'd share via npm for example). While the ui5-dev.yaml is being used to create the library or application build.

Q: Why do we need rollup.js in the control library?

Someone has to resolve the ES6 modules for us and pre-bundle them so they're ready for consumption via UI5. Ever tried using ES6 modules without a bundler? Check out this blog post by @christian. For already build/bundled (non ES6) assets we can use Project-Shims, as mentioned earlier.

Q: Is a Renderer.js file necessary?

Generally speaking it isn't. It does however make the library more readable and clearly seperated. Head over to ui5-webcomponent-showcase for a more elaborate example repository.

Q: How does the yarn linking (workspace) work?

It only works for private packages so you have to define the private attribute in all of your package.json files. Having done that, you define the workspace attribute in the root of your poject. After that you should be all set and just typing in yarn should do the trick for ya.

Q: Why are the project-, module- and application IDs so ... weird?

Well... I suck at naming things. 😂

Q: Is the .library file necessary for a library?

I wouldn't say so. It is one way for the UI5 tooling to retrieve information (for e.g. the build process) about your project but It's not necessary. The UI5 tooling mainly takes it's information from the manifest.json file. In case you don't have a manifest.json but a .library file, the tooling will pull needed information from the .library file and generate a .manifest.json file during the build process for you.

Thanks!

I really highly appreciate all the examples out there. Sadly a lot of information regarding libraries are quite outdated so some of it can feel a bit of detective work, especially when you want to get it "right". Therefore I linked lots of resources that I used right below 🔽🔽. I'm definitely not saying that I'm currently doing it right, there is lots of room for improvement - don't get me wrong. ☺

Credits / Resources