Printing Report Regions

You can configure a classic report region to print by exporting it to a number of different formats. Oracle BI Publisher supports Adobe Portable Document Format (PDF), Microsoft Word Rich Text Format (RTF), or Microsoft Excel format (XLS), or Extensible Markup Language (XML). The supplied OC4J with Apache FOP alternative only supports PDF and XML. If you choose to use other third-party rendering engines, other output formats can also be configured.

By taking advantage of region report printing, your application users can view and print reports that have a predefined orientation, page size, column headings, and page header and footer. Interactive reports also have the ability to export to PDF, RTF, Microsoft Excel and Comma Separated Values (CSV). Note that for interactive reports, it is not possible to define a custom report layout.

Topics:

About Printing Reports to PDF
About Report Printing Configuration Options
About Classic Report Printing Methods
About Report Queries
About Report Layouts
Configuring Classic Report Region Print Attributes
Configuring Interactive Report Region Print Attributes

Tip:

If you are running Oracle Application Express with Oracle Database 11g Release 1 (11.1), you must enable network services in order to use report printing. See "Enabling Network Services in Oracle Database 11g"

See Also:

"How to Create a Master Detail PDF Report" in Oracle Application Express Advanced Tutorials

About Printing Reports to PDF

When printing to a PDF, the report data is transformed using an externally defined report server. When the application end user clicks a print link, a request is sent to the Application Express engine. The Application Express engine then generates the report data in XML format and report template in XSL-FO or RTF format. The external reporting engine then transforms the data and the template into a PDF which displays to the end user using the conversion servlet that ships with BI Publisher 10.1.3.2 (formerly known as Oracle XML Publisher). Fortunately, this architectural complexity is transparent to both end users and developers. End users just click a print link, and developers just declaratively set regions to support PDF printing. Output to other formats operates in the same manner using the necessary conversion servlet.

About Report Printing Configuration Options

Your report server can be Oracle BI Publisher, OC4J with Apache FOP, or another standard XSL-FO processing engine. Oracle BI Publisher provides a higher level of functionality and facilitates "high fidelity" output requirements including master-detail reports, charts, and so on. To accommodate the difference in functionality, Oracle Application Express provides two report printing configuration options:

Standard Support. Enables you to print report regions and report queries using either the built-in templates (provided with a standard XSL-FO processing engine), or other XSL-FO compatible formats you provide. This setting does not support RTF.

Standard Support provides declarative formatting of report regions and report queries with basic control over page attributes, including page orientation, page size, column heading formats, page header, and page footer.
Advanced Support. Requires a valid license of Oracle BI Publisher (also known as Oracle XML Publisher). This setting, provides you with all the capabilities of the Standard configuration plus the ability to define RTF-based report layouts developed using the BI Publisher Word Template Builder.

To learn more about installing and configuring Oracle BI Publisher, see PDF Printing in Application Express 3.1. Go to:
```
http://www.oracle.com/technology/products/database/application_express/html/configure_printing.html
```

Note:

To use the full functionality of report printing, your Oracle Application Express service administrator must enable it for your site. See "Configuring Report Printing" in Oracle Application Express Administration Guide.

About Classic Report Printing Methods

There are two ways to print classic report regions:

Configure Printing Attributes for a Report Region. You can print a report region by configuring the Printing Attributes for the region. See "Configuring Classic Report Region Print Attributes".
Create a Report Query. You can print a report by defining a report query as a Shared Component. See "About Report Queries".

Both report regions and report queries can be downloaded in the following formats:

PDF - Adobe Portable Document Format.
RTF - Microsoft Word Rich Text Format.
XLS - Microsoft Excel format. Note that this is not a true .xls file because the content is HTML-based.
HTML
XML - Extensible Markup Language.

To format either a report region or report query, you associate it with a report layout. To learn more, see "About Report Layouts".

About Report Queries

You can print a report region by defining a report query as a Shared Component. A report query identifies the data to be extracted. Unlike SQL statements contained in regions, report queries contain SQL statements that are validated when you save the query. Note that report queries must be SQL statements, not functions returning SQL statements.

