Export to Adobe PDF

The Adobe Portable Document Format (PDF) is a well-established file format standard and a widely-accepted method of distributing reports. This topic discusses how to export Logi reports to Adobe PDF.


About Exporting Reports to PDF

The PDF format is useful because of its ability to faithfully reproduce the appearance of a document, including graphics, images, and text, so that it can be easily viewed using the Adobe Reader program or browser plug-in. Notice the emphasis on "document" - PDF was not initially designed as a format for reproducing browser content and it doesn't always do so very well. Even though PDFs can be viewed within a browser, the two technologies are quite different.

For example, recent browser versions and Logi products support doctype declarations, which serve to tell the browser how to handle content layout, how to apply style, and more. Report pages can look quite different with different doctype selections. However, the PDF format does not support doctype declarations, and therefore can't represent everything exactly as the browser does. So, exported report pages may not look exactly like they do in the browser if a doctype has been applied.

What does this mean? It means developers and users should be realistic in their expectations about just how faithfully a Logi report can be reproduced when exported as a PDF document.

Chart Canvas charts are exported as SVG objects rather than as images. This results in Chart Canvas charts exported to PDF having extremely high resolution - they can be zoomed or printed with high-quality at any resolution.

Logi Studio provides the Action.Export PDF element so that Logi reports can be exported to PDF files.


     

Developers can give users the ability to export a report in two ways: manually (to a PDF viewed in their own browser) or automatically (to a PDF file) based on an event or schedule. Manual exports are configured within report definitions and automated exports are configured within process definitions

The PDF export engine uses the Gecko-based rendering technology developed by Mozilla and found in the Firefox browser, resulting in Chart Canvas charts being exported as SVG objects rather than as images. This means that Chart Canvas charts exported to PDF have extremely high resolution - they can be zoomed or printed with high quality at any resolution.
 

Exporting Links

By default, links in reports are not enabled when they're exported to PDF. However, "live links", which are those that do not use Action.Link, can be enabled in the PDF output. To enable them, set the Target.PDF element's Show Links attribute to True.

Live links are created by using a Label element, with its Format attribute set to HTML, and adding <a> tags around the text in its Caption. Here's an example of a valid Caption attribute value for this purpose:

    <a href="https://www.logianalytics.com">Visit the Logi Analytics web site</a>

A complete URL must be specified, as shown, not a relative URL.
 

Specifying a Custom Temp File Location

In .NET Info applications, the PDF rendering engine used during exports writes temporary files to the C:\Windows\Temp folder by default. However, some anti-virus tools will flag multiple file-writing operations to this folder as potentially dangerous behavior and block them. Developers who encounter this situation can tell the PDF rendering engine to write temporary files elsewhere by adding a section to the Info application's web.config file:
 

<configSections>
   <section name="ABCpdf9.Section" type="WebSupergoo.ABCpdf9.ConfigSection, ABCpdf" allowLocation="true" allowDefinition="Everywhere" allowExeDefinition="MachineToLocalUser" overrideModeDefault="Allow"
restartOnExternalChanges="true" requirePermission="true" />
</configSections>

<ABCpdf9.Section>
    <Preferences>
       <clear />
       <add Key="TempDirectory" Value="C:\my_PDF_Temp_Folder" />           
    </Preferences>
</ABCpdf9.Section>

Add the code above that starts with <ABCpdf9.Section> just after the </configSections> section closing tag, as shown. Provide your own custom folder value for the TempDirectory key.

 Ensure that your custom temp folder already exists - the rendering engine will not create it.

Exporting a Report Manually

Here's an example of how to create a report with a link that allows the report to be exported manually:

     

  1. In your report definition, add an Action.Export PDF element as the child of a Label, Image, Button or Chart element, as shown above.
  2. Beneath it, add the required Target.PDF element.
  3. If the report to export is the current report, you need do nothing more. Just save your definition, preview or browse your report, and click the link to export it. It should open in the PDF viewer associated with your browser. It's that simple.

    In order to export the current report while maintaining any sort order the user may have applied, set the Target.PDF's Report Definition File attribute to CurrentReport.
     
  4. If the report to export is not the current report, specify that report by setting the Target.PDF's Report Definition File attribute appropriately.
  5. If you wish to export only a specific data table, provide its ID in the Export Data Table ID attribute. This prevents anything else in the report, such as headers or footers, images, etc., from being exported.

