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

Customizing Upload Pane

Yet another way to change Image Uploader appearance and add extra features is to re-work its default layout.

Detaching the Upload Pane

Image Uploader provides means to change the standard three-pane layout by configuring its upload pane position. The idea is to untie the pane from the ImageUploader control, put it in the place where you want it to be and link it back with the "parent" control. This way you are able not only to change its size and position, but also to add an arbitrary HTML code between the pane and the control.

In short, you should carry out the following steps:

  1. Hide the default upload pane. You can do it by setting the FolderPaneHeight property to -1.
  2. Create a separate upload pane control (UploadPane class) and insert it in the necessary position in your HTML page. Use the UploadPaneWriter to do it. See the Image Uploader Embedding Scripts Library Reference for more details about it.
  3. Link this UploadPane with ImageUploader using the ParentControlName property. Just set it to the ID you specified when creating the ImageUploaderWriter.

Here is an example how to do it.

JavaScript
<script type="text/javascript" src="iuembed.js">  </script>
<script type="text/javascript">
var iu = new ImageUploaderWriter("ImageUploader", 650, 400);
//...Other params and event handlers...

//Hide the standard pane
iu.addParam("FolderPaneHeight", "-1");

//...Other params and event handlers...

iu.writeHtml();

</script>

<!-- Extra HTML, if needed -->

<script type="text/javascript">
var up = new UploadPaneWriter("UploadPane", 650, 200);
//...Other params and event handlers...

up.addParam("ParentControlName", "ImageUploader");

//...Other params and event handlers...
up.writeHtml();
</script>

Custom Upload Pane

You may stop at this point, if you need only to change the layout. But you may want more customization. For example, you may need not just to change the pane position, but modify the layout of each item in the upload list. In this case you can create your own upload pane based on the Thumbnail control.

It works in the following way:

  1. You create a container for thumbnails in your HTML page. For example, you can use the DIV element for this purpose.
  2. When the user chooses some files for the upload, you do the following:
    1. Add instances of the Thumbnail control using the ThumbnailWriter class.
    2. Associate this control with an item in the upload list of Image Uploader using the Thumbnail.Guid property. You should set it to the ImageUploader.UploadFileGuid of an appropriate upload item.
    3. If necessary, subscribe to the Thumbnail.Click event. It allows your JavaScript to be notified when a thumbnail in your custom upload pane has been clicked.
    4. Add whatever necessary HTML elements near the Thumbnail control. For example, you can add input fields, dropdown elements, etc. that can be used to fill information about this particular file.
  3. If an item is removed from the upload list, an appropriate Thumbnail control should be removed from the container as well.

Now it is time to see how to use this approach in practice.

First of all, insert the DIV element that will hold thumbnails (in other words, the element that presents the upload pane).

HTML
<div id="UploadPane">
    <!-- The thumbnails will be here -->
</div>

The UploadFileCountChange event tells the JavaScript when the user adds (or removes) something for upload. So, we will create the thumbnails in the handler of this event.

JavaScript
<script type="text/javascript" src="iuembed.js">  </script>
<script type="text/javascript">
var iu = new ImageUploaderWriter("ImageUploader", 650, 400);
    
//...Other params and event handlers...
    
iu.addParam("FolderPaneHeight", "-1");
iu.addEventListener("UploadFileCountChange", "ImageUploader_UploadFileCountChange");
    
//...Other params and event handlers...
    
iu.writeHtml();
</script>

The UploadFileCountChange event handler should carry out the following:

  1. Add Thumbnail controls.
  2. Associate Thumbnail controls with the parent ImageUploader control.
  3. Add appropriate HTML elements. In our case it will be an input element and a text area.
JavaScript
prevUploadFileCount = 0;
    
function ImageUploader_UploadFileCountChange() {

	if (imageUploader) {
		var uploadFileCount  = imageUploader.getUploadFileCount();
	
	//Files are being added
	if (prevUploadFileCount <= uploadFileCount) {
		for (var i = prevUploadFileCount + 1; i <= uploadFileCount; i++) {
			
			var fileName = imageUploader.getUploadFileName(i);
	
			//This variable can contain any additional HTML markup you need,
			//including extra input fields
			var h = "";
			
			//Add a thumbnail control and link it with Image Uploader by its name
			//and GUID
			var tn = new ThumbnailWriter("Thumbnail" + uniqueId, 96, 96);
			tn.addParam("ParentControlName", "ImageUploader");
			tn.addParam("Guid", imageUploader.getUploadFileGuid(i));
			h += tn.getHtml();
			
			//Create the DIV element which will represent the upload list item
			var div = document.createElement("div");
			div.innerHTML = h;
			div._fileName = fileName;
			
			//Append this upload list item to the custom upload pane.
			document.getElementById("UploadPane").appendChild(div);
		}
	}
	//Files are being removed
	else {
		//Get the hash with filenames as keys using some helper function
		var fileNameIndexHash = getFileNameIndexHash();
		var UploadPane = document.getElementById("UploadPane");
		var i = UploadPane.childNodes.length - 1;
		while (i >= 0) {
			if (fileNameIndexHash[UploadPane.childNodes[i]._fileName] == undefined) {
				UploadPane.removeChild(UploadPane.childNodes[i]);
			}
			i--;
		}
	}
			
	prevUploadFileCount = uploadFileCount;
	
	}
	
}

Do not forget that if you add form elements to a custom thumbnail, and want to send the data entered by the user, you also have to put the appropriate fields to the POST request. The best way to do it is to use the AddField() method in the BeforeUpload event handler.

Full code demonstrating how to create custom upload pane can be found in the Multiple Descriptions Sample.

See Also

Reference

Samples

Manual