SoftArtisans ExcelWriter Guide

Output Options

Output Options with ExcelApplication: The Save Method
Output Options with ExcelTemplate in ASP: The Process Method
Output Options with ExcelTemplate in ASP.NET: The Save Method

Output Options with ExcelApplication: The Save Method

ExcelWriter can write spreadsheets in a number of different ways. You may choose to save a generated spreadsheet to the server's hard disk, return the file in memory, or open the file in either the browser or Microsoft Excel. Both ExcelApplication and ExcelTemplate provide several options for writing the generated spreadsheet.

Using the ExcelApplication object's Save method, you can,

Save a spreadsheet to disk.
Return the spreadsheet as a BinaryStream, that is, as a sequence of bytes in memory. (Technically, this is a variant of type VT_UI1 | VT_ARRAY.)
Stream the spreadsheet to the client and open it in Excel.
Stream the spreadsheet to the client and open it in the browser. In this case, Internet Explorer's menus and toolbars will be replaced with Excel's.
Return the spreadsheet as an ExcelTemplate object. *

*This feature is not available in ExcelWriterSE, ExcelWriterLE, or ExcelWriterFree.

ExcelApplication's Save method takes three optional parameters:

[varBytes =] objExcelApplication.Save [FileName], [SaveMethod], [SaveFormat]

ExcelApplication.Save Parameters

FileName Optional. If saving to disk, assign the path and file name of the new spreadsheet. If opening the file, assign a file name only. To return the file in memory, do not assign a value to this parameter.

SaveMethod

Optional. Specifies whether to save the file to disk, open it in Excel, open it in the browser, return it in memory, or return it as an ExcelTemplate object.

`0`	`saDefault`	If a `FileName` is assigned, the file will be saved to disk. If a `FileName` is not assigned, the file will be returned in memory as a sequence of bytes.
`1`	`saOpenInExcel`	Open the file in Excel
`2`	`saOpenInPlace`	Open in the browser
`3`	`saOpenAsTemplate`	Return an ExcelTemplate object. This feature is not* available in ExcelWriterSE and ExcelWriterLE.

Note: To use ExcelWriter constants (e.g., saOpenInExcel), include ExcelWriter's TypeLib metadata tag at the beginning of your script:

<!--METADATA TYPE="TypeLib" UUID="{7BCD2133-64A0-4770-843C-090637114583}"-->

Default value: 0

SaveFormat

Optional. Specifies whether to save the spreadsheet in BIFF7 (Excel 95) or BIFF8 (Excel 97/2000) format.

`7` in V1.x `8` in V2 or later	`saFileFormatDefault`
`7`	`saFileFormatExcel95`
`8`	`saFileFormatExcel97`
`8`	`saFileFormatExcel2000`

Note: To use ExcelWriter constants (e.g., saFileFormatExcel95), include ExcelWriter's TypeLib metadata tag at the beginning of your script:

<!--METADATA TYPE="TypeLib" UUID="{7BCD2133-64A0-4770-843C-090637114583}"-->

Default value: 7 in V1.x, 8 in V2

ExcelApplication.Save Examples
Filename	SaveMethod	SaveFormat	Result	Example
Null	saDefault (=0)	saDefault (=0)	Return the spreadsheet as a sequence of bytes to varBytes.	`varBytes = xlw.Save`
Path and file name	saDefault (=0)	saFileFormatExcel95 (= 7)	Save the file in Excel95 (BIFF7) format to a specific location on the hard disk.	`xlw.Save "d:\reports\report1.xls",,_ saFileFormatExcel95`
File name only, no path	saOpenInExcel (=1)	saDefault (=0)	Open in Excel on the client. If the user saves the file, it will have `report.xls` as the default name. If the file has already been cached by the browser, it will appear as report(1).xls.	`xlw.Save "report.xls", saOpenInExcel`
File name only, no path	saOpenInPlace (= 2)	saDefault (=0)	Open in the browser window. If the user doesn't have MS-Excel support in IE, it will ask the user to save the file. In this case, the `Filename` property isn't used, instead the browser will use the webserver script(which generates this Excel file) name as the default name.	`xlw.Save "report.xls", saOpenInPlace`

Top

Output Options with ExcelTemplate in ASP: The Process Method

Using the ExcelTemplate object's Process method, you can,

Save a spreadsheet to disk.
Stream the spreadsheet to the client and open it in Excel.
Stream the spreadsheet to the client and open it in the browser. In this case, Internet Explorer's menus and toolbars will be replaced with Excel's.
Return the spreadsheet as an ExcelApplication object. The spreadsheet can then be modified using ExcelApplication's objects, methods, and properties. See Passing ExcelTemplate to ExcelApplication. *

*This feature is not available in ExcelWriterSE, ExcelWriterLE, or ExcelWriterFree.

ExcelTemplate's Process method takes three parameters:

ExcelTemplate.Process Parameters

FileName Path and file name of the new spreadsheet

