File Upload - User Defined

Description

Upload one or more files to the server. A server-side event then gets called to allow you to process the uploaded files.

Discussion

This action allows you to upload multiple files at once. Once the files have been uploaded, an Xbasic event handler that you define is called to processes the uploaded files.

To see what information is available to you in the 'e' object that is passed into your Xbasic event handler, put a debug statement in your function:

debug(1)

When the component is run in Live Preview, the Xbasic debugger will open when the debug statement is encountered, allowing you to inspect the 'e' object to see what information is available.

Tutorial - Uploading Files using the File Upload - User Defined Action 

There are two different actions in Action Javascript for uploading files from a UX component. If the UX component has been 'data bound' then the 'File Upload' action is appropriate. But if the UX component is not data bound, or if you want to write your own handler for the binary data that was uploaded to the server, the 'File Upload - User Defined' action should be used.

When you use the File Upload - User Defined action, an Xbasic function that you define is called after the file (or multiple files if you choose to allow multiple files to be uploaded) has been uploaded. Your Xbasic function is free to process the uploaded data in any way.

In this video we show how the File Upload - User Defined action can be used to save the uploaded data to a file on the server.

Download Component

2014-10-02

Customizing the File Upload Window Text 

When you upload a file or image, a window is displayed where you can select the file or image to upload.

You can customize several aspects of this window, including:

  • Window title
  • The prompt above the 'file select' textbox
  • The watermark text shown in the 'file select' textbox when no selection has been made
  • Upload and Cancel button text

A common pattern for specifying the text to show in the Window is to use Language Tags when you define the strings for the customizable parts of the window. For example, you might set the window title to:

<a5:r>UploadWindowTitle</a5:r>

If you want to use International Characters when customizing the text in the Window, you must use Language Tags.

Language Tags are defined in the 'Language Definition' for the component. To edit the Language Definition, click the smart field button for the 'Language Definition' property.

Setting the 'Prompt' and 'Watermark' Text Properties Using Language Tags 

When you set the 'Prompt' and 'Watermark' text properties using Language Tags you need to make sure that the Language Tags return urlencoded values.

If you simply type a text string into the 'Prompt' or 'Watermark' property, the builder will automatically urlencode the string. But if you use a Language Tag, then the builder cannot do automatic url encoding for you, and it is necessary to embed an instruction into the Language Definition to URL encode the value.

For example, say you set the 'Prompt' property in the builder to:

<a5:r>FileUploadPrompt</a5:r>

When you define the 'FileUploadPrompt' tag in the Language Definition, you will need to use the special tag (urlencode{{...}}) to ensure that the Language Definition returns a URL encoded value for this language tag. For example, here is how the 'FileUploadPrompt' tag might be defined in the Language Definition:

FileUploadPrompt=urlencode{{HTML encoded text goes here}}

To get the HTML encoded version of a text string that contains International Characters, you can select the 'Open text encoder window' menu command from the 'Tools' menu when the Web Control Panel has focus.

Contrast File Upload Actions 

Action Scripting offers two different File Upload actions. These are:

  • File Upload - User Defined
  • File Upload - Amazon S3 Storage or Alpha Anywhere Server

The actions are similar in that they both allow you to select one or more files to upload and then call an Xbasic function to process the uploaded files.

The main difference between the two actions is apparent when you configure the actions to allow the user to select multiple files to be uploaded.

Both actions can upload files to either the Alpha Anywhere server or to Amazon S3

In the case of the File Upload - User Defined action, the user must select one file at a time from the File Selection dialog that opens when they click a button to select files. The selected files do not all have to be in the same directory. Once the upload starts, a single progress bar is displayed to show the progress of the entire upload job and the Xbasic function that is specified to process the uploaded files is called once when all of the selected files have been uploaded. The user can cancel the upload before the job is completed, but the entire job is cancelled - the user cannot cancel individual files.

On the other hand, the File Upload - Amazon S3 Storage or Alpha Anywhere Server action allows the user to select multiple files at once. However, all of the selected files must come from the same directory. Once the upload starts, a separate progress bar is shown for each selected file, allowing the user to cancel the upload of individual files. The Xbasic function that is specified to process the uploaded files is called for each uploaded file once each file has been uploaded.

The File Upload - Amazon S3 Storage or Alpha Anywhere Server action is newer and has more configuration options.

File Upload Properties 

  • Allow multiple file upload 

    If enabled, allows the user to upload multiple files at once.

  • Allowed file extensions 

    Specify a comma delimited cases 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 cases of file types.

  • Disallowed file extensions 

    Specify a comma delimited cases 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 

    The message shown when the user tries to upload a file with an extension that is not allowed.

  • 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.

    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.

    Type
    Description
    A5

    Use a specially styled progress bar that blends well with the selected component style.

    Basic

    Use a progress bar that works best with older Alpha Anywhere web themes (e.g. 'GrBlue', 'GrOlive', etc.)

  • Maximum combined size of all selected files 

    Specify the max combined file size of all selected files that can be uploaded.

    Regardless of this settings, the server also specifies a maximum POST body size. The lower of the maximum POST body size and the max combined file size of all selected files will apply.

  • Max combined file size exceeded message 

    Specify the error message to show if the selected file(s) to upload exceed the allowed maximum combined file size.