You can associate a report query with a report layout and download it as a formatted document. If no report layout is selected, a generic layout is used. The generic layout is intended to be used to test and verify a report query. When using the generic layout option and multiple source queries are defined, only the first result set is included in the print document. The reports can include session state of the current application.

To make these reports available to end users, you then integrate them with an application. For example, you can associate a report query with a button, list item, branch, or other navigational component that enables you to use URLs as targets. Selecting that item then initiates the printing process.

Topics:

Creating a Report Query
Editing Report Queries
Copying Report Queries

Creating a Report Query

Note that the availability of the report query options depends on how your service administrator configures report printing for your instance. All options described in these steps may not be available to you.

To create a report query:

Navigate to the Shared Components page. See "Accessing the Shared Components Page".
Under Reports, click Report Queries.
Click Create.
For Query, specify the following information:
1. Report Query Name - Enter a name to identify the report query. When referencing a report query as a link target, the report query name is part of the request string.
2. Output Format - Select the report output format. Valid options include:
  - PDF - Adobe Portable Document Format.
  - Word - Microsoft Word Rich Text Format.
  - Excel - Microsoft Excel format. Note that this is not a true .xls file because the content is HTML-based.
  - HTML
  - XML - Extensible Markup Language.
3. Item - Select the item to hold the format value. This can be used to determine the output format at runtime.
4. View File As - Select how the Web browser opens the report query document. Options include:
  - Attachment - Displays a File Open/Save dialog box when the user clicks the report query download button.
  - Inline - Displays the report query document inside the Browser window.
5. Session State - Select this check box to reference session state values, such as the values of page items in the XML structure of your report.
6. Click Next.
For SQL Query, enter a SQL statement directly or click Query Builder to build a SQL statement by clicking and pointing.

To reference applications and page items in the SQL statement, reference them as bind variables. Click Set Bind Variables to be able to enter in values for each bind variable and test the query to ensure the expected output is returned.
For Download Definition, specify the following:
1. Data Source for Report Layout - Use this option to download a report definition export file. Select XML Data or XML Schema and then click Download.
  
  XML Schema creates XSD file (that is, a XML schema definition of your XML structure.)
2. Add Query - Click this button to add another query to the report query. Adding another query enables the production of complex reports with more than one output component (for example, a chart and a report based on two different queries).
3. Create Report Query - Click this button to exit the wizard early. The Report Layout Source will default to use the generic report layout.
4. Click Next.
For Upload Report Layout, specify the following:
1. Report Layout Source - Specify how the report layout is derived. If you choose the report based file layout then the layout name and report layout file must be provided.
2. Layout Name - Enter a layout name (optional). The default is the report query name.
3. Report Layout File - Click Browse and select a Rich Text Format (RTF).
4. Click Next.
For Confirm:
1. Query Name - Identifies the query.
2. Report Layout - Identifies the report layout you selected.
3. Output Format - Identifies the format for this report query.
4. Derive from Item - Identifies the item to hold the format information.
5. URL - To integrate this report with your application, use the displayed URL as the target for a button, list item, link, or other navigational component. End users can click a button, for example, to start the printing process.
6. Test Report - Click this to preview your report. If you have chosen to use a generic report layout then the Test Report will not produce an output.
7. Click Finish.
  
  The Report Query is created and saved to Shared Components.

Editing Report Queries

To edit a report query:

Navigate to the Shared Components page. See "Accessing the Shared Components Page".
Under Reports, click Report Queries.
On the Report Queries page, you can use the Navigation bar at the top of the page to search for a query by name or change the page display. For example, you can change the default display by making a selection from View list. Available options include:
- Icons (the default) displays each query as a large icon. To edit a query, click the appropriate icon.
- Details displays each query as a line in a report. To edit a query, click the name.
Select the appropriate report query. On the Edit Report Query page, edit the information.
Click Apply Changes.

Copying Report Queries

To copy a report query:

Navigate to the Shared Components page. See "Accessing the Shared Components Page".
Under Reports, click Report Queries.
On the Report Queries page, click Copy.
On the Copy Report Query, select the query you want to copy, enter a name for the report query, and click Copy.

The copy appears in the query list.

About Report Layouts

