Revision as of 08:19, 5 July 2012

Dropupload

Demonstration: N/A
Java API: Dropupload
JavaScript API: Dropupload
Style Guide: N/A
Available in ZK EE only

Employment/Purpose

Dropupload leverages HTML 5 technology to handle file uploading where users can simply drag and drop the file(s) they want to upload into Dropupload and the uploading process will start automatically. The behaviour and operation of this Dropupload component is similar to ZK's file upload button but with better user experience and performance.

Example

Following is a typical example of its implementation

	<dropupload maxsize="5120" detection="none" onUpload="doSomething(event)">
		<attribute name="content"><![CDATA[
			<b>Drop Here</b><br/>
			size < 5MB
		]]></attribute>
	</dropupload>

Maxsize

The maxsize attribute is used for limiting the file size of a single file in which users are allowed to upload. Users are allowed to drag in two or more files at once but each of them has to be smaller than the size set by Maxsize. If one of the files is larger than the size set by Maxsize, an error message will occur and nothing will be uploaded.

For example, in the case of the previous sample code, you can upload multiple files, say, four files that are smaller than 5120KB at once but if one of them exceeds 5120KB, then an exception will occur and none of the four files will be uploaded to the server.

The unit of MaxsizeM attribute is in KB. If it is not assigned a value, it will use the value of Configuration.getMaxUploadSize() automatically while a negative value would mean that the file size is unlimited.

Detection

To collate "Drag and Drop" behavior, we are indroducing attribute detection. By set this attribute, when user are dragging in your application, Dropupload or it's content will show.

There are four valid value of detection :

none : Ignore drag action, always show Dropupload and content.
browser (default) : Dropupload does not show initially. When user dragging into browser, both Dropupload and content will be shown.
self : It will show Dropupload initially. When user dragging into Dropupload, the content will be shown.
id of other component : It's almost the same of self, but the trigger area is the component of appointed id.

The content value can be any HTML string, remember surround content value by CDATA block .

Notice : The Dropupload with detection="browser" setting can't put together with other Dropupload that detection is not "browser". If do so, the user can't drop file on it.

Customized File Viewer

Like traditional File Upload, it will show progress when uploading file.

Developer can design customized File Viewer. First implement a JAvaScript class handling the desplay of the uploading files. There is an example :

foo.MyFileViewer = zk.$extends(zk.Object, {
	updated: null,
	$init: function (uplder,  file) {
		this._uplder = uplder;
		var id = uplder.id,
			uri = zk.ajaxURI('/web/zk/img/progress2.gif', {au:true}),
			html = '<div id="' + id + '" class="viewer"><image class="float-left" src="' + uri + '"/>'
			+ '<div class="float-left">FileName: ' + file.name
			+ ' <a id="' + id + '-cancel">Cancel</a></div><div class="float-right">'
			+ msgzk.FILE_SIZE + ': <span id="' + id + '-sent">0</span> of '
			+ '<span id="' + id + '-total">0</span></div><div class="clear"></div></div>';
				
		jq(uplder.getWidget().getPage()).append(html);
			
		this.viewer = jq('#'+ id)[0];
		jq('#' + id + '-cancel').click(function() {
			uplder.cancel();
		});
	},
	update: function (sent, total) {
		jq('#'+ this._uplder.id + '-sent').html(Math.round(sent/1000) + msgzk.KBYTES);
		if (!this.updated) {
			this.updated = true;
			jq('#'+ this._uplder.id + '-total').html(Math.round(total/1024)+msgzk.KBYTES);
		}
	},
	destroy: function () {
		jq(this.viewer).remove();
	}
});

There are three functions above, $init, update, and destroy.

$init(uplder, file): When a user selects a file from file chooser, the function will be invoked.
- uplder A uploader object
- file The file user upload. It is a File object.
update(send, total): After the uploading engine receives the uploaded size, the function will be invoked.
- sent: An integer of the uploaded size.
- total: An integer of the total uploaded size.
destroy(): After the uploaded file is done or a user cancels the uploading file or the uploading file causes an error, the function will be invoked.

After finish foo.MyFileViewer, specify the JavaScript class in the viewerClass attribute.

<dropupload viewClass="foo.MyFileViewer" content="custom viewer" detection="none" />

Uploader

Here is a description table of the Uploader when passed a user selected a file.

Method	Usage
getWidget	Returns the widget that it belongs to.
cancel	Stops the uploading process.

Transforming the original File Viewer

Customized File Viewers written in the past can continued to be used, only with the need to make some slight changes :

The second parameter of $init() changes from the original filenm (type: String) into a file (type: File) object. Add filenm = file.name to solve it.
The first parameter of update(), send would originally pass an integer value in a range from 0 to 100, representing the percentage of the uploading process. Now it will pass the amount of the already uploaded amount of data (Bytes).

After Upload Finish

The uploaded files can be retrieved from the companion event, which is an instance of UploadEvent. For example,

<zscript><![CDATA[
public void showFileName(org.zkoss.zk.ui.event.UploadEvent event){
	org.zkoss.util.media.Media[] medias = event.getMedias();
	StringBuffer sb = new StringBuffer();
	for (org.zkoss.util.media.Media m : medias) {
		sb.append(m.getName()+"\n");
	}
	Messagebox.show(sb.toString());
}
]]></zscript>
<dropupload detection="none" onUpload="showFileName(event)" />

Browser Support

As Dropupload uses HTML5 technology, there are several browsers that does not support it. Currently it operates normally on Firefox (v.13), Chrome (v.19) and Safari (v.5.1.x), but IE9, Opera v.11.x cannot use this function.

Moreover, the detection setting cannot be displayed on some older machines.

Supported Events

Name	Event Type
`onUpload`	Event: UploadEvent Denotes user has uploaded a file to the component

Inherited Supported Events: LabelImageElement

Supported Children

*NONE

Use Cases

Version	Description	Example Location

Version History

Last Update : 2012/07/05

Version	Date	Content
6.1.0	June, 2012	Dropupload was introduced.