UploadAgent"

From Documentation
m (correct highlight (via JWB))
 
(28 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Template:UnderConstruction}}
 
 
{{ZATSEssentialsPageHeader}}
 
{{ZATSEssentialsPageHeader}}
 
__TOC__
 
__TOC__
 
  Since 1.1.0
 
  Since 1.1.0
  
ZATS Mimic introduces the <tt>UploadAgent</tt> to simulate file uploading operation with consistent usage. <tt>UploadAgent</tt> supports single or multiple files uploading as ZK components do. Following is typical steps:
+
ZATS Mimic introduces the <code>UploadAgent</code> to simulate file uploading operation and <code>UploadAgent</code> supports single or multiple file uploading. The following are the usage steps:
# Obtain a <tt>UploadAgent</tt> instance according to your case. '''Notice that you should use the same instance in one uploading iteration.'''
+
# Obtain a <code>UploadAgent</code> object.
# Upload a file by invoking <tt>upload()</tt> method. While uploading multiple files, repeat step 2.
+
#: Depending on your case, you could get it from a ''Button'' or from desktop. '''Note that you should use the same object before calling <code>finish()</code>.'''
# Invoke <tt>finish()</tt>method when the uploading is done.
+
# Upload a file by invoking <code>upload()</code> method.
 +
# Invoke <code>finish()</code> when there is no more file to upload.
  
