ColdFusion 9: CFPDF - Adding Headers and Footers (and a Few Quirks) - Part 2

In Part 1 I posted some examples of text and image headers. CF9 also introduced some new constants for working with page numbers and labels.


Page Numbers
Though "Page X of Y" headers/footers are not exactly earth-shattering, it is a little easier to add them to existing pdf's with the new constants _PAGENUMBER and _LASTPAGENUMBER.

<!--- Sample Document --->
<cfdocument format="pdf" name="pdfInput">
    <cfloop from="1" to="10" index="x">
        The Blank Page 
        <cfif x lt 10>
            <cfdocumentitem type="pagebreak" />
        </cfif>
    </cfloop>
</cfdocument>

<!--- Add Page X of Y Footers --->
<cfpdf action="addFooter"
   source="pdfInput"
   name="pdfOutput"
   text="Page _PAGENUMBER of _LASTPAGENUMBER" 
/>

<!--- Display results --->
<cfcontent type="application/pdf" variable="#ToBinary(pdfOutput)#" />

NumberFormat
With the help of the neat numberFormat attribute, you can change boring decimal page numbers into Roman numeral format (both upper and lower case). The supported values are: LOWERCASEROMAN, NUMERIC, UPPERCASEROMAN.

<!--- Sample Document --->
<cfdocument format="pdf" name="pdfInput">
    <cfloop from="1" to="10" index="x">
        The Blank Page 
        <cfif x lt 10>
            <cfdocumentitem type="pagebreak" />
        </cfif>
    </cfloop>
</cfdocument>

<!--- Add Page X of Y in Roman Numerals --->
<cfpdf action="addFooter"
    source="pdfInput"
    name="pdfOutput"
    numberFormat="UpperCaseRoman"
    text="Page _PAGENUMBER of _LASTPAGENUMBER" 
/>

<!--- Display results --->
<cfcontent type="application/pdf" variable="#ToBinary(pdfOutput)#" />

Page Labels
If your pdf contains custom Page Labels, you can also add that text to headers/footers using the _PAGELABEL and/or _LASTPAGELABEL constants. Obviously if your pdf doesn't have custom page labels, you will probably just see the default decimal page numbers instead. But I am pretty sure you can add custom labels with ddx (or alternately with iText).

<!--- Add Page Label to Header --->
<cfpdf action="addHeader"
    source="testDocumentWithLabels.pdf"
    name="pdfOutput"
    text="<b>Label For Page (_PAGENUMBER):</b> _PAGELABEL" 
/>

<!--- Display results --->
<cfcontent type="application/pdf" variable="#ToBinary(pdfOutput)#" />

Things You Cannot Do ...
Perhaps this is an obvious point, but these settings have no affect on information already embedded within the pdf. In other words, you cannot change existing pdfs with page numbers already embedded in the file. However, if you use cfpdf to generate the headers/footers you can certainly remove them and add new ones.

Printing Headers/Footers
For cases when you do not always want headers/footers to be printed, you can use the showOnPrint option to control visibility when printing. For example, you could tweak some of the previous snippets to display both the graphic and text headers on screen, but use showOnPrint="false" to make only the text header "printable". Obviously you can also use the pages attribute to apply that behavior only to select pages.

<!--- 
    Display the graphics header only on screen
--->
<cfpdf action="addHeader" 
    source="inputFile.pdf" 
    destination="pdfWithImageHeader.pdf" 
    topMargin="2.6"
    leftMargin="0"
    rightMargin="0"
    align="center"
    image="http://www.google.com/logos/olympics10-prsskating-hp.png"
    overwrite="true"
    showonprint = "false"
/>

....

<!--- 
    Display the text header both on screen and when printed
--->
<cfpdf action="addHeader" 
    source="pdfWithImageHeader.pdf" 
    name="pdfOutput" 
    topMargin="1.7"
    leftMargin="0"
    rightMargin="0"
    align="center"
    text="#headerText#"
    showonprint = "true"
/>

As you can see, it is not extremely complex. But hopefully these examples make a good addendum to the limited documentation on the addHeader / addFooters features.