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.
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 (
|1||Content-Type||This field is used to:
|2||File size in bytes||This field is used to:
|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
|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.|
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:
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 (
Here is how you can create such a listener.
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.
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.
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.
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:
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.