Dropupload"
Line 47: | Line 47: | ||
= Customized File Viewer = | = Customized File Viewer = | ||
− | Similar to [http://books.zkoss.org/wiki/ZK_Component_Reference/Essential_Components/Button#File_Upload '''file upload button'''], the file viewer will show the progress | + | Similar to [http://books.zkoss.org/wiki/ZK_Component_Reference/Essential_Components/Button#File_Upload '''file upload button'''], the default file viewer will show the uploading progress via a pop-up bar as illustrated below. |
[[Image:DefaultFileUploadVeiwer.JPG]] | [[Image:DefaultFileUploadVeiwer.JPG]] | ||
− | + | Alternatively, developers can also design customized File Viewer by implementing a JavaScript class to handle the display screen when uploading files. | |
+ | Below is an example of a customized file viewer where the progress bar is shown at the bottom of the browser. | ||
+ | |||
+ | [[File:CustomizedFileUploadVeiwer.JPG]] | ||
+ | |||
+ | |||
<source lang="javascript"> | <source lang="javascript"> | ||
foo.MyFileViewer = zk.$extends(zk.Object, { | foo.MyFileViewer = zk.$extends(zk.Object, { |
Revision as of 09:06, 6 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 set as unlimited.
Detection
This attribute will define what users see when they drag and drop files into the application i.e. how the Dropupload component and its content will appear according to their action.
There are four valid values of detection
:
none
: Ignore users' drag action, always show Dropupload and its content.browser
(default setting) : Dropupload is not visible in the application initially but shows up along with the content when users drag files into the browser.self
: Dropupload is visible in the application initially but the content only appears when users drag files into the component.- id of another component : Behaviour of this value is almost identical to
self
, except that the trigger area is inside the component of the appointed id.
The content
value can be any HTML string and remember to surround the content value by CDATA
block .
Note : A Dropupload with detection="browser"
cannot be used with another Dropupload component that has a different detection setting; users won't be able to drag a file into the component successfully.
Customized File Viewer
Similar to file upload button, the default file viewer will show the uploading progress via a pop-up bar as illustrated below.
Alternatively, developers can also design customized File Viewer by implementing a JavaScript class to handle the display screen when uploading files. Below is an example of a customized file viewer where the progress bar is shown at the bottom of the browser.
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 originalfilenm
(type: String) into afile
(type: File) object. Addfilenm = 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
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
Version | Date | Content |
---|---|---|
6.1.0 | June, 2012 | Dropupload was introduced. |