New in IntraWeb XIV: IWFileUploader

New in IntraWeb XIV: IWFileUploader

There is a new control in IntraWeb XIV: IWFileUploader

When you install IntraWeb XIV in XE3 you may notice that there is a new control there: IWFileUploader.

This control replaces old IWFile control. Yes, IWFileUploader replaces IWFile. Old IWFile is not supported anymore and you must replace all IWFile controls in your IntraWeb projects by the new IWFileUploader. IWFile is still being kept in the pallete (the same for IWCompFile unit) so you can still open your forms and build your IntraWeb applications, but IWFile won’t work as expected (it won’t upload any file).

IWFileUploader is a completely new control, based on Valums Ajax File uploader, originally written by Andrew Valums. We based our control on a fork/version licensed under MIT license, so it is ok for us to use it in IntraWeb. Many other forks/versions have different licenses no so permissive as MIT.

IWFileUploader uploads files using XMLHTTPRequests (AJAX). The practical effect – a cool one – is that there is no page refresh during file uploads. There is an issue though… the old and “good” Internet Explorer does not support it. But the file uploader falls back to a hidden iframe and still provides an AJAX-like file upload experience. When applicable (i.e. when using something other than IE) drag-and-drop of files is also supported.

TIWFileUploader main properties:

  • AllowedExtensions (string)

A comma separated list of file extensions, without mask chars, like *. If set, IWFileUploader will not allow the user to upload files with different file extensions. When you set AllowedExtensions value, spaces, quotes and dots are removed. Semicolons, if entered, are replaced by commas.

e.g.: pdf, doc, zip

Default value: empty string, meaning that any file can be uploaded.

  • AutoHideListTime (Cardinal)

Time in milliseconds after which the list of uploaded files will be hidden. If you let it with “0” (zero) the list will not be hidden.

Default value: “0” (zero), meaning that the auto hide feature is disabled.

  • AutoSave (boolean)

When set to TRUE, the uploaded file will be automatically saved when the upload is completed. If FALSE, you will have to tell IntraWeb if you want to save the file or not (using events).
AutoSave will use AutoSavePath property, or the current user cache folder, in case AutoSavePath is blank.

Default value: False

  • AutoSavePath (string)

When AutoSave = True, AutoSavePath – if set – is used as the path to save uploaded files. The folder will be created if it does not exist.

Default value: empty string

  • MaxFileSize (Int64)

Maximum size in bytes that an uploaded file may have. When the file size is above that limit, a message will be shown to the user. When this value is “0” (zero) there is no maximum size limit.

Default value: 20971520 (20 MB)

  • MinFileSize (Int64)

Minimum size in bytes that an uploaded file may have. When the file size is below that limit, a message will be shown to the user. When this value is “0” (zero) there is no minimum size limit.

Default value: “0” (zero – no limit)

  • OverwriteExisting (boolean)

This property controls if the uploaded file will overwrite an existing file with the same name in the destination folder. When True, the file will be overwritten, and when false, if a file with the same name still exists, an exception will be raised (this exception is shown in the browser).

Default value: True

  • TextStrings (TIWFileUploaderTextStrings)

Using this property you can customizeall text messages shown to users. Strings between curly brackets shouldnot be localized (e.g. {extensions}, {file}, etc.)

  • Style (TIWFileUploaderStyle)

This property controls every aspect of IWFileUploader rendering style (CSS).

  • ButtonHoverOptions: Aligment, color and font used when the mouse is over the IWFileUploader button
  • ButtonOptions: Aligment, color, border radius, size and font of IWFileUploader button
  • DropAreaActiveOptions: Aligment, color, border radius, size and font of IWFileUploader drop area, when it is active, i.e. when the files being dragged are over the drop area.

  • DropAreaOptions:Aligment, color, border radius, size and font of IWFileUploader droparea when dragging of files is occurring.

  • ListErrorOptions:Aligment, color, and font of IWFileUploader list when there is an upload error.

  • ListOptions:Aligment, color, border radius, size and font of IWFileUploader list when files are being uploaded.
  • ListSuccessOptions:Aligment, color, and font of IWFileUploader list when there is some file is uploaded with success.

TIWFileUploader events:

  • OnAsyncUploadCompleted:

property OnAsyncUploadCompleted: TUploadCompleteEvent read FOnAsyncUploadCompleted write FOnAsyncUploadCompleted;

TUploadCompleteEvent = procedure (Sender: TObject; var DestPath, FileName: string; var SaveFile: boolean; var Overwrite: boolean) of object;

This event fires everytime that a file upload is completed, and before the file being saved. This gives you the chance to save the file with a different name, specify file path, etc.

Event parameters:

  • DestPath (string): The path that will be used to save the file. When the event fires, it contains user cache directory or AutoSavePath property, when this is set.
  • FileName (string): File name that will be used when saving the file. When the event fires, it contains the original file name of the uploaded file.
  • SaveFile (Boolean): If true, the file will be saved after the event fires. If false, the file won’t be saved. Default True.
  • Overwrite (Boolean): If true, a file with the same name in DestPath folder will be overwritten. If false, the file won’t be overwritten and an exception is raised – and sent back to the browser. The default Overwrite value equals the value of OverwriteExisting property.