Using Cookies with LXP

Setting Cookies

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.

Accessing Cookie Values

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.

<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.

<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.