| Scripting File Downloads |
While it is possible to use and customize AppletFile using only applet parameters, a scripting interface is also available for advanced processing using client-side JavaScript.
Initialization
Polling for confirmation
Polling for completion
It is recommended that you use applet parameters to customize AppletFile whenever possible. The scripting interface is intended only for developers that have advanced expertise in client-side JavaScript programming.
By default, the File Download Applet will immediately begin downloading as soon as it is loaded. If you want to use any of the scripting methods, you must stop the File Download Applet from automatically starting by adding the following parameter to your download page:
<PARAM NAME="noAutoStart" VALUE="true">
By setting the noAutoStart to true, the downloading will not start until you call the download method.
Before calling any of the scripting methods, you must first wait until the File Download Applet has been loaded and has finished initializing. This can be accomplished by calling a polling function from your document's onLoad event. For example:
<HTML><HEAD>
<SCRIPT language="JavaScript">
<!--
function waitForInit()
{
var applet = document.FileDownload;
if (applet.hasInitialized())
{
// Okay to execute other methods
:
:
}
else // Keep polling until applet initializes
window.setTimeout('waitForInit()',200);
}
//-->
</SCRIPT></HEAD>
<BODY onLoad="waitForInit();">
:
:
Once the hasInitialized method returns true, it is safe to call the other scripting methods. Attempts to call other scripting methods prior to this will be ignored by the applet.
In cases where you do not know the download directory in advance, or you are giving the user the option to change the download directory using the 'Save All To' button, you can use the confirm method to prompt the user to confirm the download prior to the download actually occuring. This can be useful for validating the download directory as well as performing checking on existing files. Calling the confirm method is optional.
Because of threading limitations in JavaScript, the confirm method as well as other methods that do not return immediately must run asynchronously. To ensure that confirmation has completed before you perform any validation, you need to poll using the getDownloadMode method as in the following example:
function waitForConfirmation()
{
var mode = document.FileDownload.getDownloadMode();
if (mode == 0)
{
// Confirmation isn't complete - keep polling
window.setTimeout('waitForConfirmation()',200);
return;
}
if (mode > 0)
{
// Perform additional validation
:
:
}
else
window.status = "Download canceled!";
}
Once the confirmation is complete, you can call a variety of methods include getFile, getFileCount, getFileDate, getFileMD5 and getFileSize to check for existing files prior to the download. The data returned by these methods can then be used to validate if the file should be downloaded or simply saved for tracking purposes.
Because the user has already confirmed the download, you should not attempt to call addFile or setDirectory at this point. If you do the confirmation will be reset and the user will be prompted to confirm the download again the next time you call either the confirm or download method. However, it is okay to remove files from the download list using either the removeFile or clearFiles method.
Like the confirm method, the download method also runs asychronously. If you wish to perform any processing after the download, you will need to poll for completion by calling getDownloadProgress until it returns 100. You can accomplish this by adding the following function to your page and calling it right after you call the download method.
function waitForCompletion()
{
var percent = document.FileDownload.getDownloadProgress();
if (percent > 0) window.status = percent + '% complete';
if (percent == 100)
{
alert("Download complete!");
window.status = '';
}
else if (percent == -2)
window.status = "Download canceled!";
else
window.setTimeout('waitForCompletion()',100);
}