WMultiFileWidget
WMultiFileWidget is a component for creating a multi file upload tool and their associated file management list.
- Why use WMultiFileWidget
- Creating WMultiFileWidget
- File manipulation
- Input constraints
- Accessibility
- HTML output
- Appearance
- Setting a dropzone
- Disabling
- Hiding
- Related components
- Further information
WMultiFileWidget is used to upload files. Under most circumstances WMultiFileWidget should be preferred to WFileWidget, even if the upload is to be limited to a single file. WMultiFileWidget provides for asynchronous and drag-and-drop upload including setting a custom dropzone for the upload action.
- asynchronous upload;
- support for drag and drop upload;
- display of uploaded file's filename and/or icon;
- optional pre-upload image editor to do simple resizing, cropping, rotation and zoom of the image including customisable masks.
WMultiFileWidget has only a default constructor. This will create an empty, interactive multi file upload with no constraints.
WMultiFileWidget upload = new WMultiFileWidget();Files are usually added by the user but may be added and removed programmatically to represent files previously uploaded or the default files for a particular instance (based on, for example, bean data).
TODO: write me!
Files may be added using addFile().
TODO: write me!
TODO: write me!
A WMultiFileWidget may be marked as being a mandatory field in the UI. The input element will be marked required and the WLabel for the component, if present, will be decorated with a visual indicator that the component is mandatory.
// given WMultiFileWidget `upload`
// make the component mandatory
upload.setMandatory(true);A list of all MIME types which may be uploaded using the WMultiFileWidget may be set. If nothing is specified then any file type may be uploaded. If an application is required to limited the types of files uploaded then this must be explicitly specified for each WMultiFileWidget.
Valid values for this property are:
- the string
"audio/*"; - the string
"video/*"; - the string
"image/*"; - any valid MIME type with no parameters (see RFC 2616 s3.7); or
- any comma separated combination of these.
If the user attempts to upload a file which is in conflict with this setting they will receive an error message indicating the file type is not supported and cannot be uploaded.
The acceptable file types are set using a String array or Collection of Strings.
// Given WMultiFileUpload `upload`
// set acceptable file type to `PDF`
upload.setFileTypes(new String[]{"application/pdf"});
// set acceptable types to pdf, jpg or png:
upload.setFileTypes(new String[]{"application/pdf", "image/jpeg", "image/png"});It is possible to limit the largest file size (in bytes, as a long) allowed by the WMultiFileWidget. This is an optional property with no default. If not specified the largest file size will be determined by the host web server application. It is recommended that this property be specified for each WMultiFileWidget in an application.
If the user attempts to upload a file which is in conflict with this setting they will receive an error message indicating the file is too big and cannot be uploaded.
// Given WMultiFileUpload `upload`
// set max file size to 5MB (1E6 byters)
upload.setMaxFileSize(5* 1000 * 1000);
// Note to grumpy old nerds: 1 Kb is 1000 bytes NOT 1024 bytes (etc)It is possible to constrain the maximum number of files which may be uploaded using a single WMultiFileWidget (as an int). This is an optional property with no default setting. NOTE if this property is not specified then the WMultiFileWidget has no limit on the number of files which may be uploaded.
WComponents will attempt to process all uploaded files according to the action determined within the application but will take steps to preserve the memory and stability of the application server. Therefore if a WMultiFileWidget is allowed to upload an unlimited number of files some files may not be processed depending upon the size and number of files uploaded.
// Given WMultiFileUpload `upload`
// set max files to 5
upload.setMaxFiles(5);All WMultiFileWidgets must be adequately labelled (see below).
WMultiFileWidget allows files to be uploaded when they are dropped onto the component's dropzone. The default dropzone is the component itself. This is not available to keyboard-only users but it does not remove or replace the normal multi-file upload capability of the browser which is keyboard drivable. It does not, therefore, contravene accessibility norms.
All WMultiFileWidgets in a UI must be associated with a label or otherwise have their usage and intent exposed to all users. This may be done using (in order of preference):
- WLabel or by using the component in a WFieldLayout (preferred) this is required if the label must be visible in the UI; or
- using the toolTip property if the label does not have to be visible in the UI; or
- using the accessibleText property.
When designing a UI containing a file upload component and a visible label the WLabel must be placed immediately before the file upload component. This is done automatically by WFieldLayout.
See toolTip. A WMultiFileWidget may use the toolTip property if it is not possible to include a label in the UI. This should be a last resort.
// given WMultiFileWidget `upload`
// to set the toolTip
upload.setToolTip("this is a toolTip");WMultiFileWidget may have accessible text applied as information additional to the visible label text. This should be used with care and restraint as it may result in less accessible applications.
// with WMultiFileWidget `field`
field.setAccessibleText("Some further context to this file upload.");A WLabel for a WMultiFileWidget may be given an access key to provide rapid keyboard access. Using the access key to access a WFileWidget will immediately activate the file upload dialog in most modern user agents.
WMultiFileWidget outputs a HTML fieldset element containing form-related interactive content and must not be used in any context which forbids this content category.
When in read-only mode the WMultiFileWidget will output a HTML div element containing one or more lists of the uploaded files (if any) as determined by the thumbnails setting. This is non-phrasing content.
WMultiFileWidget when presented as an editable control with no files present:
-
-
WMultiFileWidget with a file ready to upload
-
WMultiFileWidget with thumbnails
The presentation of the file list or thumbnails of WMultiFileWidget are determined by the columns property.
-
No columns set
-
Three columns set
-
Columns set explicitly to 0
When read-only WMultiFileWidget shows uploaded files (optionally as thumbnails) but without the upload and delete controls:
The arrangement of uploaded file names (or thumbnails) is determined by setting a number of columns to display. If it is not set then the files are output in a single column. If set to 0 then the files are output in a row.
// Given WMultiFileUpload `upload`
// show the uploaded files in a single, wrapping row
upload.setColumns(0);
// show the files in three columns
upload.setColumns(3);Uploaded files may be displayed as a filename or a thumbnail. When displaying thumbnails WComponents can use a default thumbnail, generate thumbnails for image files, or use an application-defined thumbnail for particular file types.
// Given WMultiFileUpload `upload`
// show the uploaded files as thumbnails
upload.setUseThumbnails(true);
// show the files as text names
upload.setUseThumbnails(false);The size of the thumbnail may be controlled. The default is for the thumbnail to be 64px high and scaled. The thumbnail size is set using a java.awt.Dimension. If either the width or height of the Dimension is set to -1 then this dimension will be scaled to preserve the aspect ratio of the original image. Note, though that both width and height may not be -1.
// Given WMultiFileUpload `upload`
// set thumbnail size to a 32px square
upload.setThumbnailsSize(new Dimension(32, 32));
// set the thumbnail to 48px high and scaled to keep aspect ratio
upload.setUseThumbnails(new Dimension(48, -1));The file name may be included with the thumbnail by setting an ImagePosition. If this is not set (which is the default) then the file is displayed as a thumbnail without visible text.
// Given WMultiFileUpload `upload`
// show the uploaded files as thumbnails
upload.setUseThumbnails(true);
// show the text to the EAST
upload.setThumbnailPosition(ImagePosition.EAST);WMultiFileWidget may have a dropzone for uploading files via drag-and-drop. The dropzone may be any identified WComponent in the view and defaults to the WMultiFileWidget itself.
// Given WMultiFileUpload `upload` and WPanel `panel`
// set the dropzone to `panel`
upload.setDropzone(panel);A WMultiFileWidget may be disabled on page load. When disabled the WMultiFileWidget will not respond to user input or interaction. This property may be used in conjunction with WSubordinateControl controls to enable or disable content without making another server call. This property is ignored if the WMultiFileWidget is in a read only state.
// given WMultiFileWidget `upload`
// make it disabled
upload.setDisabled(true);A WMultiFileWidget may be hidden on page load. When hidden the WMultiFileWidget is not available to any compliant user agent. It is present in the source and is not obscured in any way. This property is determined by a WSubordinateControl. When a WMultiFileWidget is hidden its file and any WLabels associated with it are also hidden.
WMultiFileWidget may be a trigger for a WAjaxControl when the control will fire when a file is added, removed, selected or deselected. In addition there is a secondary action available when a file is uploaded.
TODO: extend this and add code sample.
See com.github.bordertech.wcomponents.examples.WMultiFileWidgetAjaxExample.