ProcessMethod

Optional. Specifies whether to save the file to disk, open it in Excel, open it in the browser, or return an ExcelApplication object. Assign ProcessMethod by name or number:

`0`	`saProcessDefault`	Save the file to disk
`1`	`saProcessOpenInExcel`	Open the file in Excel
`2`	`saProcessOpenInPlace`	Open in the browser
`3`	`saProcessOpenForScripting`	Return the file in memory as an ExcelApplication object. The spreadsheet can then be modified using ExcelApplication's objects, methods, and properties. See Example 2: Using ExcelTemplate with ExcelApplication. Note: This value is not available in ExcelWriterSE and ExcelWriterLE.

Default value: 0

ExcludeMacro Optional. If set to True, macros in the template will be excluded from the generated spreadsheet.

When ExcludeMacro is enabled, buttons associated with macros may produce the error "Data may have been lost." Therefore, when excluding macros, remove all associated buttons from the spreadsheet. Default value: False

Top

Output Options with ExcelTemplate in ASP.NET: The Save Method

Using the ExcelTemplate object's Save method, you can:

Save a spreadsheet to disk.
Stream the spreadsheet to the client and open it in Excel.
Stream the spreadsheet to the client and open it in the browser. In this case, Internet Explorer's menus and toolbars will be replaced with Excel's.
Return the spreadsheet as an ExcelApplication object. The spreadsheet can then be modified using ExcelApplication's objects, methods, and properties. See Passing ExcelTemplate to ExcelApplication.*

*This feature is not available in ExcelWriterSE, ExcelWriterLE, or ExcelWriterFree.

ExcelWriter includes 5 ExcelTemplate.Save methods:

`SAExcelApplicationDotNet Save()`

Returns the generated spreadsheet as an SAExcelApplicationDotNet object. This allows you to populate a template and then pass it to SAExcelApplicationDotNet to be modified.

Example:

[C#]
SAExcelApplicationDotNet XlwApp = XlwTempl.Save();
	
[VB.NET]
Dim XlwApp As SAExcelApplicationDotNet = XlwTempl.Save()

`Save(outputFileName)`

Saves the generated Excel file on the server.

outputFileName specifies a complete path and file name for the generated file. ExcelWriter will save the file to this location. If a file with the same name exists, it will be overwritten by the new Excel file.

Example:

[C#]
oExcelTemplate.Save(@"C:\Reports\Orders.xls");
	
[VB.NET]
oExcelTemplate.Save("c:\Reports\Orders.xls")

`Save(outputStream)`

Writes the generated Excel file to the specified System.IO.Stream, or a class derived from System.IO.Stream (for example, System.IO.FileStream).

If you pass Save a System.IO.FileStream, ExcelWriter will save the generated file on the server. If you pass Save Response.OutputStream, ExcelWriter will stream the the generated file to the client.

Example:

[C#]
//--- FileStream and FileMode are in the System.IO namespace
FileStream fstream = new FileStream(@"C:\temp\outfile.xls", FileMode.Create);
	
//--- Pass the FileStream to ExcelTemplate
oExcelTemplate.Save(fstream);
	
//--- Close the FileStream (could be in a finally block)
fstream.Close();
	
[VB.NET]
'--- FileStream and FileMode are in the System.IO namespace
Dim fstream As New FileStream("C:\temp\outfile.xls", FileMode.Create)
	
'--- Pass the FileStream to ExcelTemplate
oExcelTemplate.Save(fstream)
	
'--- Close the FileStream (could be in a finally block)
fstream.Close()

`Save(response)`

Streams the generated Excel file to the client.

If you pass Save an HttpResponse object object, ExcelWriter will stream the generated file to the client. If the user chooses to open (rather than save) the file, it will open in the browser window. The browser will use the ExcelWriter script name as the default file name displayed in the File Download dialog. To set a different file name and/or to open the file in Microsoft Excel, use the signature Save(response, attachmentName, OpenInBrowser).

Example:

[C#]
oExcelTemplate.Save(Page.Response);
	
[VB.NET]
oExcelTemplate.Save(Page.Response)

`Save(response, attachmentName, OpenInBrowser)`

Streams the generated Excel file to the client.

If you pass Save an HttpResponse object, ExcelWriter will stream the generated file to the client. This method allows you to specify a default client-side file name, and whether the file should be opened in the browser window or in Microsoft Excel.

The parameter attachmentName specifies a name for the generated Excel file; this name will be displayed in the download dialog when the file is streamed to the browser. If the parameter openInBrowser is set to true, and the user chooses to open the file, the file will open in the browser window. If openInBrowser is set to false, and the user chooses to open the file, the file will open in Microsoft Excel. By default, the file will open in the browser window. Note: not all browsers can embed an Excel file in the browser window.

[C#]
oExcelTemplate.Save(Page.Response, "Output.xls", false);

[VB.NET]
oExcelTemplate.Save(Page.Response, "Output.xls", False)

Top