Parent | Child | Previous | Next
 

File Upload

Description

Upload a file to the server and store the file name or file contents in a field in a Grid, UX, or database table.

If you want to upload multiple files or have more control over the file upload, see File Upload - User Defined.

If you wish to upload files to Amazon S3, see File Upload - Amazon S3 Storage or Alpha Anywhere server.

If you are uploading files in a Cordova mobile application, see PhoneGap - File Upload.

Xbasic Event Handlers - Control Values

In a UX component, when the server-side Xbasic events defined in the Action Javascript builder fire, the control values for all of the controls on the UX are available to the Xbasic code. For example, assume that the UX had a control called 'FIELD1'. In the Xbasic event handlers, you can reference this value as follows

request.variables.v.r1.field1

File Upload in a UX Component

In order to add an event handler that performs a file upload action, you must add a special [File Upload/Download] control to the UX component.

The [File Upload/Download] control is in the Other Controls section of the Toolbox.

images/fileuploaddownload.jpg

Once you have added the [File Upload/Download] control, you can then use Action Javascript to define a File Upload action.

The [File Upload/Download] control can be data bound (just like any other control).

However, it is not required that the [File Upload/Download] control be data bound. If the control is not data bound, then then it is your responsibility to decide what to do with the uploaded binary data when the UX Component is submitted.

If the [File Upload/Download] control is data bound, it can be bound to either a character field or a binary field. When the UX Component is submitted, the uploaded data will be saved into the corresponding bound field (assuming you have added a Save Record Server-side event handler to the AfterValidate event).

If the [File Upload/Download] control is bound to a binary field, the binary contents of the uploaded file will be saved in the bound field.

If the [File Upload/Download] control is bound to a character field, the filename of the uploaded file will be stored in the character field, and the uploaded file itself will be stored in the folder that you specified when you defined the File Upload Action. (Actually, the transformed filename, as specified by the 'Stored filename transformation expression' will be stored in the bound field).

In the case where the [File Upload/Download] control is not data bound, your AfterValidate event handler can retrieve the binary data that was uploaded as follows (assuming that the Id of the [File Upload/Download] control is 'FILEUPLOAD_1'):

dim blobKey as c
'Every [File Upload/Download] control has an associated control with
'a '_A5FILEUPLOAD' name.
'After the file has been uploaded, it is stored in temporary session storage
'The 'key' for the data in session storage is stored in this hidden field.

blobKey = e.dataSubmitted.FILEUPLOAD_1__A5FILEUPLOAD
blobKey = word(blobKey,1,":")

dim blobUploaded as b
Session.GetDataFromFile(blobUploaded,blobKey)
Session.DeleteSessionFile(blobKey)

'You now have the uploaded file data in a variable called 'blobUploaded'
'Your event handler can process this data.

File Upload Properties

Target [File Upload/Download] control

Specify the name of the control to which the file will be uploaded.

Upload target

Defines the location where the file will be stored:

Target
Description
Server

Upload the file to the Application Server and store it in a folder on the server. Not supported on Alpha Cloud.

AmazonS3

Upload the file to a bucket on Amazon S3 or Wasabi Storage. File is uploaded directly to Amazon S3 or Wasabi Storage from the application, bypassing the Application Server.

AmazonS3Indirect

Upload the file to Amazon S3 or Wasabi Storage from the Application Server. The file is uploaded to the Application Server before being stored on Amazon S3 or Wasabi Storage.

Allowed file extensions

Specify a comma delimited list of allowed filename extensions. If the user uploads a file that does not match an allowed extension, the operation is aborted. If you leave this blank then any filetype can be uploaded as long as it is not on the disallowed list of file types.

Disallowed file extensions

Specify a comma delimited list of disallowed filename extensions. The user will not be able to upload a file with one of these extensions. You can only specify disallowed file types if the Allowed file types property is blank.

Invalid extension error message

Invalid extension error message property.

Upload folder

Specify the name of the folder where the uploaded file will be stored. You can use aliases in the name. If you enter a folder without a drive letter, the folder is assumed to be in the webroot. IMPORTANT: The folder that you specify here is a folder on the machine where your Application Server is running - not a folder on this machine! VERY IMPORTANT:If you have the Security Framework turned on and the upload folder is in the webroot, be sure to set the appropriate permissions for this upload folder and the files that it contains. You can use a session variable to specify the upload folder.

File exists action

If the file that was uploaded already exists in the Upload folder, what action should be taken. You can either overwrite the existing file, or rename the uploaded file. Choices include Overwrite, Rename.

Field for object type

For embedded files, the file type of the embedded file must be stored in a field. Choices include.

Field for object description

