For UI5 developers maybe Demo Kit is the most useful tool. We could find many documents as well as samples. But sometimes we still have some questions that Demo Kit could not answer. So I would like to write a blog series called “Things that Demo Kit didn’t tell you“. In this series I would like to explore the controls with some other resources, e.g. source code, Fiori Guideline. Hope this series could help you and if you find any mistakes in my blog please also help to point them out. Thank you! Catalog of this series could be found here.
To be honest for a very long time, I always thought that sap.m.MessageBox is a normal control just like sap.m.Button or sap.m.Text. Until one day I tried to write something like this:
The function crashed and in the console it said that sap.m.Message is not defined. Why? I always use Button and some other controls in this way. Problem is fixed until I claimed MessageBox in the second line. Then I realized there's something different in MessageBox.
And my guess was right. MessageBox is not a control but actually a static class. As you see in the document it is a namespace.
So everywhere you want to use it, you need such a statement in the header of your controller. Then UI5 will load the source file for you. Then what is the fact of a MessageBox? The answer is a sap.m.Dialog. The MessageBox static class is just like a util, which could help the user to generate a dialog easily, which is strictly aimed to show some message.
As a static class, MessageBox provides 7 public functions: show(), alert(), confirm(), error(), information(), success() and warning(). And actually all the last 6 functions are based on the first function show(). Even you could use show() to achieve all your requirements instead of all the others, it is not recommanded to do so. You should usee the last 6 functions based on your requirements to keep the consistency.
MessageBox can do more than just showing a static message. User could have customized actions in the dialog footer. You just need to specify your action in the field "actions", MessageBox will create a Button for you automatically. In the on close function you just need to judge the action type and have your own logic.
Another thing that many people ignored is, you could have a powerful "Show Details" block in your MessageBox. I say it's powerful because besides plain text you could also have formatted content and even code formatted content. This function is very useful when you want to show some detailed information about your message. But be noticed that the "Show Details" function is only availabe in the show() function.
MessageBox is a quite flexible control, so we need some guidelines for it!
Fact of sap.m.MessageBox
To be honest for a very long time, I always thought that sap.m.MessageBox is a normal control just like sap.m.Button or sap.m.Text. Until one day I tried to write something like this:
sap.ui.define([
"sap/ui/core/mvc/Controller"
], function (Controller) {
"use strict";
return Controller.extend("myPath.MyController", {
...
myFunction: function() {
sap.m.MessageBox.show("Some Message");
}
...
});
})The function crashed and in the console it said that sap.m.Message is not defined. Why? I always use Button and some other controls in this way. Problem is fixed until I claimed MessageBox in the second line. Then I realized there's something different in MessageBox.
And my guess was right. MessageBox is not a control but actually a static class. As you see in the document it is a namespace.
So everywhere you want to use it, you need such a statement in the header of your controller. Then UI5 will load the source file for you. Then what is the fact of a MessageBox? The answer is a sap.m.Dialog. The MessageBox static class is just like a util, which could help the user to generate a dialog easily, which is strictly aimed to show some message.
Functions of MessageBox
As a static class, MessageBox provides 7 public functions: show(), alert(), confirm(), error(), information(), success() and warning(). And actually all the last 6 functions are based on the first function show(). Even you could use show() to achieve all your requirements instead of all the others, it is not recommanded to do so. You should usee the last 6 functions based on your requirements to keep the consistency.
MessageBox can do more than just showing a static message. User could have customized actions in the dialog footer. You just need to specify your action in the field "actions", MessageBox will create a Button for you automatically. In the on close function you just need to judge the action type and have your own logic.
Another thing that many people ignored is, you could have a powerful "Show Details" block in your MessageBox. I say it's powerful because besides plain text you could also have formatted content and even code formatted content. This function is very useful when you want to show some detailed information about your message. But be noticed that the "Show Details" function is only availabe in the show() function.
Guidelines of MessageBox
MessageBox is a quite flexible control, so we need some guidelines for it!
Error MessageBox
- Do not use Error MessageBox, if the error message could be shown in a form element. E.g. use "valueState=Error and valueStateText=Error Message" in a sap.m.Input to tell the user, that the input value is invalid.
- Do not just describe the problem; tell the user how to resolve it.
- In the short text, speak the language of the end user. Do not include system or configuration details.
- If the solution is more involved or technical, add a long text.
- Do not repeat the short text in the long text. They both appear together on the screen.
Warning MessageBox
- If no decision is needed. Then just show an OK button.
- If the user need to decide continue or not, show OK and Cancel buttons.
- If user could have some special action, show it as a custom action button.
Success MessageBox
- Normally we don't show a Success MessageBox to tell the user his actions succeed. Insteadly we use a sap.m.MessageToast. Since it will disappear automatically and do not need user's additional action.
- SAP Managed Tags:
