3.7. Saving & Exporting Charts

After you finish designing a chart, you can save the definition as a chart or as a chart template, and provide XML definitions for both. You can also generate a number of static image exports of the chart or create a JSP/JNLP page with the Chart Viewer JNLP (More about Applets in JNLP: Section 1.2.7 - Run Applets in WebStart with JNLP file).

3.7.1. Saving Charts with Report Data

When you design a chart using report data, the chart cannot be run/viewed any place except within the report. Because of this, most of the file operations are disabled in the Chart Designer. When you opt to save a chart it will be automatically saved with the same name as the report in the /chart/ directory of the installation. For example, if your report is named SalesReport, any charts in the report that use report data would be saved in the following convention SalesReport_0.tpl, SalesReport_1.tpl, etc

It is possible to have these charts in a different relative location when running reports. Runtime API options allow you to change the chart path.

Although most of the file options are disabled when you use report data for the chart, you can apply a template to carry over the appearance properties of another chart. Chart templates are covered in Section 3.7.2.1 - Working with Templates.

3.7.2. Saving Charts without Report Data

If your chart uses an independent data source from the report, it can be saved in any place with any filename. To save the current chart, select FileSave or FileSave As, or click on the Save button on the toolbar. Assuming you have not saved the chart before, or selected FileSave As, the following dialog will appear:

Save As Dialog

The first option allows you to specify a name and file path for the saved chart. You can browse to the appropriate file path by clicking on the Browse button at the bottom of the dialog. The second option allows you to specify which format you would like to use when saving the chart. As detailed in Section 3.2 - Charting Basics, there are two principle ways in which chart definitions can be saved.

Chart format:

Chart files save the chart in a binary file called filename.cht. A chart file stores both the definitions of the chart (type, dimension, etc), as well as the data that was used to create the chart.

Template format:

Template files save the chart in a binary file called filename.tpl. A template file only stores chart definitions. It doesn't store any chart data. Hence, any time a template file is opened, it will try to connect to the original data source to retrieve the data.

PAC format:

PAC files save the chart in such a way that makes them ready for deployment. A .PAC file takes the chart and all the supplementary files associated with it, such as background images, dynamic drill-downs, or parametric drill-downs, and places them in a single binary file.

Once you select a format you want to use, click on the OK button and the chart will be saved.

[Note]Note

When your report is run, EspressReport will try to load the chart along a relative path from where ever the chart is saved. If the chart cannot be found, it will not display. However, you can specify a different path for the chart using options available in the API.

3.7.2.1. Working with Templates

Chart templates are a special format in which chart definitions can be saved. Unlike chart files (.cht format) which saves both the chart definitions as well as the data for the chart, templates only save the definitions (i.e. the chart attributes and the layout of the individual components), and the data source information. This means that templates store the location/connection information for the data source that was used to create the chart, but they store none of the actual data in the file. (Templates do keep 10 records of back-up data, allowing them to be opened when the data source is not present).

Template files can be used in two ways. First, it can be opened, viewed, or exported, allowing you to see a chart with fresh data. This way data for the chart are retrieved based on the data source specified in the file. If the original data source is not accessible, this method cannot be used. The second way in which templates can be used is to apply its attributes to other charts. In this scenario, the chart to which the template is applied will inherit appearance properties of the template (including colors, fonts, size of chart components, position of legends, etc). This feature allows you to produce a consistent look and feel among charts.

The second approach is very useful if you are using the API to generate charts programmatically, using JDBC code or some other data source. You can then use a pre-defined template to control the look and feel of the generated chart without having to define the appearance properties in code or relying on the default chart properties. For more on applying templates in the API, please see Section 3.9.5.2 - Applying a Chart Template.

You can apply a template in Chart Designer by selecting FileApply Template. This will bring up a dialog prompting you to specify the template file you want to use.

Apply Template Dialog

The dialog allows you to specify the template file and its location. You can browse to a file by clicking on the Browse button.

Note that when the chart and the template being applied are different sizes (i.e. chart canvas size), the resulting chart may not display correctly. This is because the text size will not change between template and chart to which it is applied. While the other components will adjust to the size of the new canvas, the font will not. To keep a consistent look, the size of your template should be close to the size of the chart to which it will be applied.

Hyperlinks, floating lines, floating text, and axis scales defined in the template files carry over. You may have to redefine them in the chart, if necessary. Chart type and dimension are not modified by the template. For example, a three-dimensional chart will not be changed to a two-dimensional chart if the template is a two-dimensional chart. Likewise, a pie chart remains a pie chart when a template of a bar chart is applied. Although the chart type does not change when you apply a template, some appearance properties will not translate very well from a template with another chart type. For best results, try to apply templates of the same type and dimension to a chart.

3.7.2.2. Saving XML Templates

In addition to the two binary chart representations, you can also save the chart definitions in XML format. This option allows you to have a text-based chart template that can be used to modify chart properties outside of Chart Designer or the API.

To create an XML file when saving the chart, check the Create XML File box in the save as dialog when saving the chart. This will create an XML file for the chart. Note that the XML file is a representation of the .tpl format and not the .cht format.

3.7.2.3. Creating a Viewer Page

The other option to specify is whether you would like to create an HTML page to view the chart. The HTML page will redirect to a JSP which contains the Chart Viewer JNLP, which allows end users to view and manipulate the chart. The features of the Chart Viewer are discussed in detail in Section 3.8 - Chart Viewer

To create an HTML page when saving the chart, check the Create HTML File box in the save as dialog when saving the chart. This will create the HTML page with the same name as the chart file under the html// directory of your EspressReport installation. Before the file is written, you will be prompted to select which version of the Viewer that you would like to use.