What happens: the report is exported to a temporary PDF file which is created in your project folder's rdDownload folder on the web server. The temp file is then opened automatically in your browser. Temporary files are cleaned up automatically over time.

If you wish to export to PDF in "landscape" page orientation, you should use the Printable Paging element, as described in Create Printable Reports.

Exporting a Report Automatically

The following example, for Logi Info only, shows how to create a process task that exports data automatically:
 

  1. In your Process definition, add a Procedure.ExportPDF element beneath your Task element.
  2. In the element's Filename attribute, specify the output path and filename, on the web server, for the exported report. The filename should include the ".pdf" file extension. For example, this value uses a token to export the report to a folder called myExports within your project folder: @Function.AppPhysicalPath~\myExports\myfile.pdf
     
     


  1. Add the required Target.PDF element.
  2. In the element's Report Definition File attribute, you must specify the report to be exported (a blank value is not allowed). The CurrentReport option in the suggested values is not valid in this case, which means that the report will be exported but will not reflect any sort order that the user may have applied before clicking the export link.
  1. If you wish to export only a specific data table, provide its ID in the Export Data Table ID attribute. This prevents anything else in the report, such as headers or footers, images, etc., from being exported.

What Happens: When your task runs, the specified report will be exported to a temporary file in your project folder's rdDownload folder on the web server; the temp file is then copied to your output file. The file is not opened in your browser automatically.

Adding Exported Headers and Footers

Reports exported to PDF are paginated and you may want to have a report header and/or footer appear on each exported page. This can be done, without affecting the normal appearance of the HTML report output in a browser, using the Printable Paging element.
 


As shown above, the Printable Paging element is added beneath the report's top-level Report element. It has its own Page Header and Page Footer child elements which are containers for Label and other elements. In the example above, the captions of the footer labels could use the @Date.Today~, @Function.PageCount~, and @Function.PageNumber~ tokens.

When the report is run and viewed in a browser, the header and footer under the Printable Paging element will not be visible. When the report is exported to PDF, the header and footer will be visible on each exported page.

Suppose you want to have different-looking headers or footers on an exported page depending on the page number? For example, you might want Page 1 to have a fancy header and the following pages, a less-fancy header. Developers can do this using Division elements:
 

As shown in the example above, place Division elements beneath the Page Header element and then set their Condition attributes to evaluate the PageNumber token. The Condition attribute value for the first division is shown, and the value for the second division might be @Function.PageNumber~ > 1. Each division, and its child elements, will appear in the export then, depending on the page number. The same functionality is available in exported report footers.

 Adding a header or footer beneath the Printable Paging element will increase rendering time. Their inclusion causes the export engine to have to make multiple passes through the entire report while generating the PDF, and the performance hit incurred may be acceptable for short reports but not for longer reports. The alternative is to use regular Report Header and Report Footer elements, which will appear in the report in a browser, rather than the Printable Paging element's Page Header and Page Footer child elements.

Forcing Page Breaks in Exports

When a report is paginated during an export, it may be useful to be able to force a page break, for example, to ensure that sections of the report start on new pages. This can be done using the Printer Page Break element.
 

You can add one or more Printer PageBreak elements beneath the Body element to break the exported pages where desired. In the example above, these elements ensure that the "dtProducts" table and the "dtOrders" table start on new pages. When the report is viewed in the browser, however, like the Printable Paging element, the Printer Page Break element has no effect.
 

Forcing a Data Table Row Break

When working with data tables with multi-line rows, developers may want to ensure that rows break cleanly across pages of their PDF exports. In other words, they want to prevent different lines of the same data table row from appearing on different PDF pages. This can be accomplished through CSS, using code like:

.noPageBreakCell { page-break-inside: avoid; }

Assigning the above class to a Data Table Column element will create the desired effect.
 

Printer Page Break Attribute Restriction

The Gecko-based rendering engine used in PDF exports does not fully support printer page breaks within HTML tables. This means that enabling the Printer Page Break attribute for the Group Header Row, Group Summary Row, and More Info Row Column elements, which use tables internally, will produce unpredictable results in PDF exports.

As a "last resort" alternative you can make these page breaks work by switching to the older IE rendering engine; this is done by creating the constant rdPdfRenderingType=MSHTML in your _Settings definition. Unfortunately, this will also eliminate some of the benefits of the Gecko engine, such as the ability to export Chart Canvas Charts as SVG objects, and so it's not generally recommended. 

