4.4: File Upload Control (Requires Server Controllers)

This control can be used to upload a file from you local computer to the server. You can drag the control onto a page in exactly the same manner as with other controls, but there are a few additional considerations due to the fact that a file is being uploaded instead of a simple value. This control supports two different approaches for handling the files uploaded to the server, Encode into Data and Upload to Directory, which are described in more detail below. For each control, you can choose which approach to use on the Page Display Bindings section of the Bindings tab on Page Design. Encode into Data This is the default option, and will cause the uploaded file to be base 64 encoded, with the resulting string inserted into the XML message. The Action Submission binding for each control indicates where the information will be inserted, and the following XML format will always be placed at this location:

<fileUpload success="true" name="myfile.png" type="image/png">base 64 encoded string</fileUpload>

The name attribute will contain the name of the file that has been uploaded, and the type attribute will indicate its mime type. If the upload fails for any reason then the success attribute will be set to false, and there will be an additional errorMsg attribute indicating the cause of the problem. Upload to Directory With this option, the uploaded file will be placed in a directory on the server rather than included in the XML message. In this mode, the information placed at the action submission binding location will be like the following:

<fileUpload success="true" name="myfile.png" type="image/png" location="c:\path\to\webapp\uploaded_files\01715441E103CDE532226B1C35826E17_myfile.png"/>

The success, name, and type attributes are the same as above. The location attribute will contain the full path to where the uploaded file has been placed. You can use file manipulation code/rules on the server to further process your uploaded files. By default, these files will be placed within a directory called uploaded_files located within the context location for the deployed web application. This means that they will be accessible to all users accessing the application. If required, you can change the directory in which the uploaded files are placed by editing the xgate.xml configuration file. (See section on the XGate Servlet.) This will contain a file_upload plugin element which can have an upload_dir attribute specified. If provided, this should contain the full path to the directory in which any uploaded files will be stored. When the Select File button is clicked, their browser will provide a standard file selection popup to enable the selection of the file that requires uploading. By default, this will show all files, but it is possible to suggest to the browser which types of files should be allowed. This can be done by adding a Custom Attribute to the control called accept, and a value indicating what files to allow, e.g. .png,.jpg. For more details on the supported values please see this page on the w3schools.com site. It is important to note that this is only a suggestion to the browser. Not all browsers support it, and those that do, still provide the option to select a different file. If required, you can perform some additional checks on the selected file by using an onchange event on the file upload control. This will be called whenever a file has been selected, and you can get the 'value' of the control to find the name of the selected file. (If using HTML5-compliant browsers you can obtain even more details using the File API) Regardless of any client-side checks and restrictions you put in place, there will still be ways for someone to circumvent them and send an arbitrary file to the server. Therefore, for security, you will need to add additional server-side checks as described below. The file upload functionality on the server can be extended if required to perform additional checks or exercise greater control over the process. This is done by writing a custom File Upload Plugin in Java, and then updating the xgate.xml configuration file for your project to include it. Each File Upload Plugin should be a custom Java class that implements the com.hyfinity.xgate.upload.FileUploadPlugin interface. The JavaDoc for this interface is available here, and it defines two important methods. The init method will be called when the plugin is first initialised, whereas the processUpload will be called for every uploaded file and will need to contain the main processing. This method will be called before the built-in file handling is performed, and it must return a boolean value which will control whether this built in functionality happens at all. As an example, if you wanted to only allow certain types of files, you could create a plugin which performs a check on the mime type of the uploaded file in the processUpload method. If the file is acceptable, the method can just return true. If not, it could set the success attribute of the statusElem parameter to false, and add an appropriate errorMsg attribute. It can then return false to stop the file from being uploaded. Similarly, you may wish to perform a virus scan of the uploaded file before accepting it. For this, you would interface with the virus scanning engine you are using in the processUpload method of the plugin, and return true or false accordingly as above. It is also possible to completely handle the upload process in the plugin, and always return false to prevent the default behaviour. However, it is important to update the statusElem accordingly, as this is the information that will be available in the rest of the application (e.g. rules processing) about the uploaded file. To get the application to use your plugin it needs to be compiled and made available to the runtime environment. For example, by creating a JAR, and placing this into the WEB-INF/lib directory for the project. The xgate.xml configuration file also needs to be updated to include the details for this plugin. Within this, the file_upload element should be given a plugin_class attribute. This should contain the complete class name of the specific FileUploadPlugin to use for this application. e.g. com.example.MyFileUploadPlugin. Newer web browsers (e.g. IE10+, Edge, Chrome, Firefox) have better support for file uploads, and provide additional capabilities. For example, in these browser it is possible to upload files to the server using AJAX calls as well as traditional form submissions. This means that within WebMaker, any AJAX Submission calls (to load in a Partial Page) can be used to upload files to the server within these browsers. It is also possible to allow uploading of multiple files at a time, by enabling the Allow multiple selections? option. With this enabled, modern browsers will allow the selection of multiple files in the File Selection dialogue in the standard way (e.g. ctrl-click, shift-click etc). When the data is submitted, each selected file will be treated independently by WebMaker, and you will receive a 'fileUpload' XML fragment in the data (as described above) for each one. Another option provided by WebMaker is to Allow drag and drop of files?. This is available if multiple selection is active, and when enabled will show a 'drag area' beneath the upload control onto which files can be dragged for upload. The exact appearance of this drag area will be controlled by the Theme that is in use, but the help text displayed within this area can be set using the 'Display text for the drag area' field. As files are dragged onto the area, the text will change to show the names of the files that have been dragged. It is important to note that any files that are dragged on in this way can only be uploaded using an AJAX Submission action. They will not be included in a standard form submission. As a result, it is quite common to use an onchange event with this type of control to automatically begin uploading the files as soon as they are dragged on.