Web Applications - File/Image Download Feature Pack

To purchase this Feature Pack, please click here. To purchase the File Upload, Image Upload and File/Image Download Feature Pack Bundle click here.


Watch Video - Quick Overview

Watch Video - In Depth Part 1

Watch Video - In Depth Part 2


The File Download Feature Pack allows you to define an action for an event in your Grid (such as when a user clicks a button) that downloads a file from the server to the user's machine.

Using the Feature Pack, you can:


The File Upload Feature Pack and Image Upload Feature Pack (separately sold) allow you to upload files to the server. The combination of the File Upload and File Download Feature Packs, make it very easy to design these types of web applications:



To use the File Download Feature Pack, add a new button or hyperlink to the Grid and then define the action using Action Javascript. If the Feature Pack is installed, the list of available actions in Action Javascript will include the 'File Download' action.

If you select the 'File Download' action, the following dialog box will open.


You must first specify the 'Type' of file that you are downloading and its source. When you click the smart field for the 'Type' prompt, you will see this dialog:



File Download Types

Absolute Filename - The filename of a file on the server you want to download. e.g. c:\myfiles.excel.xls.

Grid field contains filename - A field in the Grid contains the filename of a file on the server.

When you select this option the builder will prompt for an optional 'Folder name' property.

The field in the Grid can either contain a fully qualified filename (e.g. c:\excelfiles\sales.xls), or it can contain a relative filename (e.g. customerReport.pdf)

If the field in the Grid contains a relative filename, the actual file that gets downloaded is from the folder specified in the 'Folder name' property. For example if 'Folder name' is set to 'c:\downloadfiles' and the field in the current grid row contains 'report1.pdf' then the file that gets downloaded is 'c:\downloadfiles\report1.pdf'

Grid field contains a linked or embedded image - Downloads the image that is displayed in a field in the Grid. The image can either be a linked image (i.e. the Grid field contains the name of the image), or an embedded image (i.e. the Grid field is a BLOB field and it contains the actual image data).

Table contains an embedded object - The data that you want to download is stored in a BLOB field in the table that the Grid is based on.

The field does not have to be actually selected as part of the Grid (and it is likely that it will not be selected as part of the Grid because it can't be displayed anyway, and including it in the Grid query would just slow down the Grid unnecessarily).

The BLOB data in the table field might be an excel spreadsheet in one Grid row, a .pdf file in another Grid row, a Word document in yet another Grid row, and so on. Each row of the Grid could embed a different type of BLOB data in the field.

When you select this option a new property is displayed: 'Object type mode'. This choices for this property are 'Dynamic' (each row in the table could store a different type of object in the Blob field) or 'Fixed' (each row in the table stores the same type of data in the BLOB field).

If you choose the 'Dynamic' option, then you are prompted for the name of field that contains the object type for the row. If you choose the 'Fixed' option, then you specify the fixed type (e.g. .xls, .pdf, etc.)

Javascript - When you select this option a Javascript function is called. This Javascript function can compute the name of the file to download. Once the function has computed the filename, an Ajax callback is made to the server to actually download the file.

When you choose this option, you are prompted for the name of a Javascript function that will compute the filename. This function must be defined in the 'Javascript Function Declarations' section and it must return a filename that exists on the server.

Ajax Callback - This option allows you to dynamically compute the name of the file to download in a server-side event, or to dynamically construct the file itself that you want to download. For example, your Xbasic callback script might query the database and compute an XML file that can then be downloaded to the client machine.


Function Prototype of the Ajax Callback Function


The Xbasic code below shows the prototype of the Ajax Callback function. The e object that is passed into the function has many properties.

The most important properties are:


e.ajaxCallBackType - this property must be set to 'FileDownload'

e.filename - the filename that you want to download to the client



function mycallbackFunction as c (e as p)
'This function will handle the Ajax callback.

'Your code must set these properties in the e object:
'e.ajaxCallBackType = "FileDownload"
'e.Filename = The name of the file to download
'e.Folder = (optional) If e.filename is a relative filename, the name of the folder where e.Filename is located
'e.Action = (optional) 'Display Message' or 'Do nothing' - action to take if the file to download is not found
'e.Message = (optional) The message to display to the user if the file to download is not found and e.Action is set to 'Display Message'
'e.CSFilename = (optional) The default name for the file when the user is prompted to save the file on their computer. If you leave this blank then the default name is the same as e.filename.

'The 'e' object contains all of the data that is submitted in the Ajax callback.

'In addition, the 'e' object contains:
'e._currentRowDataOld - (only if the grid is editable) - original value in the current row before field was edited.
' examples: e._currentRowDataOld.lastname, e._currentRowDataOld.firstname
'e._currentRowDataNew as p - current field values in the current row.
' examples: e._currentRowDataNew.lastname, e._currentRowDataNew.firstname
'e._currentRowKeys - an array containing primary key field values for the current row
' example: If the primary key for the table that the grid is based on is 'Lastname' and 'Firstname',
' e._currentRowKeys[1] will contain the value for 'Lastname' and e._currentRowKeys[2] will contain the value for 'Firstname'

'In addition, the 'e' object contains:
'e.tmpl - the Component definition
'e.session - session variables
'e.__si - state information that is stored in a hidden field in the component.
'e.rtc - holds runtime calculations that are performed when component is executing.
end function