ColdFusion 9.0 Resources

cfcookie

Description

Defines web browser cookie variables, including expiration and security options.

Syntax

<cfcookie  
    name = "cookie name" 
    domain = ".domain" 
    expires = "period" 
    httponly = "yes|no" 
    path = "URL" 
    secure = "yes|no" 
    value = "text">

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.

History

ColdFusion MX 6.1:

Changed the expires attribute: it now accepts a date time object.
Cookie names can include all ASCII characters except commas, semicolons, or whitespace characters.

ColdFusion 9:

Added the attribute httponly.

Attributes

Attribute	Req/Opt	Default	Description
`name`	Required		Name of cookie variable. ColdFusion converts cookie names to all-uppercase. Cookie names set using this tag can include any printable ASCII characters except commas, semicolons, or white space characters.
`domain`	Required if `path` attribute is specified. Optional otherwise		Domain in which cookie is valid and to which cookie content can be sent from the user’s system. By default, the cookie is only available to the server that set it. Use this attribute to make the cookie available to other servers. Must start with a period. If the value is a subdomain, the valid domain is all domain names that end with this string. This attribute sets the available subdomains on the site on which the cookie can be used. For a `domain` value that ends in a country code, the specification must contain at least three periods; for example, `".mongo.state.us"`. For top-level domains, two periods are required; for example, `".mgm.com"`. You cannot use an IP address as a domain.
`expires`	Optional	session only	Expiration of cookie variable. The cookie expires when the user closes the browser, that is, the cookie is "session only". A date or date/time object (for example, 10/09/97). A number of days (for example, 10, or 100). `now`: deletes cookie from client cookie.txt file (but does not delete the corresponding variable the Cookie scope of the active page). `never`: The cookie expires in 30 years from the time it was created (effectively never in web years).
`httponly`	Optional		If `yes`, sets cookie as httponly so that it cannot be accessed using JavaScripts. Note that the browser must have httponly compatibility.
`path`	Optional		URL, within a domain, to which the cookie applies; typically a directory. Only pages in this path can use the cookie. By default, all pages on the server that set the cookie can access the cookie. path = "/services/login" To specify multiple URLs, use multiple `cfcookie` tags. If you specify `path`, also specify `domain`.
`secure`	Optional		If browser does not support Secure Sockets Layer (SSL) security, the cookie is not sent. To use the cookie, the page must be accessed using the https protocol. `yes`: Variable must be transmitted securely. `no`
`value`	Optional		Value to assign to cookie variable. Must be a string or variable that can be stored as a string.

Usage

If this tag specifies that a cookie is saved beyond the current browser session, the client browser writes or updates the cookie in its local cookies file. Until the browser is closed, the cookie resides in browser memory. If the expires attribute is not specified, the cookie is not written to the browser cookies file.

If you use this tag after the cfflush tag on a page, ColdFusion does not send the cookie to the browser; however, the value you set is available to ColdFusion in the Cookie scope during the browser session.

Note: You can also create a cookie that expires when the current browser session expires by using the cfset tag or a CFScript assignment statement to set a variable in the Cookie scope, as in <cfset Cookie.mycookie="sugar">. To get a cookie’s value, refer to the cookie name in the Cookie scope, as in <cfif Cookie.mycookie is "oatmeal">.

You can use dots in cookie names, as the following examples show:

<cfcookie name="person.name" value="wilson, john"> 
<cfset cookie.person.lastname="Santiago">

To access cookies, including cookies that you set and all cookies that are sent by the client, use the Cookie scope. For example, to display the value of the person.name cookie set in the preceding code, use the following line:

<cfoutput>#cookie.person.name#</cfoutput>

Example

<!--- This example shows how to set/delete a cfcookie variable. ---> 
<!--- Select users who have entered comments into a sample database. ---> 
<cfquery name = "GetAolUser" dataSource = "cfdocexamples"> 
    SELECT EMail, FromUser, Subject, Posted 
    FROM Comments 
</cfquery> 
<html> 
<body> 
<h3>cfcookie Example</h3> 
<!--- If the URL variable delcookie exists, set cookie expiration date  
    to NOW ---> 
<cfif IsDefined("url.delcookie") is True> 
    <cfcookie name = "TimeVisited" 
    value = "#Now()#" 
    expires = "NOW">         
<cfelse> 
<!--- Otherwise, loop through list of visitors; stop when you match  
    the string aol.com in a visitor's e-mail address. ---> 
<cfloop query = "GetAolUser"> 
    <cfif FindNoCase("aol.com", Email, 1) is not 0> 
        <cfcookie name = "LastAOLVisitor" 
        value = "#Email#" 
        expires = "NOW" >         
    </cfif> 
</cfloop> 
<!--- If the timeVisited cookie is not set, set a value. ---> 
    <cfif IsDefined("Cookie.TimeVisited") is False> 
        <cfcookie name = "TimeVisited" 
        value = "#Now()#" 
        expires = "10"> 
    </cfif> 
</cfif> 
<!--- Show the most recent cookie set. ---> 
<cfif IsDefined("Cookie.LastAOLVisitor") is "True"> 
    <p>The last AOL visitor to view this site was 
    <cfoutput>#Cookie.LastAOLVisitor#</cfoutput>, on 
    <cfoutput>#DateFormat(COOKIE.TimeVisited)#</cfoutput> 
<!--- Use this link to reset the cookies. ---> 
<p><a href = "cfcookie.cfm?delcookie = yes">Hide my tracks</A> 
<cfelse> 
    <p>No AOL Visitors have viewed the site lately. 
</cfif>