Select Viewer Dialog

EspressReport supports AWT and swing versions of Viewer. Note that if you use Viewer, the client will need to have the Java plug-in.

Once you have created the HTML page, you can point your browser to the page to view the chart. Note that in order for the chart to appear you must load the HTML page vial http protocol. It will not work it you attempt to load it over a file protocol (i.e. browsing to the file and opening it). This means that your EspressReport must be installed in a Web server, and you must access the page via http (i.e. http://machinename:port/EspressReport/yourfile.html) in order for it to load correctly.

3.7.2.3.1. Viewer Options

There are a number of Chart Viewer options that you can configure from within Chart Designer. These are properties that are saved with the chart, which will appear when the chart is displayed in the viewer. To modify the viewer options, select FormatViewer Options. This will bring up the following dialog.

Viewer Options Dialog

The following options are available:

Auto Rotation:

This will enable automatic rotation for three-dimensional charts. The charts will begin to rotate when the applet is loaded. The rotation can be stopped using the appropriate button on the navigation panel.

Enable Menu:

This allows you to turn on or off the pop-up menu when users are viewing the chart in Chart Viewer.

2D/3D.

This allows you to turn on or off the dimension toggle in the pop-up menu. If this is turned off, users will not be able to change the chart dimension.

Type:

This allows you to turn on or off the type sub-menu in the pop-up menu. If this is turned off, users will not be able to change the chart type.

For .cht files, you can also set a scheduled refresh. This will allow the chart to periodically refresh the data when the chart is being viewed in Chart Viewer. To schedule a refresh rate, select DataSchedule refresh. This will bring up a dialog, allowing you to set the schedule options.

Schedule Refresh Dialog

From this dialog you can set the hour, minute, and second for the refresh interval. If you check the Disable Scheduler box, the Scheduler will be turned off.

3.7.3. Exporting Charts

From the Chart Designer, you can generate a number of static image exports for your chart. To export the current chart, select FileExport, or click the Export button on the toolbar. This will bring up a dialog allowing you to specify options for the generated file.

Click to view larger image

Export Chart Dialog

The first option allows you to specify a name and the file path for the generated file. You can browse to the appropriate file path by clicking the Browse button at the bottom of the dialog. The second option allows you to select what type of export you would like. The following options are available:

GIF

EspressReport can generate GIF images. GIF has 256 color limit which keeps image file sizes small.

JPEG

JPEG is another popular image format. It is a higher resolution image format than GIF and it is not patent protected. When generating a JPEG file, you can specify quality/compression of the file. The higher the quality, the larger the file.

If you select JPEG as the export format, after clicking OK you will be prompted to specify the quality. The higher quality image you select, the larger the generated file size. It is recommended that with the JPEG export, you use specify a high-quality image, as the low-quality results will most likely be undesirable.

PNG

PNG is an image format that is less popular, but can be displayed in most browsers. It is a high-quality image with a smaller file size than JPEG. It also provides transparent image background option.

SVG

SVG (Scalable Vector Graphics) is a relatively new image format, which saves the image as vectors in an XML-based text format. Generally, you will need a browser plug-in to view these images.

SWF

SWF is an Adobe Flash file. The flash format is vector based and allows the chart to be resized after export. Also, flash allows for high-resolution printing and produces a small file size. When selecting this export type, you can also specify the frame count (number of frames in the animation) and the frame rate (number of frames shown per second) or choose to disable the animation.

BMP

This is a Windows bitmap format.

WMF

WMF is the Windows Meta File format. This can be used for import/export into MS Office documents.

PDF

This will generate the chart in Adobe Portable Document Format. The chart will be generated as a one-page PDF document.

XML

This will generate an XML data file containing the chart's data. This will not generate an XML chart attribute file, only the data will be written into XML format.

XLS

Will generate an XLS (MS Excel) file and insert the chart as an image to the first XLS sheet.

TXT

This will generate a text data file containing the chart's data.

In addition, if your chart contains hyperlinks, you can choose to export a map file along with any of the generated images. The map file contains an HTML image map with the links for the generate chart. Map files are generated in the same location as the image file, and have the same file name. To generate a map file, check the Generate Data Map File box prior to exporting.

3.7.3.1. PDF Font Mapping

As with reports, you can use any font in the system for the labels, text, and titles in a chart. For most image exports, the text is written in the image and no additional configuration is necessary. For PDF export, however, you will need to specify a .ttf (true type font), .ttc (true type collection), .pfb, or .afm file for any system font you want to use in the chart.

To set font mapping for PDF export, select FormatFont Mapping. This will bring up a dialog allowing you to specify font files.

Click to view larger image

Font Mapping Dialog

For each font and style combination, you can select a specific .ttf, .ttc, .pfb, or .afm file for that font. You can either type the full path or browse to the font file. If you are using a .ttc file you will need to specify the font index in the box provided (.ttc files contain more than one font). Once you have specified the correct file, click the 'Add' button to save the mapping to the list. You can edit or delete existing mappings by selecting them in the list and then clicking the appropriate button.

[Note]Note

You only need to apply font mapping when exporting the chart by itself. If the chart is in a report, it will inherit the font mapping defined in the report.

3.7.3.1.1. PDF Font Mapping Import/Export

You can pass the font mapping from one chart to another using the Import/Export feature. You can export the font mapping by clicking on the Export button on the font mapping dialog. This will bring up a dialog box prompting you to specify a file name. The font mapping will then be saved as an XML file. You can load a font mapping XML file by selecting the Import option from the dialog. This will bring up a dialog box prompting you to specify the XML file that you would like to import. Click on OK and the mapping stored in the XML file will be applied to the current chart.