File Downloader will work properly only if you supply a list of files available for download. Hence, such a list is an important part of the control configuration.

File List Format

First of all, let us study the list format. A file list should be provided as a plain text. It consists of one or more entries separated by line feeds. Each entry comprises the following four fields separated by pipes (|).

# Field Purpose
1 Content-Type This field is used to:
  • Show the user the MIME type of the file they are going to download.
  • Check the MIME type returned by the Web server for the current file. If the values correspond to each other, the file will be downloaded. If not, the file will not be downloaded.
To prevent File Downloader from checking the MIME type correspondence, specify the */* value for this field.
2 File size in bytes This field is used to:
  • Show the user the size of the file they are going to download.
  • Check the file size returned by the Web server for the current file. If the values are equal, the file will be downloaded. If not, the file will not be downloaded.
Specifying the file size is optional; to ignore it set this field to 0.
3 Local file name

This field is used to specify a name for saving the file on the user's computer. The field can optionally contain subfolders that will be created before saving the file in the download folder.

This field cannot contain relative parent paths. That is, the ..\folder\file.ext value is incorrect, but the folder\file.ext value is acceptable. If an incorrect value is specified, the DownloadItemComplete event will return 6 as a value of the Result parameter.

4 URL to file This field is used to specify the remote location from which the file will be downloaded. Remember that the file should reside on the same site where File Downloader and the file list itself reside.
Note

The order of fields in the entries is important.

The fields cannot be empty.

Here is an example of a correct file list.

image/jpeg | 174546 | apples.jpg | http://localhost/Fruits/apples.jpg
image/jpeg | 134257 | apricots.jpg | http://localhost/Fruits/apricots.jpg
image/png | 545675 | avocados.png | http://localhost/Fruits/avocado.png

A location of the file list is specified using the FileList property. You can provide a URL of a simple text file as its value. But this URL can also point to some server script that will generate the file list. For example of the latter approach, see the Basic Sample topic.

The file list is downloaded in the following cases:

Accessing File List Items Through JavaScript

Working With the FileDownloader Object

Along with simple downloading a file list from the site, File Downloader allows creating the list dynamically through JavaScript. For that you have to use the FileDownloader object. After it is created, you can add and remove entries by changing its properties and calling its methods.

Important

The FileDownloaderWriter object is not a FileDownloader instance.

The FileDownloader instance is created after the writeHtml method of the FileDownloaderWriter object is called. But it is not guaranteed that the FileDownloader object will be created right after this method returns. However, you can get a notification about the object creation by subscribing to the InitComplete event or by specifying a fullPageLoadListenerName function. The second approach is preferable, if you use the helper script (iuembed.js). Here is how you can create such a listener.

JavaScript

<script language="javascript">
function onFullPageLoad(){
	// ... Add necessary code ...
}

var fd = new FileDownloaderWriter("FileDownloader", 122, 44);
fd.fullPageLoadListenerName = "onFullPageLoad";
// ... Configure File Downloader ...
fd.writeHtml();
</script>

Now, you can access the FileDownloader object properties and methods from the onFullPageLoad function. For example, you can manipulate the file list from it, and there is more than one way to do it.

Modifying the FileList Property

The most obvious way is to change the URL of the file list. It can be useful if your file list is generated by some server-side script depending on the parameters passed to it. An example of changing the URL of the file list is listed below.

JavaScript

<script language="javascript">
function onFullPageLoad(){
	//The getParams() function is a function that retrieves a string of parameters 
	//from the user interface
	var params = getParams();
	getFileDownloader("FileDownloader").setFileList(
		"http://localhost/filedownloader/filelistgenerator.aspx?" + params);
}

var fd = new FileDownloaderWriter("FileDownloader", 122, 44);
fd.fullPageLoadListenerName = "onFullPageLoad";
// ... Configure File Downloader ...
fd.writeHtml();
</script>

Accessing Existing File List

If the FileList property is not empty, you can download the file list before it is displayed to the user. In this case, you can modify it the way you need before the actual download starts. Use the DownloadFileList() method to download the list specified with the FileList property. Calling this method does not delete a file list created manually as described in the Constructing a New File List section. Instead, the method adds the content of the server file list to the manually created one. If you want to delete the manually created list before calling the DownloadFileList() method, use the ClearFileList() method.

Note

After the file list is displayed to the user, it cannot be modified.

This can be useful in the case like the following. Assume, you need to implement some kind of a filter that will remove certain files - files of a particular type or with particular names or of a particular size - that is completely up to you. As the filter condition will probably be specified by the user, and you do not want him to reload the whole file list, it is better to implement the filter on the client side. The filter will do the following:

  1. Iterate through entries of the file list. For that we will use two methods:
    • The DownloadFileCount property returns the amount of entries in the file list.
    • The DownloadFileName property returns a file name from the entry with the specified index.
  2. Check the conditions. In our example files with names containing the word old should be removed.
  3. If the specified conditions are met, the file is removed. All the rest files can be downloaded by the user. To remove a file from the file list, the DownloadFileRemove() method is used.

JavaScript

<script language="javascript">
function onFullPageLoad(){
	var downloader = getFileDownloader("FileDownloader");
	downloader.DownloadFileList();
	var i=0;
	while (i<downloader.getDownloadFileCount()){
		if (downloader.getDownloadFileName(i).search(/old/) >= 0)
			downloader.DownloadFileRemove(i);
		else
			i++;
	}
}
function onError(Code, Description, HttpCode, Page, Url, Index){
	alert("An error occured: " + Code);
}

var fd = new FileDownloaderWriter("FileDownloader", 122, 44);
fd.fullPageLoadListenerName = "onFullPageLoad";
fd.addParam("FileList", "http://localhost/filedownloader/filelist.txt");
//This listener should be added as the DownloadFileList method does not return
//anything at all
fd.addEventListener("Error", "onError");
// ... Configure File Downloader ...
fd.writeHtml();
</script>

Constructing New File List

There is also another way of working with the file list: you can leave the FileList property blank and create a completely new list in run time using the DownloadFileAdd() method. For example, the list of the desired files is a list of search results and is already in the page. If we assume that this result list is returned in the following format:

HTML

<!-- ... -->
<table id="results">
	<thead>
		<tr>
			<th>Name</th>
			<th>Size in bytes</th>
		</tr>
	</thead>
	<tr>
		<td><a href="http://localhost/files/file1">file1</a></td>
		<td>2542118</td>
	</tr>
	<tr>
		<td><a href="http://localhost/files/file2">file2</a></td>
		<td>34216155</td>
	</tr>
	<!-- ...more rows... -->
</table>
<!-- ... -->

Then the file list can be built as listed below.

JavaScript

<script language="javascript">
function getFiles(){
	var result = new Array;
	var table = document.getElementById("results");
	var rows = table.getElementsByTagName("tr");
	for (i=1;i<rows.length;i++){
		result[i-1] = new Array(3);
		//Get url
		result[i-1][0] = rows[i].getElementsByTagName("a")[0].href;
		//Get name
		result[i-1][1] = rows[i].getElementsByTagName("a")[0].firstChild.data;
		//Get size
		result[i-1][2] = rows[i].getElementsByTagName("td")[1].firstChild.data;
	}
	return result;
}
function onFullPageLoad(){
	var downloader = getFileDownloader("FileDownloader");
	var files = getFiles();
	for (i=0;i<files.length;i++)
		//Populate the file list
		downloader.DownloadFileAdd("*/*", files[i][2], files[i][1], files[i][0]);
}

var fd = new FileDownloaderWriter("FileDownloader", 122, 44);
fd.fullPageLoadListenerName = "onFullPageLoad";
// ... Configure File Downloader ...
fd.writeHtml();
</script>