ZK Component Reference/Supporting Classes/Messagebox

Messagebox

• Demonstration: Messagebox
• Java API: Messagebox
• JavaScript API: N/A

Employment/Purpose

It provides a set of utilities to show a message and have a user to confirm a situation.

It is typically used to alert users when an error occurs, or to prompt users for an decision.

Example

The simplest use of a message box is to inform the user something is done. For example,

Messagebox.show("The backup has been done.");
Messagebox.show("Failed to access the information", null, 0,  Messagebox.ERROR);

There are a lot of utilities that allow you to show a message in different look, such as the buttons, icon and title. Please refer to Messagebox for more information.

Take Actions Depending On Which Button Is Clicked

If you'd like to know which button is clicked, you have to implement an event listener. For example,

Messagebox.show("Something is changed. Are you sure?", 
	"Question", Messagebox.OK | Messagebox.CANCEL,
	Messagebox.QUESTION,
	 	new org.zkoss.zk.ui.event.EventListener(){
	 		public void onEvent(Event e){
	 			if(Messagebox.ON_OK.equals(e.getName())){
	 				//OK is clicked
	 			}else if(Messagebox.ON_CANCEL.equals(e.getName())){
	 				//Cancel is clicked
	 			}
	 		}
	 	}
	);

The invocation of Messagebox.show(String, String, int, String) will return immediately after the invocation. Then, if the user clicks a button, the event listener will be invoked. You could examine the event name to know which button is clicked. If the user clicked the Close button on the right-top corner, the onClose event is fired.

---

Listen ClickEvent

Since 6.0.0

Since ZK 6, the event listener will be invoked with an instance of Messagebox.ClickEvent, and it is easy to retrieve the button being clicked from it. For example,

Messagebox.show("Something is changed. Are you sure?", 
	"Question", Messagebox.OK | Messagebox.CANCEL,
	Messagebox.QUESTION,
	 	new org.zkoss.zk.ui.event.EventListener<ClickEvent>(){
	 		public void onEvent(ClickEvent e){
	 			switch (e.getButton()) {
	 			case Messagebox.Button.OK: //OK is clicked
	 			case Messagebox.Button.CANCEL: //Cancel is clicked
				default: //if the Close button is clicked, e.getButton() returns null
				}
	 		}
	 	}
	);

Customization

Assign the Order of Buttons

Since 6.0.0

If you'd like to assign the order, you could use Messagebox.show(String, Button[], EventListener listener) as follows.

 Messagebox.show("Cancel the operation?",
 	new Messagebox.Button[] {Messagebox.Button.NO, Messagebox.Button.YES},
 		new EventListener<Messagebox.ClickEvent>() { //optional
 			public void onEvent(Messagebox.ClickEvent event) {
 				//...
 			}
 		});

The buttons will be displayed in the same order as the array specified in the buttons argument.

If you don't care the order, you could use a combination of constants, such as Messagebox.OK. For example,

 Messagebox.show("Cancel the operation?", null, Messagebox.YES+Messagebox.NO, null);

Assign the Labels of Buttons

Since 6.0.0

By default, the label of a button is loaded from the message file based on the current locale. However, you could assign any label you'd like.

onClick='Messagebox.show("Yes and No", "Custom Labels",
	new Messagebox.Button[] {Messagebox.Button.YES, Messagebox.Button.NO},
	new String[] {"Yes, it is correct"},
	Messagebox.INFORMATION, null, null)'/>

The btnLabels argument is an array of labels you'd like to use. If it is null or the length is shorter than the array specified the buttons argument, the default label will be used.

The Default Title

If the title is not specified in the application's name (returned by WebApp.getAppName()). You could change it by invoking WebApp.setAppName(String).

Since 5.0.6, you could specify the application's name with a library property called org.zkoss.zk.ui.WebApp.name. For example, you could specify the following in WEB-INF/zk.xml:

<library-property>
    <name>org.zkoss.zk.ui.WebApp.name</name>
    <value>My Killer Application</value>
</library-property>

The Template

The UI of a message box is based on a ZUL file, so you could customize it by replacing it with your own implementation. It can be done easily by invoking Messagebox.setTemplate(String). Notice that it affects all message boxes used in an application. It is typically called when the application starts (i.e., in WebAppInit.init(WebApp) -- for more information, please refer to ZK Developer's Reference: Life Cycle Listener).

To implement a custom template, please take a look at the default template.

The Width and Parameters

Since 6.0.0

The params argument in Messagebox.show(String, String, Button[], String[], String, Button, EventListener, Map) allows you to customize a message dialog further. For example, you could make the dialog wider with the parameter called width as shown below.

Map params = new HashMap();
params.put("width", 500);
Messagebox.show("This is a very long statement and meaningless to see if it looks ok with the given width.",
 	null, null, null, Messagebox.INFORMATION, null,
	new EventListener() {
		public void onEvent(Event event) {
			//...
		}
	}, params);

The parameters will be passed to the dialog template (described in the previous section), so you could pass whatever you'd like as long as the template recognize them. In additions, the priority of the params argument is higher, i.e., it could override the default values, though it is rarely required.

Since 7.0.1 User also can customize the style of message dialog with the parameter called sclass as below.

Map params = new HashMap();
params.put("sclass", "myMessagebox");
Messagebox.show("It's a customized style message box.",
 	null, null, null, Messagebox.INFORMATION, null,
	new EventListener() {
		public void onEvent(Event event) {
			//...
		}
	}, params);

Without Buttons' Dialog

Since 6.5.1

If you'd like to show a non-buttons dialog, you could use Messagebox.show(String, Button[], EventListener listener) with an empty array as follows.

 Messagebox.show("Cancel the operation?",
 	new Messagebox.Button[0], null);

This messagebox will show without any buttons.

Supported events

Name	Event Type
None	None

Supported Children

*NONE

Use cases

Version	Description	Example Location

Version History

Version	Date	Content
6.0.0	October 2011	The order and labels of the buttons were assignable.
6.0.0	October 2011	Messagebox.ClickEvent was introduced to simplify the identification of a button.
6.5.1	September 2012	Messagebox with no button
7.0.1	January 2014	Add sclass to messagebox