org.zkoss.zul
Class Fileupload

java.lang.Object
  org.zkoss.zk.ui.AbstractComponent
      org.zkoss.zk.ui.HtmlBasedComponent
          org.zkoss.zul.Fileupload

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable, HtmlBasedComponent, Component, Scope, ComponentCtrl, Fileupload

public class Fileupload
extends HtmlBasedComponent
implements Fileupload

A fileupload dialog used to let user upload a file.

There are two ways to use Fileupload:

1. Open as a modal dialog:

You don't create Fileupload directly. Rather, use get() or get(String, String).

2. Embed as part of the page:

You can create it as a component and then listen to the onUpload event (UploadEvent). If the cancel button is pressed or file(s) is uploaded, the onClose event (Event). is sent to notify the application. By default, it does nothing but invalidate the component, i.e., all fields are cleared.

A non-XUL extension.

Author:

tomyeh

See Also:

Filedownload, Serialized Form

Nested Class Summary

protected class

Fileupload.ExtraCtrl A utility class to implement AbstractComponent.getExtraCtrl().

Nested classes/interfaces inherited from class org.zkoss.zk.ui.AbstractComponent

AbstractComponent.Children

Field Summary

Fields inherited from class org.zkoss.zk.ui.HtmlBasedComponent

_zclass, RS_NO_DISPLAY, RS_NO_HEIGHT, RS_NO_WIDTH

Fields inherited from class org.zkoss.zk.ui.AbstractComponent

_visible

Fields inherited from interface org.zkoss.zk.ui.Component

APPLICATION_SCOPE, COMPONENT_SCOPE, DESKTOP_SCOPE, PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, SPACE_SCOPE

Constructor Summary

Fileupload()

Method Summary

static Media	get() Opens a modal dialog with the default message and title, and let user upload a file.
static Media	get(boolean alwaysNative) Opens a modal dialog with the default message and title, and let user upload a file.
static Media[]	get(int max) Opens a modal dialog to upload mulitple files with the default message and title.
static Media[]	get(int max, boolean alwaysNative) Opens a modal dialog to upload mulitple files with the default message and title.
static Media	get(java.lang.String message, java.lang.String title) Opens a modal dialog with the specified message and title, and let user upload a file.
static Media	get(java.lang.String message, java.lang.String title, boolean alwaysNative) Opens a modal dialog with the specified message and title, and let user upload a file.
static Media[]	get(java.lang.String message, java.lang.String title, int max) Opens a modal dialog to upload multiple files with the specified message and title.
static Media[]	get(java.lang.String message, java.lang.String title, int max, boolean alwaysNative) Opens a modal dialog to upload multiple files with the specified message, title and options.
static Media[]	get(java.lang.String message, java.lang.String title, int max, int maxsize, boolean alwaysNative) Opens a modal dialog to upload multiple files with the specified message, title and options.
int	getMaxsize() Returns the maximal allowed upload size of the component, in kilobytes, or a negative value if no limit.
int	getNumber() Returns the maximal allowed number of files to upload.
static java.lang.String	getTemplate() Returns the template used to create the upload modal dialog.
boolean	isChildable() No child is allowed.
boolean	isNative() Returns whether to treat the uploaded file(s) as binary, i.e., not to convert it to image, audio or text files.
protected java.lang.Object	newExtraCtrl() Used by AbstractComponent.getExtraCtrl() to create a client control.
void	onClose() Hanldes the onClose event which is sent when file(s) is uploaded or when the cancel button is pressed.
void	setMaxsize(int maxsize) Sets the maximal allowed upload size of the component, in kilobytes.
void	setNative(boolean alwaysNative) Sets whether to treat the uploaded file(s) as binary, i.e., not to convert it to image, audio or text files.
void	setNumber(int maxnum) Sets the maximal allowed number of files to upload.
static void	setTemplate(java.lang.String uri) Sets the template used to create the upload modal dialog.

Methods inherited from class org.zkoss.zk.ui.HtmlBasedComponent

focus, getAllOnClickAttrs, getDraggable, getDroppable, getHeight, getInnerAttrs, getLeft, getMoldSclass, getOuterAttrs, getRealSclass, getRealStyle, getRealStyleFlags, getSclass, getStyle, getTooltiptext, getTop, getWidth, getZclass, getZindex, getZIndex, redraw, setClass, setDraggable, setDroppable, setFocus, setHeight, setLeft, setMoldSclass, setSclass, setStyle, setTooltiptext, setTop, setWidth, setZclass, setZindex, setZIndex

Methods inherited from class org.zkoss.zk.ui.AbstractComponent