Customization - File Select Window Properties 

  • Window title 

    Specify the title of the File Select dialog window.

  • Window position 

    Specify where the File Select 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 language tag for the text, be sure that the language definition returns a URL encoded value. See Setting the 'Prompt' and 'Watermark' Text Properties Using Language Tags above for more information.

  • 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 is shown in the File Select window. If you use a language tag for the text, be sure that the language definition returns a URL encoded value. See Setting the 'Prompt' and 'Watermark' Text Properties Using Language Tags above for more information.

  • Remove file label 

    Specify the label for the button that allows a user to de-select a file so that it is not uploaded.

  • 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 image is uploaded, this button closes the dialog. If a confirmation dialog is show after the image is uploaded, this button aborts the action and does not save the uploaded image to the database.

Server-side Events Properties 

  • After upload 

    Specify the name of the Xbasic function to call after the file(s) have been uploaded. This Xbasic function can be defined in the 'Xbasic function declarations' section. The function is called after the file(s) selected in the Upload Files dialog have been uploaded to the server. The Xbasic function is responsible for processing each file that has been uploaded to the server.

    The following properties are available to you in the 'e' object:

    Property
    Description
    e.fileCount

    The number of files that were uploaded.

    e.fileArray

    A property array with one entry for each uploaded file. See Xbasic function arguments array mode below for more information.

    e.uploadProperties

    Contains multiple sub-properties for all of the properties set for the File Upload - User Defined action.

    e.tmpl

    A pointer to the component definition

    e.rtc

    A pointer variable that contains run-time calculations

    e.__si

    Component state information

    If you want to send any JavaScript back to the browser to execute after this event has completed, you can set the e.javascript property. For example:

    e.javascript = "alert('File upload complete.');"

    EXTREMELY IMPORTANT The JavaScript that is sent back to the browser is executed in the context of the IFrame that contains the File Select window. Therefore, in order for the Javascript you send back to invoke methods of the UX component, you must prefix all methods with window.parent.

    window.parent.{dialog.object}.setValue('CONTROL1','VALUE1');

    The file upload can also be aborted by setting the e.abort property to .t. and returning an error message to the user:

    e.abort = .t.
    e.errorText = "File upload aborted. You selected a file with no data."

  • Xbasic function arguments array mode 

    Specify if the array containing information about the uploaded files that is passed into the Xbasic 'After upload' function should contain the actual uploaded data, or a temporary filename for the file in which the uploaded data has been saved. The Xbasic function arguments array mode property can be set to either 'Filename' or 'Data'. For new actions, this property is set to 'Filename'.

    Mode
    Description
    Filename

    The default for all new actions. Files are uploaded and stored in temporary file. The 'After upload' function will be given the temporary filename for each uploaded file.

    Data

    Files are uploaded into server memory and passed to the 'After upload' function. If a large number of files are uploaded, this can lead to server errors if the server does not have enough memory to handle large files or multiple users uploading files concurrently.

    When the upload is complete, the 'After upload' Xbasic function is called. This function is passed an 'e' object that contains an array with information about each uploaded file.

    For example, assume the user has uploaded two files. If the 'Data' option is selected, the e object passed to the 'After upload' function will contain these properties:

    e.fileArray[1].file.characterSet - character set of the uploaded file
    e.fileArray[1].file.contentType - MIME type (e.g. 'application/octet-stream')
    e.fileArray[1].fileName - filename of the file on the client machine
    e.fileArray[1].encoding - For text files, specifies the encoding type
    e.fileArray[1].data - data that was uploaded.
    e.fileArray[1].file.dataType = Either 'text' or 'binary'
    
    e.fileArray[2].file.characterSet - character set of the uploaded file
    e.fileArray[2].file.contentType - MIME type (e.g. 'application/octet-stream')
    e.fileArray[2].fileName - filename of the file on the client machine
    e.fileArray[2].encoding - For text files, specifies the encoding type
    e.fileArray[2].data - data that was uploaded.
    e.fileArray[2].file.dataType = Either 'text' or 'binary'

    Note that the array has a .data property that contains the data that was uploaded.

    If Xbasic function arguments array mode is set to 'Filename', however, the array will not contain the .data and file.dataType properties. Instead, it will contain a property called 'tempFileUploadedData', which contains the location on the server where the file was saved. So, in the case where the user uploaded two files, the e object will contain:

    e.fileArray[1].file.characterSet
    e.fileArray[1].file.contentType
    e.fileArray[1].fileName
    e.fileArray[1].encoding
    e.fileArray[1].tempFileUploadedData - The temporary file location on the server
    
    e.fileArray[2].file.characterSet
    e.fileArray[2].file.contentType
    e.fileArray[2].fileName
    e.fileArray[2].encoding
    e.fileArray[2].tempFileUploadedData - The temporary file location on the server

    It is recommended to always use 'Filename' mode. If you are modifying any existing actions, this will require that you also change your Xbasic function that processes the uploaded data because the array passed to your function will no longer have the .data property.

    The benefit of the 'Filename' option over the 'Data' option is that uploaded data is never loaded into memory. If you use the 'Data' option, the uploaded data is read into memory. This consumes virtual memory on your server and may result in server errors if you have a large number of users uploading files (or just one user uploading a huge file).

    With the 'Filename' option, your application will be able to handle larger file uploads, or more users concurrently uploading files.

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 successfully uploaded.

See Also