- SAP Managed Tags:
I like to write some notes down, from my findings how to implement custom tiles with in Portal service on Cloud Foundry (SCP / Cloud Platform). Unfortunately, the current documentation is limited and doesn't show a good end-to-end sample. I only could get it running with a lot of trial and error.
03/27/2020 – added end-to-end sample with one Portal, two custom tiles, one basic UI5 app as target and CAP based service as backend for the charts: https://github.com/citoki/portal-custom-tile
This is the result. You'll get a tile, where you can put in your controls of choice. In my sample below, I use two ComparisonMicroChart controls in the left tile and in the right one two HarveyBallMicroChart controls. For the first tile I used a JS-View and for the second a XML-View, just for demonstration. You can choose what fits better to your coding style.
As a starting point for a new FLP project I like to generate the necessary artefacts by the WebIDE. You can follow the steps described by iris_blog in her detailed blog: SAP Fiori launchpad site with portal service on SAP Cloud Platform
One thing which is crucial to get a minimal project running on CF (Cloud Foundry), is that the custom tile points to an existing UI5 app. That is the target app which will be defined in business app file
In my case, I called the target app like this: tutorial.app.one.app1
Now let's jump into the code!
For the new custom tile we need a separate UI5 app. There are a lot of ways to scaffold an UI5 app. One thing I can recommend is the Yo-plugin by mariusobert. He started developing the Yo plugin Generator-Easy-UI5. With that plugin you'll be fast on the track.
The only thing you need to add in the UI5 app, is the FLP configuration This tells the Portal service that the app should be handled as a Tile with a specific
Below you can see the structure we need in the end.
The configuration for the Launchpad (FLP) is done via the
This tells the FLP runtime, that there is a special visualisation for
In the same file (
The configuration and the target mapping, when clicking on the custom tile has to be made in a specific folder
And that's it. Just deploy the FLP like normal and the custom tile should appear right there.
Please read the Fiori guidelines on tiles, for further details on when to use tiles and which content should be shown.
Do not play videos in their and do not provide any interactive controls like buttons, polls, list. ?
In some use cases the OVP (Overview Page) could be the better choice.
Now, for tiles are quickly coming up questions like "How can read the data continuously every X seconds?" Well, you might have seen the dynamic tile. For that you can configure an interval to update the data in the tile. Unfortunately, there is no API to tell the Portal that your custom tile wants to hook into the events like "dashboardTileClick", "setTilesNoVisibility", "onHiddenTab". These events are managed only for DynamicTiles by DashboardLoadingManager.js.
Well, as a workaround you could handle some window/documents events by your own, like "window.blur", "window.focus" and "document.hidden".
But, that's not enough. When you have an update loop running (e.g. via
DON'T TRY THIS AT HOME or in PRODUCTION!! ?
Imagine you want to dynamically load data in you custom tile, e.g. a specific type of notifications, within the custom tile. And you don't want to create another tile app and parameterise the OData/REST call.
Then you could add just another visualisation to the business app configuration, into the
The
During debugging the custom tile, the
targetURL: "#data-display?param1=new%20param%20value1&sap-ui-app-id-hint=tutorial.app.one.app1"
Technically this is the hash/link which should be called after clicking on the custom tile.
You could now parse this string and extract the
See code sample for an End-To-End sample project: https://github.com/citoki/portal-custom-tile
Updates
03/27/2020 – added end-to-end sample with one Portal, two custom tiles, one basic UI5 app as target and CAP based service as backend for the charts: https://github.com/citoki/portal-custom-tile
This is the result. You'll get a tile, where you can put in your controls of choice. In my sample below, I use two ComparisonMicroChart controls in the left tile and in the right one two HarveyBallMicroChart controls. For the first tile I used a JS-View and for the second a XML-View, just for demonstration. You can choose what fits better to your coding style.
Contents
- Create a Starter Project
- Create a Tile App
- Tile Content
- Reading Data Continuously
- Parameterise Custom Tile via FLP Config
- Code - End-To-End Sample
Create a Starter Project
As a starting point for a new FLP project I like to generate the necessary artefacts by the WebIDE. You can follow the steps described by iris_blog in her detailed blog: SAP Fiori launchpad site with portal service on SAP Cloud Platform
One thing which is crucial to get a minimal project running on CF (Cloud Foundry), is that the custom tile points to an existing UI5 app. That is the target app which will be defined in business app file
baCustomTile.json later in this blog.In my case, I called the target app like this: tutorial.app.one.app1
Create a Tile App
Now let's jump into the code!
For the new custom tile we need a separate UI5 app. There are a lot of ways to scaffold an UI5 app. One thing I can recommend is the Yo-plugin by mariusobert. He started developing the Yo plugin Generator-Easy-UI5. With that plugin you'll be fast on the track.
The only thing you need to add in the UI5 app, is the FLP configuration This tells the Portal service that the app should be handled as a Tile with a specific
tileSize of 1x1."sap.flp": {
"type": "tile",
"tileSize": "1x1"
},tileSize currently only supports 1x1 (square tile) and 1x2 (wide rectangle tile).Fiori Launchpad Configuration
Below you can see the structure we need in the end.
flp/portal-site/CommonDataModel.json
flp/portal-site/business-apps
└── baCustomTile.json
flp/portal-site/i18n
└── i18n.propertiesThe configuration for the Launchpad (FLP) is done via the
flp/portal-site/CommonDataModel.json file. In config path "payload.catalogs.payload.viz" add following object to the viz array:File: CommonDataModel.json
viz: [{
"id": "tutorial.app.one.app1", // has to be equal to 'appId' wihtin groups
"vizId": "customTile-displayToCustom" // visualization from business app configuration
}]This tells the FLP runtime, that there is a special visualisation for
app1 available.In the same file (
CommonDataModel.json), we need to set the specific visualisation for the tile. That is done in the object path "payload.groups.payload". Just add the following code there:File: CommonDataModel.json
"viz": [{
"id": "tutorial.app.one.app1-0-1573035031268",
"appId": "tutorial.app.one.app1",
"vizId": "customTile-displayToCustom" // visualisation ID from business app configuration
}]The configuration and the target mapping, when clicking on the custom tile has to be made in a specific folder
flp/portal-site/business-apps. Just create a JSON file (in my example: baCustomTile.json) with following code:File: baCustomTile.json
{
"_version": "3.0.0",
"identification": {
"id": "tutorial.app.one.app1", // app which should be opened by the custom tile
"entityType": "businessapp",
"i18n": "i18n/i18n.properties"
},
"payload": {
"visualizations": { // multiple visualisations are possible to be defined here
"customTile-displayToCustom": { // one sample of visualization for our 'app1'
"vizType": "project.namespace.customTile", // type has to be set to the app name of our customTile
"vizConfig": {
"sap.app": {
"title": "{{notifList.tile.title}}",
"subTitle": "{{notifList.tile.subtitle}}"
},
"sap.flp": {
"target": {
"inboundId": "data-display" // inbound config for the target app 'app1'
}
}
}
}
}
}
}And that's it. Just deploy the FLP like normal and the custom tile should appear right there.
Tile Content ?
Please read the Fiori guidelines on tiles, for further details on when to use tiles and which content should be shown.
Do not play videos in their and do not provide any interactive controls like buttons, polls, list. ?
In some use cases the OVP (Overview Page) could be the better choice.
Reading data continuously
Now, for tiles are quickly coming up questions like "How can read the data continuously every X seconds?" Well, you might have seen the dynamic tile. For that you can configure an interval to update the data in the tile. Unfortunately, there is no API to tell the Portal that your custom tile wants to hook into the events like "dashboardTileClick", "setTilesNoVisibility", "onHiddenTab". These events are managed only for DynamicTiles by DashboardLoadingManager.js.
Well, as a workaround you could handle some window/documents events by your own, like "window.blur", "window.focus" and "document.hidden".
But, that's not enough. When you have an update loop running (e.g. via
setInterval() to refresh data in your custom tile, it would run the whole time. It also runs when the user has click, on a different tile, endless.Parameterise Custom Tile via FLP Config - now it's getting dirty!!
DON'T TRY THIS AT HOME or in PRODUCTION!! ?
Imagine you want to dynamically load data in you custom tile, e.g. a specific type of notifications, within the custom tile. And you don't want to create another tile app and parameterise the OData/REST call.
Then you could add just another visualisation to the business app configuration, into the
visualizations object:"customTile2-display": {
"vizType": "project.namespace.customTile2",
"vizConfig": {
"sap.app": {
"title": "{{customTile2.title}}",
"subTitle": "{{customTile2.subtitle}}"
},
"sap.flp": {
"target": {
"inboundId": "data-display",
"parameters": {
"param1" : {
"value": {
"value": "new param value1",
"format": "plain"
}
}
}
}
}
}The
parameters property is read via a readVisualizations function readVisualizations.getOutbound(). During debugging the custom tile, the
_oProperties object now has created the target URL with the configured param1 parameter:targetURL: "#data-display?param1=new%20param%20value1&sap-ui-app-id-hint=tutorial.app.one.app1"
Debug code line: https://github.com/citoki/portal-custom-tile/blob/0d91424d1f373307d49d605d66ed33f69fe7db86/app-custo...
Technically this is the hash/link which should be called after clicking on the custom tile.
You could now parse this string and extract the
param1 parameter and use this during the initialisation for the custom tile.Code - End-To-End Sample
See code sample for an End-To-End sample project: https://github.com/citoki/portal-custom-tile
16 Comments