(Optional) For embedded files, stores the filename of the file that is embedded in the target field. Choices include.

Control to store filename

Specify the name of the control where the uploaded filename will be stored. (Note: If your component has been bound to a table, this control will typically be set to not be updateable, whereas the target [File Upload/Download] control will be bound to the same field and will be set to updateable.) Choices include.

Stored filename transformation expression

Specify what value to store in the target field. This is typically some transformation of the file name of the uploaded file. If you leave this blank, the fully qualified filename is stored in the target field.

On Stored filename compute Xbasic function

(Optional) If you want complete control over the filename of the uploaded file, you can call an Xbasic function to compute the filename.

Maximum file size

Specify the maximum file size that can be uploaded. Specify value in bytes. Specify 0 if you do not want to restrict the size of the file that can be uploaded. IMPORTANT: Regardless of this settings, the server also specifies a maximum POST body size. The lower of this setting and your setting for this property will apply.

Maximum file size exceeded message

Specify the message to display to the user if the uploaded file exceeds the maximum allowed file size.

Show progress/allow cancel

On certain browsers it is possible to show progress while files are being uploaded and to allow the user to cancel the operation. IE9 and earlier does not support this feature.

Abort upload button label

Specify the text for the Abort button. This button allows a user to stop an upload before it has completed.

Abort upload message

Specify the message to show if the user aborts an upload.

Progress bar type

Specify the type of progress bar. The 'A5' bar uses a specially styled progress bar that blends well with the selected component style. If you are using certain styles (e.g. GrBlue, GrOlive, etc.) you way want to switch to the 'Basic' style. Choices include A5, Basic.

Amazon S3 Storage Properties Properties

Method for specifying Amazon S3 credentials and bucket

Should the Amazon S3 credentials and bucket be read from a named storage connection string, or do you want to specify explict values for the access key, secret and bucket. Choices include Named Storage Connection String, Explicit.

Storage connection string

Specify the named storage connection string. IMPORTANT: The storage connection string MUST NOT BE ENCRYPTED. TIP: To define a storage connection string, go to the Tools menu in the Web Projects Control Panel.

Access key

Specify the access key.

Secret

Specify the secret.

Bucket

Specify the bucket.

Maximum file size

Specify the maximum size file that the user can select. Set to -1 for no maximum.

Max file size exceeded error message

Specify message to show if user selects a file that is too big. You can use language or text dictionary tags. Your message can include these placeholders: [filename], [filesize], [maxfilesize]. Leave blank if you have defined a custom Javascript onValidate event handler.

Max total file size

DOES NOT APPLY -- MULTIPLE NEVER ALLOWED Specify the maximum total size of all selected files. Set to -1 for no maximum.

Max total file size exceeded error message

DOES NOT APPLY -- MULTIPLE NEVER ALLOWED Specify message to show if all files selected exceed the max allowed. You can use language or text dictionary tags. Your message can include these placeholders: [filecount], [totalfilesize] and [maxtotalfilesize]. Leave blank if you have defined a custom Javascript onValidate event handler.

Allowed file types

Enter a comma delimited list of allowed file extensions. Leave blank to allow all file extentions.

Invalid file type error message

Specify message to show if all files selected exceed the max allowed. You can use language or text dictionary tags. Your message can include these placeholders: [filename], [filetype]. Leave blank if you have defined a custom Javascript onValidate event handler.

Display progress during file upload

Specify if progress should be shown while file(s) are being uploaded.

Allow cancel

Specify if the user can cancel an upload while the file is being uploaded.

Progress indicator type

Specify the progress indicator style. 'Text' - display the percentage as text, 'Bar' - display a progress bar. Choices include Text, Bar.

Progress bar color

Specify the progress bar color.

Progress bar width

Specify the progress bar width. Use CSS units.

Placeholder for progress indicator

Specify the name of a Placeholder control where the progress indicator should be shown. In the case of a Grid component, specify the name of a Static Text control which will act as a placeholder.

Authenticated read

Specify if authentication is required to read the object once it has been uploaded to S3

Format of value to store in target field

