I’m no user expert but I often see the same kind of request on or SAP PI/CPI testing tool that we have made. The application is made in Open UI5, we started in SAP UI5 but moved to the free version once we started development on a separate Java engine. We wanted to avoid the same question and enable users to get started faster with our application. The faster they start the faster we can get paid.
A part of introducing the application to developers is to make a guide that takes them thru the different steps in the process. We see this at a lot of different places both in business and private applications. We also wanted a good guide in our application to make it faster to adopt the tool.
In this video you will find a guided tour on how to use IRT on ui5:
A tour is a guide with which will highlight some UI elements and ask a user to click on some buttons. There are plenty of libraries (free and paid) providing such a functionality. You can read about some of them here: https://pronovix.com/blog/free-and-open-source-walkme-alternatives. Some of them require programming skills, some not. We decided that we have programming skills which probably allows us to control what is going on in more flexible way. So we selected a library called Bootstrap Tour http://bootstraptour.com/. Important: despite its name, it can work without any real limitations not only on Bootstrap projects. “Not using Bootstrap? It works anyway!” - they say. It is even possible to customize an appearance of the prompt, e.g., if you don’t want to see the Prev button or want to add something to this prompt. This article is about how to integrate this library Bootstrap Tour into OpenUI5 project.
We experienced a few problems with this integration.
We created a singleton class encapsulating all the tours:
Then we can simply inject this singleton to each controller we want:
All of our tours use multiple controllers and work on different routes. Unfortunately, it seems like Bootstrap Tour is not adopted for single page applications having multiple routes. At least we don’t found an easy solution out of the box so we had to apply some workarounds.
So what is the problem? Assume you have step №0 in controller A and step №1 in controller B. Assume you assigned step №0 to a navigation button, you start your tour (in controller A), click on the button and you want to pop up step №1 (in controller B) once it will be opened. The problem is that by default Bootstrap Tour tries to switch on the next step immediately (after clicking on the button Next or on UI element itself). So by default it doesn’t wait until the markup from the next page will be loaded.
Controller A
Controller B
Possible solutions:
We decided not to use this approach because we use on<SomeButton>Click handlers for navigation where we have a custom logic and it is not clear how to connect these handers with this redirect callback and force it to work correctly.
2. Use a delay parameter
So it can just wait for some time before popping up the next prompt. This time can be used by OpenUI5 for navigating to the next route and rendering a markup.
3. Prevent a transition to the next step and execute it forcibly once markup will be ready. According to documentation, the following piece of code just prevent the next step from popping up:
Then in the controller B you need to open step №1 from your js code. We use onAfterRendering method because it’s being called once the rendering is completed.
Unfortunately, it may be called before CSS styles will have been applied so that your prompt will be shown in the wrong place of page. That is why here we decided to wait for 2 seconds as well.
As you can see, both ways that we use relates on a time constant. Obviously, it is not an ideal solution but we guess that in real life cases it will not be a big problem. Maybe users will just need to wait around 1-2 seconds. Of cause, this issue is relevant only for transitions between controllers. Tour steps inside the common controller are working fine without any workarounds. If you have some more elegant solutions, we will be really happy to know about it.
Prompts are expected to be assigned to a particular UI element. (You can also use orphan flag thanks to which a prompt will be positioned in the middle of the page, but it is not a very common case). Bootstrap Tour uses CSS selector for looking for an element. So the question here is how to write this selector considering the fact that you never know the final id of the element because OpenUI5 generates it automatically. In our understanding, there are two the most useful ways:
Then you can just use .<class-name> notation for your css selector:
Unfortunately, not all the OpenUI5 elements have a property “class”. That is why we had to find another solution.
2. Use more complicated CSS selectors based on the generated ids. Here you need to analyze your markup in the browser’s console. For example, final id of NavigationListItem element with id=” integrationObjectsNavigationListItem” will look like “__xmlview0--integrationObjectsNavigationListItem”. So the beginning of this id can be different from time to time and you can’t rely on it. But the ending of this id, we hope, will be the same all the time. In this case a CSS selector can be: “li[id$='--integrationObjectsNavigationListItem']”. So it is up to you how to configure the CSS selector. We will be happy to know other possible or more elegant ways.
Generally speaking you just need to call tour.goTo(stepNumber) method. Our startTourByName
method looks like this:
Here we take into account cases when the tour was canceled/ended. Also according to our business logic, we forcibly finish all the other tours except the started one. So this method allows us to start/restart a tour from every page we want.
I hope you liked the intro. If you want to see how we have implemented it. Check out the Figaf IRT application out, it is free to get started and then you can see it in action.
A part of introducing the application to developers is to make a guide that takes them thru the different steps in the process. We see this at a lot of different places both in business and private applications. We also wanted a good guide in our application to make it faster to adopt the tool.
In this video you will find a guided tour on how to use IRT on ui5:
A tour is a guide with which will highlight some UI elements and ask a user to click on some buttons. There are plenty of libraries (free and paid) providing such a functionality. You can read about some of them here: https://pronovix.com/blog/free-and-open-source-walkme-alternatives. Some of them require programming skills, some not. We decided that we have programming skills which probably allows us to control what is going on in more flexible way. So we selected a library called Bootstrap Tour http://bootstraptour.com/. Important: despite its name, it can work without any real limitations not only on Bootstrap projects. “Not using Bootstrap? It works anyway!” - they say. It is even possible to customize an appearance of the prompt, e.g., if you don’t want to see the Prev button or want to add something to this prompt. This article is about how to integrate this library Bootstrap Tour into OpenUI5 project.
Problems
We experienced a few problems with this integration.
- How to make a multipage tour shareable between several controllers.
- How to force Bootstrap Tour to assign a prompt to a correct UI element (because OpenUI5 generates ids automatically and you can’t really predict the whole value of id)
- How to start a tour from step № N (where N != 0).
How to make a multipage tour shareable between several controllers
We created a singleton class encapsulating all the tours:
Then we can simply inject this singleton to each controller we want:
All of our tours use multiple controllers and work on different routes. Unfortunately, it seems like Bootstrap Tour is not adopted for single page applications having multiple routes. At least we don’t found an easy solution out of the box so we had to apply some workarounds.
So what is the problem? Assume you have step №0 in controller A and step №1 in controller B. Assume you assigned step №0 to a navigation button, you start your tour (in controller A), click on the button and you want to pop up step №1 (in controller B) once it will be opened. The problem is that by default Bootstrap Tour tries to switch on the next step immediately (after clicking on the button Next or on UI element itself). So by default it doesn’t wait until the markup from the next page will be loaded.
Controller A
Controller B
Possible solutions:
- Use Path/redirect properties:
We decided not to use this approach because we use on<SomeButton>Click handlers for navigation where we have a custom logic and it is not clear how to connect these handers with this redirect callback and force it to work correctly.
2. Use a delay parameter
So it can just wait for some time before popping up the next prompt. This time can be used by OpenUI5 for navigating to the next route and rendering a markup.
3. Prevent a transition to the next step and execute it forcibly once markup will be ready. According to documentation, the following piece of code just prevent the next step from popping up:
Then in the controller B you need to open step №1 from your js code. We use onAfterRendering method because it’s being called once the rendering is completed.
Unfortunately, it may be called before CSS styles will have been applied so that your prompt will be shown in the wrong place of page. That is why here we decided to wait for 2 seconds as well.
As you can see, both ways that we use relates on a time constant. Obviously, it is not an ideal solution but we guess that in real life cases it will not be a big problem. Maybe users will just need to wait around 1-2 seconds. Of cause, this issue is relevant only for transitions between controllers. Tour steps inside the common controller are working fine without any workarounds. If you have some more elegant solutions, we will be really happy to know about it.
How to force Bootstrap Tour to assign a prompt to a correct UI element
Prompts are expected to be assigned to a particular UI element. (You can also use orphan flag thanks to which a prompt will be positioned in the middle of the page, but it is not a very common case). Bootstrap Tour uses CSS selector for looking for an element. So the question here is how to write this selector considering the fact that you never know the final id of the element because OpenUI5 generates it automatically. In our understanding, there are two the most useful ways:
- Specify a fake Class for your UI control.
Then you can just use .<class-name> notation for your css selector:
Unfortunately, not all the OpenUI5 elements have a property “class”. That is why we had to find another solution.
2. Use more complicated CSS selectors based on the generated ids. Here you need to analyze your markup in the browser’s console. For example, final id of NavigationListItem element with id=” integrationObjectsNavigationListItem” will look like “__xmlview0--integrationObjectsNavigationListItem”. So the beginning of this id can be different from time to time and you can’t rely on it. But the ending of this id, we hope, will be the same all the time. In this case a CSS selector can be: “li[id$='--integrationObjectsNavigationListItem']”. So it is up to you how to configure the CSS selector. We will be happy to know other possible or more elegant ways.
How to start a tour from step № N (where N != 0)
Generally speaking you just need to call tour.goTo(stepNumber) method. Our startTourByName
method looks like this:
Here we take into account cases when the tour was canceled/ended. Also according to our business logic, we forcibly finish all the other tours except the started one. So this method allows us to start/restart a tour from every page we want.
I hope you liked the intro. If you want to see how we have implemented it. Check out the Figaf IRT application out, it is free to get started and then you can see it in action.
- SAP Managed Tags:
