Introduction
Your browser must be RFC 1867-compliant to be able to upload files. Netscape 3.0+ and Microsoft IE 4.0+ are RFC 1867-compliant. IE 3.0 requires a special file upload add-on (patch) available at download.com (search for "upload patch").
Getting Started
This is out first HTML file Test1.asp:
<HTML>
<BODY
BGCOLOR="#FFFFFF">
Notice the ENCTYPE="multipart/form-data" attribute in the FORM tag. It instructs the browser to send the entire file to the server and not just the file name entered in the input text box. It is absolutely mandatory that your uploading forms contain this attribute, or no uploading can be performed.
Let us now look at the corresponding uploading script UploadScript1.asp:
| <HTML>
<BODY> <%
Count = Upload.Save(Server.Mappath ("/upload")) <% = Count %> files uploaded. </BODY>
|
The first line of the ASP script simply creates an instance of the AspUpload object. The second line calls the Save method of the component which actually does the job: it parses the posting received from the browser, figures out how many files are being uploaded, and saves them in the specified local directory. The directory name may or may not be backslash terminated. All the files will be saved in that directory under their original names. We will see how to change any or all the file names shortly.
The Save method returns the number of files successfully uploaded. In case of an error this method will throw an exception.
We can now go ahead and try to upload a few files. Notice that you can use any or all of the three input boxes on our form. AspUpload is smart enough to figure out which input boxes are used and which are not.
<HTML>
<BODY
BGCOLOR="#FFFFFF">
File
2:<INPUT TYPE=FILE NAME="FILE2">
Description
2:<INPUT TYPE=TEXT NAME="DESCR2"><BR>
<INPUT
TYPE=SUBMIT VALUE="Upload!">
| <HTML>
<BODY> <%
Upload.Save(Server.Mappath ("/upload")) Files:<BR>
<P> Otheritems:<BR> <%
</BODY>
|
Notice that our HTML form now has two kinds of input boxes, TYPE=FILE and TYPE=TEXT. Because of the ENCTYPE attribute of out form, we can no longer access the form variables via the standard ASP Request.Form collection. That's where the Upload.Form collection comes to the rescue. This collection is almost identical to Request.Form, i.e. we can access its elements via integer or string indexes, for example:
Set Item1 = Upload.Form("DESCR1")
or
Set Item1 = Upload.Form(1).
We can also scroll through the items in the collection using the For-Each statement as shown in the code sample above. The Form collection contains objects of the type FormItem which only have two string properties, Name and Value (default property).
It's important to remember that the Upload.Form collection only includes non-file items, i.e. form items other than <INPUT TYPE=FILE>. We have chosen to have another collection, namely Files, to contain objects of the type UploadedFile which represent uploaded files that came from the <INPUT TYPE=FILE> items. Much like the Form collection, the Files collection items can be accessed using string or integer indexed, or via a For-Each statement, as shown in the example above.
After running Example 2, we will see something like this:
Files:
FILE1=d:\web\domain\upload\File1.xls (108544)
FILE2=d:\web\\domain\upload\File2.zip (211687)
Other items:
DESCR1=bla bla
DESCR2=test test
Notice that we have obtained the destination paths and sizes of the uploaded files via the Path and Size properties of the UploadedFile object, respectively.
If our form only contained 1 file input box, say <INPUT TYPE=FILE NAME="ONLYFILE">, there would be no need to use a For-Each statement. We could simply say
Response.Write Upload.Files("ONLYFILE").Path
or, more generally,
Response.Write Upload.Files(1).Path
IMPORTANT: Neither the Files nor Form collections are
populated until the Save method is called. It is therefore incorrect
to refer to either of these collections before calling Upload.Save.
<%
Set Upload = Server.CreateObject("Persits.Upload.1")
Upload.SetMaxSize
50000, False
Upload.Save(Server.Mappath
("./"))
%>
In this example we are limiting the size of the uploaded files to 50000 bytes. The optional second parameter specifies whether a file larger than the maximum should be truncated (if set to False or omitted), or rejected with an error exception (if set to True).
Upload.OverwriteFiles = False
This property is True by default.
To prevent name collisions, AspUpload will append the original file name with an integer number in parentheses. For example, if the file MyFile.txt already exists in the upload directory, and another file with the same name is being uploaded, AspUpload will save the new file under the name MyFile(1).txt. If we upload more copies of MyFile.txt, they will be saved under the names MyFile(2).txt, MyFile(3).txt, etc.
AspUpload 2.1 is capable of obtaining image size information from GIF, JPEG, PNG and BMP files via the properties UploadedFile.ImageWidth and UploadedFile.ImageHeight. You can use these properties to limit the size of uploaded images. To determine the type of an uploaded image, you may use the property UploadedFile.ImageType which returns the strings "GIF", "JPG", "PNG" or "BMP" for GIF, JPEG, PNG and BMP files, respectively. If an uploaded file is not an image or its type cannot be determined, this property returns the string "UNKNOWN". The following example demonstrates the usage of these properties (another example can be found in the sample file UploadScript7.asp):<%
Set Upload = Server.CreateObject("Persits.Upload.1")
Upload.Save(Server.Mappath ("./"))
For Each File in Upload.FilesIf File.ImageType <> "GIF" and File.ImageType <> "JPG" ThenNext
Response.Write "GIF or JPG files only please!"
Exit For
End IfIf File.ImageWidth > 150 Then
Response.Write "Image width cannot exceed 150 pixels."
Exit For
End IfIf File.ImageHeight > 200 Then
Response.Write "Image height cannot exceed 200 pixels."
Exit For
End If
%>