To format either a classic report region or report query, you associate it with a report layout. Using report layouts renders the data in a printer-friendly format. If you do not select a report layout, a default XSL-FO layout is used. The default XSL-FO layout is always used for rendering Interactive Report regions.

When creating and using report layouts, you can:

Take advantage of the default layouts for report regions and generic layouts for report queries provided with Oracle Application Express.
Utilize the built-in XSL-FO-based layouts for report regions by copying and customizing the code. You can edit a number of attributes for report regions that control page size, fonts, colors, and so on.
Create RTF or XSL-FO report layouts to customize the report look and feel. To use RTF report layouts, your Oracle Application Express service administrator must select the Advanced setting for your site. See "Configuring Report Printing" in Oracle Application Express Administration Guide.

Topics:

About Report Layout Options
Creating a Report Layout
Editing Report Layouts
Copying Report Layouts

About Report Layout Options

You can create a report layout based on one of these options:

Generic Columns - A generic report layout works with most query result sets. With this layout, the number of columns is automatically adjusted when generating the printable document.

A number of report layout attributes can be defined declaratively for report regions using the built-in XSL-FO default layout. This step allows for creating customizable copies of the built-in default XSL-FO layout, if additional control over the report layout is needed.
Named Columns - A named column report layout is a query-specific report layout designed to work with a defined list of columns in the query result set. This type of layout is used for custom-designed layouts when precise control of the positioning of page items and query columns is required.

Note that the availability of the Report Layout options depends on how your site administrator configured the report printing settings at your site. All options described in these steps may not be available to you.

See Also:

"Configuring Report Printing" in Oracle Application Express Administration Guide.

Creating a Report Layout

To create a report layout:

Navigate to the Shared Components page. See "Accessing the Shared Components Page".
Under Reports, click Report Layouts.
Click Create.

The Create Report Layout wizard appears.
For Report Layout Type, select an option and click Next:
- Generic Columns (XSL-FO) - This layout is pre-populated with a default template, which you can edit to fit your needs.
- Named Columns (RTF) - This layout is uploaded as an RTF file.
- Named Columns (XSL-FO) - This layout is uploaded as an XSL-FO file.
For Layout Source, review and edit the appropriate information. The options that appear on this page depend on the layout type you select:
- If you selected Generic Columns:
1. Report Layout Name - Enter a name to identify the report layout when associating it with a report query or report region.
2. Report Layout - The report layout is the XSL-FO based definition of the page formatting. All attributes defining page size, orientation, fonts, styles, and so on, are defined in this section.
  
  To see a list of valid substitution strings and other information, click the item label, Report Layout. This opens a separate Help window.
3. Report Column Heading - Defines the look of each cell in the report heading row.
4. Report Column - Defines the look of each cell for all report rows.
5. Report Column Width - This width is computed at runtime time or can be derived from the report column definition of a report region.
- If you selected Named Columns:
1. Layout Name - Enter a name to identify the report layout when associating it with a report query or report region.
2. 8.b) Report Layout File - Upload the file containing the report layout.

Editing Report Layouts

You can edit a generic column report layout directly in Application Express. However, to edit a named column report layout, you must download the current file, edit it, and then upload it again.

To edit a report layout:

Navigate to the Shared Components page. See "Accessing the Shared Components Page".
Under Reports, click Report Layouts.
On the Report Layouts page, select the layout you want to edit.
For generic column layouts, edit the layout directly on the Edit Report Layout page and then click Apply Changes.
For named column layouts, click Download and save the file to your computer.

Edit the file and then upload the updated version as a new report layout.

Copying Report Layouts

You can copy a report layout to edit and save.

To copy a report layout:

Navigate to the Shared Components page. See "Accessing the Shared Components Page".
Under Reports, click Report Layouts.
On the Report Layouts page, click Copy.
On the Copy Report Layout page, select the layout you want to copy, enter a name for the copy, and click Copy.

The copy appears in the layout list.

Configuring Classic Report Region Print Attributes

One approach to printing a report region is to configure Print Attributes. Once configured, these attributes only apply only to current region and cannot be used outside the context of the region.

If the printing feature is set up for your instance, you can configure a report region to print in various formats.

See Also:

