From Documentation

(Difference between revisions)
Jump to: navigation, search
m (properties)
Line 3: Line 3:
= Button =
= Button =
*Demonstration: [ Button] and [ Fileupload]
*Demonstration: [ Button] and [[Small_Talks/2009/July/ZK_5:_New_File_Upload#Live_Demo |Fileupload]]
*Java API: <javadoc>org.zkoss.zul.Button</javadoc>
*Java API: <javadoc>org.zkoss.zul.Button</javadoc>
*JavaScript API: <javadoc directory="jsdoc">zul.wgt.Button</javadoc>
*JavaScript API: <javadoc directory="jsdoc">zul.wgt.Button</javadoc>

Revision as of 06:41, 17 December 2010




You could assign a label and an image to a button by the label and image properties. If both are specified, the dir property control which is displayed up front, and the orient property controls whether the layout is horizontal or vertical.

Within ZK 5, the file upload has been redesigned so it can be integrated with any widget. For example, The button can now be used to upload a file. In addition to this, the display of the upload status has been enhanced and can be customized easily.


ZKComRef Button.jpg

	<button label="Left" image="/img/network.gif" width="125px"/>
	<button label="Right" image="/img/network.gif" dir="reverse" width="125px"/>
	<button label="Above" image="/img/network.gif" orient="vertical" width="125px"/>
	<button label="Below" image="/img/network.gif" orient="vertical" dir="reverse" width="125px"/>

In addition to employing URLs to specify images, you can dynamically assign a generated image to a button using the setImageContent method. Refer to the following section for details.

Tip: The setImageContent method is supplied by all components that have an image property. Simply put, setImageContent is used for dynamically generated images, while image is used for images identifiable by a URL.

File Upload

Any button[1] can be used to upload files. All you need to do is:

  1. Specify the upload attribute with true
  2. Handles the onUpload event.
<button upload="true" label="Fileupload" onUpload="myProcessUpload(event.getMedia())"/>

When the file is uploaded, an instance of UploadEvent is sent to the button. Then, the event listener can retrieve the uploaded content by examining the return value of UploadEvent.getMedia().

  1. Any Toolbarbutton can be used to upload files too.

Limitation of the Default Mold

The default mold of a button uses HTML BUTTON tag to represent it visually. It is efficient, but it has some limitations:

  1. The look might be different from one browser to another.
  2. It doesn't support the file upload. In fact, it will become the trendy mold automatically if upload is specified.

If it is an issue, you could use the trendy mold instead.

<button label="OK" mold="trendy"/>

Configure to Use the Trendy Mold as Default

If you prefer to use the trendy mold as default, you could configure ZK by adding the following to /WEB-INF/zk.xml



The onClick Event and Href Property

There are two ways to add behavior to a button and toolbarbutton. Firstly, you can specify a listener for the onClick event. Secondly, you could specify a URL for the href property. If both are specified, the href property has the higher priority, i.e., the onClick event won't be sent.

	<window title="example">
			void do_something_in_Java()
				//redirect to another page

		<button label="click me" onClick="do_something_in_Java()"/>
		<button label="don't click that one, click me" href="/another_page.zul"/>

The SendRedirect Method of the org.zkoss.zk.ui.Execution Interface

When processing an event, you can decide to stop processing the current desktop and redirect to another page by using the sendRedirect method. In other words, from the users viewpoint the following two buttons have exactly the same effect.

			void sendRedirect(url)
				alert("sending redirect");
				//send redirect url
		<button label="redirect" onClick="sendRedirect(&quot;another.zul&quot;)"/>
		<button label="href" href="another.zul"/>

Since the onClick event is sent to the server for processing, you are able to perform additional tasks before invoking sendRedirect, such as redirecting to another page only if certain conditions are satisfied.

On the other hand, the href property is processed at the client side. Your application won't be notified when users click the button.


To prevent multiple clicks of a button upon clicking a button and a process executing the button is now disabled. The button is then re-enabled after the processing has finished, this is done using the autodisable feature.

<button id="ok" label="OK" autodisable="self" />

The above code demonstrates autodisable functionality, it is possible to re-enable buttons using the following method.

<button label="enable all" onClick="ok.disabled = cancel.disabled =
[Since 5.0.0]

Supported Events

Event Type
Event: Event

Denotes when a component gets the focus.

Event: Event

Denotes when a component loses the focus.

Event: UploadEvent

Denotes user has uploaded a file to the component.

Supported Molds

Available molds of a component are defined in lang.xml embedded in zul.jar.

Button mold default.png
Button mold trendy.png
Button mold os.png

Supported Children


Use Cases

Version Description Example Location
3.6 Get dynamically generated Button reference in onClick Event
3.6 How to fire onClick Event on a Button

Version History

Last Update : 2010/12/17

Version Date Content
5.0.4 August 2010 Button.setType(String) was introduced to allow a button able to submit or reset a form.
<n:form action="a_uri" xmlns:n="native">
  <button type="submit" label="Submit"/>
  <button type="reset" label="Reset"/>

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