Introduction
In web development, generating dynamic PDF documents can be a common requirement, especially for creating reports, invoices, or printable pages directly from a web application. Adobe ColdFusion provides a powerful way to generate PDFs with the <cfdocument> tag, which makes it easy to convert HTML content into a PDF format. One of the key features often required in PDF creation is the ability to control page breaks, ensuring that content is properly structured and separated into different pages. This tutorial demonstrates how to implement page breaks using ColdFusion’s <cfdocumentitem> tag within a PDF document.
In this example, we retrieve data from a database and display it in a PDF document with a page break separating different sections of the content. Understanding how to use the <cfdocumentitem> tag for page breaks is crucial for developers looking to control the layout of their ColdFusion-generated PDF documents.
Database Query and Data Retrieval
The first step in the example involves retrieving data from a database using ColdFusion’s <cfquery> tag. In this case, we query a database table that contains information about parks, specifically their names and associated cities. The result of the query is stored in the qParks variable, which will be used later to display the data in the PDF document.
This step is typical in dynamic PDF generation, where you often pull data from a database to present in a structured format like a table. By limiting the number of rows to 10 (maxrows="10"), we ensure that the PDF only contains a manageable amount of data for demonstration purposes.
PDF Generation Using <cfdocument>
The core of this tutorial revolves around the <cfdocument> tag, which handles the generation of the PDF. The format is set to "pdf", instructing ColdFusion to generate the output as a PDF file. Everything inside the <cfdocument> tag will be included in the PDF, making it an essential container for all the content you want to appear in the document.
The use of the <cfoutput> tag allows dynamic ColdFusion expressions and variables to be processed within the PDF content. This combination is commonly used to output both static text and dynamic data, as well as to implement advanced PDF features such as headers, footers, and page breaks.
Adding Headers and Footers
The <cfdocumentitem> tag is used within the PDF to define special sections, such as headers and footers. In this example, the header contains the text “This is Page Header” and dynamically includes the total page count using the #cfdocument.totalpagecount# variable. This feature is particularly useful when creating multi-page documents where you want to include page numbers or additional information consistently at the top or bottom of each page.
Headers are defined using type="header" within the <cfdocumentitem> tag, making them appear at the top of each page. This is a handy way to ensure that information like page numbers or document titles appear uniformly across all pages.
Displaying Data in a Table
The main content of the PDF includes a table that lists park names and their respective cities. The <cftable> tag is used here to create a simple table, with the columns dynamically populated from the qParks query. This is a powerful feature of ColdFusion, allowing you to directly bind query results to a table and easily generate PDF tables from database queries.
Each column in the table is defined using the <cfcol> tag, where header defines the column header, and text specifies the dynamic data to display. In this example, the ParkName and City fields from the query are inserted into the table columns.
Implementing Page Breaks
The key feature of this tutorial is the use of the <cfdocumentitem> tag to add a page break. By specifying type="pagebreak", you instruct ColdFusion to insert a page break at that point in the PDF document. This ensures that all content before the page break is placed on one page, and any content after the page break starts on a new page.
In the example, a table of parks is displayed on the first page, and after the page break, a new section is introduced with the heading “This is another page.” This demonstrates how you can easily control where content should be split across multiple pages in a PDF document, which is useful for creating structured and organized reports.
Styling and Layout
The example includes basic inline styling for the headings, with color and font-style applied to make the PDF visually appealing. ColdFusion allows you to use HTML and CSS within the <cfdocument> tag to style your PDF content just as you would for a regular web page. This flexibility enables developers to create visually rich PDF documents while maintaining control over the layout and formatting.
In this case, the heading “cfdocument example: using page break” is styled with a crimson color and italic font, while the second page’s heading “This is another page” uses a dim gray color. These styles help distinguish different sections of the document visually.
Conclusion
Generating PDF documents in ColdFusion is a straightforward and efficient process thanks to the <cfdocument> and <cfdocumentitem> tags. This tutorial demonstrated how to add page breaks, headers, and structured tables to a PDF, all while retrieving dynamic data from a database. By utilizing the type="pagebreak" functionality, developers can ensure that content is neatly separated across multiple pages in a professional-looking document.
Understanding these techniques allows ColdFusion developers to create well-organized, multi-page PDFs suitable for a variety of use cases, from business reports to invoices. With the flexibility of ColdFusion’s PDF generation capabilities, developers can easily meet the demands of modern web applications that require printable and shareable documents.
cfdocumentPagebreak.cfm
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>cfdocument tag: how to use pagebreak (page break) as cfdocumentitem type in printable document</title>
</head>
<body>
<cfquery name="qParks" datasource="cfdocexamples" maxrows="10">
SELECT ParkName, City FROM PARKS
</cfquery>
<cfdocument format="pdf">
<cfoutput>
<cfdocumentitem type="header">
This isPage Header <br />
Total Page Count: #cfdocument.totalpagecount#
</cfdocumentitem>
<cfdocumentsection>
<h3 style="color:Crimson; font-style:italic">
cfdocument example: using page break
</h3>
<cftable query="qParks" colheaders="yes" htmltable="no" border="no">
<cfcol header="Park Name" text="#ParkName#">
<cfcol header="City" text="#City#">
</cftable>
<cfdocumentitem type="pagebreak">
</cfdocumentitem>
<h3 style="color:DimGray; font-style:italic">
This is another page
</h3>
</cfdocumentsection>
</cfoutput>
</cfdocument>
</body>
</html>
