This documentation is for the old version. Go to the latest Upload Suite docs

Writing Client-Side Upload Code Using ASP.NET Control

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.

Handling Client-Side Events

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.

ASP.NET
<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>
Note

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.

OnClientFullPageLoad

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.

ASP.NET
<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>

OnClientInitWriter

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.

ASP.NET
<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>

Writing Server-Side Upload Script

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.

Getting 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:

  • SourceFile contains a source file.
  • Thumbnails contains a list of thumbnails.
  • Description contains user-specified description.
  • Exif and Iptc contain EXIF and IPTC metadata fields respectively.
  • and others.

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:

ASP.NET
<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:

C#
protected void FileUploaded(object sender, Aurigma.ImageUploader.FileUploadEventArgs e)
{
    //Your code        
}

Now all the data we need is available through e parameter properties.

Note

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.

Getting Source File

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.

C#
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);    
}

Getting Thumbnails

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.

ASP.NET
<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.

C#
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.

C#
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");
    }
}

Getting Metadata

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:

ASP.NET
<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.

C#
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"));
}

Recovering Folder Structure on Server

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.

See Also

Reference

Manual