Special Considerations for Java Apps

Developers creating Logi apps that use the Java libraries and include less commonly-used fonts or special character sets may need to take steps to ensure that those character sets or fonts are also used in their PDF exports. This is done by adding the Globalization element in the _Settings definition, and setting its Java Font Folder attribute:
 

The value of this attribute identifies the folder where TrueType font files, for use with PDF exports, are located. These are required when PDF exports use fonts that contain characters that are not in the ISO 8859_1 character set, such as Arabic, Cyrillic, and Korean language characters. Depending on your Java environment, you may even need to point the Logi application to the location of your regular fonts in order to ensure that they'll be used.

A typical value for a Windows installation might be something like C:\Windows\Fonts. For a Linux installation, the value might be something like /usr/local/share/fonts/ttfonts. This attribute is only functional when creating a Java application.

 CSS classes are cached for Java application exports to PDF. If you need to stop this caching, add this case-sensitive constant in your _Settings definition: rdJavaPdfClearCache = True.

Hiding Elements When Exporting

When exporting to PDF, developers commonly want to hide some of the elements in the report page, like the Export button or link. This can be done very easily using Show Modes.
 

Consider the example shown above. The definition, on the left, includes a button that can be clicked to export the report to a PDF. However, when it's exported, shown on the right, the Export to PDF button appears in the PDF itself. We don't want that button to appear in the PDF.
 

The first step in "hiding" the button in the export is to place the button beneath a Division element. This element supports Show Modes, which the button, by itself, does not. Set the Division element's Show Modes attribute value to an arbitrary string, such as "NoExport", as shown above.
 

Then set the Target.PDF element's Report Show Modes attribute value to an arbitrary string that does not match the string used in the previous step, as shown above.
 

When the report is run and exported, as shown above, the PDF no longer includes the Export to PDF button. Any element whose Show Modes attribute value does not match the Target.PDF element's Report Show Modes attribute will not appear in the export.

Exporting More Info Rows

If your report contains a data table and you're using the More Info Row element to show/hide additional detail data within the table, you may want the detail rows (when visible) to be exported along with the main table data.

To enable this, as shown above, set your Target.PDF element's Keep Show Elements attribute to True.

Keep Show Elements works with Action.Show Elements (used to show/hide the More Info Row) so that items that have been shown or hidden by the user remain that way when the report is re-displayed or exported.

In addition, you may want to set the Keep Table Headers with More Info Row attribute to True if you want to ensure that all the tables in the report have repeatable table headers, even if they have a More Info Row containing other reports with tables.

It is possible to "nest" More Info Row elements, so that you have one More Info Row element as a child of a table that's a child of another More Info Row. However, be aware that the lowest More Info Row contents may not export correctly, or at all, so we don't recommend this design arrangement if exporting of expanded rows is desired.

Cascading Style Sheet Support

When a PDF export is being generated, the export engine processes any style sheet information along with the report data. The style sheet assigned to the report is used; you do not need to do anything additional to specify the style sheet. Because your browser is used to render the PDF, your browser's style sheet limitations or quirks apply to the exported PDF.

