|
cfcache
DescriptionStores
a copy of a page on the server and/or client computer, to improve
page rendering performance. To do this, the tag creates temporary
files that contain the static HTML returned from a ColdFusion page.
Use
this tag if it is not necessary to get dynamic content each time
a user accesses a page.
You can use this tag for simple URLs
and for URLs that contain URL parameters.
Syntax<cfcache
action = "action"
dependsOn = "variable name list"
directory = "directory path"
expireURL = "wildcarded URL reference"
id = "object identifier"
idleTime = "decimal number of days"
metadata = "variable name"
name = "variable name"
password = "password"
port = "port number"
protocol = "http://|https://"
stripWhiteSpace = "false|true"
throwOnError = "false|true"
timespan = "decimal number of days">
useCache = "true|false"
username = "username"
value = "value">
The page fragment to be cached, if any.
</cfcache>
Note: You can specify
this tag’s attributes in an attributeCollection attribute
whose value is a structure. Specify the structure name in the attributeCollection attribute
and use the tag’s attribute names as structure keys.
HistoryColdFusion
9:
Added support for the following features:
Caching in memory. Memory is now the default cache location.
Caching page fragments.
Caching specific objects, including the ability to put, get,
and flush cached objects.
Setting cache dependencies.
Setting an idle timeout.
Getting metadata about cached objects.
The ability to strip white space from cached page fragments.
The ability to throw an exception if an error occurs when
flushing a cached object.
Added get and put values
of the action attribute. These values support caching
of objects.
Added dependsOn, id, idleTime, key, metadata, name, stripWhiteSpace, throwOnError, useCache,
and value attributes.
ColdFusion
MX:
Deprecated the cachedirectory and timeout attributes.
They might not work, and might cause an error, in later releases.
Added the timespan attribute.
Changed how pages are cached: the default action attribute
value, cache, caches a page on the server and the
client. (In earlier releases, this option cached a page only on
the server.)
Changed the source of the protocol and port values:
the default protocol and port values
are now taken from the current page URL. (In earlier releases, they
were "http" and "80", respectively.)
Changed how session state is handled when caching a page:
this tag can cache pages that depend on session state, including
pages that are secured with a ColdFusion login. (In earlier releases,
the session state was cleared when caching the page, causing authentication
to be lost.)
Changed how files are cached: this tag uses a hash() of the
URL for the filename to cache a file. (In earlier releases, ColdFusion
used the cfcache.map file.)
Attributes
Attribute
|
Actions
|
Req/Opt
|
Default
|
Description
|
action
|
All
|
Optional
|
serverCache
|
cache: server-side
and client-side page caching.
clientcache: browser-side page caching only.
To cache a personalized page, use this option.
flush: remove the current versions of cached
pages, fragments, or an object from the cache. The cache is refreshed
the next time a user accesses the item. For more information see
Description.
get: get an object from the cache.
optimal: same as cache.
put: Add an object to the cache.
serverCache: server-side caching only.
|
dependsOn
|
cacheserverCacheoptimal
|
Optional
|
|
A comma separated list of variables. If
any of the variable values change, ColdFusion updates the cache.
This attribute can take an expression that returns a list of variables.
|
directory
|
cache,serverCache,clientCache,optimal, flush, put
|
Optional
|
Cache in memory
|
Absolute path of cache directory.
|
expireURL
|
flush
|
Optional
|
Flush all cached pages
|
A URL reference. Can include wildcards,
for example: "*/view.cfm?id=*". ColdFusion flushes
the cache pages that match the specified URL or pattern.
|
id
|
flush, get, put
|
See description
|
|
The identifier for a cached object.
This
attribute is required for the any operation on an object. Therefore it
is required for the get and put actions,
and to flush an object. It is not required to flush a page.
|
idleTime
|
cache,serverCache,clientCache,optimal, flush, put
|
Optional
|
No idle timeout
|
Flushes the cached item if it is not accessed
for the specified time span:
A decimal number of
days, for example: ".25", for one-fourth day (6 hours); "1", for
one day; "1.5", for one and one half days
A return value from the CreateTimeSpan function,
for example, "#CreateTimeSpan(0,6,0,0)#".
|
metadata
|
get
|
Optional
|
|
The name of a structure variable in which
to put object metadata. The get operation returns the following
data:
timespan: The time span during which the
cached item is valid; the value of the timespan attribute for the
cached item.
createdtime: The time when the cache was created
lasthit: The time when the cached item was most recently
used.
hitnumber: Number of times the cached item has been used.
missnumber: Number of misses
|
name
|
get
|
Required
|
|
The name of the variable in which to put
the retrieved object.
|
password
|
cache,serverCache,clientCache,optimal, flush
|
Optional
|
|
A password. Provide this if the page requires
authentication at the web-server level.
|
port
|
cache,serverCache,clientCache,optimal, flush
|
Optional
|
The port for
the current page
|
Port number of the web server from which
the URL for the cached page is requested. In the internal call from cfcache to cfhttp,
ColdFusion resolves each URL variable in the page; this ensures
that links in the page remain functional.
|
protocol
|
cache,serverCache,clientCache,optimal, flush
|
Optional
|
The current page
protocol
|
Protocol that is used to create URL from
cache.
|
stripWhiteSpace
|
cache,serverCache,optimal
|
Optional
|
false
|
Specifies whether to strip any unnecessary
white space characters from a cached page fragment. Does not have
any effect on cached pages or objects.
|
throwOnError
|
flush with id attribute
|
Optional
|
false
|
A Boolean value specifying whether to throw
an error if the flush action encounters an error.
Otherwise the action does not generate an error if it fails. If
this attribute is true you can handle the error
in a cfcatch block, for example, if a specified
id value is invalid.
|
timespan
|
cache,serverCache,clientCache,optimal, flush, put
|
Optional
|
See Description
|
The interval until the item is flushed from
the cache.
A decimal number of days, for example:
".25", for one-fourth day (6 hours); "1", for one day; "1.5", for
one and one half days
A return value from the CreateTimeSpan function,
for example, "#CreateTimeSpan(0,6,0,0)#".
The default action is to flush
the item when it is idle for the time specified by the idleTime attribute,
or cfcache action="flush" executes.
|
useCache
|
cache,serverCache,optimal,
|
Optional
|
true
|
Specifies whether to use caching for a page.
This attribute can be useful during development., or you could use
a function to predict when to use a cache based on the application
state.
|
username
|
cache,serverCache,clientCache,optimal, flush
|
Optional
|
|
A username. Provide this if the page being
cached or flushed requires authentication at the web server level.
|
value
|
put
|
Required
|
|
The object to cache.
|
UsageColdFusion 9 additions
The
following is new information applies to features added for ColdFusion
9. For additional information, see the History section and the Attributes
table.
Page fragments: To cache a page fragment, put
the fragment in the body of the tag, between the begin tag and the
end tag. Do not use a tag body to cache full pages or objects.
flush: The flush action
can have two formats: One uses the ExpireURL attribute
to specify the page to flush, the other uses the id attribute
to specify the object to flush. When you flush an object, ColdFusion
ignores errors by default. If you specify a throwOnError attribute
with a true value, the action throws the errors,
and you can use a catch block to handle them. This is useful to determine
if you use invalid cache ID values.
From ColdFusion 8 and earlier
The
following remaining information for this tag also applied to previous releases.
Use
this tag in pages whose content is not updated frequently. Taking
this action can greatly improve the performance of your application.
The
output of a cached page is stored in a file on the client browser
and/or the ColdFusion server. Instead of regenerating and downloading
the output of the page each time it is requested, ColdFusion uses
the cached output. ColdFusion regenerates and downloads the page
only when the cache is flushed, as specified by the timespan attribute,
or by invoking cfcache action=flush.
To enable
a simple form of caching, put a cfcache tag, specifying
the timespan attribute, at the top of a page. Each
time the specified time span passes, ColdFusion flushes (deletes)
the copy of the page from the cache and caches a new copy for users
to access.
You can specify client-side caching or a combination
of client-side and server-side caching (the default), using the
action attribute. The advantage of client-side caching is that it
requires no ColdFusion resources; the browser stores pages in its
own cache, improving performance. The advantage of combination caching
is that it optimizes server performance; if the browser does not
have a cache of the page, the server can get data from its own cache.
(Adobe recommends that you use combination caching, and do not use
server-side only caching.)
If a page contains personalized
content, use the action = "clientcache" option
to avoid the possibility of caching a personalized copy of a page
for other users.
Debug settings have no effect on cfcache unless
the application page enables debugging. When generating a cached
file, cfcache uses cfsetting showDebugOutput = "no".
The cfcache tag
evaluates each unique URL, including URL parameters, as a distinct
page, for caching purposes. For example, the output of http://server/view.cfm?id=1
and the output of http://server/view.cfm?id=2 are cached separately.
The cfcache tag
uses the cfhttp tag to get the contents of a page
to cache. If there is an HTTP error accessing the page, the contents
are not cached. If a ColdFusion error occurs, the error is cached.
For
more information, see Caching
ColdFusion pages that change infrequently in the Developing ColdFusion Applications.
Example<!--- This example produces as many cached files as there are URL parameter permutations.
You can see that the page is cached when the timestamp doesn't change.--->
<cfcache
timespan="#createTimeSpan(0,0,10,0)#">
<body>
<h3>This is a test of some simple output</h3>
<cfoutput>
This page was generated at #now()#<br>
</cfoutput>
<cfparam name = "URL.x" default = "no URL parm passed">
<cfoutput>The value of URL.x = # URL.x #</cfoutput>
|