LXP has the ability to both set and retrieve cookie values. The LXP tag to set a cookie is
<setcookie>, and the LXP tag to display a cookie value is
<putcookie>.
The setting of a cookie must happen before any content is sent from the Apache server. This is
because the cookie is included in the headers that precede the actual output of the requested document.
A special construct exists for this type of scenario, called the initialization dock, which is
defined with <dock type="init">. This tag must be the first LXP tag following the
<lxp> tag in your document. Within it, you may use the
<setcookie> tag. Here is the syntax for opening an initialization dock:
<lxp>
<dock type="init">
Once the dock is open, you may set cookies with the following syntax:
<setcookie name="cookie_name" value="cookie_value"
domain="cookie_domain" path="cookie_path"
expires="cookie_expiration" />When the dock is closed with </dock>, the cookies will be set, and content
following the closing dock tag will be sent to the client.
Only the name and value attributes are required to
set a cookie. Supplying an empty value has the effect of deleting the cookie.
Setting an explicit domain is helpful in specifying the detail of a domain the cookie should be accepted for (e.g.,
www.thelinuxreview.com, versus .thelinuxreview.com for all subdomains).
Similarly, the path attribute specifies a URI path to maintain the cookie for (e.g.,
path="/app/").
If the expires attribute is omitted, the cookie is set as a
session cookie, and it will expire when the browser is closed. Otherwise, the value represents either
the number of hours in which the cookie should expire, or the complete epoch value (the number of
seconds since 1970 to the moment the cookie should expire). If the value is larger than one million, it is implied that it
is describing the latter.
Note that, unlike some web languages, LXP documents will be immediately aware of any cookies that you have set within
the same request that sets the cookie. This awareness is handled through logic internal to LXP, and included documents of
other types (such as PHP) will not be aware of a cookie that has been set until a request following the one which sets the
cookie is submitted. This is due to the client-side nature of cookies.
Note: An initialization dock is also a good region in which to perform any general initialization for a document, as no
comments or newlines in an initialization dock will be sent to the browser. You can include an external LXP file from
within the dock.
Unlike some other web-languages, such as PHP, cookies are not implicitly treated as variables. Instead, LXP maintains
a separate list of cookies in addition to its list of variables. This is done to ensure that methods that should apply to
cookies always do, and to prevent the collision of variable names and cookie names.
Therefore, to display a cookie, use the <putcookie> tag, as shown in Example 13-7.
Example 13-7. Displaying a cookie value
<lxp>
Your cookie "user" is set to: <putcookie name="user" />
</lxp>
If you wish to substitute the value of a cookie into an LXP attribute, you might think you could do so with the same
dollar sign notation used to substitute variable values. However, this introduces a point of ambiguity between cookie
values and variable values. Therefore, cookie values may be accessed through the special
cookies LXP object.
Example 13-8. Substituting cookie values
<lxp>
<setvar welcome_msg="Welcome, @cookies.user!" />
<if cookies.user>
<putvar name="welcome_msg" />
</if>
</lxp>As of LXP 0.8, for backwards compatibility, if a variable is not found with a specified substitution name (e.g.,
$my_cookie), LXP will search the list of cookies for a cookie with that name. This
behavior is scheduled to either be removed (or be made configurable) in future versions of LXP, however.
