Most of us at one time or another have experienced the poor result of printing Web content from a browser. The page printout is ugly because the printer breaks the Web content into pages with borders and edges. Trying to fix the HTML code with style sheets and other layout tricks still yields an unsatisfactory outcome. You, the developer, and your end users desperately need a solution for printing rich document formats.

Likewise, if you are on the road without Internet access and want to pass your work to a client who is outside your company firewall, you need a way to distribute documents easily.

You've already invested an enormous amount of time and resources setting up and publishing Web pages and articles so they look just the way you want. You don't want to rework them just to generate a rich document - you need an easy conversion tool.

Introducing the cfdocument tag. This new ColdFusion MX 7 feature takes your current HTML/CFML pages and converts them into Macromedia FlashPaper or Adobe PDF formats in seconds. Best of all, using this tag requires no learning curve. In this article, we explain how the ColdFusion team created this new functionality and how you can use it to create printable Web documents.

Requirements
Software: To complete this tutorial you will need to install the following software and files: ColdFusion MX 7 (www.macromedia.com/cfusion/tdrc/index.cfm?product= coldfusion&promoid=devcenter_tutorial_product_090903).

Prerequisite knowledge: Familiarity with ColdFusion tag syntax

Your Need for the cfdocument Tag
When it came time to brainstorm for features in ColdFusion MX 7, many ColdFusion team members wondered what we could give developers, so that you would get even more use out of ColdFusion. One theme we heard consistently was how hard it is to create portable rich document from Web pages. We thought, wouldn't it be nice for developers to be able to add a button to any Web page, which would convert rich HTML content into easily printable PDF or FlashPaper documents?

Your request resonated with the team. We thought about a ColdFusion tag, one that consumes HTML content and converts it to rich documents. Last year, during the MAX 2003 conference, we demonstrated this idea in the sneak-peek session. We heard a resounding approval from you when we told you the possibility of providing this functionality in the next version of ColdFusion - it was that approval that helped us decide to make it part of ColdFusion 7.

The development team faced many challenges during the design and implementation phase. Foremost, HTML is a very lenient language. HTML writers can get away with broken syntax on modern browsers. This factor created an enormous challenge for parsing data and converting it to PDF/FlashPaper-specific "language." During our research, we found that there are some products out there already trying to address this issue. However, most of them either require an extra installation procedure, such as a C++/native solution that is not platform-friendly, or require an expensive add-on OEM with ColdFusion.

One technology that came close to adoption was Apache FOP, which converts XML to PDF by relying on XSL (style sheets) masking. The main advantage of FOP is that it deploys on top of Java, the technology that ColdFusion MX standardized upon. However, the ColdFusion team found that the Apache FOP engine only consumes parsed XML content. It applies the XSL style sheet for layout information and then translates it to native PDF content. Adopting FOP would have required ColdFusion developers to edit their HTML into XHTML, which would have increased the difficulty of their using this feature and the learning curve for developers. This was out of the question. We researched the idea of autogenerating XHTML from HTML but that was extremely error-prone and raised other issues.

Therefore, we settled on our own solution - one that allowed us to consume regular HTML 4.01 and CSS 1 and 2 without requiring any modification by the developer. This greatly enhanced the developer experience, increased the value of this feature, and - at the same time - met all our original goals.

Easy-to-Use Solution for Developers
As ColdFusion engineers, we like to think that our job is to make ColdFusion developers' lives easier. This was the exact mindset we applied while working on this task. We thought, what can we create so that all that developers need to do is wrap their HTML with a ColdFusion tag, so that conversion occurs once the browser invokes the Web request? Thus, the cfdocument tag syntax was born. Here's an overview of the syntax:

<cfdocument format="flashpaper/PDF">
<!-insert your HTML, CFML, and cfdocumentitem tags->
</cfdocument>

This is it! No messy XML, Java classpath configuration, or registering native libraries. Best of all, it is a part of the ColdFusion engine. Once you install ColdFusion, this feature is available to you. You don't need to change anything in your existing HTML/CFML content.

In addition to the simplicity of the tag's functionality, we also added attributes to help you manipulate document layouts (see Table 1). The only tag requirement is the format attribute, which specifies to the ColdFusion engine which type of file to generate (PDF or FlashPaper); the others are optional attributes.

Besides providing basic printing functionality, the cfdocument tag also had to be robust and conform to standards. Our first priority was to support HTML 4.01. This standard was required before anything else because most of our users use the HTML 4.01 standard. Second, CSS versions 1 and 2 were required because style sheets are an important part of HTML formatting, making it a feature requirement.

