Button"

From Documentation
 
(54 intermediate revisions by 8 users not shown)
Line 10: Line 10:
 
= Employment/Purpose =
 
= Employment/Purpose =
  
You could assign a <tt>label</tt> and an <tt>image</tt> to a button by the <tt>label</tt> and <tt>image</tt> properties. If both are specified, the <tt>dir</tt> property control which is displayed up front, and the <tt>orient</tt> property controls whether the layout is horizontal or vertical.
+
You could assign a <code>label</code> and an <code>image</code> to a button by the <code>label</code> and <code>image</code> properties. If both are specified, the <code>dir</code> property control which is displayed up front, and the <code>orient</code> 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.  
+
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 =
 
= Example =
Line 24: Line 24:
 
<button label="Below" image="/img/network.gif" orient="vertical" dir="reverse" width="125px"/>
 
<button label="Below" image="/img/network.gif" orient="vertical" dir="reverse" width="125px"/>
 
</source>
 
</source>
In addition to employing URLs to specify images, you can dynamically assign a generated image to a button using the <tt>setImageContent</tt> method. Refer to the following section for details.
+
In addition to employing URLs to specify images, you can dynamically assign a generated image to a button using the <code>setImageContent</code> method. Refer to the following section for details.
  
'''Tip:''' The <tt>setImageContent</tt> method is supplied by all components that have an <tt>image</tt> property. Simply put, <tt>setImageContent</tt> is used for dynamically generated images, while <tt>image</tt> is used for images identifiable by a URL.
+
'''Tip:''' The <code>setImageContent</code> method is supplied by all components that have an <code>image</code> property. Simply put, <code>setImageContent</code> is used for dynamically generated images, while <code>image</code> is used for images identifiable by a URL.
  
 
= File Upload =
 
= File Upload =
  
Any button<ref>Any <javadoc>org.zkoss.zul.Toolbarbutton</javadoc> can be used to upload files too.</ref> can be used to upload files. All you need to do is:
+
A button or a [[ZK_Component_Reference/Essential_Components/Toolbarbutton#File_Upload | Toolbarbutton]] can be used to upload files. All you need to do is:
  
# Specify the <tt>upload</tt> attribute with true
+
# Specify the <code>upload</code> attribute with <code>true</code>
# Handles the <tt>onUpload</tt> event.
+
# Handles the <code>onUpload</code> event
  
 
<source lang="xml">
 
<source lang="xml">
Line 41: Line 41:
 
When the file is uploaded, an instance of <javadoc>org.zkoss.zk.ui.event.UploadEvent</javadoc> is sent to the button. Then, the event listener can retrieve the uploaded content by examining the return value of <javadoc method="getMedia()">org.zkoss.zk.ui.event.UploadEvent</javadoc>.
 
When the file is uploaded, an instance of <javadoc>org.zkoss.zk.ui.event.UploadEvent</javadoc> is sent to the button. Then, the event listener can retrieve the uploaded content by examining the return value of <javadoc method="getMedia()">org.zkoss.zk.ui.event.UploadEvent</javadoc>.
  
<blockquote>
+
= Custom Error Message When Fileupload Over Maxsize =
----
+
 
<references/>
+
1. Write your own AuLoader
</blockquote>
+
<source lang="java" highlight="9,10,11,12">
 +
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);
 +
  }
 +
}
 +
</source>
 +
 
 +
2. Apply it in the web.xml
 +
 
 +
<source lang="xml" highlight="5,6,7,8">
 +
<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>
 +
</source>
 +
 
 +
* Result Video Demo
 +
** http://screencast.com/t/MZlxSR9JzG
  
 
= Limitation of the Default Mold  =
 
= Limitation of the Default Mold  =
Line 52: Line 85:
 
# The look might be different from one browser to another.
 
# The look might be different from one browser to another.
 
# It doesn't support the file upload. In fact, it will become the trendy mold automatically if <code>upload</code> is specified.
 
# It doesn't support the file upload. In fact, it will become the trendy mold automatically if <code>upload</code> is specified.
 
+
# 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.
 
If it is an issue, you could use the trendy mold instead.
  
Line 61: Line 94:
 
== Configure to Use the Trendy Mold as Default ==
 
