Messagebox"

From Documentation
Line 73: Line 73:
 
=Customization=
 
=Customization=
 
==Assign the Order of Buttons==
 
==Assign the Order of Buttons==
  [since 6..0.0]
+
  [since 6.0.0]
  
 
If you'd like to assign the order, you could use <javadoc method="show(java.lang.String, org.zkoss.zul.Messagebox.Button[], org.zkoss.zk.ui.event.EventListener listener)">org.zkoss.zul.Messagebox</javadoc> as follows.
 
If you'd like to assign the order, you could use <javadoc method="show(java.lang.String, org.zkoss.zul.Messagebox.Button[], org.zkoss.zk.ui.event.EventListener listener)">org.zkoss.zul.Messagebox</javadoc> as follows.
Line 96: Line 96:
  
 
==Assign the Labels of Buttons==
 
==Assign the Labels of Buttons==
  [since 6..0.0]
+
  [since 6.0.0]
  
 
By default, the label of a button is loaded from [[ZK Developer's Reference/Internationalization/Warning and Error Messages|the message file]] based on the current locale. However, you could assign any label you'd like.
 
By default, the label of a button is loaded from [[ZK Developer's Reference/Internationalization/Warning and Error Messages|the message file]] based on the current locale. However, you could assign any label you'd like.

Revision as of 09:15, 13 October 2011

Messagebox

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[1]. 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[2]. 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.


  1. If you want to make it running under clustering environment, you should implement SerializableEventListener. For more information, please refer to ZK Developer's Reference: Clustering.
  2. Here we assume the event thread is disabled (default). If the event thread is enabled, the show method will suspend until the user clicks a button. Thus, you could know which button is clicked by simply examining the returned value.

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: Init and Cleanup).

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

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.



Last Update : 2011/10/13

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.