The remaining tasks were to provide image, HTML links, security, and accessibility support so that generated rich documents act similarly to browser-rendered content. Furthermore, to support fonts that a user specifies within HTML content, the team built the cfdocument tag to work with the ColdFusion font manager to locate necessary fonts on the system. We took some of the PDF-specific functionality and made bidirectional language (such as Arabic, Hebrew) support possible for PDF-formatted documents.

Using the cfdocument Tag
This is the most exciting part of introducing this feature - showing you how to use it!

Sample 1: Using the cfdocument with cfhttp tag
This is what makes the cfdocument tag powerful. There is no need to edit your current HTML. You just redirect the content of the HTTP request through the cfdocument tag (see Figure 1):

<cfhttp url="http://www.w3.org/TR/REC-html32"
method="get" resolveURL="true">
<cfdocument format="flashpaper">
   <cfoutput>#cfhttp.filecontent#</cfoutput>
</cfdocument>

Sample 2: Using the cfdocument tag with existing third-party report output
If you use a third-party reporting engine and plan to output the results in HTML, you can use the cfdocument tag to help create a portable document exactly as it appears. This saves much time and effort on your part because you don't need to recreate reports just for the purpose of printing to rich document formats. You simply wrap your query/report result with the tag and it gives you the desired printing result (see Figure 2).

Sample 3: Creating portable documents for easier sharing
Besides printing in a visually appealing format, you can use the cfdocument tag to create documents that are portable and that you can combine with the cfmail tag to send output to other users:

<cfhttp url="http://www.w3.org/TR/REC-
 html32" method="get" resolveURL="true">
<cfdocument format="flashpaper"
 filename="c:\temp\w3spec.swf">
   <cfoutput>#cfhttp.filecontent#</cfoutput>
</cfdocument>
<cfmail to = "recipient"
  from = "sender"
  subject = "msg_subject"
MIMEAttach = "c:\temp\w3spec.swf">

Hi John, here is the spec you were looking for.

Regards,

</cfmail>

Sample 4: Bidirectional text support
If you write text from right to left, you can now use the cfdocument tag to print (only available in PDF).

Code Examples for the cfdocument Tag
There are a few additional supporting subset tags for the cfdocument tag: cfdocumentitem and cfdocumentsection. These two tags provide additional format control.

The cfdocumentitem tag has three different attributes: header, footer, and pagebreak. Their attribute names indicate their functionality. The header and footer attribute values support document headers and footers, while the pagebreak attribute value specifies an inserted page break in the document:

<cfdocument format="pdf">
  Hello World!!!
  <cfdocumentitem type="pagebreak"/>
  <cfdocumentitem type="header">
     Company Name
   </cfdocumentitem >
   <cfdocumentitem type="footer"> 
<div align="center">
<font color="navy" size="1"
  face="Tahoma">
page 
<cfoutput>
  #cfdocument.currentpagenumber#
</cfoutput>/
     <cfoutput>
       #cfdocument.totalpagecount#
     </cfoutput>
     </font>
     </div>
  </ cfdocumentitem >
  <!-- insert your other HTML text
    here-->
</cfdocument>

You use the cfdocumentsection tag to break HTML into different segments. You can specify unique headers, footers, and other HTML style for each section without affecting other parts of the document:

<cfdocument format="flashpaper/pdf">
  <cfdocumentsection margintop="1">
  <cfdocumentitem type="header">
Company Name
  </cfdocumentitem >
  <cfdocumentitem type="footer"> 
<div align="center">
<font color="navy" size="1"
  face="Tahoma">
page 
<cfoutput>
  #cfdocument.currentpagenumber#
</cfoutput>/
<cfoutput>
  #cfdocument.totalpagecount#
</cfoutput>
</font>
</div>
  </ cfdocumentitem >

  <body style="background-color:
   #dddddd">
	Hello World!!!
  </body>
</cfdocumentsection>

<cfdocumentsection margintop="2">
<cfdocumentitem type="header">
  Different Header
</cfdocumentitem >
<cfdocumentitem type="footer"> 
  different footer
</ cfdocumentitem >

<body style="background-color:
  #eeeeee">
	Another Section 
</body>
</cfdocumentsection>
</cfdocument>

The user-requirements criteria - ease of use and standards support - were key factors in creating the cfdocument printing functionality. The cfdocument tag gives you a tool that you can use immediately.

We'll continue to refine this important feature in the future, and we welcome your feedback. We hope you are able to make use of this great new functionality wherever you need to print Web content.

Credits
Xu Chen and Sherman Gong developed this technology jointly. Xu designed the cfdocument architecture and provided the tag's implementation and PDF output format. Sherman Gong provided the FlashPaper format support and font management, and worked on the links and anchors support with Xu. Hiroshi Okugawa and Collin Tobin provided quality assurance for the cfdocument tag and numerous other ColdFusion features.