"About Classic Report Printing Methods" and "Configuring Report Printing" in Oracle Application Express Administration Guide

To configure a classic report region for printing:

In your application, select the page containing the classic report region you want to print.

The Page Definition appears.
Under Regions, click Report next to the region you want to print.
Click the Print Attributes tab.
Under Printing, specify the appropriate information:
1. Enable Report Printing - Select Yes.
2. Link Label - Enter the text for the link that starts the printing process.
3. Response Header - Specify whether the response header generated by Oracle Application Express is based on your Report Settings or the Print Server. The response header is the information the server sends back to the Web browser in response to receiving an HTTP request. It contains the date, size and type of file that the server is sending back to the client and also data about the server itself. To specify content disposition (using the attribute View File As) and file name, the response header needs to be based on Report Settings.
4. View File As - Select how the Web browser opens the report query document. Options include:
  - Attachment - Displays a File Open/Save dialog box when the user clicks the report query download button.
  - Inline - Displays the report query document inside the Browser window.
5. (Optional) File Name - Enter a name for the downloaded file. If you leave this blank, the region name is used as the file name.
6. Output Format - Select an output option.
7. Item - Determines the output format at runtime. Select the application or page item that holds format value.
8. Report Layout - Select Default Report Layout to use the built-in generic report layout, or an available report layout you or your administrator created. See item Help for a listing of the supported substitution strings available when building custom XSL-FO report layouts.
9. Print Server Overwrite - Specify an alternate print server. A print server is typically configured centrally for all workspaces in Oracle Application Express Administration Services. See "Configuring Report Printing" in Oracle Application Express Administration Guide.
  
  Configuring an alternative print server at the report level makes debugging and diagnosis of potential printing problems easier and supports the use of specific custom built end points to perform custom XSLT transformations.
10. Print URL - Report regions can be printed using the standard print link or using a page button. To use a button, remove the Link Label, create a button on your page, and use the URL shown in this attribute as the button target.
In the remaining sections, define page size, paper orientation, page headers and footers, fonts, text color, and background color.
Under Report Columns, specify the width for each column.

The default is to make each column the same width. The Total Width is a display only field that shows the sum of all column width values. When changing the width for an individual column the Total Width is automatically recalculated. If Column Width Units is set to Percentage, rather than Points, then the total column width must be less than or equal to 100.

Use the Reset Column Width button to reset the Column Width Units to Percentage and change all column widths back to their default value. The Recalculate button maintains the current ratios between column widths but reduce all column widths such that the Total Width is less than or equal to 100%.
Click Apply Changes.

Configuring Interactive Report Region Print Attributes

Unlike classic reports, the Interactive Report Print Attributes can only utilize the default XSL-FO layout and is initiated from the Report Attributes, Download section rather than directly from this screen. Once configured, these attributes only apply only to the current region and cannot be used outside the context of the region.

If the printing feature is set up for your instance, you can configure a report region to print in various formats

To configure a interactive report region for printing:

In your application, select the page containing the interactive report region you want to print.

The Page Definition appears.
Under Regions, click Interactive Report next to the region you want to print.
Click the Print Attributes tab.
Under Printing, specify the appropriate information:
1. Response Header - Specify whether the response header generated by Oracle Application Express is based on your Report Settings or the Print Server. The response header is the information the server sends back to the Web browser in response to receiving an HTTP request. It contains the date, size and type of file that the server is sending back to the client and also data about the server itself. To specify content disposition (using the attribute View File As) and file name, the response header needs to be based on Report Settings.
2. Content Disposition - Select how the Web browser opens the report query document. Options include:
  - Attachment - Displays a File Open/Save dialog box when the user clicks the report query download button.
  - Inline - Displays the report query document inside the Browser window.
3. Print Server Overwrite - Specify an alternate print server. A print server is typically configured centrally for all workspaces in Oracle Application Express Administration Services. See "Configuring Report Printing" in Oracle Application Express Administration Guide.
  
  Configuring an alternative print server at the report level allows for easier debugging and diagnosis of potential printing problems and supports the use of specific custom built end points to perform custom XSLT transformations.
In the remaining sections, define page size, paper orientation, page headers and footers, fonts, text color, and background color.
Click Apply Changes.