WFileWidget
WFileWidget is a component for creating file upload fields. Under most circumstances WMultiFileWidget should be used instead. WFileWidget is limited to a single, synchronous file upload though a HTTP post.
- When to use
- Creating WFileWidget
- Accessibility
- HTML output
- Read only
- Appearance
- Disabling
- Hiding
- Related components
- Further information
Under most circumstances WMultiFileWidget should be preferred to WFileWidget, even if the upload is to be limited to a single file.
WFileWidget has only a default constructor. This will create an empty, interactive file upload with no constraints.
WFileWidget upload = new WFileWidget();A WFileWidget 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 WFileWidget `upload`
// make the component mandatory
upload.setMandatory(true);A list of all MIME types which may be uploaded using the WFileWidget 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 WFileWidget.
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 WFileWidget `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 WFileWidget. 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 WFileWidget 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 WFileWidget `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)WFileWidget uses a native file upload input to maximise cross platform compatibility and accessibility. All interactive WFileWidget controls are keyboard operable and exposed to assistive technologies. All file upload components must be adequately labelled.
All WFileWidgets 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 WFileWidget may use the toolTip property if it is not possible to include a label in the UI. This should be a last resort.
// given WFileWidget `field`
// to set the toolTip
field.setToolTip("this is a toolTip");WFileWidget 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 WFileWidget `field`
field.setAccessibleText("Some further context to this file upload.");A WLabel for a WFileWidget 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.
WFileWidget outputs a HTML input element of type="file" which is wrapped in a span element.
When in a read-only state the WFileWidget will output a HTML span element.
The read-only state changes the output rendering of the WFileWidget so that it appears as a reference to the uploaded file (if any). The control does not return any value back to the application.
A WFileWidget 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.
WFileWidget when presented as an editable control with no files present:
When a file is added to the control WFileWidget simply shows the file name in the input field:
A WFileWidget may be disabled on page load. When disabled the WFileWidget 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 WFileWidget is in a read-only state.
// given WFileWidget `upload`
// make it disabled
upload.setDisabled(true);A WFileWidget may be hidden on page load. When hidden the WFileWidget 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 WFileWidget is hidden any WLabels associated with it are also hidden.