You can either store the URL for the object in the field (e.g. https://BUCKETNAME.s3.amazonaws.com/OBJECTNAME, or you can store a specially formatted JSON string that defines the object name and the connection string. For example: {cs: 'alphamediacapture',object: '4282.JPG',source: 'S3'} Choices include URL, JSON.

Temporary message to show field after upload completes

Specify the text to show in the target field after the upload has completed, but before the record is saved. Your text can use [objectName] as a placeholder for the name of the object on S3.

Customization - File Select Window Properties

Window title

Specify the title of the File Select dialog window.

Window position

Specify where the window will be shown.

Auto upload

Specify if the file should be uploaded as soon as the user has selected the file to upload. Alternatively, the upload will only start once the user has clicked on the 'Upload' button.

Working message

Specify the working message to display while the file is being uploaded to the server

Upload button

Specify the button text for the 'Upload' button.

Watermark

Specify the watermark text that appears in the file box. If you use a langauge tag for the text, be sure that the language definition returns a URL encoded value. See hyperlink below for more help.

File select button image

Select the image that appears on the button to open the file select window.

Prompt

Specify the text for the prompt that appears above the file box. If you use a langauge tag for the text, be sure that the language definition returns a URL encoded value. See hyperlink below for more help.

Window height

Specify the height for the pop-up File Select window.

Window width

Specify the width for the pop-up File Select window.

Cancel button label

Specify the label for the Cancel button. Before the file is uploaded, this button closes the dialog. If a confirmation dialog is show after the file is uploaded, this button aborts the action and does not save the uploaded file to the database.

Customized Error Messages Properties

Table not updateable

Specify the message to show if the table is not updateable because the logged in user does not have permission to update this table.

Field not updateable

Specify the message to show if the field is not updateable because the logged in user does not have permission to update this field.

Session expired

Specify the message to show if the session has expired. This error could occur if the 'Close File Select window after upload' property is false, the user uploads a file, but then does not click the 'OK' to save button immediately.

File Upload on New record row

Specify the message to show if the user tries to upload a file to a new record row. Files can only be uploaded to existing rows. Typically, you would want to hide the button that invokes the File Upload action for new record rows by specifying a 'Client-side show/hide expression' (e.g. data.rowNumber > 0)

Server-side Events Properties

After upload

Specify the name of the Xbasic function to call after the file has been uploaded. This Xbasic function can be defined in the 'Xbasic function declarations' section.

Javascript Properties

Target object name on Amazon S3

You can define a function that returns the name of the object in Amazon S3. By default, the filename of the file on the client will be used. Your code can reference e.name, e.size and e.type (the client-side name, size and mime-type of the selected file). Your function must return the name to use. The name can include a folder. For example: return 'myfolder1/' + e.name. This will use the same name as the client-side file but the object will be stored in a folder called 'myfolder1'. NOTE: The target name on Amazon will be available to other Javascript functions in the e.targetName property.

Before file select

Fires before the user selects file(s). If the Javascript contains 'return false;', the file upload is aborted.

After file select

Fires after file(s) have been selected, but before any files have been uploaded. If your code includes 'return false' the upload is aborted. You code can reference 'e' - an array of objects with information about each file selected. Each item in the array contains these properties: name, size, type.

On Progress

Fires when another 'chunk' of the file being uploaded has been sent. This event allows you to write custom progress displays. Your code can reference these variables: e.percent - percentage complete, e.message - message describing the current state of the upload operation, e.name - name of the file being uploaded, e.number - if more than one file was selected, the number of file, e.size - the file size and e.type - the mime-type of the file, e.targetName - the name to use on Amazon to store the file (usually the same as e.name unless your 'Target name on Amazon S3' function returned a different name or specified a folder)

On Error

Fires if there is any type of error. Your Javascript can reference e.errorText, e.errorCode - the XHR error code and e.fileObject - an object with properties (such as name, size, type) for the file on which the error occured.

On Upload Complete

Fires after the selected file has been uploaded. Your code can reference this variables: e.name - name of the file just uploaded, e.type - mime-type, e.size - file size, e.targetName - name used on Amazon.

On validate error

Fires if any of the selected files violate a validation rule. Your Javascript can refer to e.violationType ( can be 'size', 'totalSize' or 'type'), e.name, e.size and e.type.

Client-side Events Properties

Before upload

Specify the name of the Javascript function to call before the file upload window is shown. If this function returns false, the upload is aborted.

After upload

Specify the name of the Javascript function to call after the file has been sucessfully uploaded.

Videos

'File Upload' Action in Action Javascript

This video shows how you can configure the UX component to upload a file to the Alpha Anywhere server and then store the filename of the uploaded file in a character field in the table to which the UX component is data bound.

2015-02-15

Tutorial - Uploading Files and Images to a Data Bound UX Component

When you upload a file or an image to a data bound UX component, the assumption is that you want to store the uploaded image or file in the record to which the UX component is bound. You can either store the binary data that was uploaded in a field in the record, or you can save the binary data that was uploaded into a file on the server and then store the filename of the file in a character field in the record.

In this video we show how image upload and file upload to a data bound UX component can be done. Images and files are uploaded to both binary and character fields in the record.

Download Component

2014-10-02

The zip file also contains the MySQL SQL script to create the table that the UX component is based on.

See Also