ADVANCED macromedia COLDFUSION MX 7 Application Development [Electronic resources] نسخه متنی

Document Properties

Microsoft Excel, PowerPoint, and Word files are natively stored in a binary format referred to as an

OLE Compound Document . In this hierarchical structured format, programs that understand even a small part of the hierarchy can interact with that data while ignoring the rest without fear of corrupting the document. This allows us to manipulate Microsoft Office files through ColdFusion safely and efficiently.

One part of the document data associated with every OLE Compound Document, including Office files, is the Document Summary Properties. These properties are commonly known as the built-in properties users occasionally set through the Office user interface, such as the title, subject, and author, as shown in Figure 27.1.

NOTE

All of the examples in this chapter use DSOFile to read and write document properties. DSOFile is a COM object and thus these examples are targeted at ColdFusion servers installed on Microsoft Windows servers. Document properties can also be read and written using Apache POI, as discussed later in this chapter. The concepts discussed here apply equally to POI-based integrationonly the code has been changed. In order to run these samples and use DSOFile in ColdFusion, applications download the COM object from Microsoft and install it on the server. It is available at:

http://www.microsoft.com/downloads/details.aspx?familyid=9ba6fac6-520b-4a0a-878a-53ec8300c4c2.

Review Listing 27.1 for an example of reading Document Properties. This example lists all of the files in a directory along with their author.

Listing 27.1. ListAuthors.cfmList Files with Authors Using Summary Properties

<!---
Filename: ListAuthors.cfm
Purpose: List files in a directory along with the author property.
Depends on: DSOFile COM object installed on server.
--->
<!--- get a list of files in the target directory --->
<cfset dir=ExpandPath("files")>
<cfdirectory
action="list"
directory="#dir#"
name="files">
<!--- Instantiate a Document Properties object --->
<cfobject
action="create"
  type="com"
name="props">
<!--- display headings for our table --->
<h1>Directory Listing with Author</h1>
<table border="0" cellpadding="0" cellspacing="0">
<tr>
<th>File</th>
<th>Modified</th>
<th>Author</th>
</tr>
<!--- loop through files and read their summary properties --->
<cfoutput query="files">
<cfset props.Open(dir & "/" & files.name)>
<cfset summary = props.SummaryProperties>
<!--- display data from cfdirectory and the property reader --->
<tr>
<td>#files.name#</td>
<td>#DateFormat(files.dateLastModified)#</td>
<td>#summary.author#</td>
</tr>
<!--- we're done with this file --->
<cfset props.Close()>
</cfoutput>
</table>
<!--- we're done with the reader, release it --->
<cfset ReleaseComObject(props)>

This example starts with a standard directory listing and includes information provided by ColdFusionthe filename and the last modified date. In addition, it instantiates a DSOFile.OleDocumentProperties object that is used to read the properties of each file in order to display the author. To accomplish this, the PropertyReader provides an Open method and then a SummaryProperties object, which in turn includes an Author property. The SummaryProperties object includes all the built-in properties listed in Table 27.1.

Besides these built-in properties, all documents can have an unlimited number of custom properties. This is where true integration begins. Through these custom properties we can provide updated data to an existing document and provide a customized document to the user. Listing 27.2 is an example that customizes an existing Word document with the name and address of a customer.

Listing 27.2. MailMerge.cfmServe a Word Document with Custom Information

<!---
Filename: MailMerge.cfm
Purpose: Merge data into a Word document via custom properties
Requires: Existing word document as template and DSOFile installed
--->
<!--- create a copy of our source document --->
<cfset source=ExpandPath("files\merge.doc")>
<cfset tempFile=GetTempFile(GetTempDirectory(),"doc")>
<cffile
action="copy"
source="#source#"
destination="#tempFile#">
<cfscript>
// Open the temp file properties
props = createObject("COM","DSOFile.OleDocumentProperties");
props.Open(tempFile);
customProps = props.CustomProperties;
// set custom property values.  In a real application, these
// would come from a form or database.
customProps.Item("OrderDate").Value = "November 23, 2004";
customProps.Item("FirstName").Value = "Samuel";
customProps.Item("LastName").Value = "Neff";
customProps.Item("Address").Value = "215 East Road";
customProps.Item("City").Value = "Rockville";
customProps.Item("State").Value = "MD";
customProps.Item("Zip").Value = "20850";
// save and close the document
props.Save();
props.Close();
ReleaseComObject(props);
</cfscript>
<!---
send the document to the user.  Specify that the file is an
attachment to prevent Internet Explorer from opening it
through automation. --->
<cfheader
name="Content-Disposition"
value="attachment; filename="Confirmation.doc"">
<cfcontent
reset="yes"
type="application/msword"
file="#tempFile#"
deleteFile="true">

MailMerge.cfm starts by copying the template document to a new temporary file and then opening the custom document properties for that file. The custom properties are each updated by referencing the existing property objects by name and changing their values. Finally, the properties are saved and closed and the document is sent to the user.

Notice the use of both the <cfheader> and <cfcontent> tags. The <cfheader> tag instructs the browser to treat the document as a downloaded file to be opened outside the browserwithout this tag Internet Explorer would open the file internally using Microsoft Word as an automation server. The <cfcontent> tag specifies the file type, which is how the browser knows the document is a Microsoft Word documentbrowsers always ignore filename extensions.

This example uses a Word document that is already set up with custom properties as placeholders. Word provides developers with the ability to create fields within the document that are linked to custom properties and will show the updated data when the document is loaded. Figure 27.3 shows the field editor creating a DocProperty field pointing to a custom OrderDate property.