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 can process the uploaded data.

Used with the Grid and UX components

TIP: 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.

 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.

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

 File Upload Properties

Allow multiple file upload

Can the user upload multiple files at once?

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.

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.

Maximum combined size of all selected files

Specify the max combined filesize of all selectd files. 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.

Max combined file size exceeded message

Specify the error message to show if user selects file with a combined size that exceeds the maximum allowed.

 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.

Prompt

Specify the prompt that is shown on the File Select dialog box.

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.

 Import properties Properties

Target

Specify if the data in the uploaded file should be imported into the table for the current Grid, or some external table. Choices include <CurrentGrid>, <External>.

External type

Specify if the external table is a SQL table or a .DBF table Choices include SQL, DBF.

External connection string

Specify the connection string for the external database where the external table is stored.

External table name

Specify the name of the external table into which you want to import records.

External table name

Specify the name of the external table into which you want to import records.

Honor Grid rules and events

Specify if each record from the uploaded file should be validated using the Grid's validation rules, and if the Grid's CanInsertRecord event should fire before each row of data in the uploaded file is imported. NOTE:Importing records will be SUBSTANTIALLY slower if this property is checked.

Maximum records to process

Specify the maximum number of records in the uploaded file to process. Importing records can tie up your server so you might want to limit the number of records that can be processed. Set to 0 for no limit.

Maximum records exceeded error message

Specify the message to show if the user tries to import to many records at once. You can use language tags in the message. e.g. <a5:r>message</a5:r>

Success message

Specify the message to show if the import operation is successful. You can use language tags in the message. e.g. <a5:r>message</a5:r>

Partial success message

Specify the message to show if some records were rejected because they did not satisfy Grid validation rules.

Import results window title

Specify the caption for the title of the confirmation window after records are imported.

Import results window close button

Specify the caption for the button to close the confirmation window after records are imported.

Pre-process uploaded file Xbasic function

This function is called AFTER the file is uploaded, but BEFORE the raw file has been imported. It is ONLY called if the uploaded file contains ascii data. For example, say you know that the user will upload a file that does not have titles in the first row. This function will allow you to manipulate the uploaded file and add titles to the first row. Click the hyperlink below to get a sample prototype for your function.

Data validation Xbasic function

After the data has been uploaded (and imported into a temporary table on the server), you can specify the name of an Xbasic function to call to validate the data. The data from the uploaded file will be imported into a temporary .dbf table and your Xbasic function can process this table before it is imported into the target table. Click the hyperlink below to get a sample prototype for your validation function.

 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.

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.

 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.

See Also