| Download Applet |
The Download Applet automates the task of downloading multiple files while providing better control and feedback during the process.
<APPLET CODE=FileDownload.class ARCHIVE=FileDownload.jar NAME=FileDownload
CODEBASE="/AppletFile/classes" WIDTH=2 HEIGHT=2 MAYSCRIPT>
<PARAM NAME="cabbase" VALUE="/AppletFile/classes/FileDownloadIE3.cab">
<PARAM NAME="cabinets" VALUE="/AppletFile/classes/FileDownload.cab">
<PARAM NAME="url1" VALUE="Source URL">
<PARAM NAME="directory" VALUE="Destination directory">
<PARAM NAME="file1" VALUE="Destination file path">
:
Optional Parameters
:
</APPLET>
alternateUrl, autoSync, autoZipPost, autoZipUrl, bgColor, browseTitle, cabbase, cabinets, directory, fileN, finishUrl, language, noAutoStart, noConfirm, noError, noProgress, noSaveAll, noSaveAllTo, noSaveAs, urlN, useCache
addFile, clearFiles, confirm, download, getAutoSync, getAutoZipUrl, getBrowseTitle, getDirectory, getDownloadMode, getDownloadProgress, getDownloadStatus, getFile, getFileCount, getFileDate, getFileMD5, getFileSize, getFileUrl, getUseCache, hasInitialized, removeFile, setAutoSync, setAutoZip, setBrowseTitle, setDirectory, setUseCache
The Download Applet must be initialized by specifying at least one fileN and one urlN parameter (file1 and url1) as <param name="paramname" value="paramvalue"> tags inside the <applet> tag. Additional customizations are possible by adding one or more of the parameters described below.
<param name="alternateUrl" value="URL">
URL to an alternate HTML page to display if Applet lacks permissions needed for file download processing.
Default: none
Notes: This parameter can be used to provide an alternate HTML page that will automatically be displayed in the case where the user does not agree to grant permissions to the Applet or the browser that is being used does not support digitally signed Applets. This alternate HTML page could be simply informational or contain an alternative mechanism for downloading files.
Example: Display alt.html if permissions are not granted<PARAM NAME="alternateUrl" VALUE="alt.html">
<param name="autoSync" value="method">
Synchronize existing files using one of the following methods:
Method Value Description "ALWAYS" Always replace existing files without prompting user. "NEVER" Never replace existing files. "NEWER" Only replace existing files with newer files. "PROMPT" Prompt user before replacing existing files. Default: PROMPT
Notes: This parameter is useful for controlling how files are downloaded when the file already exists on the client. This parameter only applies when the download mode is SAVEALL or SAVEALLTO.
Example: Always replace existing files.<PARAM NAME="autoSync" VALUE="always">
<param name="autoZipPost" value="{true|false}">
Flag indicating if file information should be posted to the URL specified for downloading ZIP data.
Default: Nothing
Notes: This parameter is useful for passing file information to a server-side script that is generating ZIP data on-the-fly. To use this parameter, you must also set autoZipUrl to reference your server-side script. When enabled, a FILEn variable for each downloaded file (FILE1, FILE2, ... ) will sent in the POST stream allowing the script to generate the ZIP data for just the files being downloaded.
Example: Enable posting of file information.<PARAM NAME="autoZipPost" VALUE="true">
<param name="autoZipUrl" value="URL">
Url to a zip archive to use to download and automatically extract all files.
Default: Nothing
Notes: This parameter is useful for improving download performance by allowing compressed data to be transferred. It can reference either a static ZIP archive or a server-side script that uses a product like ActiveFile to generate the ZIP data on-the-fly.
Example: Download from a ZIP archive.<PARAM NAME="autoZipUrl" VALUE="archive.zip">
<param name="bgColor" value="#RRGGBB">
Background color of the applet displayed within the HTML page.
Default: undefined
Notes: Even though the download applet does not make use of the space it occupies on the HTML page, it is not possible to set the width and height to zero. This means that a few pixels on your HTML page that represent the applet may not match the background color unless you set the parameter. Setting the value of this parameter to match the BGCOLOR attribute of the <BODY> tag in your HTML page will allow the applet to blend with the rest of your page. The value must be the pound sign (#) followed by six hexadecimal digits representing red, green, and blue color values. Color names are not supported. If this parameter is not specified, the default is browser and operating system dependent.
Example: Set background color to white<PARAM NAME="bgColor" VALUE="#ffffff">
<param name="browseTitle" value="text">
Title displayed in the Browse dialog.
Default: "Select a download directory"
Notes: This parameter is useful for giving users a better idea of what type of file you want them to select.
Example: Ask user to pick a working directory<PARAM NAME="browseTitle" VALUE="Select your working directory">
<param name="cabbase" value="URL">
Location of cabinet file containing the Applet.
Default: none
Notes: This required parameter is an URL used to locate the cabinet file containing the IE 3.02 version of the Applet. The value of this URL will depend on where AppletFile is installed but should ultimately point to the cabinet file FileDownloadIE3.cab.
Example: Set the location of cabinet file to be under the applets folder<PARAM NAME="cabbase" VALUE="/applets/FileDownloadIE3.cab">
<param name="cabinets" value="URL">
Location of cabinet file containing the Applet.
Default: none
Notes: This required parameter is an URL used to locate the cabinet file containing the IE 4.0 and higher version of the Applet. The value of this URL will depend on where AppletFile is installed but should ultimately point to the cabinet file FileDownload.cab.
Example: Set the location of cabinet file to be under the applets folder<PARAM NAME="cabinets" VALUE="/applets/FileDownload.cab">
<param name="directory" value="path">
Save files relative to this directory path.
Default: none
Notes: Each fileN parameter represents a path name that is relative to this common parent directory. This allows 'Save All To' operations to save the files in a different location without flattening the underlying subdirectories.
Example: Save files in C:\My Documents<PARAM NAME="directory" VALUE="C:\My Documents">
<param name="fileN" value="path">
Destination path for a downloaded file.
Default: none
Notes:
One or more fileN parameters starting with file1 and numbered sequentially can be used to specify the location to place files being downloaded.
Each fileN parameter value should represent a path name relative to the directory parameter. By using relative paths, you can include subdirectory information that will automatically be recreated during downloading. This allows a tree of files to be downloaded without the directory tree already existing on the client.
For each fileN parameter, there must be a corresponding urlN parameter.
Example: Download a spreadsheet file to the user's D: drive
<PARAM NAME="file1" VALUE="work\foo.xls"> <PARAM NAME="directory" VALUE="D:\My Files">In the above example, the file foo.xls will be downloaded to D:\My Files\work. If the subdirectory work does not exist, it will automatically be created.
A complete example would also require the parameter url1.
<param name="finishUrl" value="URL">
URL of the document to display upon completion of downloading.
Default: none
Notes: When all of the files to be downloaded have been processed, the URL specified by this parameter will be requested and displayed. The query string parameter STATUS will be included on the URL to notify the server of the result of the download operation. The possible values for STATUS are described in the table below.
Status Value Description "SAVEALL" All files were successfully saved in their default locations. "SAVEALLTO" All files were successfully saved in a single location1 chosen by the user. "SAVEAS" One or more files were saved in different locations. "CANCELED" Download of one or more files was canceled by the user. "ERROR" Applet encountered an invalid parameter. "IOERROR" An I/O error occured while downloading a file. "NOTAUTHORIZED" Applet was not granted permissions by the user or the browser does not support digitally signed Applets.2
Footnotes
1 The location selected by the user is also included with the URL as the value of the query string parameter DIR.
2 This status would only be passed to finishUrl if the parameter alternateUrl is not specified.Example: Refer user to the page finish.html after downloads are complete
<PARAM NAME="finishUrl" VALUE="finish.html">
<param name="language" value="language code">
Language to use for text of messages.
Default: en (English)
Notes: This parameter represents the ISO language code specifying the language to use for the text of various dialog boxes and messages. Currently only en (English), de (German) and fr (French) are supported. If an unsupported language code is specified, English will be used.
Example: Enable German language messages<PARAM NAME="language" VALUE="de">
<param name="noAutoStart" value="{true|false}">
Do not automatically start downloading.
Default: false
Notes: By default, the Download Applet will automatically start the download process when it loads. You need to set this parameter to true if you want to make use of scripting to customize the download process.
Example: Turn off auto starting<PARAM NAME="noAutoStart" VALUE="true">
<param name="noConfirm" value="{true|false}">
Suppress the file download confirmation dialog.
Default: false
Notes: Setting this parameter to true is useful if you do not want the user to be prompted with the list of files to be downloaded. The user will still be prompted but will include a "Don't ask me next time" checkbox to suppress the dialog during future downloads.
Example: Supress confirmation dialog<PARAM NAME="noConfirm VALUE="true">
<param name="noError" value="{true|false}">
Do not display error dialogs during the download.
Default: false
Notes: This parameter is useful for customizing the Applet's user interface. If you want to create your own error dialog in JavaScript, set this parameter to true and call the getDownloadProgress and getDownloadMode methods to poll for errors.
Example: Hide error dialogs<PARAM NAME="noError" VALUE="true">
<param name="noProgress" value="{true|false}">
Do not display the Progress dialog during the download.
Default: false
Notes: This parameter is useful for customizing the Applet's user interface. If you want to create your own progress dialog in JavaScript, set this parameter to true and call the getDownloadProgress and getDownloadStatus methods to update your display.
Example: Hide the Progress dialog<PARAM NAME="noProgress" VALUE="true">
<param name="noSaveAll" value="{true|false}">
Do not allow 'Save All' operations from the File Download dialog.
Default: false
Notes: This parameter is useful for restricting download operations. By setting this parameter to true, you can force users to select the download location for the files using 'Save All To' or 'Save As' operations.
Example: Hide the 'Save All' button<PARAM NAME="noSaveAll" VALUE="true">
<param name="noSaveAllTo" value="{true|false}">
Do not allow 'Save All To' operations from the File Download dialog..
Default: false
Notes: This parameter is useful for restricting download operations. By setting this parameter and noSaveAs to true, you can prevent users from selecting a different download location for the files.
Example: Hide the 'Save All To' button<PARAM NAME="noSaveAllTo" VALUE="true">
<param name="noSaveAs" value="{true|false}">
Do not allow 'Save As' operations from the File Download dialog.
Default: false
Notes: This parameter is useful for restricting download operations. By setting this parameter and noSaveAllTo to true, you can prevent users from selecting a different download location for the files.
Example: Hide the 'Save As' button<PARAM NAME="noSaveAs" VALUE="true">
<param name="urlN" value="URL">
Source URL for a file to be downloaded.
Default: none
Notes: One or more urlN parameters starting with url1 and numbered sequentially can be used to specify the source location of the files being downloaded. Each parameter value must represent an URL. For each urlN parameter, there must be a corresponding fileN parameter.
Example: Download a text file from the server<PARAM NAME="url1" VALUE="data.txt">A complete example would also require the parameter file1.
<param name="useCache" value="{true|false}">
Use files located in the browser's cache.
Default: false
Notes: By default, the browser's cache is not used so that the file is always downloaded from the server each time it is requested. By setting this parameter to true, you can take advantage of the browser's cache, including download restart capabilities for HTTP 1.1 configurations.
Example: Enable use of browser's cache<PARAM NAME="useCache" VALUE="true">
The Download Applet is fully scriptable using the methods found below. You can use these methods to implement your own JavaScript-based user interface and validation logic.
addFile(file, url)
Adds a file to the download list.
Parameter Description file The name and relative path to use for saving the file. url The download URL to use to retrieve the file from the server. Returns: Boolean indicating if the file was added successfully.
Notes: Similar to the fileN and urlN parameters, this method can also be used to preselect files. If the URL is invalid, it will not be added to the download list and the function will return false.
Example: The following JavaScript code will add files based on a numbering scheme:for (i = 0; i < 1000; i++) document.FileDownload.addFile("stage\file" + i + ".dat","download.asp?i=" + i);
clearFiles()
Clears all of the files from the download list.
Returns: Nothing.
Notes: This method is useful for emptying out the download list prior to adding files using the addFile method.
Example: The following JavaScript code will remove all the files from the download list:document.FileDownload.clearFiles();
confirm()
Confirms the download operation with the user.
Returns: Nothing.
Notes:
This method is useful if you want to analyze the download location and any pre-existing files prior to the download actually occuring.
Because this method returns before user confirmation completes, you must use the getDownloadMode method to poll for completion.
If you do not call this method, user confirmation will occur automatically at the start of the download process.
Example: The following JavaScript code will start confirmation:
document.FileDownload.confirm();
download()
Starts downloading files in the download list.
Returns: Nothing.
Notes:
By setting noAutoStart to true, you can use this method to start the download process instead of it starting automatically.
Because this method returns before all of the downloads complete, you must use the getDownloadProgress method to poll for completion.
Example: The following JavaScript code will start the download:
document.FileDownload.download();
getAutoSync()
Returns the method used to synchronize existing download files.
Returns: String.
Notes: This method will return the current AutoSync setting as specified by the last call to setAutoSync or the setting of the autoSync parameter. You can use this method to see which AutoSync method is being used.
Example: The following JavaScript code will display the AutoSync method being used:alert(document.FileDownload.getAutoSync());
getAutoZipUrl()
Returns the URL used to download the files in ZIP format.
Returns: URL.
Notes: This method will return the current setting of the AutoZipUrl as specified by the last call to setAutoZip or the setting of the autoZipUrl parameter. You can use this method to see if AutoZip is turned on or to retrieve the URL being used.
Example: The following JavaScript code will check to see if AutoZip is turned on:if (document.FileDownload.getAutoZipUrl() == null) alert('AutoZip is on'); else alert('AutoZip is off');
getBrowseTitle()
Returns the current title of the Browse dialog.
Returns: String containing the dialog title.
Notes: This method will return the current title of the Browse dialog used to select the download location. This title can be set by either the browseTitle parameter or the setBrowseTitle method.
Example: The following JavaScript code will display the dialog title:alert('The current title is: ' + document.FileDownload.getBrowseTitle());
getDirectory()
Returns the current download location.
Returns: String containing the directory path.
Notes: This method will return a directory representing the download location. This directory can be set by the directory parameter, the setDirectory method, or by the user navigating to a directory and selecting a file using the Browse dialog.
Example: The following JavaScript code will display the current directory:alert('The current directory is: ' + document.FileDownload.getDirectory());
getDownloadMode()
Returns the mode of a download request.
Returns: Integer having one of the following values:
Value Description 3 All files will be downloaded to the application-specified download location. 2 All files will be downloaded to a user-specified download location. 1 Each file will be saved to a user-specified location. 0 Unknown mode because user confirmation has not completed. -1 Error occurred during user confirmation. -2 User canceled operation. -3 Applet was not granted permissions by the user or the browser does not support digitally signed Applets. Only returned if alternateUrl is not set. Notes: This method can be used in conjunction with the confirm method to allow you to locate the download location before the download actually starts. After calling confirm, use window.setTimeout to poll until getDownloadMode returns a non-zero value. Once confirmation is complete, you can use getFileDate, getFileMD5, and getFileSize to retrieve file information about existing files that will be replaced.
Example: The following JavaScript function checks to see if the download has been confirmed:function checkConfirmation() { var mode = document.FileDownload.getDownloadMode(); if (mode == 0) window.setTimeout('checkConfirmation()', 200); else alert('Download confirmed ' + (status < 0 ? 'unsuccessfully' : 'successfully') ); }
getDownloadProgress()
Returns the progress of a download request.
Returns: Integer having one of the following values:
Value Description 100 Download completed successfully, 100% complete. 0-99 Download inprogress where value is the percent complete. -1 Download not inprogress. -2 Download failed or canceled. Notes: The download method starts the download asynchronously. This means the call to download will return before the downloading is complete. Using the getDownloadProgress method and window.setTimeout you can poll for completion of the download and determine if it was successful or not. To distinguish cancels from other types of failures call getDownloadMode.
Example: The following JavaScript function checks to see if the download completed:function checkDownload() { var status = document.FileDownload.getDownloadProgress(); if (status >= 0 && status < 100) window.setTimeout('checkDownload()', 200); else alert('Download completed ' + (status < 0 ? 'unsuccessfully' : 'successfully') ); }
getDownloadStatus()
Returns the status text of the download.
Returns: String containing the status text of the download.
Notes: Used in conjunction with the getDownloadProgress method, this method is useful for retrieving status information about the download that is inprogress.
Example: The following JavaScript code displays the current status of the download.alert('Download status = ' + document.FileDownload.getDownloadStatus());
getFile(index)
Returns a file from the download list.
Parameter Description index Number specifying the position (starting at 1) of the file Returns: String containing the file path.
Notes: This method will return the path of a file from the download list. Using this method along with getFileCount you can enumerate the files to create your own custom display and download logic.
Example: The following JavaScript code will enumerate the files in the download list:count = document.FileDownload.getFileCount(); for (i=1; i <= count; i++) alert(document.FileDownload.getFile(i));
getFileCount()
Returns the number of files in the download list.
Returns: Number representing the number of files in the download list.
Notes: This method will return the number of files in the download list. Using this method along with getFile, getFileDate, getFileMD5, and getFileSize you can enumerate the files to be downloaded and perform your own customized download processing.
Example: The following JavaScript code will display the number of files in the download list:alert('There are ' + document.FileDownload.getFileCount() + ' files in the download list.');
getFileDate(index)
Returns the last modified date of a file in the download list.
Parameter Description index Number specifying the position (starting at 1) of the file Returns: Date when the file was last modified.
Notes: This method can be used to determine the last modified date of an existing file that is going to be replaced. To do this, you must first confirm the download location using confirm and polling getDownloadMode. If you attempt to call this function before the download location is confirmed, or the file does not exist, it will return null. Note that checking the last modified date of a file after it has been downloaded is not that useful since the file has just been created.
Example: The following JavaScript function will check to see if the first file is out of date and remove it from the download list if it is not:var currentDate = ...; document.FileDownload.confirm(); checkDate(); function checkDate() { var mode = document.FileDownload.getDownloadMode(); if (mode == 1 || mode == 2) { if (document.FileDownload.getFileDate(1) < currentDate) document.FileDownload.removeFile(1); document.FileDownload.download(); } else if (mode == 0) window.setTimeout('checkDate()',200); }
getFileMD5(index)
Returns the MD5 checksum of a file in the download list.
Parameter Description index Number specifying the position (starting at 1) of the file Returns: String containing the MD5 checksum in hexadecimal format.
Notes:
This method can be used to calculate the MD5 checksum of a file after it has been downloaded by calling download and polling getDownloadProgress until it reaches 100. By comparing this against a checksum calculated on the server, you can check for possible data corruption during transfer.
This method can also be used to calculate the MD5 checksum of an existing file that is going to be replaced. To do this, you must first confirm the download location using confirm and polling getDownloadMode. By comparing this against a checksum calculated on the server for the new file, you can build in logic to only download files that are different.
This method can take a long time to execute, particularly on large files.
If you attempt to call this function before the download location is confirmed, or the file does not exist, it will return -1.
Example: The following JavaScript code will display the checksum of the first file:
alert('The MD5 checksum is: ' + document.FileDownload.getFileMD5(1));
getFileSize(index)
Returns the size in bytes of a file in the download list.
Parameter Description index Number specifying the position (starting at 1) of the file Returns: Number containing the file's size in bytes.
Notes:
This method can be used to determine the size of a file after it has been downloaded by calling download and polling getDownloadProgress until it reaches 100.
This method can also be used to determine the size of an existing file that is going to be replaced. To do this, you must first confirm the download location using confirm and polling getDownloadMode.
If you attempt to call this function before the download location is confirmed, or the file does not exist, it will return -1.
Example 1: The following JavaScript code will display the size of the first file in the download list after it has been downloaded:
document.FileDownload.download(); function showNewFileSize() { var progress = document.FileDownload.getDownloadProgress(); if (progress == 100) alert('Size of the first file is ' + document.FileDownload.getFileSize(i)); else if (progress >= 0) window.setTimeout('showNewFileSize()',200);}Example 2: The following JavaScript function will display the size of the first file in the download list before it has been replaced by the downloaded file:
document.FileDownload.confirm(); function showOldFileSize() { var mode = document.FileDownload.getDownloadMode(); if (mode == 1 || mode == 2) alert('File exists and has a size of ' + document.FileDownload.getFileSize(1)); else if (mode == 0) window.setTimeout('showOldFileSize()',200); }
getFileUrl(index)
Returns the download URL of a file from the download list.
Parameter Description index Number specifying the position (starting at 1) of the file Returns: String containing the download URL of the file.
Notes: This method will return the download URL of a file from the download list. Using this method along with getFileCount you can enumerate the URLs to create your own custom display and download logic.
Example: The following JavaScript code will enumerate the download URLs in the download list:count = document.FileDownload.getFileCount(); for (i=1; i <= count; i++) alert(document.FileDownload.getFileUrl(i));
getUseCache()
Returns a flag indicating if the browser's cache will be used when downloading files.
Returns: Boolean flag.
Notes: This method will return the current setting of the UseCache flag as specified by the last call to setUseCache or the setting of the useCache parameter.
Example: The following JavaScript code will check to see if UseCache is turned on:if (document.FileDownload.getUseCache()) alert('UseCache is on'); else alert('UseCache is off');
hasInitialized()
Returns a flag indicating if the applet has finished initializing.
Returns: Boolean flag.
Notes: This method can be used to make sure the applet has finished initializing before attempting to make other scripting calls. The best way to use this function is with window.setTimeout allowing you to poll until the applet has finished initializing.
Example: The following JavaScript function waits until initialization is complete:function waitForInit() { if (document.FileDownload.hasInitialized()) { alert('Applet has loaded!'); : // Perform custom initialization : } else window.setTimeout('waitForInit()', 200); }
removeFile(index)
Removes a file from the download list.
Parameter Description index Number specifying the position (starting at 1) of the file Returns: Nothing.
Notes: This method will remove the file at the given position from the download list. It does NOT delete a file from the user's system. This method is useful for implementing your own custom download logic. To remove all the files in a single call, use the clearFiles method.
Example: The following JavaScript code will remove the first file from the download list:document.FileDownload.removeFile(1);
setAutoSync(method)
Parameter Description method AutoSync method used to synchronize existing files. Sets the AutoSync method to use to synchronize existing files during the download.
Returns: Nothing.
Notes: This method can be used to set the AutoSync method that controls how files that already exist on the client will be handled. This method is equivalent to setting the autoSync parameter and is useful for dynamically controlling this option through user input or your own scripting logic.
Example: The following JavaScript code will set AutoSync so that existing files are never replaced:document.FileDownload.setAutoSync("never");
setAutoZip(url,post)
Parameter Description url URL referencing either a static ZIP archive or a server-side download script post Boolean flag to enable or disable the posting of file information to the download script Sets the URL and post flag indicating if files will be zipped during download.
Returns: Nothing.
Notes: This method can be used to set or clear the AutoZip operation that controls whether files will be downloaded as a single ZIP archive and automatically unzipped. This method is useful for dynamically controlling this option through user input or your own scripting logic.
Example 1: The following JavaScript code will turn AutoZip on:document.FileDownload.setAutoZip("download.asp", true);Example 2: The following JavaScript code will turn AutoZip off:
document.FileDownload.setAutoZip(null, false);
setBrowseTitle(title)
Parameter Description title String containing the text to display as the title Sets the title of the Browse dialog.
Returns: Nothing
Notes: This method will set the title of the Browse dialog used to select the download location. This is useful for giving users a better idea of which directory they should select.
Example: The following JavaScript code will change the browse dialog title:document.FileDownload.setBrowseTitle("Please select your Alpha project directory");
setDirectory(path)
Parameter Description path String containing the new directory path Sets the download directory location.
Returns: String containing the directory path.
Notes: This method will set the download directory location. This method is equivalent to setting the directory parameter, but can be used to dynamically change the directory based on your own scripting logic.
Example: The following JavaScript code will set the current directory:document.FileDownload.setDirectory("C:\My Documents");
setUseCache(flag)
Parameter Description flag Boolean flag to enable or disable use of the browser's cache when downloading files Sets a flag indicating if files residing in the browser's cache should be used.
Returns: Nothing.
Notes: This method can be used to set or clear the UseCache flag that controls whether the browser's cache should be used.
Example: The following JavaScript code will turn UseCache on:document.FileDownload.setUseCache(true);