Button"
m (→Properties) |
|||
Line 71: | Line 71: | ||
=Properties= | =Properties= | ||
− | == | + | == Autodisable == |
[Since 5.0.0] | [Since 5.0.0] | ||
Line 87: | Line 87: | ||
false"/></source> | false"/></source> | ||
− | == | + | == Href == |
If a button shall jump to another URL when the user clicks, you could specify the URL in the href property (<javadoc method="setHref(java.lang.String)">org.zkoss.zul.Button</javadoc>). | If a button shall jump to another URL when the user clicks, you could specify the URL in the href property (<javadoc method="setHref(java.lang.String)">org.zkoss.zul.Button</javadoc>). | ||
Line 124: | Line 124: | ||
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. | 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. | ||
− | == | + | == Type == |
[Since 5.0.4] | [Since 5.0.4] | ||
Line 138: | Line 138: | ||
</source> | </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, | 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, |
Revision as of 08:24, 17 January 2011
Button
- Demonstration: Button and Fileupload
- Java API: Button
- JavaScript API: Button
- Style Guide: 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 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.
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
Any button[1] can be used to upload files. All you need to do is:
- Specify the upload attribute with true
- 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().
- ↑ 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:
- 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
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
<library-property>
<name>org.zkoss.zul.Button.mold</name>
<value>trendy</value>
</library-property>
Properties
Autodisable
[Since 5.0.0]
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 =
false"/>
Href
If a button shall jump to another URL when the user clicks, you could specify the URL in the href property (Button.setHref(String)).
Notice that the end user could hold the Contro key and click on the button to follow 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 for 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("another.zul")"/>
<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 tag. You rarely need it unless you want to work with 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 -->
Another options for the upload can be specified as follows:
<button label="Upload" upload="true,maxsize=-1,native"/>
where
- 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.
Supported Events
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. |
- Inherited Supported Events: LabelImageElement
Supported Molds
Available molds of a component are defined in lang.xml embedded in zul.jar.
Supported Children
*NONE
Use Cases
Version | Description | Example Location |
---|---|---|
3.6 | Get dynamically generated Button reference in onClick Event | http://www.zkoss.org/forum/listComment/8780 |
3.6 | How to fire onClick Event on a Button | http://www.zkoss.org/forum/listComment/1716 |
Version History
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>
|