Using cfcache

Using `<cfcache>`

In many applications, templates are built dynamically every time a page is requested. But often a ColdFusion template stays the same every time it's requested. An example of this scenario is a home page that has no personalized content. Why should the page be built dynamically from the ColdFusion template when it rarely changes? This is a good question, and the <cfcache> tag can help resolve the issue.

When the <cfcache> tag is used on a page, it creates a separate file of the HTML code that the page generates. When the page is requested next, the tag sends the Web server the generated HTML code that was saved earlier, rather than dynamically rebuilding the page. This means that complete pages that do not change often can be cached, thus saving processing time and improving performance.

When a page is cached, it is uniquely identified by its URL. For instance, Product.cfm, Product.cfm?Prod_ID=6, and Product.cfm?Prod_ID=11 all would be considered unique pages and cached as different pages. All of these pages would be considered good candidates for <CFCACHE>. But some pages are poorly suited to <CFCACHE>. Consider an action page based on a form that varies depending on user input in form controls. In most cases, this would be a terrible candidate for <CFCACHE>. The first user to fill in the form would generate output from the action page, and that output would be cached. All subsequent users, no matter how they filled in the form, would see the cached page until it timed out or was deleted.

The attributes used with <cfcache> are shown in Table 49.1. All are optional.

Table 49.1. `<cfcache>` Tag Attributes
ATTRIBUTE	DESCRIPTION
`action`	Specifies the action that the tag should perform. The options are `Cache` (the default), `Flush`, `ClientCache`, and `Optimal`.
`directory`	Specifies the directory from which cached files should be flushed (used with `action="Flush"`).
`expireurl`	Specifies the generated HTML files whose original files should be deleted; for instance, `expireurl="Product.cfm?*" (`used with `action="Flush")`.
`password`	Login password to be used if the page requires Web serverlevel authentication.
`port`	Specifies the port to be used during the communication between the tag and server. The default is `80`.
`protocol`	Specifies the protocol to be used during the communication between the tag and server. The options are `http://` (the default) and `https://`.
`timespan`	The time-out interval. Valid values are numbers and time spans.
`username`	Login user name to be used if page requires Web serverlevel authentication.

You can create a template as follows:

 <cfcache> <html> <head>  <title>Untitled</title> </head> <body> <cfset thevar="Pass the test!"> <cfoutput>#VARIABLES.TheVar#</cfoutput> </body> </html>

A file is created and saved, and ColdFusion generates its name. The saved file looks like this:

 <html> <head>  <title>Untitled</title> </head> <body> Pass the test! </body> </html>

After the ColdFusion tags are processed, the HTML code is generated and then saved as a separate file. The next time a user browses this page, ColdFusion sees the <cfcache> tag and uses a special map file to check whether the generated code already exists.

The cached page can be timed out in a number of ways. One is to use the TIMEOUT attribute with the <cfcache> tag. The following example would time out the cache after 5 hours:

 <cfcache action="Cache" timeout="#DateAdd("h","-5",Now() )#">

You also can schedule a page to run at certain intervals or dynamically by using the Flush value for the action attribute, as follows:

 <cfcache action="Flush" expireurl="*">

CAUTION

The ColdFusion documentation is inconsistent about whether you should use attributes when action="Flush". In some places, it implies that no attributes are needed, and in others, it indicates that both EXPIREURL and DIRECTORY are required. In practice, at least EXPIREURL must be used.

Using <cfcache>

Table 49.1. <cfcache> Tag Attributes

Using `<cfcache>`

Table 49.1. `<cfcache>` Tag Attributes