1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/cookies.html Sat Apr 30 00:21:44 2005 +0000
1.3 @@ -0,0 +1,85 @@
1.4 +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.5 +<html xmlns="http://www.w3.org/1999/xhtml">
1.6 +<head>
1.7 + <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" />
1.8 + <title>Cookies</title>
1.9 + <meta name="generator"
1.10 + content="amaya 8.1a, see http://www.w3.org/Amaya/" />
1.11 + <link href="styles.css" rel="stylesheet" type="text/css" />
1.12 +</head>
1.13 +<body>
1.14 +<h1>Cookies</h1>
1.15 +<p>The term "cookie" is a technical term describing information which
1.16 +is set in a response sent to a user and which is then provided every
1.17 +time the user accesses the application. In effect, the application asks
1.18 +the user to remember something on its behalf and to remind the
1.19 +application of that thing over and over again.</p>
1.20 +<h2>Potential Uses</h2>
1.21 +<p>Although there are some restrictions on how much information can be
1.22 +stored in a cookie and the type of that information (it must be a plain
1.23 +Python string), the mechanism is useful for identifying users or
1.24 +remembering simple things about the operations that the user has been
1.25 +performing. Some applications use cookies to remember the state
1.26 +of their user interfaces, such as which parts of a navigational
1.27 +menu have been opened by the user, for example.</p>
1.28 +<div class="WebStack">
1.29 +<h3>WebStack API - Using Cookies</h3>
1.30 +<p>The <a
1.31 + href="../apidocs/public/WebStack.Generic.Transaction-class.html">transaction</a>
1.32 +object provides the following methods for setting cookie information
1.33 +and accessing it on later occasions:</p>
1.34 +<dl>
1.35 + <dt><code>set_cookie_value</code></dt>
1.36 + <dd>This method stores a piece of information associated with a given
1.37 +name and having a given plain Python string value as a cookie. Other
1.38 +information can also be specified which controls the way the
1.39 +cookie is used, notably the path (to which applications the cookie is
1.40 +sent) and expiry time (a UNIX time style number which states when the
1.41 +cookie should stop being exchanged).</dd>
1.42 + <dt><code>set_cookie</code></dt>
1.43 + <dd>This method stores an existing cookie object as a cookie in
1.44 +future communications with the user concerned. The form of such objects
1.45 +is described below.</dd>
1.46 + <dt><code>get_cookies</code></dt>
1.47 + <dd>This method returns a dictionary mapping names to cookie objects.</dd>
1.48 + <dt><code>get_cookie</code></dt>
1.49 + <dd>This method returns a specific cookie object for a given name.</dd>
1.50 + <dt><code>delete_cookie</code></dt>
1.51 + <dd>This method deletes a cookie, ensuring that the information
1.52 +within it is not exchanged in future.</dd>
1.53 +</dl>
1.54 +<p><a
1.55 + href="../apidocs/public/WebStack.Helpers.Request.Cookie-class.html">Cookie</a>
1.56 +objects can be any objects having the following properties:</p>
1.57 +<dl>
1.58 + <dt><code>name</code></dt>
1.59 + <dd>This is the name associated with the cookie. It must be a plain
1.60 +Python string.</dd>
1.61 + <dt><code>value</code></dt>
1.62 + <dd>This is the information stored in the cookie. It must be a plain
1.63 +Python string.</dd>
1.64 +</dl>
1.65 +</div>
1.66 +<h2>How and When to Get and Set Cookies</h2>
1.67 +<p>Cookies which were set in previous interactions are always available
1.68 +straight away unless they were deleted at some earlier point in time.
1.69 +Typically, your application will have reserved a cookie name and will
1.70 +then access the cookie using that name; for example:</p>
1.71 +<pre> # In the respond method...<br /> my_cookie = trans.get_cookie("my_cookie") # this gets a cookie object<br /> my_information = my_cookie.value # trans.get_cookie_value would get this value directly</pre>
1.72 +<p>It is possible to modify the cookie object, but on its own this has
1.73 +no effect on the value exchanged between the application and the user.
1.74 +To update the cookie in that way, you must also use the <code>set_cookie</code>
1.75 +method, or instead use the <code>set_cookie_value</code> method:</p>
1.76 +<pre> # In the respond method after getting the cookie...<br /> my_cookie.value = "Something else!" # this must be a plain string<br /> trans.set_cookie(my_cookie) # this uses the existing object<br /> trans.set_cookie_value("another_cookie", "More information!") # this adds a new cookie with the given name</pre>
1.77 +<p>Note that changing a cookie's value directly using <code>set_cookie_value</code>
1.78 +will not necessarily change the value found in cookie objects returned
1.79 +by subsequent calls to <code>get_cookie</code> during the handling
1.80 +of the same request.</p>
1.81 +<p>To delete cookies, actual cookie objects must be provided:</p>
1.82 +<pre> # In the respond method after getting the cookie...<br /> trans.delete_cookie(my_cookie)</pre>
1.83 +<p>This does not necessarily remove the cookie from the dictionary
1.84 +returned by <code>get_cookies</code> or prevent <code>get_cookie</code>
1.85 +returning a cookie object for the name specified in the deleted
1.86 +cookie during the handling of the same request.</p>
1.87 +</body>
1.88 +</html>