addAnnotation, addAnnotation, addEventHandler, addEventListener, addForward, addForward, addForward, addForward, addMoved, addSharedAnnotationMap, addSharedEventHandlerMap, appendAsapAttr, appendAsapAttr, appendChild, applyProperties, beforeChildAdded, beforeChildRemoved, beforeParentChanged, clone, containsVariable, detach, disableClientUpdate, equals, getAnnotatedProperties, getAnnotatedPropertiesBy, getAnnotation, getAnnotation, getAnnotations, getAnnotations, getAttribute, getAttribute, getAttributes, getAttributes, getChildren, getCommand, getDefinition, getDesktop, getEventHandler, getEventHandlerNames, getExtraCtrl, getFellow, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getMoldURI, getNamespace, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getUuid, getVariable, hasFellow, insertBefore, invalidate, isAsapRequired, isInvalidated, isListenerAvailable, isVisible, newChildren, onChildAdded, onChildRemoved, onDrawNewChild, onPageAttached, onPageDetached, onWrongValue, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, response, sessionDidActivate, sessionWillPassivate, setAttribute, setAttribute, setComponentDefinition, setId, setMold, setPage, setPageBefore, setParent, setVariable, setVisible, smartUpdate, smartUpdate, smartUpdate, smartUpdateDeferred, smartUpdateValues, toString, unsetVariable

Methods inherited from class java.lang.Object

finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface org.zkoss.zk.ui.api.HtmlBasedComponent

focus, getHeight, getLeft, getSclass, getStyle, getTooltiptext, getTop, getWidth, getZclass, getZindex, getZIndex, setDraggable, setDroppable, setFocus, setHeight, setLeft, setSclass, setStyle, setTooltiptext, setTop, setWidth, setZclass, setZindex, setZIndex

Methods inherited from interface org.zkoss.zk.ui.Component

addEventListener, addForward, addForward, addForward, addForward, appendChild, applyProperties, clone, containsVariable, detach, getAttribute, getAttribute, getAttributes, getAttributes, getChildren, getDefinition, getDesktop, getFellow, getFellowIfAny, getFellows, getFirstChild, getId, getLastChild, getListenerIterator, getMold, getNamespace, getNextSibling, getPage, getParent, getPreviousSibling, getRoot, getSpaceOwner, getUuid, getVariable, insertBefore, invalidate, isInvalidated, isListenerAvailable, isVisible, redraw, removeAttribute, removeAttribute, removeChild, removeEventListener, removeForward, removeForward, setAttribute, setAttribute, setId, setMold, setPage, setPageBefore, setParent, setVariable, setVisible, unsetVariable

Constructor Detail

Fileupload

public Fileupload()

Method Detail

getMaxsize

public int getMaxsize()

Returns the maximal allowed upload size of the component, in kilobytes, or a negative value if no limit.

Default: -1.

Since:

3.6.0

setMaxsize

public void setMaxsize(int maxsize)

Sets the maximal allowed upload size of the component, in kilobytes.

Note: Configuration.setMaxUploadSize(int) is also allowed to limit the size, if the maximal size is -1.

Since:

3.6.0

isChildable

public boolean isChildable()

No child is allowed.

Specified by:

isChildable in interface Component

Overrides:

isChildable in class AbstractComponent

getNumber

public int getNumber()

Returns the maximal allowed number of files to upload.

Specified by:

getNumber in interface Fileupload

Since:

2.4.0

setNumber

public void setNumber(int maxnum)
               throws WrongValueException

Sets the maximal allowed number of files to upload.

Default: 1.

Specified by:

setNumber in interface Fileupload

Parameters:

maxnum - the maximal allowed number (positive or negative). Since 3.0.2, the value can be negative, which means no limitation at all and the end user can upload any numbers he wants (since 3.0.2)

Throws:

WrongValueException - if non-positive, or it exceeds 1000

Since:

2.4.0

isNative

public boolean isNative()

Returns whether to treat the uploaded file(s) as binary, i.e., not to convert it to image, audio or text files.

Default: false.

Specified by:

isNative in interface Fileupload

Since:

3.0.0

See Also:

Configuration.getUploadCharset(), Configuration.getUploadCharsetFinder()

setNative

public void setNative(boolean alwaysNative)

Sets whether to treat the uploaded file(s) as binary, i.e., not to convert it to image, audio or text files.

Specified by:

setNative in interface Fileupload

Parameters:

alwaysNative - whether to treat the uploaded file as binary stream, regardless its content type. If false (the default), it will convert to Image, Audio, binary stream, or text files depending on the content type.

Since:

3.0.0

See Also:

Configuration.setUploadCharset(java.lang.String), Configuration.setUploadCharsetFinder(org.zkoss.zk.ui.util.CharsetFinder)

onClose

public void onClose()

Hanldes the onClose event which is sent when file(s) is uploaded or when the cancel button is pressed.

By default, it simply invalidates itself, i.e., all fields are cleared. If you want to do something different, you can intercept the onClose event.

Since:

2.4.0

newExtraCtrl

protected java.lang.Object newExtraCtrl()

Description copied from class: HtmlBasedComponent

Used by AbstractComponent.getExtraCtrl() to create a client control. It is used only by component developers.

Defaut: creates an instance of HtmlBasedComponent.ExtraCtrl.

Overrides:

newExtraCtrl in class HtmlBasedComponent

get

public static Media get()
                 throws java.lang.InterruptedException

Opens a modal dialog with the default message and title, and let user upload a file.

