The FILE_UPLOAD Widget

The FILE_UPLOAD widget is a type of widget through which users can specify a file on a local computer to be uploaded to the server. Usually, the widget is displayed as a text field with a Browse button beside it. The user can click the button to open a file dialog box and select a file for upload.

Button appearance: The button is created by the browser. Therefore, the actual appearance of the button can vary depending on the browser that is being used. The normal widget attributes WIDTH and WIDTH_UNITS do not apply to the FILE_UPLOAD widget. Some browsers do not permit the width of the file name entry box to be set for security reasons. For example, if the width is set to zero width, the file name entry box could be hidden while it was still active.

Also, because the FILE_UPLOAD widget uses browser-specified controls, the text on the button is displayed in whatever locale the browser is set to, regardless of the locale that is configured in the application.

File Size Validation: There are settings to limit the maximum size of a file that is allowed to be uploaded. The validations for these settings are carried out on the server side after the file is fully uploaded to a temporary directory. Therefore, it should be kept in mind that large files could be uploaded consuming a large amount of disk space. We recommend checking the file upload folder at intervals to ensure disk space usage meets requirements.

There are three application-level configuration settings for the FILE_UPLOAD widget. These control how the web-server handles the incoming files. Default settings are already present, but the default values can be overridden by adding configuration settings to the ApplicationConfiguration.properties file. The settings follow the same name = value format of all the other entries there. The settings are as follows:

uploadMaximumSize: This is the maximum size of a file that can be uploaded to the server. The number is specified in bytes. If the number is negative, there is no limit to the file size. By default, the value is -1 (no limit).
uploadThresholdSize: This is maximum number of bytes of the file's content that the web-server will hold in memory while the file is being uploaded. Once the number of bytes uploaded exceeds this limit, the web-server will begin to store the file on disk to save memory. By default, the value is 1024.
uploadRepositoryPath: This is the path to the folder on the disk in which the files will be stored as they are uploaded if they exceed the threshold size. By default, the value is the JVM defined temp folder, so this folder must be present on your system. If it is not on your system, you can create it or explicitly set the uploadRepositoryPath to a folder of your choice.

The WIDGET element should have the TYPE attribute set to FILE_UPLOAD. The widget supports the following WIDGET_PARAMETER elements:

Table 1. Parameters to the FILE_UPLOAD Widget
Parameter Name	Required	Description and Connections
`CONTENT`	Yes	This parameter indicates the target connection for the actual content of the uploaded file. A single `CONNECT` element with a `TARGET` that connects to a property of an `ACTION` phase server interface is required.
`FILE_NAME`	No	This parameter represents the name of the file to be uploaded. The parameter can be set to provide a default name for the file to be uploaded, and can also supply the name of the file chosen by the user. If present, the parameter can include `CONNECT` elements for either or both end-points: a `SOURCE` end-point for the initial name of the file, and a `TARGET` end-point for the file that was actually chosen. The `SOURCE` end-point can specify a property of a `DISPLAY` phase server interface. The `TARGET` end-point can specify a property of an `ACTION` phase server interface. Note: Many browsers do not allow a default value for the name of a file to be uploaded. In this case, setting a `SOURCE` connection will have no effect.
`CONTENT_TYPE`	No	This parameter indicates the target connection for the content type of the uploaded file. The content type describes the format of the uploaded data. For example, a simple text file would have a content type of "text/plain" and a Microsoft Word document would have a content type of "application/msword". A single `CONNECT` element with a `TARGET` that connects to a property of an `ACTION` phase server interface is required.
`ACCEPTABLE_CONTENT_TYPES`	No	A HTML page only allows certain types of content to be uploaded by default (the actual default types are dependent on the browser). This parameter can specify the types of content that the page will accept. The value of the parameter should be a comma-separated list of content types. If there is more than one `FILE_UPLOAD` widget on a page, the acceptable content types of all widgets are pooled together and define what is acceptable for that page (this is a limitation of the HTML specification.) A single `CONNECT` element with a `SOURCE` that connects to a `TEXT` property is allowed.