Adobe ColdFusion 8

Report definition guidelines

To ensure a successful report, you should plan the following before defining it in the ColdFusion Report Builder:

  • Report design issues:

    Audience: Why are you creating this report? Who is the audience?

    Data: What data needs to be in the report? Where does it come from? Whether you use the Query Builder or pass a query to the report, you should plan the data in advance.

    Grouping: Are groups required? If so, ensure that the result set is returned in the correct order, and you define a group based on the sort column.

    Calculated fields: Are there fields that must be totalled or calculated? For column totals, use calculated fields. For calculated totals on individual rows, use SQL. For more information, see Common reporting tasks and techniques.

    Input parameters: Does the report require variable input? If so, define an input parameter and pass values to the report at run time by using the cfreportparam tag. For more information, see Common reporting tasks and techniques.

  • Data retrieval strategy:

    Query Builder and basic SQL: Use this option when your report has standard selection criteria (such as a WHERE clause with sorting and a fixed set of selection criteria) and when you have to develop a report quickly. This method also lets you specify cfquery options, such as caching.

    Query Builder and advanced query mode: Use this option when you use a ColdFusion query encapsulated in the report definition. This option is also useful if the query comes from the cfdirectory, cfldap, or cfpop tags; query of queries; or is dynamically constructed with the QueryNew function.

    The cfreport tag and a passed query: Use this option when you require more control over the result set used in the report; for example, your application might have a form that your clients use to construct dynamic selection criteria.

  • Related visual information:

    Charts: For more information, see Using charts.

    Subreports: For more information, see Using subreports.

Managing fonts with printable reports

Ideally, reports should achieve a consistent look across all client platforms and all browsers. ColdFusion handles this automatically for graphics and images, using the size specifications in the report definition. However, potential differences in font availability across browsers, browser versions, languages, and platforms can affect the font display for your report. There are a variety of factors that you must understand to ensure consistent report display.

Embedded fonts

You can ensure consistent report display by embedding fonts. However, reports with embedded fonts have a larger file size.

Output format

The FlashPaper and PDF output formats handle embedded fonts differently.

FlashPaper: FlashPaper always embeds fonts, which ensures that reports always display appropriately.

PDF: PDF reports can optionally embed fonts, however, if your report doesn't use embedded fonts, you must ensure that the fonts are available on the client computers.

Font availability on the server computer and the client computer

ColdFusion has different requirements for rendering the fonts in a report, depending on where the fonts are located.

Server computer: For all formats, the fonts used in a report must reside on the computer that runs ColdFusion. ColdFusion requires these fonts to render the report accurately. ColdFusion automatically locates Acrobat built-in fonts and fonts stored in typical font locations (such as the Windows\fonts directory). However, if your server has additional fonts installed in nonstandard locations, you must register them with the ColdFusion Administrator so that the cfdocument and cfreport tags can locate and render PDF and FlashPaper reports.

Client computer: If your PDF report does not embed fonts, the fonts reside on the client computer to ensure consistent report display.

Mapping logical fonts to physical fonts

If you are using Java logical fonts, such as serif, sans serif, or monospaced, ColdFusion maps these fonts to physical fonts by using specifications in the cf_root/lib/cffont.properties file (on the multiserver or J2EE configuration, this is the cf_webapp_root/WEB-INF/cfusion/lib directory). You can modify these mappings, if necessary. Also, if you are using an operating system whose locale is not English, you can create a locale-specific mapping file by appending .java-locale-code to the filename. If ColdFusion detects that it is running on a non-English locale, it first checks for a cffont.properties.java-locale-code file. For example, on a computer that uses the Chinese locale, name the file cffont.properties.cn. For more information on Java locale codes, see the Sun website.

The ColdFusion install includes a cffont.properties.ja file for the Japanese locale.

This discussion applies to both the cfdocument and cfreport tags. For more information, see the Report Builder online Help.