== 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 <tt>/WEB-INF/zk.xml</tt>
+
If you prefer to use the trendy mold as default, you could configure ZK by adding the following to <code>/WEB-INF/zk.xml</code>
  
 
<source lang="xml">
 
<source lang="xml">
Line 69: Line 102:
 
</library-property>
 
</library-property>
 
</source>
 
</source>
 +
 +
= File Download and browser processed links=
 +
Similar to [[ZK_Component_Reference/Essential_Components/A#File_download_link_problem | file download link problem]], if you specify <code>href</code> to use a button for downloading, or if you are using a browser-processed link such as <code>mailto:</code>, <code>tel:</code>, or other similar user-processed instruction which would trigger a page unloading event, you also need to specify <code>target</code>:
 +
 +
<syntaxhighlight lang='xml'>
 +
<button label="download" href="/myfile.pdf" target="_blank"/>
 +
</syntaxhighlight>
 +
* If no specifying <code>target</code>, you will find event firing doesn't work anymore after you download a file.
  
 
=Properties=
 
=Properties=
== The onClick Event and Href Property ==
+
== Autodisable ==
There are two ways to add behavior to a <tt>button</tt> and <tt>toolbarbutton</tt>. Firstly, you can specify a listener for the <tt>onClick</tt> event. Secondly, you could specify a URL for the <tt>href</tt> property. If both are specified, the <tt>href</tt> property has the higher priority, i.e., the onClick event won't be sent.
+
 
 +
<javadoc method="setAutodisable(java.lang.String)">org.zkoss.zul.Button</javadoc> 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 <code>self</code> as follows. Then, the button is disabled when it is clicked.
 +
 
 +
<source lang="xml">
 +
<button id="ok" label="OK" autodisable="self" />
 +
</source>
 +
 
 +
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.
 +
 
 +
<source lang="xml">
 +
<button id="ok" label="OK" autodisable="ok,cancel" />
 +
<button id="cancel" label="Cancel" autodisable="ok,cancel" />
 +
</source>
 +
 
 +
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 <javadoc method="setDisabled(boolean)">org.zkoss.zul.Button</javadoc> explicitly), you could prefix the ID with a plus (<code>+</code>). For example,
 +
 
 +
<source lang="xml">
 +
<button id="ok" label="OK" autodisable="+self, +cancel" />
 +
</source>
 +
 
 +
Then, you could enable them manually under the situation depending on your application's requirement, such as
 +
 
 +
<source lang="java">
 +
if (something_happens) {
 +
  ok.setDisabled(false);
 +
  cancel.setDisabled(false);
 +
}
 +
</source>
 +
 
 +
=== Enable Autodisable for All Buttons===
 +
 
 +
As described in [[ZK Developer's Reference/Customization/Component Properties|ZK Developer's Reference: Customization]], you could customize ZK to enable <code>autodisable</code> for all button by specifying the following in the custom language addon:
 +
 
 +
<source lang="xml">
 +
<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>
 +
</source>
 +
 
 +
== Href ==
 +
In addition to handling the onClick event, you could specify the URL in the href property (<javadoc method="setHref(java.lang.String)">org.zkoss.zul.Button</javadoc>), 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 <javadoc method="setTarget(java.lang.String)">org.zkoss.zul.Button</javadoc> (just like using a HTML A tag).
 +
 
 +
Notice that the end user could hold the <code>Control</code> 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 <code>button</code> and <code>toolbarbutton</code>. Firstly, you can specify a listener to the <code>onClick</code> event. Secondly, you could specify a URL for the <code>href</code> property (<javadoc method="setHref(java.lang.String)">org.zkoss.zul.Button</javadoc>). If both are specified, the <code>href</code> property has the higher priority, i.e., the onClick event won't be sent.
  
 
<source lang="xml" >
 
<source lang="xml" >
 
<zk>
 
<zk>
 
<window title="example">
 
<window title="example">
<zscript>
 
void do_something_in_Java()
 
{
 
alert("hello");
 
//redirect to another page
 
}
 
</zscript>
 
 
 
<button label="click me" onClick="do_something_in_Java()"/>
 
<button label="click me" onClick="do_something_in_Java()"/>
 
<button label="don't click that one, click me" href="/another_page.zul"/>
 
<button label="don't click that one, click me" href="/another_page.zul"/>
Line 91: Line 178:
 
</source>
 
</source>
  
== The SendRedirect Method of the org.zkoss.zk.ui.Execution Interface ==
+
=== Href and SendRedirect  ===
When processing an event, you can decide to stop processing the current desktop and redirect to another page by using the <tt>sendRedirect</tt> method. In other words, from the users viewpoint the following two buttons have exactly the same effect.
+
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 <javadoc method="sendRedirect(java.lang.String)">org.zkoss.zk.ui.Executions</javadoc> if it shall jump to another URL.
 +
 
 +
For end users, there is no difference between the use of <javadoc method="setHref(java.lang.String)">org.zkoss.zul.Button</javadoc> and <javadoc method="sendRedirect(java.lang.String)">org.zkoss.zk.ui.Executions</javadoc>.
  
 
<source lang="xml" >
 
<source lang="xml" >
 
<zk>
 
<zk>
<window>
+
<window>
<zscript>
+
<button label="redirect" onClick="Executions.sendRedirect(&quot;another.zul&quot;)"/>
void sendRedirect(url)
 
{
 
alert("sending redirect");
 
//send redirect url
 
}
 
</zscript>
 
 
<button label="redirect" onClick="sendRedirect(&quot;another.zul&quot;)"/>
 
 
<button label="href" href="another.zul"/>
 
<button label="href" href="another.zul"/>
 
</window>
 
</window>
Line 111: Line 194:
 
</source>
 
</source>
  
Since the onClick event is sent to the server for processing, you are able to perform additional tasks before invoking <tt>sendRedirect</tt>, such as redirecting to another page only if certain conditions are satisfied.
+
Since the onClick event is sent to the server for processing, you are able to perform additional tasks before invoking <javadoc method="sendRedirect(java.lang.String)">org.zkoss.zk.ui.Executions</javadoc>, such as redirecting to another page only if certain conditions are satisfied.
 +
 
 +
On the other hand, the <code>href</code> property is processed at the client side. Your application won't be notified when users click the button.
 +
 
 +
== Type ==
 +
 
 +
{{versionSince| 5.0.4}}
 +
 
 +
<javadoc method="setType(java.lang.String)">org.zkoss.zul.Button</javadoc> sets the button's type. It is designed to work with the HTML <code><form></code> and Servlets. For example,
 +
 
 +
<source lang="xml">
 +
<n:form action="/foo/my_handler" xmlns:n="native">
 +
  <textbox/>
 +
  <button type="submit" label="Submit"/>
 +
  <button type="reset" label="Reset"/>
 +
</n:form>
 +
</source>
 +
 
 +
== Upload ==
 +
 
 +
By specifying the upload property (<javadoc method="setUpload(java.lang.String)">org.zkoss.zul.Button</javadoc>), you could make a button used for uploading files. For example,
 +
 
 +
<source lang="xml">
 +
<button label="Upload" upload="true" onUpload="handle(event.media)"/>
 +
</source>
 +
 
 +
Once the file(s) are uploaded, the onUpload event will be sent with an instance of <javadoc>org.zkoss.zk.ui.event.UploadEvent</javadoc>. And, you could retrieve the uploaded files from <javadoc method="getMedia()">org.zkoss.zk.ui.event.UploadEvent</javadoc> and <javadoc method="getMedias()">org.zkoss.zk.ui.event.UploadEvent</javadoc>
  
On the other hand, the <tt>href</tt> property is processed at the client side. Your application won't be notified when users click the button.
+
If you want to customize the handling of the file upload at the client, you can specify a JavaScript class when calling this method:
  
== Autodisable ==
+
<source lang="xml">
 +
<button upload="foo.Upload"/> <!-- assume you implement a JavaScript class: foo.Upload -->
 +
</source>
  
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.
+
=== Options ===
 +
Some options for the upload can be specified as follows:
  
 
<source lang="xml">
 
<source lang="xml">
<button id="ok" label="OK" autodisable="self" />
+
<button label="Upload"  
 +
upload="true,maxsize=-1,multiple=true,accept=audio/*|video/*|image/*|MIME_type, native"/>
 
</source>
 
</source>
  
The above code demonstrates autodisable functionality, it is possible to re-enable buttons using the following method.
 
  
 +
* <code>maxsize</code>: the maximal allowed upload size of the component, in kilobytes, or a negative value if no limit.
 +
* <code>native</code>: treating the uploaded file(s) as binary, i.e., not to convert it to image, audio, or text files.
 +
* <code>multiple</code>: {{versionSince| 6.0.0}} treating the file chooser allows multiple files to upload, the setting only works with HTML5-supported browsers
 +
* <code>accept</code>: {{versionSince| 7.0.0}} specifies the MIME types of files that the server accepts, the setting only works with HTML5-supported browsers. [http://www.iana.org/assignments/media-types/media-types.xhtml MIME type list].
  
 +
=== Customize Upload Size Exceeding Message ===
 +
{{versionSince| 8.0.0}}
 +
Please refer to [[ZK_Developer%27s_Reference/Internationalization/Warning_and_Error_Messages#Change_particular_message|ZK Developer's Reference/Internationalization]].
 +
 +
For Example, (in WEB-INF/zk-label.properties)
 
<source lang="xml">
 
<source lang="xml">
<button label="enable all" onClick="ok.disabled = cancel.disabled =
+
MZul.2105=The request was rejected because its size ({0}) exceeds the configured maximum ({1})
false"/></source>
+
</source>
[Since 5.0.0]
+
Notice that you can change the index {0} & {1} to display different file size unit. (Auto:{0},{1} Byte:{2},{3} KB:{4},{5} MB:{6},{7})
 +
 
 +
=Inherited Functions=
 +
 
 +
Please refer to [[ZK_Component_Reference/Base_Components/LabelImageElement | LabelImageElement]] for inherited functions.
  
 
=Supported Events=
 
=Supported Events=
  
{| border="1" | width="100%"
+
{| class='wikitable' | width="100%"
 
! <center>Name</center>
 
! <center>Name</center>
 
! <center>Event Type</center>
 
! <center>Event Type</center>
 
|-
 
|-
| <center><tt>onFocus</tt></center>
+
| <center><code>onFocus</code></center>
 
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.Event</javadoc>
 
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.Event</javadoc>
  
Line 143: Line 268:
  
 
|-
 
|-
| <center><tt>onBlur</tt></center>
+
| <center><code>onBlur</code></center>
 
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.Event</javadoc>
 
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.Event</javadoc>
  
 
Denotes when a component loses the focus.
 
Denotes when a component loses the focus.
 
|-
 
|-
| <center><tt>onUpload</tt></center>
+
| <center><code>onUpload</code></center>
 
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.UploadEvent</javadoc>
 
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.UploadEvent</javadoc>
 
Denotes user has uploaded a file to the component.
 
Denotes user has uploaded a file to the component.
Line 156: Line 281:
 
=Supported Molds=
 
=Supported Molds=
 
Available molds of a component are defined in lang.xml embedded in zul.jar.
 
Available molds of a component are defined in lang.xml embedded in zul.jar.
{| border="1" | width="100%"
+
{| class='wikitable' | width="100%"
 
! <center>Name</center>
 
! <center>Name</center>
 
! <center>Snapshot</center>
 
! <center>Snapshot</center>
Line 173: Line 298:
  
 
  *NONE
 
  *NONE
 
=Use Cases=
 
 
{| border='1px' | width="100%"
 
! Version !! Description !! Example Location
 
|-
 
| 3.6
 
| Get dynamically generated Button reference in onClick Event
 
| [http://www.zkoss.org/forum/listComment/8780 http://www.zkoss.org/forum/listComment/8780]
 
|-
 
| 3.6
 
| How to fire onClick Event on a Button
 
| [http://www.zkoss.org/forum/listComment/1716 http://www.zkoss.org/forum/listComment/1716]
 
|}
 
  
 
=Version History=
 
=Version History=
 
{{LastUpdated}}
 
{{LastUpdated}}
{| border='1px' | width="100%"
+
{| class='wikitable' | width="100%"
 
! Version !! Date !! Content
 
! Version !! Date !! Content
 
|-
 
|-
Line 202: Line 313:
 
   <button type="reset" label="Reset"/>
 
   <button type="reset" label="Reset"/>
 
</n:form>
 
</n:form>
 +
</source>
 +
|-
 +
| 6.0.0
 +
| December 2011
 +
| <javadoc method="setUpload(java.lang.String)">org.zkoss.zul.Button</javadoc> the ''multiple'' setting was introduced to allow to choose multiple files to upload at the same time. (HTML5 supported browsers only)
 +
 +
<source lang="xml">
 +
  <button upload="true,multiple=true" label="Fileupload"/>
 +
</source>
 +
|-
 +
| 7.0.0
 +
| September 2013
 +
| <javadoc method="setUpload(java.lang.String)">org.zkoss.zul.Button</javadoc> the ''accept'' setting was introduced to allow to specify the types of files that the server accepts. (HTML5 supported browsers only)
 +
 +
<source lang="xml">
 +
  <button upload="true,accept=audio/*|video/*|image/*|MIME_type" label="Fileupload"/>
 
</source>
 
</source>
 
|}
 
|}
  
 
{{ZKComponentReferencePageFooter}}
 
{{ZKComponentReferencePageFooter}}

Latest revision as of 14:46, 29 August 2023

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

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

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 UploadEvent is sent to the button. Then, the event listener can retrieve the uploaded content by examining the return value of UploadEvent.getMedia().

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

Button.setAutodisable(String) 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 Button.setDisabled(boolean) 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 (Button.setHref(String)), 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 Button.setTarget(String) (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 (Button.setHref(String)). 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 Executions.sendRedirect(String) if it shall jump to another URL.

For end users, there is no difference between the use of Button.setHref(String) and Executions.sendRedirect(String).

<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 Executions.sendRedirect(String), 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.4

Button.setType(String) sets the button's type. It is designed to work with the HTML <form> and Servlets. For example,

<n:form action="/foo/my_handler" xmlns:n="native">
  <textbox/>
  <button type="submit" label="Submit"/>
  <button type="reset" label="Reset"/>
</n:form>

Upload

By specifying the upload property (Button.setUpload(String)), you could make a button used for uploading files. For example,

<button label="Upload" upload="true" onUpload="handle(event.media)"/>

Once the file(s) are uploaded, the onUpload event will be sent with an instance of UploadEvent. And, you could retrieve the uploaded files from UploadEvent.getMedia() and UploadEvent.getMedias()

If you want to customize the handling of the file upload at the client, you can specify a JavaScript class when calling this method:

<button upload="foo.Upload"/> <!-- assume you implement a JavaScript class: foo.Upload -->

Options

Some options for the upload can be specified as follows:

<button label="Upload" 
upload="true,maxsize=-1,multiple=true,accept=audio/*|video/*|image/*|MIME_type, native"/>


  • maxsize: the maximal allowed upload size of the component, in kilobytes, or a negative value if no limit.
  • native: treating the uploaded file(s) as binary, i.e., not to convert it to image, audio, or text files.
  • multiple: Since 6.0.0 treating the file chooser allows multiple files to upload, the setting only works with HTML5-supported browsers
  • accept: Since 7.0.0 specifies the MIME types of files that the server accepts, the setting only works with HTML5-supported browsers. MIME type list.

Customize Upload Size Exceeding Message

Since 8.0.0 Please refer to ZK Developer's Reference/Internationalization.

For Example, (in WEB-INF/zk-label.properties)

MZul.2105=The request was rejected because its size ({0}) exceeds the configured maximum ({1})

Notice that you can change the index {0} & {1} to display different file size unit. (Auto:{0},{1} Byte:{2},{3} KB:{4},{5} MB:{6},{7})

Inherited Functions

Please refer to LabelImageElement for inherited functions.

Supported Events

Name
Event Type
onFocus
Event: Event

Denotes when a component gets the focus.

onBlur
Event: Event

Denotes when a component loses the focus.

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

Name
Snapshot
default
Button mold default.png
trendy
Button mold trendy.png
os
Button mold os.png

Supported Children

*NONE

Version History

Last Update : 2023/08/29


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"/>
</n:form>
6.0.0 December 2011 Button.setUpload(String) the multiple setting was introduced to allow to choose multiple files to upload at the same time. (HTML5 supported browsers only)
  <button upload="true,multiple=true" label="Fileupload"/>
7.0.0 September 2013 Button.setUpload(String) the accept setting was introduced to allow to specify the types of files that the server accepts. (HTML5 supported browsers only)
  <button upload="true,accept=audio/*|video/*|image/*|MIME_type" label="Fileupload"/>



Last Update : 2023/08/29

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