Dropupload"

From Documentation
m (Created page with "{{ZKComponentReferencePageHeader}} = Dropupload = *Demonstration: N/A *Java API: <javadoc>org.zkoss.zkmax.zul.Dropupload</javadoc> *JavaScript API: <javadoc directory="jsdoc">...")
 
Line 2: Line 2:
  
 
= Dropupload =
 
= Dropupload =
 
 
*Demonstration:  N/A
 
*Demonstration:  N/A
 
*Java API: <javadoc>org.zkoss.zkmax.zul.Dropupload</javadoc>
 
*Java API: <javadoc>org.zkoss.zkmax.zul.Dropupload</javadoc>
 
*JavaScript API: <javadoc directory="jsdoc">zul.wgt.Fileupload</javadoc>
 
*JavaScript API: <javadoc directory="jsdoc">zul.wgt.Fileupload</javadoc>
 
*Style Guide: N/A
 
*Style Guide: N/A
 +
*[http://www.zkoss.org/product/edition.dsp Available in ZK PE and EE only]
  
 
= Employment/Purpose =
 
= Employment/Purpose =
 +
<code>Dropupload</code> use HTML5 tecnnology, can handle action user drag file in it, and upload them to server. The behavior of <code>Dropupload</code> look like traditional ZK file upload, but can provide better user experience.
  
 
= Example =
 
= Example =
 +
<source lang="xml">
 +
<dropupload maxsize="5120" detection="none" onUpload="doSomething(event)">
 +
<attribute name="content"><![CDATA[
 +
<b>Drop Here</b><br/>
 +
size < 5MB
 +
]]></attribute>
 +
</dropupload>
 +
</source>
 +
 +
= Maxsize =
 +
The attribute <code>maxsize</code> will limit the file size user want to upload. Notice if user drop two or more files in Dropupload, all of these file size must smaller than <code>maxsize</code> setting, or will show error message and won't upload anything.
 +
 +
The unit of <code>maxsize</code> is KB. Negative value means unlimited. If developer does not assign <code>maxsize</code> value, it will assign the value of <code>Configuration.getMaxUploadSize()</code> automatically.
 +
 +
= Detection =
 +
To collate "Drag and Drop" behavior, we are indroducing attribute <code>detection</code>. By set this attribute, when user are dragging in your application, Dropupload or it's content will show.
 +
 +
There are four valid value of <code>detection</code> :
 +
* <code>none</code> : Ignore drag action, always show Dropupload and content.
 +
* <code>browser</code> (default) : Dropupload does not show initially. When user dragging into browser, both Dropupload and content will be shown.
 +
* <code>self</code> : 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 <code>self</code>, but the trigger area is the component of appointed id.
 +
 +
The <code>content</code> value can be any HTML string, remember surround content value by <code>CDATA</code> block .
 +
 +
= Customized File Viewer =
 +
Like traditional File Upload, it will show progress when uploading file.
 +
 +
[[Image:DefaultFileUploadVeiwer.JPG]]
 +
 +
Developer can design customized File Viewer. First implement a JAvaScript class handling the desplay of the uploading files. There is an example :
 +
<source lang="javascript">
 +
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();
 +
}
 +
});</source>
 +
 +
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'' [[#Uploader|A uploader object]]
 +
#* ''file'' The file user upload. It is a [http://www.w3.org/TR/FileAPI/ 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 <code>foo.MyFileViewer</code>, specify the JavaScript class in the <code>viewerClass</code> attribute.
 +
<source lang="xml"><dropupload viewClass="foo.MyFileViewer" content="custom viewer" detection="none" /></source>
 +
 +
=== Uploader ===
 +
Here is a description table of the ''Uploader'' when passed a user selected a file.
 +
{| border="1"
 +
|-
 +
!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 <code>$init()</code> changes from the original <code>filenm</code> (type: String) into a <code>file</code> (type: File) object. Add <code>filenm = file.name</code> to solve it.
 +
* The first parameter of <code>update()</code>, <code>send</code> 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 <javadoc>org.zkoss.zk.ui.event.UploadEvent</javadoc>. For example,
 +
<source lang="xml">
 +
<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)" />
 +
</source>
 +
 +
= 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 <code>detection</code> setting cannot be displayed on some older machines.
 +
 +
= Supported Events =
 +
{| border="1" | width="100%"
 +
! <center>Name</center>
 +
! <center>Event Type</center>
 +
|-
 +
| <center><tt>onUpload</tt></center>
 +
| '''Event:''' <javadoc>org.zkoss.zk.ui.event.UploadEvent</javadoc>
 +
Denotes user has uploaded a file to the component
 +
|}
 +
*Inherited Supported Events: [[ZK_Component_Reference/Base_Components/LabelImageElement#Supported_Events | LabelImageElement]]
 +
 +
= Supported Children =
 +
*NONE
 +
 +
= Use Cases =
 +
{| border='1px' | width="100%"
 +
! Version !! Description !! Example Location
 +
|-
 +
| &nbsp;
 +
| &nbsp;
 +
| &nbsp;
 +
|}
 +
 +
= Version History =
 +
{{LastUpdated}}
 +
 +
{| border='1px' | width="100%"
 +
! Version !! Date !! Content
 +
|-
 +
| 6.1.0
 +
| June, 2012
 +
| <javadoc>org.zkoss.zkmax.zul.Dropupload</javadoc> was introduced.
 +
|}
  
 
{{ZKComponentReferencePageFooter}}
 
{{ZKComponentReferencePageFooter}}

Revision as of 04:58, 27 June 2012

Dropupload

Employment/Purpose

Dropupload use HTML5 tecnnology, can handle action user drag file in it, and upload them to server. The behavior of Dropupload look like traditional ZK file upload, but can provide better user experience.

Example

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

Maxsize

The attribute maxsize will limit the file size user want to upload. Notice if user drop two or more files in Dropupload, all of these file size must smaller than maxsize setting, or will show error message and won't upload anything.

The unit of maxsize is KB. Negative value means unlimited. If developer does not assign maxsize value, it will assign the value of Configuration.getMaxUploadSize() automatically.

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 .

Customized File Viewer

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

DefaultFileUploadVeiwer.JPG

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.

  1. $init(uplder, file): When a user selects a file from file chooser, the function will be invoked.
  2. 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.
  3. 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

Supported Children

*NONE

Use Cases

Version Description Example Location
     

Version History

Last Update : 2012/06/27


Version Date Content
6.1.0 June, 2012 Dropupload was introduced.



Last Update : 2012/06/27

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