001: /* Fileupload.java
002:
003: {{IS_NOTE
004: Purpose:
005:
006: Description:
007:
008: History:
009: Tue Jul 19 10:26:42 2005, Created by tomyeh
010: }}IS_NOTE
011:
012: Copyright (C) 2005 Potix Corporation. All Rights Reserved.
013:
014: {{IS_RIGHT
015: This program is distributed under GPL Version 2.0 in the hope that
016: it will be useful, but WITHOUT ANY WARRANTY.
017: }}IS_RIGHT
018: */
019: package org.zkoss.zul;
020:
021: import java.util.List;
022: import java.util.Map;
023: import java.util.HashMap;
024:
025: import org.zkoss.mesg.Messages;
026: import org.zkoss.zul.mesg.MZul;
027: import org.zkoss.util.media.Media;
028:
029: import org.zkoss.zk.ui.Desktop;
030: import org.zkoss.zk.ui.Execution;
031: import org.zkoss.zk.ui.Executions;
032: import org.zkoss.zk.ui.HtmlBasedComponent;
033: import org.zkoss.zk.ui.UiException;
034: import org.zkoss.zk.ui.WrongValueException;
035: import org.zkoss.zk.ui.ext.client.Updatable;
036: import org.zkoss.zk.ui.event.Events;
037: import org.zkoss.zk.ui.event.UploadEvent;
038:
039: import org.zkoss.zul.impl.FileuploadDlg;
040:
041: /**
042: * A fileupload dialog used to let user upload a file.
043: *
044: * <p>There are two ways to use {@link Fileupload}:
045: *
046: * <h3>1. Open as a modal dialog:</h3>
047: *
048: * <p>You don't create {@link Fileupload} directly. Rather, use {@link #get()}
049: * or {@link #get(String, String)}.
050: *
051: * <h3>2. Embed as part of the page:</h3>
052: *
053: * <p>You can create it as a component and then listen to
054: * the onUpload event ({@link UploadEvent}).
055: * If the cancel button is pressed or file(s) is uploaded, the onClose event
056: * ({@link org.zkoss.zk.ui.event.Event}).
057: * is sent to notify the application. By default, it does nothing but
058: * invalidate the component, i.e., all fields are cleared.
059: *
060: * <p>A non-XUL extension.
061: *
062: * @author tomyeh
063: * @see Filedownload
064: */
065: public class Fileupload extends HtmlBasedComponent { //not XulElement since not applicable
066: private static String _templ = "~./zul/html/fileuploaddlg.zul";
067:
068: //Used when embedded as a component
069: /** The maximal alllowed number of files to upload. */
070: private int _maxnum = 1;
071: /** Wether to treat the uploaded file(s) as binary. */
072: private boolean _native;
073:
074: /** No child is allowed. */
075: public boolean isChildable() {
076: return false;
077: }
078:
079: /** Returns the maximal allowed number of files to upload.
080: * @since 2.4.0
081: */
082: public int getNumber() {
083: return _maxnum;
084: }
085:
086: /** Sets the maximal allowed number of files to upload.
087: * <p>Default: 1.
088: * @param maxnum the maximal allowed number (positive or negative).
089: * Since 3.0.2, the value can be negative, which means no limitation at all and the end user can upload
090: * any numbers he wants (since 3.0.2)
091: * @exception WrongValueException if non-positive, or it exceeds 1000
092: * @since 2.4.0
093: */
094: public void setNumber(int maxnum) throws WrongValueException {
095: if (maxnum < -1000 || maxnum == 0 || maxnum > 1000)
096: throw new WrongValueException(
097: maxnum == 0 ? "Positive or Negative is required"
098: : "Number too big (maximal 1000)");
099: _maxnum = maxnum;
100: }
101:
102: /** Returns whether to treat the uploaded file(s) as binary, i.e.,
103: * not to convert it to image, audio or text files.
104: * <p>Default: false.
105: * @since 3.0.0
106: * @see org.zkoss.zk.ui.util.Configuration#getUploadCharset
107: * @see org.zkoss.zk.ui.util.Configuration#getUploadCharsetFinder
108: */
109: public boolean isNative() {
110: return _native;
111: }
112:
113: /** Sets whether to treat the uploaded file(s) as binary, i.e.,
114: * not to convert it to image, audio or text files.
115: *
116: * @param alwaysNative whether to treat the uploaded file as binary
117: * stream, regardless its content type.
118: * If false (the default), it will convert to
119: * {@link org.zkoss.image.Image}, {@link org.zkoss.sound.Audio},
120: * binary stream, or text files depending on the content type.
121: * @since 3.0.0
122: * @see org.zkoss.zk.ui.util.Configuration#setUploadCharset
123: * @see org.zkoss.zk.ui.util.Configuration#setUploadCharsetFinder
124: */
125: public void setNative(boolean alwaysNative) {
126: _native = alwaysNative;
127: }
128:
129: /** Hanldes the onClose event which is sent when file(s) is uploaded
130: * or when the cancel button is pressed.
131: *
132: * <p>By default, it simply invalidates itself, i.e.,
133: * all fields are cleared.
134: * If you want to do something different, you can intercept the onClose
135: * event.
136: * @since 2.4.0
137: */
138: public void onClose() {
139: invalidate();
140: }
141:
142: //-- ComponentCtrl --//
143: protected Object newExtraCtrl() {
144: return new ExtraCtrl();
145: }
146:
147: /** A utility class to implement {@link #getExtraCtrl}.
148: * It is used only by component developers.
149: */
150: protected class ExtraCtrl extends HtmlBasedComponent.ExtraCtrl
151: implements Updatable {
152: //-- Updatable --//
153: /** Updates the result from the client.
154: * Callback by the system only. Don't invoke it directly.
155: *
156: * @param result a list of media instances, or null
157: */
158: public void setResult(Object result) {
159: Events.postEvent(new UploadEvent(Events.ON_UPLOAD,
160: Fileupload.this , FileuploadDlg
161: .parseResult((List) result)));
162: }
163: }
164:
165: /////Open as a Modal Dialog/////
166: /** Opens a modal dialog with the default message and title,
167: * and let user upload a file.
168: *
169: * @return the uploaded content, or null if not uploaded.
170: */
171: public static Media get() throws InterruptedException {
172: return get(null, null, false);
173: }
174:
175: /** Opens a modal dialog with the default message and title,
176: * and let user upload a file.
177: *
178: * @param alwaysNative whether to treat the uploaded file as binary
179: * stream, regardless its content type.
180: * If false (the default), it will convert to
181: * {@link org.zkoss.image.Image}, {@link org.zkoss.sound.Audio},
182: * binary stream, or text files depending on the content type.
183: * @return the uploaded content, or null if not uploaded.
184: * @since 3.0.0
185: * @see org.zkoss.zk.ui.util.Configuration#getUploadCharset
186: * @see org.zkoss.zk.ui.util.Configuration#getUploadCharsetFinder
187: */
188: public static Media get(boolean alwaysNative)
189: throws InterruptedException {
190: return get(null, null, alwaysNative);
191: }
192:
193: /** Opens a modal dialog with the specified message and title,
194: * and let user upload a file.
195: *
196: * @param message the message. If null, the default is used.
197: * @param title the title. If null, the default is used.
198: * @return the uploaded content, or null if not ready.
199: */
200: public static Media get(String message, String title)
201: throws InterruptedException {
202: return get(message, title, false);
203: }
204:
205: /** Opens a modal dialog with the specified message and title,
206: * and let user upload a file.
207: *
208: * @param message the message. If null, the default is used.
209: * @param title the title. If null, the default is used.
210: * @param alwaysNative whether to treat the uploaded file as binary
211: * stream, regardless its content type.
212: * If false (the default), it will convert to
213: * {@link org.zkoss.image.Image}, {@link org.zkoss.sound.Audio},
214: * binary stream, or text files depending on the content type.
215: * @return the uploaded content, or null if not ready.
216: * @since 3.0.0
217: * @see org.zkoss.zk.ui.util.Configuration#getUploadCharset
218: * @see org.zkoss.zk.ui.util.Configuration#getUploadCharsetFinder
219: */
220: public static Media get(String message, String title,
221: boolean alwaysNative) throws InterruptedException {
222: final Media[] result = get(message, title, 1, alwaysNative);
223: return result != null ? result[0] : null;
224: }
225:
226: /** Opens a modal dialog to upload mulitple files with
227: * the default message and title.
228: *
229: * @param max the maximal allowed number that an user can upload
230: * at once. If nonpositive, 1 is assumed.
231: * @return an array of files that an users has uploaded,
232: * or null if uploaded.
233: */
234: public static Media[] get(int max) throws InterruptedException {
235: return get(null, null, max, false);
236: }
237:
238: /** Opens a modal dialog to upload mulitple files with
239: * the default message and title.
240: *
241: * @param max the maximal allowed number that an user can upload
242: * at once. If nonpositive, 1 is assumed.
243: * @param alwaysNative whether to treat the uploaded files as binary
244: * stream, regardless its content type.
245: * If false (the default), it will convert to
246: * {@link org.zkoss.image.Image}, {@link org.zkoss.sound.Audio},
247: * binary stream, or text files depending on the content type.
248: * @return an array of files that an users has uploaded,
249: * or null if uploaded.
250: * @since 3.0.0
251: * @see org.zkoss.zk.ui.util.Configuration#getUploadCharset
252: * @see org.zkoss.zk.ui.util.Configuration#getUploadCharsetFinder
253: */
254: public static Media[] get(int max, boolean alwaysNative)
255: throws InterruptedException {
256: return get(null, null, max, alwaysNative);
257: }
258:
259: /** Opens a modal dialog to upload multiple files with
260: * the specified message and title.
261: *
262: * <p>The returned format depending on the content type.
263: *
264: * @param max the maximal allowed number that an user can upload
265: * at once. If nonpositive, 1 is assumed.
266: * If max is larger than 1000, 1000 is assumed.
267: * @return an array of files that an users has uploaded,
268: * or null if uploaded.
269: */
270: public static Media[] get(String message, String title, int max)
271: throws InterruptedException {
272: return get(message, title, max, false);
273: }
274:
275: /** Opens a modal dialog to upload multiple files with
276: * the specified message, title and options.
277: *
278: * @param max the maximal allowed number that an user can upload
279: * at once. If nonpositive, 1 is assumed.
280: * If max is larger than 1000, 1000 is assumed.
281: * @param alwaysNative whether to treat the uploaded files as binary
282: * stream, regardless its content type.
283: * If false (the default), it will convert to
284: * {@link org.zkoss.image.Image}, {@link org.zkoss.sound.Audio},
285: * binary stream, or text files depending on the content type.
286: * @return an array of files that an users has uploaded,
287: * or null if uploaded.
288: * @since 3.0.0
289: */
290: public static Media[] get(String message, String title, int max,
291: boolean alwaysNative) throws InterruptedException {
292: final Map params = new HashMap(8);
293: final Execution exec = Executions.getCurrent();
294: params.put("message", message == null ? Messages
295: .get(MZul.UPLOAD_MESSAGE) : message);
296: params.put("title", title == null ? Messages
297: .get(MZul.UPLOAD_TITLE) : title);
298: params.put("max", new Integer(max == 0 ? 1 : max > 1000 ? 1000
299: : max < -1000 ? -1000 : max));
300: params.put("native", Boolean.valueOf(alwaysNative));
301:
302: final FileuploadDlg dlg = (FileuploadDlg) exec
303: .createComponents(_templ, null, params);
304: try {
305: dlg.doModal();
306: } catch (Throwable ex) {
307: dlg.detach();
308: if (ex instanceof InterruptedException)
309: throw (InterruptedException) ex;
310: throw UiException.Aide.wrap(ex);
311: }
312: return dlg.getResult();
313: }
314:
315: /** Sets the template used to create the upload modal dialog.
316: *
317: * <p>The template must follow the default template:
318: * ~./zul/html/fileuploaddlg.zul
319: *
320: * <p>In other words, just adjust the label and layout and don't
321: * change the component's ID.
322: *
323: * <p>Note: the template has no effect, if you use {@link Fileupload} as
324: * a component (and embed it to a page).
325: */
326: public static void setTemplate(String uri) {
327: if (uri == null || uri.length() == 0)
328: throw new IllegalArgumentException("empty");
329: _templ = uri;
330: }
331:
332: /** Returns the template used to create the upload modal dialog.
333: */
334: public static String getTemplate() {
335: return _templ;
336: }
337: }
|