AspUpload.com - User Manual. Chapter 5

Home
What's New
User Manual
1. Introduction
2. Simple Uploads
3. Memory Uploads
4. Database
5. Progress Bar
6. Security
7. Images
8. Unicode
9. Miscellaneous
10. Hosting Issues

Object Reference
Live Demos
Support
XUpload
JUpload
AspJpeg

Download
Purchase
Clients
Other Products
Contact Us
Newsletter Signup

Chapter 5. Progress Bar

Introducing the HTML-based Progress Bar

Starting with Version 3.0, AspUpload offers a unique feature: an HTML-based progress indicator which pops up upon the commencement of an upload and displays the current upload status including the percentage completed and time remaining information. Once an upload is finished or aborted by the user, the progress window automatically closes. This feature is particularly useful when uploading large (over 1 MB) files.
The progress bar is implemented using nothing but HTML and client-side JavaScript. No ActiveX controls or Java applets are used. A typical progress window looks like this:

The layout of the progress window is fully customizable. You can move around the progress bar and numeric indicators, change captions, add custom logos, etc.

Implementation Steps

You must carefully follow these steps to add progress bar functionality to your application.
Step 1. If your upload form is located in an .HTML file, you should make it into an .ASP file as some ASP script needs to be added to that file.
Step 2. At the top of your form file (above the actual form), place the following code:

<%
Set UploadProgress = Server.CreateObject("Persits.UploadProgress")
PID = "PID=" & UploadProgress.CreateProgressID()
barref = "framebar.asp?to=10&" & PID
%>

This code is responsible for creating a unique progress ID which connects the page containing the upload form with the progress indicator and upload script.
Step 3. Add the following JavaScript function to your form file below the ASP fragment of Step 2. You may place it between the <HEAD>...</HEAD> tags.

<SCRIPT LANGUAGE="JavaScript">
function ShowProgress()
{
  strAppVersion = navigator.appVersion;
  if (document.MyForm.FILE1.value != "" || document.MyForm.FILE2.value != "" || document.MyForm.FILE3.value != "")
  {
    if (strAppVersion.indexOf('MSIE') != -1 && strAppVersion.substr(strAppVersion.indexOf('MSIE')+5,1) > 4)
    {
      winstyle = "dialogWidth=375px; dialogHeight:130px; center:yes";
      window.showModelessDialog('<% = barref %>&b=IE',null,winstyle);
    }
    else
    {
      window.open('<% = barref %>&b=NN','','width=370,height=115', true);
    }
  }
  return true;
}
</SCRIPT>

The function ShowProgress() is responsible for opening the progress bar window upon submission of your upload form. You may need to change the line
if (document.MyForm.FILE1.value != "" || document.MyForm.FILE2.value != "" || document.MyForm.FILE3.value != "")
according to your own form name and the names of your file item(s). In our example, the form name is MyForm, and the file items are FILE1, FILE2 and FILE3.
Step 4. Add an extra parameter to the ACTION attribute of your upload form, as follows:
<FORM NAME="MyForm" METHOD="POST" ENCTYPE="multipart/form-data"
  ACTION="progress_upload.asp?<% = PID %>">
Step 5. Add an OnSubmit attribute to your upload form which calls the ShowProgress() routine added in Step 3, as follows:
<FORM NAME="MyForm" METHOD="POST" ENCTYPE="multipart/form-data"
  ACTION="progress_upload.asp?<% = PID %>"
  OnSubmit="return ShowProgress();">
Step 5. Make sure the files FRAMEBAR.ASP, BAR.ASP, and NOTE.HTM are located in the same directory as your form file. FRAMEBAR.ASP contains the main frameset for the progress indicator. Under IE, it invokes the file BAR.ASP within an <IFRAME>. Under Netscape, it invokes the files BAR.ASP and NOTE.HTM within a regular <FRAMESET>. You only need to modify the files BAR.ASP and NOTE.HTM to customize your progress indicator. We do not recommend making any changes to the file FRAMEBAR.ASP, unless you need to change the size of your progress bar.
Step 6. Add the following line to your upload script right after the CreateObject line:

