This topic is a follow-up to the Configuring Image Uploader ASP.NET Control article. It discusses the aspects of Image Uploader ASP.NET control usage related to handling client-side events and receiving uploaded files server-side.
Image Uploader ASP.NET control has a number of client-side events which are fired by Image Uploader (ActiveX control or Java applet) and handled in JavaScript. These events allow you to trace all interactions between the user and the control from the initialization to the upload completion. To add a client-side event handler you just need to write it in JavaScript and specify its name as a value of the corresponding control parameter.
<script type="text/javascript">
function ClientBeforeUpload()
{
alert("BeforeUpload");
}
</script>
<body>
<form id="form1" runat="server">
<cc1:ImageUploader ID="ImageUploader1" runat="server"
height="400" width="600"
OnClientBeforeUpload="ClientBeforeUpload">
</cc1:ImageUploader>
</form>
</body>
To access ImageUploader on the client-side it is recommended to use its ClientID property:
getImageUploader("<%=ImageUploader1.ClientID%>")
In addition to Image Uploader events the ASP.NET control provides two more client-side events.
This event fires after Image Uploader is completely initialized and all other page elements are loaded. It is recommended to use this event instead of the window.onload, because it guarantees that ActiveX control or Java applet is completely created and initialized. The following code sample demonstrates how to restore the upload list when the page with Image Uploader is completely loaded.
<script type="text/javascript">
function ClientFullPageLoad()
{
getImageUploader("<%=ImageUploader1.ClientID%>").LoadUploadList(1);
}
</script>
<body>
<form id="form1" runat="server">
<cc1:ImageUploader ID="ImageUploader1" runat="server"
height="400" width="600"
OnClientFullPageLoad="ClientFullPageLoad">
</cc1:ImageUploader>
</form>
</body>
This event fires just before initialization of ActiveX control or Java applet. It accepts the writer parameter which represents ImageUploaderWriter object. Using this parameter you can modify settings of Image Uploader on the client side before it is instantiated. The code snippet below demonstrates how to change the control layout using this event handler.
<script type="text/javascript">
function ClientInitWriter(writer)
{
writer.addParam("PaneLayout", "OnePane");
}
</script>
<body>
<form id="form1" runat="server">
<cc1:ImageUploader ID="ImageUploader1" runat="server"
height="400" width="600"
OnClientInitWriter="ClientInitWriter">
</cc1:ImageUploader>
</form>
</body>
Image Uploader ASP.NET control simplifies writing of upload processing script. It receives the data sent by Image Uploader (ActiveX control or Java applet) as a POST request, parses it, and provides a typed access to this data on a server. Here we will consider primary aspects of receiving and working with uploaded data.
The uploaded data can be retrieved and processed in the FileUploaded event handler. This event fires whenever a file is successfully uploaded and provides an access to this file and its additional data through FileUploadEventArgs properties:
See a full property list in Image Uploader ASP.NET Control Reference.
To add FileUploaded event handler just specify its name in the control events list or add OnFileUploaded parameter declaratively:
<cc1:ImageUploader ID="ImageUploader1" runat="server"
height="400" width="600"
OnFileUploaded="FileUploaded">
</cc1:ImageUploader>
The page code-behind should contain this event handler with the specified name:
protected void FileUploaded(object sender, Aurigma.ImageUploader.FileUploadEventArgs e)
{
//Your code
}
Now all the data we need is available through e parameter properties.
The FileUploaded event is not fired if the user aborts uploading. So you do not need to apply request integrity checking before saving uploaded file. If, however, you need to determine if the user cancels the upload you can use the IsRequestCompletelyReceived property.
In the case if Image Uploader is configured to send source files (the
UploadSourceFile property is
true) you can retrieve these files using the
FileUploadEventArgs.SourceFile property. It returns the
SourceFileInfo class instance. This class has a number of properties
which contain the uploaded file itself and its characteristics. The most useful of them are listed below:
In addition, it provides the Save(String) method which saves a source file to specified path on a server. Here is a short code snippet which shows how to use the SourceFileInfo class to save a source file on a server and write some file-related information (filename, image dimensions and user description) to a XML file.
protected void FileUploaded(object sender, Aurigma.ImageUploader.FileUploadEventArgs e)
{
Aurigma.ImageUploader.SourceFileInfo sourceFile = e.SourceFile;
XmlDocument descriptions = new XmlDocument();
descriptions.AppendChild(descriptions.CreateElement("files"));
XmlElement xmlFile = descriptions.CreateElement("file");
xmlFile.SetAttribute("name", sourceFile.FileName);
xmlFile.SetAttribute("width", sourceFile.Width.ToString());
xmlFile.SetAttribute("height", sourceFile.Height.ToString());
xmlFile.SetAttribute("description", e.Description);
descriptions.DocumentElement.AppendChild(xmlFile);
descriptions.Save(Server.MapPath(sourceFile.FileName + ".xml"));
sourceFile.Save(Server.MapPath("Uploads/") + sourceFile.FileName);
}
By default Image Uploader sends an original image only, however, you can configure it to send downsized, rotated, and watermarked copies of this image. You can find the detailed information about image operations in the Resizing and Rotating Images topic. Here we will consider how to adjust the ASP.NET control to create thumbnails and retrieve them on a server.
Image Uploader ASP.NET control allows configuring up to three thumbnails. To specify whether the control should upload the first, second or third thumbnail just set the UploadThumbnail1FitMode, UploadThumbnail2FitMode or UploadThumbnail3FitMode properties correspondingly to non-Off value. All other thumbnail parameters are optional, they specify such characteristics as thumbnail width and height, resize quality, etc. Use the settings below to upload the first thumbnail resized to 120x120 pixels preserving original image proportions, and the third thumbnail which size is equal to the original image.
<cc1:ImageUploader ID="ImageUploader1" runat="server"
height="400" width="600"
UploadThumbnail1FitMode="Fit"
UploadThumbnail1Height="120"
UploadThumbnail1Width="120"
UploadThumbnail3FitMode="ActualSize">
</cc1:ImageUploader>
When thumbnails are uploaded you can retrieve them server-side using the FileUploadEventArgs.Thumbnails property, which returns a collection of thumbnails. Each thumbnail in this collection is represented by an instance of the ThumbnailInfo class. This class contains the thumbnail itself and provides an access to some additional information, namely thumbnail dimensions, compression mode, etc. To save a thumbnail you can use the Save(String) method analogous to SourceFileInfo mentioned before.
There are two ways to get thumbnails out of the collection. The first one is to get them by indexes corresponded to the uploaded thumbnail. For example, if you configured the control to send the first and the third thumbnails (as it is shown in the code sample above), you should use indexes 1 and 3 to retrieve these thumbnails.
protected void FileUploaded(object sender, Aurigma.ImageUploader.FileUploadEventArgs e)
{
Aurigma.ImageUploader.SourceFileInfo sourceFile = e.SourceFile;
sourceFile.Save(Server.MapPath("Uploads/") + sourceFile.FileName);
Aurigma.ImageUploader.ThumbnailInfo thumbnail1 = e.Thumbnails[1];
thumbnail1.Save(Server.MapPath("Uploads/Thumbnails/") + sourceFile.FileName + "_" +
thumbnail1.Width.ToString() + "x" + thumbnail1.Height.ToString() + ".jpg");
Aurigma.ImageUploader.ThumbnailInfo thumbnail3 = e.Thumbnails[3];
thumbnail3.Save(Server.MapPath("Uploads/Thumbnails/") + sourceFile.FileName + "_" +
thumbnail3.Width.ToString() + "x" + thumbnail3.Height.ToString() + ".jpg");
}
The second way is to use a foreach iterator which allows you to walk through the collection of thumbnails without passing their indexes. However, if you need to know an index of the current thumbnail you can use the Index property.
protected void FileUploaded(object sender, Aurigma.ImageUploader.FileUploadEventArgs e)
{
Aurigma.ImageUploader.SourceFileInfo sourceFile = e.SourceFile;
foreach (Aurigma.ImageUploader.ThumbnailInfo thumbnail in e.Thumbnails)
{
thumbnail.Save(Server.MapPath("Uploads/Thumbnails/") + sourceFile.FileName + "_" +
thumbnail.Index.ToString() + ".jpg");
}
}
Some image file formats allow storing not only an image itself, but also some additional information about it. This data is called metadata and can be written by digital cameras or some specific software and stores capturing parameters or journalistic details. See the detailed information about supported metadata types in the Working with EXIF and IPTC Metadata topic. Here we will consider how to retrieve metadata fields server-side.
To extract EXIF and IPTC details use the ExtractExif and ExtractIptc properties. They both accept a string which contains necessary EXIF or IPTC field names, separated with semicolons. These metadata fields will be sent to the server along with the image they are extracted from, its thumbnails and other details. To access them server-side use Exif and Iptc properties respectively. Suppose you configured the control to send some EXIF and IPTC fields like this:
<cc1:ImageUploader ID="ImageUploader1" runat="server"
height="400" width="600"
OnFileUploaded="FileUploaded"
ExtractExif="ExifDateTime;ExifOrientation;ExifModel"
ExtractIptc="IptcCredit;IptcHeadline">
</cc1:ImageUploader>
You can retrieve these fields on server using the code snippet below.
protected void FileUploaded(object sender, Aurigma.ImageUploader.FileUploadEventArgs e)
{
Aurigma.ImageUploader.ExifList exifList = e.Exif;
Aurigma.ImageUploader.IptcList iptcList = e.Iptc;
XmlDocument metadata = new XmlDocument();
metadata.AppendChild(metadata.CreateElement("metadata"));
XmlElement xmlExif = metadata.CreateElement("exif");
xmlExif.SetAttribute("DateTime", exifList["ExifDateTime"]);
xmlExif.SetAttribute("Orientation", exifList["ExifOrientation"]);
xmlExif.SetAttribute("Model", exifList["ExifModel"]);
metadata.DocumentElement.AppendChild(xmlExif);
XmlElement xmlIptc = metadata.CreateElement("iptc");
xmlIptc.SetAttribute("Credit", iptcList["IptcCredit"]);
xmlIptc.SetAttribute("Headline", iptcList["IptcHeadline"]);
metadata.DocumentElement.AppendChild(xmlIptc);
metadata.Save(Server.MapPath("metadata.xml"));
}
When you upload folders you may need to save files preserving the folder structure the user sent.
This task is discussed in Uploading Folders topic. The article shows
how to configure Image Uploader to send paths along with files and
how to handle them on the server side. To solve this task using
Image Uploader ASP.NET control you should follow these instructions with only
one difference. You should use RelativeFilePath
property to retrieve a relative path instead of FileName_i POST field.
This property makes sense only if the folder upload feature is turned on (i.e. the
AllowFolderUpload is set to
true) and the uploaded file was located inside a subfolder. In that case this
property contains a relative path to the file and the OriginalFileName
represents its filename. For example, if the user sends a My Documents\My Photos\00001.jpg file
its FileName_i POST field will contain
My Documents\My Photos\00001.jpg value. However, the
RelativeFilePath property will contain
My Documents\My Photos\ value and the OriginalFileName
property will contain 00001.jpg.