If desired, you can use two different style sheets in your report definition, one for the report and one for the PDF export:

  1. Select the root element of your report definition and set its Default Show Modes attribute value to an arbitrary string, such as "Normal".
  2. Add two Style Sheet elements to your report definition.
  3. Assign one Style Sheet element's Show Modes attribute a value that matches the string used in Step 1, "Normal". This style sheet will be used for the regular HTML report.
  4. Assign the other Style Sheet element's Show Modes attribute a value that matches the Target.PDF element's Report Show Modes attribute value (both should be an arbitrary string that does not match the string from Step 1, such as "Export".

Now when the report runs in a browser, the first style sheet will be applied; when it's exported to PDF, the second style sheet will be applied.

What if you want to combine the effects from this section and the previous section, i.e. hide some elements and use different spreadsheets? Just remember that the Show Modes attribute can accept several values, separated by a comma. To combine the examples from these two sections, ensure that the root element's Default Show Modes attribute includes both Show Modes values: "Normal,NoExport" (do not enter the double quotes).

Our PDF export engine has full support for all symbols in the Unicode character set. Developers can also apply specific fonts in a CSS class. If you're having difficulty rendering to PDF in your native language, ensure that the fonts specified in your CSS classes support the language.

We do not recommend that you use absolute positioning of elements through CSS if you plan to export a report to PDF. The export engine will attempt to "fit" your report to its page size and elements so positioned may wind up in unexpected locations.

Debugging Exports

Logi Studio includes a feature that allows developers to debug their exports. When the debugger has been set to Debugger Links and the report is run, and then exported, a debug link will be included at the bottom of the exported report:
 

This mechanism allows you to review the export process in more detail and can help to diagnose any problems that may arise.

Export Considerations

The following apply when exporting to PDF:

  • The Login Info PDF export engine will not export data table captions in Java applications. Developers are advised to use a separate Label element, or a data table Header Row child element, set to Top position, instead of using the table's Caption attribute, to provide an exportable caption in Java apps.
  • Chart color transparency is not available in exports to PDF. Non-animated charts displayed in Logi HTML reports are rendered as .png images and support transparency, however, when exported to PDF, these charts are rendered as .jpg images, which do not support transparency.
     
  • It's not possible to support links that may use relative URLs in an exported document, as the document can be saved and relocated. As a result, links in general are not supported in exported PDFs. They will work when Studio's Debugging Links feature is turned on during development, but when that link is removed for a production release, they will no longer work.
     
  • Data table column headers will be repeated on each page of PDF export only if there are no sub-elements within the report. This includes Sub Report, Sub Data Table, and More Info Row.
     
  • Data table column headers will be repeated on each page of a PDF export only if there are one or more characters in the column header text. If you want a column that has no header text to be repeated, you must include a single space character in its Header attribute value.
  • When exporting to a PDF from a web browser on different computers, the page dimensions may be affected by different screen resolutions. In addition, when using different browsers, exported reports may appear differently, as different browsers handle styling differently. Developers may care to use a Printable Paging element in their report definitions, to set absolute page dimensions. For more information, see Create Printable Reports
     
  • Exporting reports that include characters that are read right-to-left, such as Arabic, from a Windows server requires that special OS files be installed, as follows: Go to Regional and Language Options in Control Panel; select "Install files for complex script and right-to-left languages (including Thai)" under the Languages tab; when prompted, insert the Windows OS CD and run the install; restart the computer once the files are completely copied and the restart prompt comes up.
     

Export Errors

"Error Exporting to PDF - HTML render is blank."

  • Insufficient Process Identity Permissions - Ensure that the account, application pool, or identity used by your web server to run your Logi app has full file access permissions to the Logi app directory or any folder outside it that you may have designated as an exported file destination.
  • Insufficient Temp File Space - Ensure that you have enough space for temporary Logi application files, by shortening your temp file cleanup interval (60 minutes by default). For more information, see our document Temporary Cache File Management.
  • Insufficient Permissions for Windows/Temp - Ensure that the account, application pool, or identity used by your web server to run your Logi app has Read/ Write file access permissions to C:\Windows\Temp (if using IIS) and the ability to create folders.
  • Web Server Unable to Resolve URLs to Itself - This means that when testing using the IP address of another machine, your code will work but when you try and render a web page on the local server using a URL, you may get errors. This is a typically a DNS problem.
     

"The type initializer for WebSupergoo.ABCpdf7.Internal.NDoc threw an exception"

  • This is usually the result of installing the Logi Server Engine on the wrong type of system. It will occur, for example, if you install the 64-bit version of the Logi engine on a 32-bit system, or vice versa, if you install the 32-bit engine on a 64-bit system. Logi products are available in 32-bit and 64-bit versions; please ensure that you have the correct version installed, based on the system's environment and the IIS configuration for running the Logi application (under Windows 7+, you can configure specific applications to run in 32- or 64-bit mode under a 64-bit version of the OS).
     

"Chart Canvas chart exported to PDF as a solid, colored block"

  • When creating Chart Canvas charts that will be exported to PDF, the Chart Canvas element must have Height and Width attribute values set. In addition, in the web server settings, the application's rdDownload folder should have Anonymous Authentication enabled, and any other authentication disabled.
     Height and Width values are no longer required.

"Invalid character at..." or similar parsing error

  • Exports may fail if XHTML reserved characters are included in the data. The application fails and produces an error message that looks like a parsing error. The most common culprit is the unencoded "&" character. Replacing the "&" character with "&amp;" is often an easy solution.