Class

WebFile

Description

WebFile is used to create binary content for the user to download. As long as the WebFile is in memory (something has a reference to it) the file will be available. Once the object is disposed of, the file will no longer be available for download. Make sure you keep a reference in a WebPage, the session or on a control to make sure the WebFile lives long enough for the download to finish.

Methods

Name

Parameters

Returns

Shared

Download

Boolean

Identifier

String

Open

file As FolderItem, [InMemory As Boolean = True]

WebFile

✓

Events

Name

Parameters

Returns

Downloaded

Property descriptions

WebFile.Cached

Cached As Boolean

Indicates whether or not the file is cached on the browser.

This property is read-only.

WebFile.Data

Data As MemoryBlock

Contains the data in the file. Data is initially a 0-byte MemoryBlock. The developer should create a new MemoryBlock of the size that will be needed to store the data.

You can also just assign a String as the Data.

Create a new file for downloading:

TextFile = New WebFile // TextFile is a property of the web page
TextFile.MimeType = "text/plain"
TextFile.ForceDownload = True // If False, the browser may try to display the file instead of download it
TextFile.FileName = "TextFile.txt"

TextFile.Data = "Hello, world!"

System.GotoURL(TextFile.URL) // This causes the file to be downloaded

WebFile.FileName

FileName As String

The name of the file.

Create a new file for downloading:

TextFile = New WebFile // TextFile is a property of the web page
TextFile.MimeType = "text/plain"
TextFile.ForceDownload = True // If False, the browser may try to display the file instead of download it
TextFile.FileName = "TextFile.txt"

TextFile.Data = "Hello, world!"

System.GotoURL(TextFile.URL) // This causes the file to be downloaded

WebFile.ForceDownload

ForceDownload As Boolean

Indicates whether the browser will always download the file instead of trying to display it (depending on the MIMEType). The default is False.

When True, the browser will always download the file rather than try to display it. For example, most web browsers will try to display simple text files and many will display PDF files inline. Set ForceDownload to True to instead ensure these types of files are downloaded instead.

If you find that FireFox users can't download files, try using Self.GotoURL and pass True for the InNewWindow parameter as well as having the user disable popup blockers.

Create a new file for downloading:

TextFile = New WebFile // TextFile is a property of the web page
TextFile.MimeType = "text/plain"
TextFile.ForceDownload = True // If False, the browser may try to display the file instead of download it
TextFile.FileName = "TextFile.txt"

TextFile.Data = "Hello, world!"

Self.GotoURL(TextFile.URL) // This causes the file to be downloaded

WebFile.MIMEType

MIMEType As String

This is the MIME type of the content. Browsers rely on this to determine what to do with the content. Setting WebFile to True will override the MIMEType. Defaults to "application/octet-stream".

This example creates a text file to make available for download. You can put it on the Pressed event handler for a WebButton so that the file is downloaded when the user clicks the button:

TextFile = New WebFile // TextFile is a property of the web page
TextFile.MimeType = "text/plain"
TextFile.ForceDownload = True // If False, the browser may try to display the file instead of download it
TextFile.FileName = "TextFile.txt"

TextFile.Data = "Hello, world!"

Self.GotoURL(TextFile.URL) // This causes the file to be downloaded

WebFile.Session

Session As WebSession

Session defaults to Nil. By assigning a session to the WebFile, that file will only be accessible from that session.

Only specify the Session if you need to restrict files in this manner. Maintaining separate files for each session will use up more memory.

WebFile.URL

URL As String

The url to the file. Best used with WebControl.GotoURL.

This property is read-only.

The Downloading example project uses WebFile.URL to download the png test file that was opened in the WebApplication event. The code for the Static Download button is:

If App.LogoFile <> Nil Then
  Self.GotoURL(App.LogoFile.URL)
Else
  MessageBox("Whoops, no logo file available")
End If

WebFile.UseCompression

UseCompression As Boolean

Determines if the web framework should compress a file before sending it to browsers that support gzip compression. The default value is True.

Method descriptions

WebFile.Download

Download As Boolean

Asks the browser to download the file. If this method returns true, it means that the request was sent to the browser, not that it was actually downloaded.

This example creates a text file to make available for download. You can put it on the Pressed event handler for a WebButton so that the file is downloaded when the user clicks the button:

TextFile = New WebFile // TextFile is a property of the web page
TextFile.MimeType = "text/plain"
TextFile.ForceDownload = True // If False, the browser may try to display the file instead of download it
TextFile.FileName = "TextFile.txt"

TextFile.Data = "Hello, world!"

If TextFile.Download Then // This causes the file to be downloaded
  // Download requested
End If

WebFile.Identifier

Identifier As String

An identifier that is unique to this WebFile.

WebFile.Open

Open(file As FolderItem, [InMemory As Boolean = True]) As WebFile

Converts the passed FolderItem to a WebFile that can be downloaded. <HideIf version=2013r3>The entire file is loaded into memory.</HideIf>The entire file is loaded in memory when InMemory is True (the default). When InMemory is False, the file is referenced directly from the disk and data is accessed in 64K chunks.

This method is shared.

Loading the entire file into memory means that the largest file that can be used is limited to the amount of free memory, up to a maximum of about 3GB or so.

When the inMemory parameter is False, the file is attempted to be loaded using 64K chunks. It is still possible, depending on the OS, for the entire file to be temporarily loaded into memory. This is not permanent as this memory will be released by the OS as part of its normal housecleaning.

If you want to download an existing file on the server, you need to create a WebFile that points to it and save the reference. The best way to do this is to use a property of the WebApplication class. In the App.Open event handler:

Var f As FolderItem = New FolderItem("MyFile.txt") // Get the file using a FolderItem
If f <> Nil And f.Exists Then
  // Convert the FolderItem to a WebFile
  App.MyFile = WebFile.Open(f) // MyFile is a property on the App object
  App.MyFile.ForceDownload = True
End If

Now in a WebButton on a page, you can download this file like this:

If App.MyFile <> Nil Then
  Self.GotoURL(App.MyFile.URL) // Download the file
End If

Event descriptions

WebFile.Downloaded

Downloaded

Fires when the current browser requests the file.

Use this event to display a message telling the user that the download is underway or perhaps to navigate them to a new page.

After the download is underway, send the user back to the main web page:

MainPage.Show

Notes

To get a reference to an existing FolderItem, use the Open shared method.

If you find that FireFox users can't download files, try using WebControl.GotoURL and pass True for the InNewWindow parameter as well as having the user disable popup blockers.

Sample code

This example creates a text file to make available for download. You can put it on the Pressed event handler for a WebButton so that the file is downloaded when the user clicks the button:

TextFile = New WebFile // "TextFile As WebFile" is a property of the web page
TextFile.MimeType = "text/plain"
TextFile.ForceDownload = True // If False, the browser may try to display the file instead of download it
TextFile.FileName = "TextFile.txt"

TextFile.Data = "Hello, world!"

TextFile.Download // This causes the file to be downloaded

If you instead want to download an existing file on the server, you need to create a WebFile that points to it and save the reference. The best way to do this is to use a property of the WebApplication class. In the App.Open event handler:

Var f As FolderItem = New FolderItem("MyFile.txt")
If f <> Nil And f.Exists Then
  App.MyFile = WebFile.Open(f) // "MyFile As WebFile" is a property on the App object
  App.MyFile.ForceDownload = True
End If

Now in a WebButton on a page, you can download this file like this:

If App.MyFile <> Nil Then
  Self.GotoURL(App.MyFile.URL) // Download the file
End If

Compatibility

Web projects on all supported operating systems.