<%
Set UploadProgress = Server.CreateObject("Persits.Upload")
Upload.ProgressID = Request.QueryString("PID") ...
%>

This tells the UploadManager object the progress ID of the current upload, thereby connecting it to the progress window.
The sample files progress.asp and progress_upload.asp demonstrate a simple progress bar-enabled upload system.
Click the link below to run this code sample:
http://localhost/aspupload/05_progress/progress.asp

Customizing the Progress Bar

To change the phrase To cancel uploading, press your browser's STOP button, make the appropriate modifications in the files FRAMEBAR.ASP (for IE) and NOTE.HTM (for Netscape).
All other modifications involve the method UploadProgress.FormatProgress called in the file BAR.ASP.
The method FormatProgress expects the following parameters:
ProgressID
Iteration (in/out)
BarColor
Format

ProgressID is a unique ID passed to the file BAR.ASP via the PID variable.
BarColor is the color of the progress bar. By default, this value is "#0000F7".
Iteration will be covered later.
Format is a string containing special characters (described below) which controls the HTML layout of the progress window. By default, this value is
"%TUploading files...%t%B3%T%R left (at %S/sec) %r%U/%V(%P)%l%t"
The format string may contain the following special characters:
%T - the beginning of an HTML table (<table><tr><td>)
%t - the end of an HTML table (</td></tr></table>)
%d - a new column (</td><td>)
%r - a new column aligned to the right (</td><td align=right>)
%c - a new column aligned to the center (</td><td align=center>)
%l - a new row (</td></tr><tr><td>)
%n - a line break (<br>)
%Bn - the progress bar; n indicates the number of percentage points per progress square. Our sample uses %B3. For a solid progress bar, use %B0.
The following special characters are placeholders for various numeric values:
%E - elapsed time
%R - remaining time
%S - current transfer speed
%U - transferred amount
%V - total upload size
%P - percentage completed
%Y - remaining amount
The code samples progress1.asp, BAR1.ASP and FRAMEBAR1.ASP demonstrate a customized progress bar which displays a logo. The following changes were made to the original files:

In the file progress1.asp, the barref variable points to FRAMEBAR1.ASP instead of FRAMEBAR.ASP. Also, the dialog height is increased by 50 points:
barref = "framebar1.asp?to=10&" & PID
winstyle = "dialogWidth=375px; dialogHeight:180px; center:yes";
...
window.open('<% = barref %>&b=NN','','width=370,height=165', true)

In the file FRAMEBAR1.ASP, all references to BAR.ASP are replaced by BAR1.ASP, and the sizes are changed as well:
<IFRAME src="bar1.asp?PID=... frameborder=0 framespacing=10 width=369 height=115></IFRAME>
...
<FRAMESET ROWS="80%, 20%" COLS="100%" border="0" framespacing="0" frameborder="NO">

In the file BAR1.ASP, the format string is changed as follows:
"<CENTER><IMG SRC=logo.gif></CENTER>%TUpload Progress%t%B3%T%R left (at %S/sec) %r%U/%V(%P)%l%t"

And finally, an image file logo.gif is placed in the appropriate virtual folder.
Click the link below to run this code sample:
http://localhost/aspupload/05_progress/progress1.asp

Fine-tuning the Progress Bar

If something goes wrong with an upload, and the progress bar window stops receiving signals from the server, it will remain open for 10 refreshes (roughly 10 seconds as the progress window is refreshed every second).
This parameter can be changed, if necessary. The value 10 is passed to the progress bar via the to (time open) variable, as follows:
barref = "framebar1.asp?to=10&" & PID
This line of code is located in the top portion of your upload form file (in our case, progress.asp and progress1.asp).