VPE+ Concepts and Examples

Reports are created in the VPE native output format (a SOURCE file of TOutputFormat = ofVPEFile), but may be exported to another format (a TARGET file of TOutputFormat = ofPDFFile, ofODTFile, ofHTMLFile, or ofXMLFile). The exception is creating a custom file format (TOutputType = ofCustomFile), of course, where the source file is necessarily the same as the target file and its format is up to you.

A common scenario is sending a report direct to preview and allowing the user to print the report or optionally save it to a file in a format of their choice. In this case the source VPE file is temporary (for automatic deletion when finished) and while no target file name is immediately necessary, a default file name may need to be set in anticipation.

In other cases, you might want to export the report direct to PDF, say, with or without prompting the user for a filename. Or you might wish to keep the VPE format report file rather than allowing it to be deleted. Or any number of permutations to suit your applications requirements...

Fortunately, VPE+ handles much of this automatically, while still allowing you to manipulate and manage the more complex filing tasks with a variety of properties and methods. Here is how it all works:

Setting the SOURCE File Name (Native VPE Format File)

Typically, the initial report (using the native VPE file format) will be generated to a temporary SOURCE file. Once it has been printed and/or saved to some other format, it is no longer needed and can be deleted.

By default, VPE+ handles this automatically - there is nothing else you need to do:

• The report will be created in the folder returned from run time property TReportInterface.ActiveTempFolder (see below for how this is derived).
• The report file name will be returned from the WinAPI function GetTempFileName using the system file extension for the VPE file format which is "vpe".

There are two ways you can intervene in this process in order to retain the source report file (ie stop it being deleted on completion of report output):

1. You can force the source VPE file to be retained by calling the method RetainVPESourceFile and supplying a permanent file name (in TReportWriter.OnConfigure, for example). The file is retained in addition to the target file format (which might be a PDF file, for example).

1. Only the file path and file name are required - the file extension will always assume the system value for VPE files which is "vpe" (see the table of extensions below).
2. In the absence of a file name, the TReportWriter.OutputDefaultFileName property value will be used (default = "Report").
3. In the absence of a file path, the run time property TReportInterface.ActiveTempFolder will be used (see below for how this is derived).

2. If ofVPEFile is the desired target output format, then the VPE source file is that file. The report is directly created as the "target" file instead.

The ReportInterface ActiveTempFolder Property

The ReportInterface determines which folder to use for temporary report files and assigns it to the run time property ActiveTempFolder. By order of preference, it is derived as follows:

1. the TReportInterface.DefaultReportFolder (design-time "global" property) if it is set and exists (default, not set)
2. a path provided in the event TReportInterface.OnGetTempFolder

eg return the OS temp folder:

3. the path of the application executable file (Application.ExeName)

The ActiveTempFolder is calculated ONCE when the ReportInterface is initialised. To force it to be reset, assign any value to the property TReportInterface.DefaultReportFolder (blank if necessary).

Setting the TARGET File Name

Basically, the target report file name is set in the run time property TReportWriter.OutputFileName which is initially blank (ie not set) for each new report.

If you do not expect to write the report to one of the available export formats (for example, the report will only be printed), then you do not need to set OutputFileName at all. Whether it is actively set or left blank, an output file name will be assigned according to this precedence sequence:

1. No Target: If the report is to be sent directly to the printer (output format = ofPrinter), no target output file is required. The output format is thus "void", and is set to ofVoid. The OutputFileName is cleared and left blank.
2. Format/Extension: In all other cases a particular file format (and therefore file name extension) is assigned:
1. The report SetupMode passed to the ExecuteReport method may indicate an explicit format.
   eg A mode of smPDFFile will set an output format of ofPDFFile.
2. If going to Preview (ofPreview) where no file output format is implied, it defaults to the value of the TReportWriter.OutputDefaultFormat design time property (default ofPDFFile).

Given an output format, the system applies a file name extension accordingly:

Note: Setting OutputFileName with a file extension is thus not required - it will be set according to this table anyway.

3. File Path and Name:
1. The file path and name set in OutputFileName will be honoured, if set and valid.
2. In the absence of a file name, the TReportWriter.OutputDefaultFileName property value will be used (default = "Report").
3. In the absence of a file path, the run time property TReportInterface.ActiveTempFolder will be used (see above for how this is derived)
4. Modifying the Default Output File Name
1. Once defaulted, the file path, name and extension are presented in the event TReportWriter.OnReportFileName.
   You can reset any of these components, although the correct file name extension will be re-applied for a system format if it has been changed.
2. If a file name is not set, a default is applied using the TReportWriter.OutputDefaultFileName property formatted as "[OutputDefaultFileName][n]".
   "n" is the batch index of the report, which is "1" unless you are batching multiple reports.
3. If a valid file path is not set, the run time property TReportInterface.ActiveTempFolder will be used (see above for how this is derived).

Using Custom File Formats

You can write code to generate a report in any format you wish - for example CSV text files, or Excel files. The same general process described above applies to custom format file names as well.

1. All custom formats are of TOutputFormat = ofCustomFile, but are uniquely identified by their FormatIndex (from 1 to CustomFormatCount).
2. You can set TReportWriter.CustomFormatDefaultIndex to specify a particular (default) custom format. This would be selected by default when the setup form is shown, for example.
3. You can set TReportWriter.SelectedCustomFormatIndex in combination with a SetupMode of smCustomFile or smEmailCustomFile to force unprompted output of a specific custom format.
4. A format name and file name extension can be provided in the event TReportWriter.OnCustomFormatQuery for any given FormatIndex. The file name extension may be anything you wish, but, as for system file formats, it will replace any other extension you might specify directly in TReportWriter.OutputFileName.

Save Prompts and Overwrite Prompts

When dealing with report file names, you may or may not wish to present the user with save prompts or file overwrite prompts. Control these aspects of report filing by setting the appropriate True/False TReportWriter.Options.

• set option roOutputFileNamePrompt = False to accept the automatically generated file name and not prompt the user.
• set option roConfirmOvewrite = False to accept file overwrites and not prompt the user.
• set option roConfirmFiled = False to not advise the user a report has been successfully filed.
• if a save dialogue has already confirmed a report file name in advance, you can set property TReportWriter.ReportFileNameConfirmed := True to avoid VPE+ re-prompting the user.

NOTE: TReportWriter.Options can be set at design time, or you can use any of several methods to apply options: see OptionAllow and OptionDisallow; OptionsAllow and OptionsDisallow; and OptionAllowed and OptionDisallowed.