New 'EvalAtPrint' attribute in CFDocumentItem

A new evalAtPrint attribute has been added to cfdocumentitem tag in ColdFusion 801 which is applicable when the item type is header or footer. The default value of this attribute is false.

Note: The cfdocumentitem behavior with the default evalAtPrint value is identical to the behavior in ColdFusion MX 7, but differs from the behavior of the ColdFusion 8 release.

When the evalAtPrint attribute value is false, the default value, ColdFusion evaluates the cfdocumentitem tag body at the same time when it is processing the cfdocument tag. This is the behavior identical to CFMX7. In this case you can use CFDocument variables (TotalPageCount, CurrentPageNumber, TotalSectionpageCount and CurrentSectionpageNumber) only inside cfoutput and not in any expression because the page numbers are not known unless the cfdocument body content is evaluated and layed out.

In order to use CFDocument variables in expression inside CFDocumentItem tagbody, you should set evalAtPrint to true as shown in the following example.

<cfdocument format="pdf">
   <cfdocumentitem type="header" evalAtPrint="true">
       <cfif (CFDocument.currentPageNumber % 2 eq 0)>
           <cfoutput> Page is even</cfoutput>
       <cfelse>
           <cfoutput> Page is odd</cfoutput>
       </cfif>
   </cfdocumentitem >
   Document body…
</cfdocument>

In this case, ColdFusion evaluates the cfdocumentitem tag body when it prints the header or footer, not when it evaluates the cfdocument tag body. This ensures that the cfdocument tag body is already evaluated and layed out and page number information is available when cfdocumentitem tag is being evaluated

A side effect of this is, if a variable is used inside both cfdocument and cfdocumentitem, cfdocumentitem tag will only see the final value of that variable. In the following example, cfdocumentitem will always get 11 as value of ‘I’ and hence all the headers will print ‘Chapter 11’.

<cfdocument format="pdf" >
<cfloop from=1 to=10 index="i">
   <cfdocumentsection>
   <cfdocumentitem type="header" >
       <cfoutput>Chapter #i#</cfoutput>
   </cfdocumentitem >
DocumentSection body
   </cfdocumentsection>
</cfloop>
</cfdocument>

To handle this, you can now pass the variable into the cfdocumentitem tag as a custom attribute, as shown in the following example:

<cfdocument format="pdf" >
   <cfloop from=1 to=10 index="i">
       <cfdocumentsection>
           <cfdocumentitem type="header" evalAtPrint="true" no = #i#>
               <cfoutput>Chapter #attributes.no#</cfoutput> 
               <cfif (CFDocument.currentPageNumber % 2 eq 0)>
                   <cfoutput> Page is even</cfoutput>
               <cfelse>
                   <cfoutput> Page is odd</cfoutput>
               </cfif>
           </cfdocumentitem >
           Document Body.
       </cfdocumentsection>
   </cfloop>
</cfdocument>