com.smartgwt.client.docs
Interface Upload


public interface Upload

Uploading Files

Smart GWT provides special client and server-side support for file upload that allows uploaded files to be treated like ordinary DataSource fields. This includes: The following documentation assumes you are using the Smart GWT Java Server. If you are not, skip to the sections near the end of this document.

Single file upload: "binary" field type

To use Smart GWT's client-server upload system, you use a DataSource field of type "binary". By default, a DynamicForm bound to a DataSource with a field of type "binary" will use the FileItem, which displays a standard HTML <input type="upload"> form control.

When you call DynamicForm.saveData on a DynamicForm containing a FileItem, Smart GWT processes the save identically to a saveData() call that did not include a file upload:

Client-side callbacks, such as the callback passed to saveData(), fire normally.

Note that FileItems cannot be programmatically populated - this is a browser security restriction over which we have no control. This restriction means that we are unable to populate a FileItem with the correct filename when a form is editing an existing record. Also, when you call saveData() on a form that is editing a new record, the FileItem will be cleared on successful completion of the saveData() call; this is a side-effect of the form being placed into "edit" mode. In both of these cases, the fact that the FileItem has been cleared will not cause the persisted binary data to be removed by Smart GWT Server on subsequent calls to setData(). If the user selects another file, it will overwrite the existing one; if the FileItem is left blank, the server simply ignores it. If you actually wish to wipe out the value of a binary field, call updateData() on the underlying dataSource, passing an explicit null value for the binary field.

Processing File Uploads with server-side business logic

Server-side business logic that processes file uploads may retrieve upload files via the server side API dsRequest.getUploadedFile(fieldName). The uploaded file is returned as an instance of ISCFileItem, which provides access to a Java InputStream as well as metadata about the file (size, name). See the server-side JavaDoc (com.isomorphic.*) for details.

NOTE: request processing engines such as Struts may parse the inbound request before Smart GWT receives it. If you are creating an RPCManager object inside of a Struts Action and the file being uploaded is not available via dsRequest.getUploadedFile(), this is likely to be the problem, and you should remove Struts from the processing of the upload.

Server-side validation errors may be provided, including validation errors for the uploaded file (such as too large or invalid content), and will be displayed in the form that attempted an upload.

Be aware of the following special concerns when processing file uploads:

Multi file upload: MultiFileItem

The MultiFileItem provides an interface for a user to save one or more files that are related to a DataSource record, where each file is represented by a record in a related DataSource.

See the MultiFileItem docs for details.

Upload without the Smart GWT Server

If it is acceptable that the application will do a full-page reload after the upload completes, you can simply:

This cause the DynamicForm component to submit to the form.action URL like an ordinary HTML <form> element. Many online tutorials are available which explain how to handle HTML form file upload in various server-side technologies.

Note that when you submitForm(), the only values that will be sent to your actionURL are values for which actual FormItems exist. This differs from saveData(), in which the entire set of form values are always sent. To handle submitting extra values, use HiddenItems.

For further details, see the UploadItem docs.

Background upload without the Smart GWT Server

Achieving background file upload without using the Smart GWT server is also possible although considerably more advanced. In addition to the steps above, create a hidden <iframe> element in the page, and use target to target the form submission at this IFRAME. In order receive a callback notification when the upload completes, after processing the file upload, your server should output HTML content for the IFRAME that includes a <SCRIPT> block which will navigate out of the IFRAME (generally via the JavaScript global "top") and call a global method you have declared as a callback.

See Also:
UploadItem, FileItem, MultiFileItem, MultiFilePicker, ViewFileItem, FileItem.getEditForm(), FileItem.getUploadItem(), FileItem.getDisplayForm(), FileItem.getDisplayItem(), FileItem.getDisplayCanvas()