4.68. set-cookie

Sets browser cookie(s) with the specified attributes.

4.68.1. Summary

    [set-cookie named_attributes]

Parameters must be named (no positional usage except in Perl call)

Attributes Description Default
name The name you give the cookie none
value The value (automatically html-escaped by Interchange) none
expire Expiration date as
    "Wdy, DD-Mon-YYYY HH:MM:SS GMT"
none
domain Overrides the domain(s) set in CookieDomain Domain(s), if any, defined in the CookieDomain directive
path legal URL paths for the cookie URL path(s) to your catalog, including aliases
Other_Characteristics  
Invalidates cache Yes
Container tag No

Usage example:

    [set-cookie name=mycookie
               value="the value"
              expire="Tue, 03-Apr-2001 17:00:00 GMT"]
---
    This tag returns no value in the page

ASP-like Perl call:

    $Tag->set_cookie(  { name   => $name,
                         value  => $value,
                         expire => $expire,
                         domain => $domain,
                         path   => $path, }  );

or similarly with positional parameters,

    $Tag->set_cookie( $name, $value, $expire, $domain, $path );

4.68.2. Description

This tag sets one or more browser cookies with your specified name, value, and expiration. (Interchange will set more than one cookie if needed to ensure that the cookie is visible from all Catalog URL path aliases and CookieDomains.)

See the Netscape specification at http://www.netscape.com/newsref/std/cookie_spec.html for more cookie-specific detail.

If you need access to the cookie from outside of your Interchange catalog, you can also set the domain and URL paths for which the cookie will be valid. If you need the cookie only within your catalog and the domains specified by the CookieDomain directive, you probably should not override the Interchange domain and path defaults.

4.68.2.1. name

This is the name of the cookie. This is the key you will use when reading the cookie later.

4.68.2.2. value

This is the value to store in the cookie.

4.68.2.3. expire

Persistent cookies (that outlive a browser session) require an expiration date. There are two ways to set it -- relative times and absolute times.

The date must be a string of the form:

and the timezone must be GMT.

Supply a period in the form NN sec|min|hours|days|weeks.

Example:

 [set-cookie name=THE_COOKIE value=foo expire="7 days"]

If you do not supply a date (either absolute or relative), the cookie will disappear when the user closes the browser.

4.68.2.4. domain

The value you set will override the Interchange default domain(s). You might set this if you need access to the cookie from outside the Interchange catalog, but it is usually better to set the CookieDomain directive in your catalog.

The default is to use your catalog's domain or all CookieDomain values.

4.68.2.5. path

The value you set will override the Interchange default URL path(s).

The default is to set a cookie with a path for each catalog alias (see the Catalog directive). This ensures that the cookie will be visible regardless of how the end user returns to your catalog.

4.68.3. Tips

You can use the time tag in conjunction with the set-cookie tag to set the expiration date to an absolute date.

   [set-cookie
     name=mycookie
     value="the value"
     expire="[time gmt=1 adjust='+2190']%a, %m-%b-%Y %H:%M:%S GMT[/time]"
   ]

In the example above, the adjustment of +2190 will set a cookie expiration of 2190 hours forward from the current date.

You can use the