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
|
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.
-
absolute
The date must be a string of the form:
-
"Wdy, DD-Mon-YYYY HH:MM:SS GMT"
and the timezone must be GMT.
-
relative
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