How to Build Download File List

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 (|).

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:

• When the user clicks the Download button.
• When the DownloadFileList() method is called in a JavaScript code provided by you. You can read more about it in the Accessing the Existing File List section below.

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.

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.

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

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

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.

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

<!-- ... -->
<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.

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

See Also

Samples

• Basic Sample

Reference

• FileList Property
• DownloadItemComplete Event
• InitComplete Event
• DownloadFileList() Method
• ClearFileList() Method
• DownloadFileCount Property
• DownloadFileRemove() Method
• DownloadFileAdd() Method
• Helper Script Reference (iuembed.js)