cfdocument Child Tags

<cfdocument> Child Tags

<cfdocument> can be used without any child tags, as seen previously. But two child tags provide greater control over generated output:

• <cfdocumentitem> is used to define headers, footers, and page breaks.

• <cfdocumentsection> is used to define sections within a generated document.

Controlling Output Using The <cfdocumentitem> Tag

<cfdocumentitem> is used within a <cfdocument> tag set to embed additional items. <cfdocumentitem> requires that a type be specified. Table 18.2 lists the supported types.

Table 18.2. <cfdocumentitem> Types

TYPE	DESCRIPTION
footer	Page footer.
header	Page header.
pagebreak	Embed a page break, this type takes no body.

NOTE

Page breaks are calculated automatically by ColdFusion. Use <cfdocumentitem type=" pagebreak"> to embed manual breaks.

The following examples uses all three types to generate a printable employee directory with a cover page, and page headers and footers:

 <!--- Get data ---> <cfquery datasource="myDsn"          name="users"> SELECT NameLast, NameFirst, Phone, EMail FROM users ORDER BY NameLast, NameFirst </cfquery> <!--- Generate document ---> <cfdocument format="pdf"> <!--- Header ---> <cfdocumentitem type="header"> Employee Directory </cfdocumentitem> <!--- Footer ---> <cfdocumentitem type="footer"> <p align="center"> <cfoutput> #CFDOCUMENT.currentpagenumber# of #CFDOCUMENT.totalpagecount# Printed #DateFormat(Now())# </cfoutput> </p> </cfdocumentitem> <!--- Title ---> <div align="center"> <h2>Employee Directory</h2> </div> <!--- Page break ---> <cfdocumentitem type="pagebreak" /> <!--- Details ---> <table>  <tr>   <th>Name</th>   <th>Phone</th>   <th>E-Mail</th>  </tr>  <cfoutput query="users">   <tr>    <td>#NameLast#, #NameFirst#</td>    <td>#Phone#</td>    <td>#EMail#</td>   </tr>  </cfoutput> </table> </cfdocument> 

The <cfdocument> content contains the following code:

 <!--- Header ---> <cfdocumentitem type="header"> Employee Directory </cfdocumentitem> 

This code defines a page header, text that will be placed at the top of each page. A footer is also defined as follows:

 <!--- Footer ---> <cfdocumentitem type="footer"> <p align="center"> <cfoutput> #CFDOCUMENT.currentpagenumber# of #CFDOCUMENT.totalpagecount# Printed #DateFormat(Now())# </cfoutput> </p> </cfdocumentitem> 

This page footer contains two special variables. Within a <cfdocument> tag a special scope exists named CFDOCUMENT. It contains two variables, as listed in Table 18.3. These variables may be used in headers and footers, as seen in this example.

Table 18.3. CFDOCUMENT Scope Variables

TYPE	DESCRIPTION
currentpagenumber	Current page number.
totalpagecount	Total number of generated pages.

In addition, the code embeds a manual page break using this code:

 <!--- Page break ---> <cfdocumentitem type="pagebreak" /> 

<cfdocumentitem> must always have an end tag, even when no body is used. The trailing / is a shortcut that you can use. In other words, the above tag is functionally identical to:

 <!--- Page break ---> <cfdocumentitem type="pagebreak"></cfdocumentitem> 

Defining Sections With <cfdocumentsection>

As you have seen, you have a lot of control over generated pages using the <cfdocument> and <cfdocumentitem> tags. But sometimes you may want different options in different parts of the same document. For example, you may want a title page to have different margins that other pages. Or you may want different headers and footers in different parts of the document.

To do this you use <cfdocumentsection> tags. A <cfdocument> tag pair may contain one or more sections, each defined using <cfdocumentsection> tags. Within each section you may specify alternate margins, and may use <cfdocumentitem> tags to specify headers and footers for each section.

NOTE

When using <cfdocumentsection>, all content must be in sections. Any content outside of sections is ignored by ColdFusion.