Manipulates ZIP and Java Archive (JAR) files. In addition to the basic zip and unzip functions, use the cfzip tag to delete entries from an archive, filter files, read files in binary format, list the contents of an archive, and specify an entry path used in an executable JAR file.
ColdFusion 8: Added this tag.
delete <cfzip required action = "delete" file = "absolute pathname
" optional entrypath = "full pathname
" filter = "file filter
" recurse = "yes|no"> list <cfzip required action = "list" file = "absolute pathname
" name = "recordset name
" optional filter = "file filter
" recurse = "yes|no" showDirectory= "yes|no"> read <cfzip required action = "read" entrypath = "full pathname
" file = "absolute pathname
" variable = "variable name
" optional charset = "encoding type
"> readBinary <cfzip required action = "readBinary" entrypath = "full pathname
" file = "absolute pathname
" variable = "variable name
"> unzip <cfzip required action = "unzip" destination = "destination directory
" file = "absolute pathname
" optional entrypath = "full pathname
" filter = "file filter
" overwrite = "yes|no" recurse = "yes|no" storePath = "yes|no"> zip <cfzip required file = "absolute pathname
"One of the following:
source = "source directory
" <cfzipparam source = "source directory
" ...> optional action = "zip" filter = "file filter
" overwrite = "yes|no" prefix = "string
" recurse = "yes|no" storePath = "yes|no">
Attribute |
Action |
Req/Opt |
Default |
Description |
---|---|---|---|---|
action |
N/A |
Optional |
zip |
Action to take. Must be one of the following:
If you do not specify an action, ColdFusion applies the default action, zip. |
charset |
read |
Optional |
default encoding of the host machine |
Character set used to translate the ZIP or JAR entry into a text string. Examples of character sets:
|
destination |
unzip |
Required |
|
Destination directory where the ZIP or JAR file is extracted. |
entryPath |
delete read readBinary unzip |
Optional |
|
Pathname on which the action is performed. |
file |
delete list read readBinary unzip zip |
Required |
|
Absolute pathname of the file on which the action is performed; for example, the full pathname of the ZIP file: c:\temp\log.zip. If you do not specify the full pathname (for example, file="log.zip"), ColdFusion creates the file in a temporary directory. You can use the GetTempDirectory function to access the ZIP or JAR file. |
filter |
delete list unzip zip |
Optional |
|
File filter applied to the action. The action applies to all files in the specified pathname that match the filter. |
name |
list |
Required |
Record set name in which the result of the list action is stored. The record set columns are the following:
|
|
overwrite |
unzip zip |
Optional |
no |
unzip: Specifies whether to overwrite the extracted files:
zip: Specifies whether to overwrite the contents of a ZIP or JAR file:
|
prefix |
zip |
Optional |
|
String added as a prefix to the ZIP or JAR entry. The string is the name of a subdirectory in which the entries are added. |
recurse |
delete list unzip zip |
Optional |
yes |
Specifies whether the action applies to subdirectories:
|
showDirectory |
list |
Optional |
no |
Specifies whether to show the directory structure:
|
source |
zip |
Required (see description) |
|
Source directory to be zipped. Not required if the cfzipparam tag is specified. |
storePath |
unzip zip |
Optional |
yes |
unzip: Specifies whether files are stored at the entry path:
zip: Specifies whether pathnames are stored in the ZIP or JAR file:
|
variable |
read readBinary |
Required |
|
Variable in which the content is stored. |
Use the cfzip tag to zip and unzip files and manipulate existing ZIP or JAR files in ColdFusion. You can use the cfzip tag independently or with one or more cfzipparam tags to manipulate multiple files or directories. The cfzip tag is the parent tag of the cfzipparam tag.
The ZIP format is the standard format for file archiving and compression. The JAR format is based on the ZIP format. JAR files are platform-independent.
Use the delete action to delete entries from a ZIP or JAR file.
<!--- This example shows how to delete all the properties in a JAR file. ---> <cfzip file="e:\work\soure.jar" action="delete" filter="*.properties, *.props"> <!--- This example shows how to delete all of the entries in a ZIP file with a JPG, GIF, or PNG extension, including entries in subdirectories. ---> <cfzip file="c:\myApp\images.zip" action="delete" filter="*.jpg, *.gif, *.png" recurse="yes"> <!--- This example shows how to delete the "images" subdirectory (and its contents) from the "myApp.zip" file. ---> <cfzip action="delete" file="c:\myApp.zip" entrypath="images"> <!--- This example shows how to delete all Java source entries in the "work/source" directory and images (*.gif, *.jpg, *.jpeg) from a JAR file. ---> <cfzip file="/downloads/source.jar" action="delete"> <cfzipparam entrypath="work/source" filter="*.java"> <cfzipparam filter="*.gif,*.jpg,*.jpeg"> </cfzip>
Use the list action to list the entries of a ZIP or JAR file. The following table shows the types of information you can retrieve for entries in the archive:
Field |
Description |
---|---|
comment |
Text string description saved with the entry source. |
compressedSize |
Compressed size of the entry in bytes. |
crc |
Checksum for the entry source. |
dateLastModified |
Date and time when the source was last modified. |
directory |
Name of the directory where the entry is stored. |
name |
Entry pathname. |
size |
Uncompressed size of the entry source in bytes. |
type |
Source type for the entry, for example, file. |
You can use the cfdump tag to list all of the information in a ZIP or JAR file, as the following example shows:
<cfzip file="c:/myApp.jar" action="list" name="entry"> <cfdump var="#entry#">
You can use the cfoutput tag to list individual fields for the entries in an archive, as the following example shows:
<cfzip file="c:\zipTest\Test.zip" action="list" name="entry"> <table> <cfoutput> <tr> <td><b>Entry Name:</b> #entry.name#</td> <td><b>Last Modified Date:</b> #dateFormat(entry.dateLastModified)#,#timeFormat(entry.dateLastModified)#</td> <td><b>Size (uncompressed):</b> #numberFormat(entry.size/1000)# KB <br></td> </cfoutput> </tr> </table>
Use the read action to read the content of the ZIP or JAR file entry in human-readable format. The read action uses the charset value to create the string.
<!--- This example shows how to read a text file in a JAR file. ---> <cfzip action="read" file="/home/sam/work/util.jar" entrypath="info.txt" variable="text">
Use the readBinary action to read the content of a ZIP or JAR file in binary format.
<!--- This example shows how to use the readBinary action to copy a ZIP entry from one ZIP file to another ZIP file. ---> <cfzip file="c:\work\instr.zip" action="readBinary" entryPath="com/test/abc.jpg" variable="xyz"> <cfzip file="c:\work\copy_instr.zip"> <cfzipparam entryPath="com/test/xyz.jpg" content="#xyz#"> </cfzip>
Use the unzip action to extract the entries from a ZIP or JAR file.
<!--- This example shows how to extract the class files of a JAR file and save the files to a local drive. ---> <cfzip file="e:\work\tools.jar" action="unzip" filter="*.class" destination="c:\temp\tools\classes"/> <!--- This example shows how to extract files from a JAR file in multiple directories. ---> <cfzip file="e:\work\images.jar" action="unzip" destination="c:\images"> <cfzipparam entryPath="toWork\small"> <cfzipparam entryPath="final\large"> </cfzip>
Use the zip action to create or update a ZIP or JAR file. This is the default action; you do not have to specify it explicitly. If you specify a ZIP or JAR file that does not exist, ColdFusion creates it. If the ZIP or JAR file exists, ColdFusion adds new entries from the source and updates existing entries if they have changed. If you set the overwrite attribute to yes, all of the entries in the ZIP or JAR file are replaced by the new content.
<!--- This example shows how to zip the directory "c:\temp" into the ZIP file "e:\work\abc.zip". ---> <cfzip file="e:\work\abc.zip" source="c:\temp"> <!--- This example shows how to zip all the class files in a directory and add a subdirectory named "classes" to the JAR file entry name. ---> <cfzip file="e:\work\util.jar" action="zip" source="c:\src\util\" prefix="classes" filter="*.class"> <!---This example shows how to zip all of the log files in the ColdFusion directory and create a subdirectory called exception where zipped files are archived. <cfzip file="c:\zipTest\log2.zip" action="zip" source="c:\ColdFusion\" prefix="exception" filter="*.log"> <!--- This example shows how to overwrite all of the content of a ZIP file with the entries specified in the source. ---> <cfzip file="c:\currentApp.zip" source="c:\myApp\work" overwrite="yes">
The following example shows how to zip image files chosen from a form and e-mail the ZIP file to the person requesting the images.
The first ColdFusion page populates a pop-up menu with the names of artists generated from a database query:
<!--- Create a query to extract artist names from the cfartgallery database. ---> <cfquery name="artist" datasource="cfartgallery"> SELECT FIRSTNAME || ' ' || LASTNAME AS FULLNAME,ARTISTS.ARTISTID FROM ARTISTS </cfquery> <!--- Create a form that lists the artists generated by the query. ---> <cfform action="zipArt_action.cfm" method="post"> <h3>Choose an Artist</h3> <p>Please choose an artist:</p> <cfselect name="artistName" query="artist" display="FULLNAME" value="ARTISTID" required="yes" multiple="no" size="8"> </cfselect> <br/><cfinput type="submit" name="submit" value="OK"> </cfform>
The first action page displays the images by the selected artist, zips the files, and writes the ZIP file to a temporary directory. Also, it includes a form to e-mail the ZIP file:
<!--- Create a query to extract artwork for the selected artist from the cfartgallery database. ---> <cfquery name="artwork" datasource="cfartgallery"> SELECT FIRSTNAME, LASTNAME, LARGEIMAGE FROM ARTISTS, ART WHERE ARTISTS.ARTISTID = ART.ARTISTID AND ARTISTS.ARTISTID=<cfqueryparam value="#form.artistName#"> ORDER BY ARTNAME </cfquery> <cfoutput> <p>You have chosen the work of #artwork.FirstName# #artwork.LastName#.</p> <cfset thisDir = ExpandPath(".")> <cfset imgDir = ExpandPath("..")> </cfoutput> <cfset xctr = 1> <table border="0" cellpadding="15" cellspacing="0" bgcolor="#FFFFFF"> <cfoutput query="artwork"> <cfif xctr mod 3 eq 1> <tr> </cfif> <!--- Use the IsImageFile function to verify that the image files extracted from the database are valid. Use the ImageNew function to create a ColdFusion image from valid image files. ---> <cfif IsImageFile("#imgdir#/cfdocs/images/artgallery/ #artwork.largeImage#")> <cfset myImage=ImageNew("#imgdir#/cfdocs/images/artgallery/ #artwork.largeImage#")> <td valign="top" align="center" width="200"> <cfset xctr = xctr + 1> <img src="#imgdir#/cfdocs/images/artgallery/#artwork.largeImage#"/> </td> <!---Zip the files by the specified artist. ---> <cfzip source="#imgDir#/cfdocs/images/artgallery/#artwork.LARGEIMAGE#" action="zip" file="#thisDir#/#artwork.lastname#.zip"> </cfif> </cfoutput> </tr> </table> <h3>Mail the ZIP File</h3> <p>Please enter your e-mail address so we can send you the ZIP file as an attachment.</p> <cfform action = "zipArt_action2.cfm" method="post"> Your e-mail address: <cfinput type = "Text" name = "MailTo"> <!--- Specify the required field. ---> <cfinput type = "hidden" name = "MailTo_required" value = "You must enter your email address"> <cfinput type="hidden" name="zipPath" value="#thisDir#/#artwork.lastname#.zip"> <p><cfinput type = "Submit" name = "OK" label="Mail"> </cfform>
The second action page mails the ZIP file as an attachment:
<h3>Mail the ZIP file</h3> <p>Your file has been mailed to you.</p> <cfset eMail="#form.MailTo#"> <cfset zipPath="#form.zipPath#"> <cfmail from="coldfusion@adobe.com" to="#eMail#" subject="see zipped attachment"> The images you requested are enclosed in a ZIP file. <cfmailparam file="#zipPath#"> </cfmail>