ZK Component Reference/Essential Components/Fileupload

Fileupload

• Demonstration: FileUpload
• Java API: Fileupload
• JavaScript API: Fileupload
• Style Guide: N/A

Employment/Purpose

There are two ways to use Fileupload: uses Fileupload as a component to upload files, or invoke Fileupload.get() to open a dialog to upload files.

Use as a Component

Fileupload itself is a component. You can use it directly as follows.

<fileupload label="Upload">
   <attribute name="onUpload">
   org.zkoss.util.media.Media media = event.getMedia();
   //then, you can process media here
   </attribute>
</fileupload>

Fileupload is actually a button with upload=true. In other words, the above is equivalent to

<button label="Upload" upload="true">
...

Please refer to Button: Upload for details.

Invoke the Static Method: get

Fileupload provides a set of static methods to simplify the file uploading, such as Fileupload.get(), Fileupload.get(String, String), and so on.

The behavior is a little bit different depending on if the event thread is enabled (default: it is disabled).

---

Event Thread Disabled

When the event thread is disabled (default), the execution won't be suspended when Fileupload.get() is called. In other words, the returned value is always null. To retrieve the uploaded files, the developer has to listen the onUpload event, which is sent when the uploading is completed.

By default, the onUpload event is sent to all root components. For example, Div will, in the following example, receive the onUpload event since it is the root component:

<div onUpload="processMedia(event.getMedias());">
    <zscript deferred="true"><![CDATA[
    import org.zkoss.util.media.Media;
 
    public void processMedia(Media[] media) {
        if (media != null) {
            for (int i = 0; i < media.length; i++) {
                if (media[i] instanceof org.zkoss.image.Image) {
                    image.setContent(media[i]);
                } else {
                    Messagebox.show("Not an image: " + media[i], "Error",
                            Messagebox.OK, Messagebox.ERROR);
                    break; //not to show too many errors
                }
            }
        }
    }
]]></zscript>
    <vbox>
        <button label="Upload" onClick="Fileupload.get(-1);" />
        <image id="image" />
    </vbox>
</div>

Specify the Target Component

[Since 5.0.2]

If you prefer the event being sent to a particular component, specify the component in the desktop's attribute called org.zkoss.zul.Fileupload.target.

For example, we could have the button to receive the onUpload event as follows:

<zk>
    <zscript deferred="true"><![CDATA[
    import org.zkoss.util.media.Media;

    Executions.getCurrent().getDesktop().setAttribute(
            "org.zkoss.zul.Fileupload.target", uploadBtn);

    public void processMedia(Media[] media) {
        if (media != null) {
            for (int i = 0; i < media.length; i++) {
                if (media[i] instanceof org.zkoss.image.Image) {
                    image.setContent(media[i]);
                } else {
                    Messagebox.show("Not an image: " + media[i], "Error",
                            Messagebox.OK, Messagebox.ERROR);
                    break; //not to show too many errors
                }
            }
        }
    }
]]></zscript>
    <vbox>
        <button id="uploadBtn" label="Upload"
            onUpload="processMedia(event.getMedias());"
            onClick="Fileupload.get(-1);" />
        <image id="image" />
    </vbox>
</zk>

Event Thread Enabled

If the event thread is enable, the uploaded file will be returned directly by Fileupload.get() and other static methods, such as:

<zk>
	<button label="Upload">
	<attribute name="onClick">{
		org.zkoss.util.media.Media[] media = Fileupload.get(-1);
		if (media != null) {
			for (int i = 0; i &lt; media.length; i++) {
				if (media[i] instanceof org.zkoss.image.Image) {
					org.zkoss.zul.Image image = new org.zkoss.zul.Image();
					image.setContent(media[i]);
					image.setParent(pics);
				} else {
					Messagebox.show("Not an image: "+media[i], "Error", Messagebox.OK, Messagebox.ERROR);
					break; //not to show too many errors
				}
			}
		}
	}</attribute>
	</button>
	<vbox id="pics" />
</zk>

As shown, Fileupload.get(int) won't return until the end user uploads the files (and/or closes the dialog).

Example

Here is an example that uses Fileupload as a component:

<image id="img" />
Upload your hot shot:
<fileupload label="Upload" onUpload="img.setContent(event.media)" />

Supported Events

Name	Event Type
None	None

• Inherited Supported Events: Button

Supported Children

*NONE

Use Cases

Version	Description	Example Location

Version History

Version	Date	Content
5.0.2	May 2010	Able to specify a target for the onUpload event sent by Fileupload.get(). Used if the event thread is disabled.