XUpload User Manual - Chapter 3: Configuration Parameters

Home
What's New
User Manual
1. Introduction
2. Basic Uploads
3. Config Params
4. Advanced
5. International
6. File Downloads

Object Reference
Live Demos
Support
Download & Buy

Other Products
Contact Us

Chapter 3: Configuration Parameters

3.1 Configuring Select Files Dialog
3.2 Setting Limits of File Size, Type and Number
3.3 Populating File List with Default Values
3.4 Authentication, SSL & Ports
3.5 Preserving Last-Modified Date Info
3.6 Directory Scanning Parameters

3.1 Configuring Select Files Dialog

An important advantage of XUpload over traditional form-based uploading is the ability to specify the "Select Files" dialog's default directory and file filters. The corresponding properties are Directory and Filter. The usage of the Directory property is straightforward:
<PARAM NAME="Directory" VALUE="c:\My Documents\Spreadsheets">
Starting with XUpload 3.0, the Directory property can also be assigned various personal user folders such as Desktop or My Documents. These personal directories are designated by a pre-defined set of keywords, each beginning with an '@' symbol. For example, the Desktop folder is denoted by the keyword @DESKTOP, and My Documents by @PERSONAL, as follows:
<PARAM NAME="Directory" VALUE="@PERSONAL">
You may also specify subfolders for these personal folders, for example:
<PARAM NAME="Directory" VALUE="@PERSONAL\My Pictures">
The keywords are case-insensitive. Below is the full list of directory keywords currently suppored:
@APPDATA
@BITBUCKET
@COMMONDESKTOPDIRECTORY
@COMMONFAVORITES
@COMMONPROGRAMS
@COMMONSTARTMENU
@COMMONSTARTUP
@CONTROLS
@COOKIES
@DESKTOP
@DIRECTORYDESKTOP
@DRIVES
@FAVORITES
@FONTS
@HISTORY
@INTERNET
@INTERNETCACHE
@NETHOOD
@NETWORK
@PERSONAL
@PRINTERS
@PROGRAMS
@RECENT
@SENDTO
@STARTMENU
@STARTUP
@TEMPLATES

The Directory parameter also affects the Select Folder dialog box.
The Filter property expects a list of pairs separated by the pipe character ( | ). Each pair defines a verbal description for a filter and the filter itself which may contain one or more wildcards separated by a semicolon (;). The two values in the pair are also separated by the pipe character. For example:
<PARAM NAME="Filter" VALUE="Images (.gif;.jpg)|*.gif;*.jpg|Documents (.doc)|*.doc|All Files|*.*">
Here we specify three filters. The first filter has the verbal description "Images (.gif;.jpg)" and consists of two wildcards, *.gif and *.jpg. The second filter has the description "Documents (.doc)" and is defined by the wildcard *.doc. The third filter is "All Files" with the wildcard *.*.

3.2 Setting Limits of File Size, Type and Number

XUpload enables you to impose certain restrictions on the files being uploaded, so that the files not meeting the restrictions are rejected before an upload begins. The restrictions are set via the properties MaxFileCount, MaxFileSize, MaxTotalSize and Extensions.
The MaxFileCount property, if set to a non-zero value, limits the total number of files selected for uploading. The MaxFileSize property, if set to a non-zero value, places a limit on the size of individual files (in bytes). The MaxTotalSize property, if set to a non-zero value, sets a limit on the total size of files selected for uploading (in bytes). These three properties are 0 by default.
The Extensions property can be used to specify a comma-separated list of acceptable file extensions. For example,
<PARAM NAME="MaxFileSize" VALUE="50000">
<PARAM NAME="MaxTotalSize" VALUE="200000">
<PARAM NAME="MaxFileCount" VALUE="10">
<PARAM NAME="Extensions" VALUE="gif,doc,jpg">

The Extensions restriction is enforced at the time of adding a file to the list. The other three restrictions are enforced at the time when XUpload is instructed to start an upload (via the user interface or Upload method.) An attempt to upload a set of files not meeting the MaxXXX restrictions results in an error message being displayed by the control.

3.3 Populating File List with Default Values

