Back to Controls

The FileUpload control encapsulates an HTML Form's File Select functionality within a Bungee Connect control, and adds a button for executing an HTTP Post.

Contents 1 Overview 2 Capabilities 2.1 Limitations 3 Requirements 4 Examples 4.1 Example 1: 4.1.1 A Simple HTML Form 4.1.2 PHP Server Code 4.2 Example 2: 5 Reference 5.1 Supported Types 6  Associated Properties 6.1 Specialized Properties 6.2 Unique Properties

Overview

The text area with the Browse button in the image above is the standard File Select control. The Upload File button is a submit button, which accomplishes an HTTP Post. When the user clicks the button, the name of the file the user is uploading is passed into the fileName field in the FileUploadHandle object. The FileUploadHandle object is necessary for the control to function at any level, and is the only data type to which you can attach the FileUpload control.

Using the Button Type property, you can set the FileUpload control to appear as any of the various button styles native to Bungee Connect. When an end user clicks the FileUpload button, a dialog opens that allows the end user to select a local file for uploading to a remote server. End users can specify the local file to upload either by entering the full path to the file, or by clicking the Browse... button and navigating to the desired file. After specifying which file to upload, the user clicks the button, sending the file to the web server you have previously designated as the destination server for files uploaded. The upload is performed as a Post of an HTML Form to a web server. The file does not get uploaded to Bungee Grid servers at anytime. The Bungee system merely initiates the connection to the destination server. This provides a cost savings to you (since no Bungee Units are accrued for file uploads), as well as ensuring the security of the contents of the file.

Capabilities

Use the FileUpload control to:

• Provide an interface for posting an HTTP Form to a web server without need for credentials (Example 1)
• Provide an interface for posting an HTTP Form to a web server requiring credentials (Example 2)

The customizations and capabilities available with the FileUpload control lie with the parameters of the HTML Form you can pass to the service that is the upload destination. These parameters are also in great measure controlled by the service itself, some services being very simple, and others quite complex. In addition, some services may require you to pass required information as a query URL, rather than in an HTML Form.

Limitations

In general terms, the limitations for this control are those you would find in the corresponding HTML File Select control.

• Longstanding Browser Limitations
• The control does not by default programmatically close the upload dialog. This is intentional. Some services provide a redirect when the file upload completes. If the FileUpload control forced a dialog close, this would override the service's functionality. In addition individual services may provide error handling which would be overwritten by a Bungee forced closure. For example, if there is a file upload error with Amazon's S3 service, S3 redirects to a web page that displays an error message. This enables you to debug file upload errors. You may choose to write your own redirects or error messages if you are providing the web server yourself. For an example of such a custom implementation, see Example 1

Requirements

The FileUpload control helps an end user designate the file to be uploaded, however most of the the functionality that makes the actual upload possible resides outside the control, and is provided through the object to which the control is bound. The actual functionality for setting the file upload destination and providing any credentials (ACL)s to the destination web server are provided through the FileUploadHandle data type.

In order for the control to work, you must:

• Obtain any needed rights to upload files to a given web server (for example, if you want to upload files to an Amazon S3 service server, you need to create an S3 account and obtain a valid key)
• Add a a field to a class in your project of type FileUploadHandle (located in the Resource TypeLib on the Dependencies tab of the Chooser), and use this interface to:
  • Provide a URI as the file upload destination
  • Provide any custom input required by the service that is the file upload destination

Examples

The following examples are intended to be used with sample code that you can import from the Design page's Home tab into your Bungee Builder DesignGroup. Each example is intended to build upon the previous example in order to provide you with a solid understanding of how to use this control.

Example 1:

Note The Bungee Sample Code for the FileUpload control will be made available on the Home tab of the Builder soon.

Example 1 shows what you need to do to enable the FileUpload control to upload files to a PHP web server destination.

A Simple HTML Form

The HTML version of the HTML Form used in the Bungee sample code appears below. This code is provided as an example of the values the Bungee sample code needed to contain. In addition, this HTML code provided a quick way to verify the interaction with the PHP code written for the server that was used in this example. 

PHP Server Code

The following code is provided as an example of the type of code you may need to write to handle file uploads if you are providing your own web server. Remember, neither the FileUpload control nor the FileUploadHandle provide a native dialog close feature. The example code below was written in PHP to enable the web server used for this example to handle uploaded files and return the proper responses for both successful and unsuccessful file uploads, as well as to close the dialog upon a successful file upload.

Example 2:

Note The Bungee Sample Code for the FileUpload control will be made available on the Home tab of the Builder soon.

Example 2 demonstrates how to configure the FileUploadHandle type so that the proper credentials are passed to enable upload to an Amazon S3 server. By setting a trigger on a function, your code can take action when the Bungee system detects the file upload and sets the fileName of the uploaded file. In this example, a function is called to display a dialog message containing the name of the file. In your own upload functionality, you might want to close all dialogs you had opened as part of the upload, and then continue processing.

 

Reference

Supported Types

Type	Summary
FileUploadHandle	The FileUploadHandle provides you the ability to set the parameters that get passed to the destination web server.

 Associated Properties

Common Properties Index

Specialized Properties

• Align
• Absorb Input Events
• ButtonImageSet
• Button Label
• Default
• Dynamic
• First Focus
• Ignore in Popup Sizing

Unique Properties

• Button Type
• Style Image
• Style Image Position