Naming Exported files from the BIRT WebViewer

A common question we get on the BIRT news group is how to change the name of an exported document. For instance, exporting to PDF, the developer may wish to have more control on what filename is used for the export. Currently the name used is just the report name followed by the emitter extension (eg MyReport.pdf).

BIRT 2.3.1 which will be released later this month now supplies a solution to this problem. The example web viewer has a setting that can be added to the web.xml that allows you to specify a Java class that will be responsible for generating the name.




<!-- Filename generator class/factory to use -->
<context-param>
<param-name>BIRT_FILENAME_GENERATOR_CLASS
<param-value>org.eclipse.birt.report.utility.filename.DefaultFilenameGenerator
</context-param>









The class specified must implement the IFilenameGenerator interface, which has one method named getFilename. This method is passed four parameters.

baseName – Contains the base filename for the report, with no extension provided.
fileExtension – The extension for the selected operation (ppt for export to PowerPoint).
outputType – The operation being executed. More on this parameter later.
options – Specific options for the operation.

The instance of the IFilenameGenerator is called in multiple locations within the example viewer. When you export the report:



When you export the report data:



And when you use the /document servlet mapping, for example:

http://localhost:8080/WebViewerExample/document?__report=OrderDetails.rptdesign





This URL will run the report and download the rptdocument.

Suppose you wish to have the date in your filename, when exporting the report. To do this, create a class with the following code:

package my.filename.generator;
import java.util.Date;
import java.util.Map;
import org.eclipse.birt.report.utility.filename.*;
public class MyFilenameGenerator implements IFilenameGenerator{
 
 public static final String DEFAULT_FILENAME = "BIRTReport"; 
 
 public String getFilename( String baseName, String extension, String outputType, Map options )
 {
  return makeFileName( baseName, extension );
 }
 public static String makeFileName( String fileName, String extensionName )
 {
  String baseName = fileName;
  if (baseName == null || baseName.trim().length() <= 0)
  {
   baseName = DEFAULT_FILENAME;
  }
  
  // check whether the file name contains non US-ASCII characters
  for (int i = 0; i < baseName.length(); i++) {
   char c = baseName.charAt(i);
 
   // char is from 0-127
   if (c < 0x00 || c >= 0x80) {
    baseName = DEFAULT_FILENAME;
    break;
   }
  }
  
  // append extension name
  if (extensionName != null && extensionName.length() > 0) {
   baseName += (new Date()).toString() + "." + extensionName; 
  }
  return baseName;
 }
}

If you check the source, you will notice this is just the default class with one modification.

   baseName += (new Date()).toString() + "." + extensionName; 



Which just inserts the date into the output.

You can also check the operation type if you wish to set the name based on the operation. Currently the available options for outputType are:

IFilenameGenerator.OUTPUT_TYPE_EXPORT – When exporting report to one of the supported formats.
IFilenameGenerator.OUTPUT_TYPE_DATA_EXTRACTION – When exporting report data.
IFilenameGenerator.OUTPUT_TYPE_REPORT_DOCUMENT – When using the document servlet mapping.

This example is located here.

Vincent Petry from the dev team has also uploaded a Birt Viewer 2.3 User Reference, which describes the settings and parameters available with the example web viewer. This document is informative and is located here.

If you wish to build your own version of the filename generator, make sure to include viewservlets.jar from the WebViewerExample\WEB_INF\lib directory in your build path.