XUpload can be configured to populate its file list automatically upon loading. This is done via tags of the form <PARAM NAME="FileN"> where N is a number greater than 0. When XUpload comes up it attempts to retrieve the PARAMs File1, File2, File3, etc. until a break in the sequence is encountered, and uses the corresponding values to populate its file list. For example:
<PARAM NAME="File1" VALUE="c:\My Documents\Bool1.xls">
<PARAM NAME="File2" VALUE="c:\My Documents\Book2.xls">
<PARAM NAME="File3" VALUE="c:\My Documents\Summary.xls">

A FileN value can start with a @-prepended keyword designating a personal user folder such as @DESKTOP or @PERSONAL, for example:
<PARAM NAME="File1" VALUE="@PERSONAL\My Pictures\dog.jpg">

See Section 3.1 for the full list of supported keywords.

3.4 Authentication, SSL & Ports

3.4.1 Authentication
When XUpload attempts to upload to a server protected by Basic Authentication, it displays a dialog box asking the user for his/her username and password which are then sent to the server. You can use the Username and Password properties to specify default credentials that will be used by XUpload. If these credentials are valid, XUpload will go ahead with the upload and no login dialog will be displayed. If the credentials are rejected by the server, XUpload will display the login dialog with the User Name and Password boxes populated with the values specified by the Username and Password properties. You may choose to disable the login dialog by setting the ShowLoginDialog property to False. In that case XUpload will proceed with the uploading even if the credentials specified by the Username/Password properties are invalid, so the upload may fail.
If your XUpload-hosting HTML page and upload script reside in a virtual directory protected by Basic Authentication, an attempt to view this page will prompt the browser to show a login dialog box even before XUpload is loaded. The username/password entered by the user can be passed on to XUpload via the Authorization parameter, so that when the user starts an upload, she would not be prompted for a username/password again, as follows:
<PARAM NAME="Authorization"
VALUE="<%=Request.ServerVariables("HTTP_AUTHORIZATION")%>">
3.4.2 SSL
If the server requires a Secure Socket Layer connection (SSL) you must set the SSL property to True, as follows:

<PARAM NAME="SSL" VALUE="True">
<PARAM NAME="Server" VALUE="www.server.com">
DO NOT prepend the Server value with https://.

<PARAM NAME="Server" VALUE="https://www.server.com">
3.4.3 Ports

By default, XUpload uses the standard HTTP port 80 to perform uploads. If an upload needs to be performed via a different port, specify it via the Port parameter. DO NOT append the port number to the Server value:

<PARAM NAME="Port" VALUE="8080">
<PARAM NAME="Server" VALUE="www.server.com">

<PARAM NAME="Server" VALUE="www.server.com:8080">

3.5 Preserving Last-Modified Date Info

When browsers upload files to the server via a form, they do not send the "Last Modified" dates together with the files, but XUpload does. The control adds a custom header, X-Last-Date, to the standard Content-Disposition and Content-Type MIME headers used in form-based uploading. When capturing the uploaded files, AspUpload uses this information to preserve the original dates of the files.
Being a custom header, X-Last-Date makes POSTs performed by XUpload somewhat irregular. If you use a server-side upload component other than AspUpload, you may experience problems uploading files. To disable the X-Last-Date header, set the property IncludeDateInfo to False.
The ASP.NET PostedFile object does not recognize the X-Last-Date header, but does not seem to be negatively affected by it either.

3.6 Directory Scanning Parameters

The user can have XUpload select all files from an arbitrary folder, and even recursively scan the subfolders via the Select Folder item of the pop-up menu, or by invoking the Select Folder method. The Browse for Folder dialog will pop up enabling the user to select a directory:

The initial directory displayed by the dialog can be specified via the Directory parameter described in Section 3.1 of this chapter. Starting with XUpload 3.0, the "Include sub-folders" checkbox can be configured to come up checked by default by setting the IncludeSubfoldersChecked parameter to True:
<PARAM NAME="IncludeSubfoldersChecked" VALUE="True">
The recursive folder scan feature enables the user to potentially select thousands of files into the control, and the scan process would take too long to complete. Besides, uploading too many files at once is generally not recommended because it may cause the server-side script to timeout. For these reasons XUpload is programmed to display a warning message to the user during the directory scanning process:

Starting with XUpload 3.0, the default threshold value of 1000 can be changed via the AskAfter parameter:
<PARAM NAME="AskAfter" VALUE="2000">