Button

Employment/Purpose

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 now can be used to upload a file. In addition to this, the display of the upload status has been enhanced and can be customized easily.

Example

    <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

A button or a Toolbarbutton 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 org.zkoss.zk.ui.event.UploadEvent is sent to the button. Then, the event listener can retrieve the uploaded content by examining the return value of

org.zkoss.zk.ui.event.UploadEvent

.

Custom Error Message When Fileupload Over Maxsize

1. Write your own AuLoader

package test;  

import org.apache.commons.fileupload.FileUploadBase.SizeLimitExceededException; 
import org.zkoss.zk.au.http.AuUploader;   

public class MyUploader extends AuUploader {    

   protected String handleError(Throwable ex) {                 
      if(ex instanceof SizeLimitExceededException){             
         SizeLimitExceededException e = (SizeLimitExceededException) ex;            
         return e.getActualSize() + " is over our limit";       
      }         
      return super.handleError(ex);     
   } 
}

2. Apply it in the web.xml

<servlet>   
   <description>The asynchronous update engine for ZK</description>     
   <servlet-name>auEngine</servlet-name>    
   <servlet-class>org.zkoss.zk.au.http.DHtmlUpdateServlet</servlet-class>   
   <init-param>         
      <param-name>extension0</param-name>       
      <param-value>/upload=test.MyUploader</param-value>    
   </init-param> 
</servlet>

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.
  3. If it is disabled it can not receive mouse events and hence can not use ZK popup component as tooltip.

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

<library-property>
    <name>org.zkoss.zul.Button.mold</name>
    <value>trendy</value>
</library-property>

File Download and browser processed links

Similar to file download link problem, if you specify href to use a button for downloading, or if you are using a browser-processed link such as mailto:, tel:, or other similar user-processed instruction which would trigger a page unloading event, you also need to specify target:

<button label="download" href="/myfile.pdf" target="_blank"/>
  • If no specifying target, you will find event firing doesn’t work anymore after you download a file.

Properties

Autodisable

org.zkoss.zul.Button

is used to disable a button automatically, when it is clicked. It is useful to prevent the user from clicking it twice (and firing redundant requests), which is common if the request takes long to serve.

The simplest use is to specify it with self as follows. Then, the button is disabled when it is clicked.

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

If you’d like to disable several buttons, you could specify all of them in this property by separating with a comma. For example, the following disables both buttons, when one of them is clicked.

<button id="ok" label="OK" autodisable="ok,cancel" />
<button id="cancel" label="Cancel" autodisable="ok,cancel" />

The button will be enabled automatically, after the request has been served (i.e., the response has been sent back to the client). If you prefer to enable them manually (i.e., by calling

org.zkoss.zul.Button

explicitly), you could prefix the ID with a plus (+). For example,

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

Then, you could enable them manually under the situation depending on your application’s requirement, such as

if (something_happens) {
   ok.setDisabled(false);
   cancel.setDisabled(false);
}

Enable Autodisable for All Buttons

As described in ZK Developer’s Reference: Customization, you could customize ZK to enable autodisable for all button by specifying the following in the custom language addon:

<language-addon>
    <component>
        <component-name>button</component-name>
        <extends>button</extends>
        <property>
            <property-name>autodisable</property-name>
            <property-value>self</property-value>
        </property>
    </component>
</language-addon>

Href

In addition to handling the onClick event, you could specify the URL in the href property (org.zkoss.zul.Button), such that the browser will navigate to the URL you specified directly (without sending back any request to the server). If you prefer to visit the URL in another browser window, you could specify the name in

org.zkoss.zul.Button

(just like using a HTML A tag).

Notice that the end user could hold the Control key and click on the button to visit the link in a new browser window (like a HTML A tag does).

Href and the onClick Event

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

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

Href and SendRedirect

The href property is processed at the client. In other words, the browser will jump to the URL specified in the href property, so your application running at the server has no chance to process it.

If you have to process it at the server or you have to decide whether to jump to another URL based on certain condition, you could listen to the onClick event, process it, and then invoke

org.zkoss.zk.ui.Executions

if it shall jump to another URL.

For end users, there is no difference between the use of

org.zkoss.zul.Button

and

org.zkoss.zk.ui.Executions

.

<zk>
    <window>        
        <button label="redirect" onClick="Executions.sendRedirect(&quot;another.zul&quot;)"/>
        <button label="href" href="another.zul"/>
    </window>
</zk>

Since the onClick event is sent to the server for processing, you are able to perform additional tasks before invoking

org.zkoss.zk.ui.Executions

, 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.

Type

since 5.0

org.zkoss.zul.Button

sets the button’s type. It is designed to work with the HTML

</code> and Servlets. For example, ```xml