Returns:

the uploaded content, or null if not uploaded.

Throws:

java.lang.InterruptedException

get

public static Media get(boolean alwaysNative)
                 throws java.lang.InterruptedException

Opens a modal dialog with the default message and title, and let user upload a file.

Parameters:

alwaysNative - whether to treat the uploaded file as binary stream, regardless its content type. If false (the default), it will convert to Image, Audio, binary stream, or text files depending on the content type.

Returns:

the uploaded content, or null if not uploaded.

Throws:

java.lang.InterruptedException

Since:

3.0.0

See Also:

Configuration.getUploadCharset(), Configuration.getUploadCharsetFinder()

get

public static Media get(java.lang.String message,
                        java.lang.String title)
                 throws java.lang.InterruptedException

Opens a modal dialog with the specified message and title, and let user upload a file.

Parameters:

message - the message. If null, the default is used.

title - the title. If null, the default is used.

Returns:

the uploaded content, or null if not ready.

Throws:

java.lang.InterruptedException

get

public static Media get(java.lang.String message,
                        java.lang.String title,
                        boolean alwaysNative)
                 throws java.lang.InterruptedException

Opens a modal dialog with the specified message and title, and let user upload a file.

Parameters:

message - the message. If null, the default is used.

title - the title. If null, the default is used.

alwaysNative - whether to treat the uploaded file as binary stream, regardless its content type. If false (the default), it will convert to Image, Audio, binary stream, or text files depending on the content type.

Returns:

the uploaded content, or null if not ready.

Throws:

java.lang.InterruptedException

Since:

3.0.0

See Also:

Configuration.getUploadCharset(), Configuration.getUploadCharsetFinder()

get

public static Media[] get(int max)
                   throws java.lang.InterruptedException

Opens a modal dialog to upload mulitple files with the default message and title.

Parameters:

max - the maximal allowed number that an user can upload at once. If nonpositive, 1 is assumed.

Returns:

an array of files that an users has uploaded, or null if uploaded.

Throws:

java.lang.InterruptedException

get

public static Media[] get(int max,
                          boolean alwaysNative)
                   throws java.lang.InterruptedException

Opens a modal dialog to upload mulitple files with the default message and title.

Parameters:

max - the maximal allowed number that an user can upload at once. If nonpositive, 1 is assumed.

alwaysNative - whether to treat the uploaded files as binary stream, regardless its content type. If false (the default), it will convert to Image, Audio, binary stream, or text files depending on the content type.

Returns:

an array of files that an users has uploaded, or null if uploaded.

Throws:

java.lang.InterruptedException

Since:

3.0.0

See Also:

Configuration.getUploadCharset(), Configuration.getUploadCharsetFinder()

get

public static Media[] get(java.lang.String message,
                          java.lang.String title,
                          int max)
                   throws java.lang.InterruptedException

Opens a modal dialog to upload multiple files with the specified message and title.

The returned format depending on the content type.

Parameters:

max - the maximal allowed number that an user can upload at once. If nonpositive, 1 is assumed. If max is larger than 1000, 1000 is assumed.

Returns:

an array of files that an users has uploaded, or null if uploaded.

Throws:

java.lang.InterruptedException

get

public static Media[] get(java.lang.String message,
                          java.lang.String title,
                          int max,
                          boolean alwaysNative)
                   throws java.lang.InterruptedException

Opens a modal dialog to upload multiple files with the specified message, title and options.

Parameters:

max - the maximal allowed number that an user can upload at once. If nonpositive, 1 is assumed. If max is larger than 1000, 1000 is assumed.

alwaysNative - whether to treat the uploaded files as binary stream, regardless its content type. If false (the default), it will convert to Image, Audio, binary stream, or text files depending on the content type.

Returns:

an array of files that an users has uploaded, or null if uploaded.

Throws:

java.lang.InterruptedException

Since:

3.0.0

get

public static Media[] get(java.lang.String message,
                          java.lang.String title,
                          int max,
                          int maxsize,
                          boolean alwaysNative)
                   throws java.lang.InterruptedException

Opens a modal dialog to upload multiple files with the specified message, title and options.

Parameters:

max - the maximal allowed number that an user can upload at once. If nonpositive, 1 is assumed. If max is larger than 1000, 1000 is assumed.

maxsize - the maximal upload size of the component.

alwaysNative - whether to treat the uploaded files as binary stream, regardless its content type. If false (the default), it will convert to Image, Audio, binary stream, or text files depending on the content type.

Returns:

an array of files that an users has uploaded, or null if uploaded.

Throws:

java.lang.InterruptedException

Since:

3.6.0

setTemplate

public static void setTemplate(java.lang.String uri)

Sets the template used to create the upload modal dialog.

The template must follow the default template: ~./zul/html/fileuploaddlg.zul

In other words, just adjust the label and layout and don't change the component's ID.

Note: the template has no effect, if you use Fileupload as a component (and embed it to a page).

getTemplate

public static java.lang.String getTemplate()

Returns the template used to create the upload modal dialog.