Skip to content

WMultiFileWidget

Jump to bottom
Mark Reeves edited this page Jan 3, 2018 · 7 revisions

WMultiFileWidget is a component for creating a multi file upload tool and its associated file list.

Why use WMultiFileWidget

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 dropzone for the upload action.

Advantages of WMultiFileWidget

  • 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.

Creating WMultiFileWidget

WMultiFileWidget has only a default constructor. This will create an empty, interactive multi file upload with no constraints.

WMultiFileWidget upload = new WMultiFileWidget();

File manipulation

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).

Accessing files

The files added to the WMultiFileUpload may be accessed for processing and manipulation. The method getFiles() returns a List of FileWidgetUpload instances which refer to the original files. Each FileWidgetUpload has an identifier which is generated during the upload process. If this identifier is available then the FileWidgetUpload may be accessed using the identifier as a key.

// Given WMultiFileUpload `upload`
// get the list of uploaded files
List<FileWidgetUpload> files = upload.getFiles();

// if we have a file ID `fileId` available
// we can get a sinfle FileWidgetUpload
FileWidgetUpload file = upload.getFile(fileId);

Adding files

Files are usually added by the user but may be added programmatically to represent files previously uploaded or the default files for a particular instance. Files may be added using addFile.

// Given WMultiFileUpload `upload`
// Add a file `file`
upload.addFile(new FileWidgetUpload(null, file));

Removing files

Each file added to the WMultiFileUpload may be removed. To do this one must have a handle to the file. This can be by using the FileWidgetUpload instance or by extracting the FileWidgetUpload instance from the List returned by getFiles().

// Given WMultiFileUpload `upload` and FileWidgetUpload `file`
// remove `file` from the list of files
upload.removeFile(file);

Removing all files

The component can be reset, removing all uploaded files, using clearFiles().

// Given WMultiFileUpload `upload`
// remove all uploaded files
upload.clearFiles();

Input constraints

Mandatory

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);

Limit file types

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"});

Limit file size

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)

Number of files allowed

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);

Accessibility

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.

Labeling

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.

A WMultiFileWidget which is not appropriately labelled may display an unlabelled control warning.

A label for a WMultiFileWidget is implemented as a HTML legend element immediate child of the WMultiFileWidget's fieldset.

If the WMultiFileWidget is associated with a WLabel (including by being added to a WField) then the content of the label is also output in-situ as a HTML span element. This span is then marked as aria-hidden="true" to prevent double reading in PC mode but has scripted helpers to ensure it behaves in a manner equivalent to a legend (for access key support) and a label (for mouse users).

Under most circumstances the pseudo-label will be hidden from all users and the legend will be visible. When in a WFieldLayout with LAYOUT_FLAT, however, this is changed and the pseudo-label is made visible and the legend moved out of viewport (not hidden). This keeps the label for a WMultiFileWidget consistent with WLabels for simple inputs.

Where a WMultiFileWidget has its toolTip property set but is not associated with a WLabel the content of the toolTip is placed in the legend and may be rendered out of viewport.

Exposing constraints

If the WMultiFileWidget has input constraints then there must be an indication of these constraints somewhere in the UI and available to all users. The appropriate place for this information is in the WLabel hint.

If the control is mandatory this indication is automatically generated within the legend element and the legend (if visible) and pseudo-label (if present) are both decorated accordingly.

Setting a toolTip

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("Some further context to this file upload");

Additional labelling text

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");

Access Keys

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.

Default focus

A WMultiFileWidget in an enabled, interactive state may be set as the default focus point for a page. If this is specified it must comply with accessibility principles regarding focus and not put users into a position where they may skip content required for full understanding of the current view. See Setting focus for more information. When focussed the file input element in the component will receive focus.

HTML output

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.

Read only

The read-only state changes the output rendering of the WMultiFileWidget so that it appears as a representation of the control which cannot change the existing files list. The control does not return any value back to the application. Files which exist within the component are rendered (with optional thumbnails) and may be accessed for viewing. Files may not be selected or deselected, added or removed.

A WMultiFileWidget in a read-only state may be the target of a WSubordinateControl or WAjaxControl. If it is the target of an AJAX action its state may be changed to remove the read-only setting.

Appearance

WMultiFileWidget when presented as an editable control with no files present:

  • File upload with no file present

  • WMultiFileWidget with a file ready to upload

    WMultiFileWidget with a file ready to upload

  • WMultiFileWidget with thumbnails

    WMultiFileWidget with two files showing thumbnails

The presentation of the file list or thumbnails of WMultiFileWidget are determined by the columns property.

  • No columns set

    WMultiFileWidget with columns unsset

  • Three columns set

    WMultiFileWidget with columns set to 3

  • Columns set explicitly to 0

    WMultiFileWidget with columns set to 0

When read-only WMultiFileWidget shows uploaded files (optionally as thumbnails) but without the upload and delete controls:

  • WMultiFileWidget in read-only mode
  • WMultiFileWidget in read-only mode
  • WMultiFileWidget in read-only mode

Arranging the file list

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);

Displaying thumbnails

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. Generated thumbnails are cached for reuse (but may be cleared, see below).

// Given WMultiFileUpload `upload`
// show the uploaded files as thumbnails
upload.setUseThumbnails(true);

// show the files as text names
upload.setUseThumbnails(false);

If thumbnails are to be removed or re-built (for example if the thumbnail size is changed), this is done by clearing the current thumbnails. If thumbnails are re-requested after clearing they will be re-generated.

// Given WMultiFileUpload `upload`
// remove thumbnails
upload.clearThumbnails();

Thumbnail size

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));

Showing text and thumbnails

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);

Customising based on HTML class

WMultiDropdown may have one or more values to be added to the component's wrapper element. This can be used for fine-grain styling of specific components but should be used with care and is not recommended for any input control.

For more information see WComponents HTML class property.

Setting a dropzone

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);

Disabling

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);

Hiding

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.

Upload actions

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.

FileWidgetUpload

The FileWidgetUpload class is a static inner class of WMultiFileWidget used to represent uploaded files. It is used when adding, accessing and removing files from a WMultiFileWidget instance. The file represented by an instance of FileWidgetUpload is a com.github.bordertech.wcomponents.file.File, most commonly (and simply) implemented via com.github.bordertech.wcomponents.file.FileItemWrap

// Given a file `file` create an instance of FileWidgetUpload
// with a generated unique id
FileWidgetUpload fwu = new FileWidgetUpload(null, file);
// Create an instance of FileWidgetUpload with a
// specified file ID 'myFileId'
fwu = new FileWidgetUpload("myFileId", file);

The file may be accessed from a FileWidgetUpload using getFile() and the file ID using getFileId().

// Given a FileWidgetUpload `fwu`
// get the file ID
String fileId = fwu.getFileId();
// get the file
File file = fwu.getFile();

Related components

Further information

Some start pages

Clone this wiki locally