= Upload File with a Component =
 
  
The basic way to upload files is using a component such as <javadoc>org.zkoss.zul.Fileupload</javadoc>, <javadoc>org.zkoss.zul.Button</javadoc>, <javadoc>org.zkoss.zul.Menuitem</javadoc>, <javadoc>org.zkoss.zul.Toolbarbutton</javadoc> and so on. <ref>for more detail, please refer to [[ZK Developer's Reference/UI Patterns/File Upload and Download]] and [[ZK Component Reference/Essential Components/Fileupload]]</ref> If we assign the <tt>upload</tt> attribute to these components, users can click and select a file to upload through the browser dialog, as following image shows:
+
= Uploading Files for Components with <code>upload</code> attribute=
 +
 
 +
To implement an uploading feature, you can simply use the <javadoc>org.zkoss.zul.Fileupload</javadoc> component. Alternatively, you can choose to use a button components such as <javadoc>org.zkoss.zul.Button</javadoc>, <javadoc>org.zkoss.zul.Menuitem</javadoc>, <javadoc>org.zkoss.zul.Toolbarbutton</javadoc> and so on.<ref>For more details, please refer to [[ZK Developer's Reference/UI Patterns/File Upload and Download]] and [[ZK Component Reference/Essential Components/Fileupload]]</ref> then set <code>true</code> to <code>upload</code> attribute of these components; users can then click and select a file to upload through a browser dialog, as illustrated below:  
 +
 
 
[[File:Zats_upload_button.png]]
 
[[File:Zats_upload_button.png]]
  
 +
'''Notes'''
 +
<references/>
  
We can cast these components as a <tt>UploadAgent</tt> and perform file uploading. Following is a typical example of single file uploading:
+
== Upload a Single File ==
  
<source lang="java" start="10" high="14, 15, 16,17,18">
+
We can cast these components described above as <code>UploadAgent</code> and perform file uploading. Following is a typical example of a single file uploading:
 +
 
 +
<source lang="java" start="10" highlight="14, 15, 16">
 
@Test
 
@Test
 
public void test() throws Exception {
 
public void test() throws Exception {
Line 23: Line 29:
 
DesktopAgent desktop = Zats.newClient().connect("/upload.zul");
 
DesktopAgent desktop = Zats.newClient().connect("/upload.zul");
 
UploadAgent agent = desktop.query("#btn").as(UploadAgent.class);
 
UploadAgent agent = desktop.query("#btn").as(UploadAgent.class);
agent.upload(file, null);
 
agent.finish();
 
 
agent.upload(file, "text/plain");
 
agent.upload(file, "text/plain");
 
agent.finish();
 
agent.finish();
 
}
 
}
 
</source>
 
</source>
* '''Line 14''': Cast component to <tt>UploadAgent</tt> and keep its reference.
+
* '''Line 14''': Cast component to <code>UploadAgent</code> and keep its reference.
* '''Line 15''': Invoke <tt>upload()</tt> method to upload a file.
+
* '''Line 15''': Invoke <code>upload()</code> method to upload a file.
* '''Line 16, 18''': Don't forget to invoke <tt>finish()</tt>method.
+
* '''Line 16''': Don't forget to invoke <code>finish()</code>method.
* '''Line 17''': After invoking <tt>finish()</tt>method, we can upload file again.
 
 
 
'''Notes'''
 
<references/>
 
  
= Upload Files with <javadoc method="get()">org.zkoss.zul.Fileupload</javadoc> =
+
== Uploading Multiple Files ==
  
Another way to upload files is to invoke the static method <tt>get()</tt> of <javadoc>org.zkoss.zul.Fileupload</javadoc>.<ref>for more detail, please refer to [[ZK Component Reference/Essential Components/Fileupload#Invoke the Static Method: get]]</ref> This static method will open a uploading dialog and allow users to upload single or multiple files (if configured), as following image shows.
+
Since '''ZK 6.0.0''', components now also support mutiple uploads at once  if they have <code>multiple=true</code> flag and users using web browsers supporting HTML5.<ref>For more detail, please refer to [[ZK_Component_Reference/Essential_Components/Button#Upload]]</ref> <code>UploadAgent</code> also supports multiple files uploading at once. Following is a typical example of uploading multiple files:
  
[[File:Zats upload dialog.png]]
+
<source lang="java" start="10" highlight="14, 15, 16, 17">
 
 
In this kind of case, we can retrieve <tt>UploadAgent</tt> from casting <javadoc>org.zkoss.zk.ui.DesktopAgent</javadoc>. Following is a typical example of file uploading with the static method:
 
 
 
<source lang="java" start="10" high="14, 15, 16, 17, 18">
 
 
@Test
 
@Test
 
public void test() throws Exception {
 
public void test() throws Exception {
 
File[] files = getFiles();
 
File[] files = getFiles();
 
DesktopAgent desktop = Zats.newClient().connect("/upload.zul");
 
DesktopAgent desktop = Zats.newClient().connect("/upload.zul");
desktop.query("#label2").click();
+
UploadAgent agent = desktop.query("#btn").as(UploadAgent.class);
UploadAgent agent = desktop.as(UploadAgent.class);
 
 
agent.upload(files[0], "text/plain");
 
agent.upload(files[0], "text/plain");
 
agent.upload(files[1], "image/png");
 
agent.upload(files[1], "image/png");
Line 57: Line 52:
 
}
 
}
 
</source>
 
</source>
* '''Line 14-15''': After triggering an event led to upload operation, we can cast <javadoc>org.zkoss.zk.ui.DesktopAgent</javadoc> as a <tt>UploadFile</tt> for uploading.
+
* '''Line 14''': Cast component to UploadAgent and keep its reference.
* '''Line 16-17''': We can upload multiple files at once.
+
* '''Line 15-16''': We can upload multiple files at once with ZK version greater than 6.0.0 and components that have <code>multiple=true</code> flag.
* '''Line 18''': Don't forget to invoke <tt>finish()</tt>method.
+
* '''Line 17''': Don't forget to invoke <code>finish()</code>method.
 +
 
  
 
'''Notes'''
 
'''Notes'''
 
<references/>
 
<references/>
  
= Upload Multiple Files with HTML5 Supported Browsers =
+
= Uploading Files with <code>Fileupload.get()</code> =
  
Since ZK 6.0.0, the components allowed uploading file support uploading multiple files at once if they have <tt>multiple=true</tt> flag and users use the web browsers supported HTML5. <ref>for more detail, please refer to [[ZK_Component_Reference/Essential_Components/Button#Upload]]</ref> Following is a typical example of multiple files uploading:
+
Another way to implement upload feature is to use the static method <javadoc method="get()">org.zkoss.zul.Fileupload</javadoc> as an event handler.<ref>For more detail, please refer to [[ZK Component Reference/Essential Components/Fileupload#Invoke the Static Method: get]]</ref> This static method will open up an uploading dialog and allow users to upload single or multiple files (if configured), as shown in the image below:
  
<source lang="java" start="10" high="14, 15, 16, 17">
+
[[File:Zats upload dialog.png]]
 +
 
 +
 
 +
<source lang='xml'>
 +
<label id="label1" value="click label1 will invoke fileupload.get()" onClick="Fileupload.get();" />
 +
<label id="label2" value="click label2 will invoke fileupload.get(3)" onClick="Fileupload.get(3);" />
 +
</source>
 +
 
 +
In this case, we can retrieve <code>UploadAgent</code> from <javadoc>org.zkoss.zk.ui.DesktopAgent</javadoc>. Following is a typical example of file uploading with <javadoc method="get()">org.zkoss.zul.Fileupload</javadoc>:
 +
 
 +
<source lang="java" start="10" highlight="14, 15, 16, 17, 18">
 
@Test
 
@Test
 
public void test() throws Exception {
 
public void test() throws Exception {
 
File[] files = getFiles();
 
File[] files = getFiles();
 
DesktopAgent desktop = Zats.newClient().connect("/upload.zul");
 
DesktopAgent desktop = Zats.newClient().connect("/upload.zul");
UploadAgent agent = desktop.query("#btn").as(UploadAgent.class);
+
desktop.query("#label2").click();
 +
UploadAgent agent = desktop.as(UploadAgent.class);
 
agent.upload(files[0], "text/plain");
 
agent.upload(files[0], "text/plain");
 
agent.upload(files[1], "image/png");
 
agent.upload(files[1], "image/png");
Line 79: Line 86:
 
}
 
}
 
</source>
 
</source>
* '''Line 14''': Cast component to UploadAgent and keep its reference.
+
* '''Line 14-15''': After triggering an event leading to an uploading operation, we can cast <javadoc>org.zkoss.zk.ui.DesktopAgent</javadoc> as a <code>UploadAgent</code> for uploading.
* '''Line 15-16''': We can upload multiple files at once.  
+
* '''Line 16-17''': We can also upload multiple files at once using <javadoc method="get()">org.zkoss.zul.Fileupload</javadoc>.
* '''Line 17''': Don't forget to invoke <tt>finish()</tt>method.
+
* '''Line 18''': Don't forget to invoke <code>finish()</code>method.
  
  
Line 102: Line 109:
 
|
 
|
 
|-
 
|-
| Button
+
| Button, Menuitem, Toolbarbutton
| 5, 6
 
|
 
|-
 
| Menuitem
 
| 5, 6
 
|
 
|-
 
| Toolbarbutton
 
 
| 5, 6
 
| 5, 6
 
|
 
|

Latest revision as of 02:56, 18 January 2022


Since 1.1.0

ZATS Mimic introduces the UploadAgent to simulate file uploading operation and UploadAgent supports single or multiple file uploading. The following are the usage steps:

  1. Obtain a UploadAgent object.
    Depending on your case, you could get it from a Button or from desktop. Note that you should use the same object before calling finish().
  2. Upload a file by invoking upload() method.
  3. Invoke finish() when there is no more file to upload.


Uploading Files for Components with upload attribute

To implement an uploading feature, you can simply use the Fileupload component. Alternatively, you can choose to use a button components such as Button, Menuitem, Toolbarbutton and so on.[1] then set true to upload attribute of these components; users can then click and select a file to upload through a browser dialog, as illustrated below:

Zats upload button.png

Notes

Upload a Single File

We can cast these components described above as UploadAgent and perform file uploading. Following is a typical example of a single file uploading:

@Test
public void test() throws Exception {
	File file = getFile();
	DesktopAgent desktop = Zats.newClient().connect("/upload.zul");
	UploadAgent agent = desktop.query("#btn").as(UploadAgent.class);
	agent.upload(file, "text/plain");
	agent.finish();
}
  • Line 14: Cast component to UploadAgent and keep its reference.
  • Line 15: Invoke upload() method to upload a file.
  • Line 16: Don't forget to invoke finish()method.

Uploading Multiple Files

Since ZK 6.0.0, components now also support mutiple uploads at once if they have multiple=true flag and users using web browsers supporting HTML5.[1] UploadAgent also supports multiple files uploading at once. Following is a typical example of uploading multiple files:

@Test
public void test() throws Exception {
	File[] files = getFiles();
	DesktopAgent desktop = Zats.newClient().connect("/upload.zul");
	UploadAgent agent = desktop.query("#btn").as(UploadAgent.class);
	agent.upload(files[0], "text/plain");
	agent.upload(files[1], "image/png");
	agent.finish();
}
  • Line 14: Cast component to UploadAgent and keep its reference.
  • Line 15-16: We can upload multiple files at once with ZK version greater than 6.0.0 and components that have multiple=true flag.
  • Line 17: Don't forget to invoke finish()method.


Notes

Uploading Files with Fileupload.get()

Another way to implement upload feature is to use the static method Fileupload.get() as an event handler.[1] This static method will open up an uploading dialog and allow users to upload single or multiple files (if configured), as shown in the image below:

Zats upload dialog.png


			<label id="label1" value="click label1 will invoke fileupload.get()" onClick="Fileupload.get();" />
			<label id="label2" value="click label2 will invoke fileupload.get(3)" onClick="Fileupload.get(3);" />

In this case, we can retrieve UploadAgent from DesktopAgent. Following is a typical example of file uploading with Fileupload.get():

@Test
public void test() throws Exception {
	File[] files = getFiles();
	DesktopAgent desktop = Zats.newClient().connect("/upload.zul");
	desktop.query("#label2").click();
	UploadAgent agent = desktop.as(UploadAgent.class);
	agent.upload(files[0], "text/plain");
	agent.upload(files[1], "image/png");
	agent.finish();
}
  • Line 14-15: After triggering an event leading to an uploading operation, we can cast DesktopAgent as a UploadAgent for uploading.
  • Line 16-17: We can also upload multiple files at once using Fileupload.get().
  • Line 18: Don't forget to invoke finish()method.


Notes

Supported Components

Components
Version
Note
DesktopAgent 5, 6
Fileupload 5, 6
Button, Menuitem, Toolbarbutton 5, 6




Last Update : 2022/01/18

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