With the introduction of the XRPdfContent control in our v20.1 release cycle, we gave users the ability to include/merge external PDF file content within a report. If you have yet to use the XRPdfContent control, please refer to the following blog post for more information: Reporting - Merge PDF Documents into Your Report (v20.1).
In our most recent update (v21.2), we extended the capabilities of the XRPdfContent control and now allow you to print report elements over merged PDF content. This simply means that you can easily display report headers/footers, pages numbers, or logos atop PDF content. We also allow you to resize merged PDF file content to mirror report page size (to help correct page dimension variances).
XRPdfContent Control - Embedded Mode
DevExpress Reports v21.2 ships with a new GenerateOwnPages property for the XRPdfContent control. When this property is set to true (default), the XRPdfContent control behaves in the manner outlined in the blog post above. When you disable this property, control content is embedded into the report instead.
When used in this manner, XRPdfContent functions like our XRSubreport control (with GenerateOwnPages property disabled) or our XRPictureBox control (displays an image). You can modify PDF page size and place other controls next to/atop PDF content.
Use Cases
Place individual Report Controls atop PDF File Content
Embedded mode will be useful if you need to print specific content (pictures, bar codes, page numbers, or report watermark) on top of a PDF file.
In the following example, we will add a PDF page to a report and place an image on top of the PDF file.
For purposes of this illustration, we will create the report within Visual Studio (If you are new to DevExpress Reports, please refer to the following helping topic to learn more about our Visual Studio Report Designer: Create a Report in Visual Studio).
Step 1: Drop the XRPdfContent control onto the Detail report band:
Step 2: Expand the control’s smart tag and:
- Assign a PDF file path to the Source property.
- Disable the Generate Own Pages property.
In this example, we will use the following PDF document: Specification.pdf.
Step 3: Modify control size so that PDF content fits the entire Detail band:
In the following steps, we’ll place the following image on top of our PDF file.
When controls overlap, the Report Designer highlights them in red, and the Report Design Analyzer displays a warning. If you do not want the controls to be highlighted, simply disable the DesignerOptions.ShowExportWarnings property.
Step 4: Drop the XRPictureBox control onto the Detail band and assign the image to the control’s Image Source property.
Step 5: Set the XRPdfContent.PageRange property to 1 to include only the first page of the PDF file and Preview the report.
Though this example might seem a bit artificial, it demonstrates the possibilities available to you. Simply said, you can embed PDF file content to a report and modify this content within the Report Designer. If you are interested in a more advanced example, please refer to the following tutorial: Create a Report with Embedded PDF Content.
Scale a PDF File (and its Page Size) to Fit Inside a Report
If a PDF file’s paper kind (or page size) differs from a report’s page dimensions, output may look like the following once you add the PDF file to your report.
A mismatch between PDF page size and report page size dimensions can produce unexpected consequences. For instance, if you wish to print a report on A4 paper, but your PDF file is in “letter” format, actual print output may be affected. In this section, we will explain how to embed/merge a PDF file into a report and maintain page dimension consistency for the report itself. We will
- Create a subreport and embed PDF content within it.
- Modify PDF content size.
- Add the subreport to the main report.
For this example, we will use a PDF file generated from our Profit and Loss demo.
Steps 1, 2, and 3: Create a blank report and repeat the steps described above:
- Drop the XRPdfContent control onto the Detail band.
- Expand the control’s smart tag. Assign a PDF file path to the Source property and disable the Generate Own Pages property.
- Modify control size so that PDF content fits the entire Detail band:
Step 4: Remove report margins (set margin size to 0). We must set margin to zero because we want to include the file in another report as a subreport. As such, we don’t want subreport margins to be duplicated within the main report’s margins.
Step 5: Create a second report and add the report with PDF content as a subreport report:
Step 6: Enable the subreport’s GenerateOwnPages property and activate the report’s Preview.
Other Use Cases
Embedded mode might also be useful in the following instances:
- Embed PDF file content into a report with common headers/footers (headers/footers will be printed on PDF file pages as well).
- Design a pre-printed form and use a PDF file as a watermark.
Refer to the following help topic for more information: Embed PDF File Content into a Report - Use Cases.
Your Feedback Matters
As always, we welcome your feedback. Does this new feature (Embedded mode) address your business needs? Have additional requirements in this regard? Feel free to share your feedback and thoughts below.