1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 2 <html xmlns="http://www.w3.org/1999/xhtml"> 3 <head> 4 <meta content="text/html;charset=ISO-8859-1" http-equiv="Content-Type" /> 5 <title>Cookies</title> 6 <meta name="generator" 7 content="amaya 8.1a, see http://www.w3.org/Amaya/" /> 8 <link href="styles.css" rel="stylesheet" type="text/css" /> 9 </head> 10 <body> 11 <h1>Cookies</h1> 12 <p>The term "cookie" is a technical term describing information which 13 is set in a response sent to a user and which is then provided every 14 time the user accesses the application. In effect, the application asks 15 the user to remember something on its behalf and to remind the 16 application of that thing over and over again.</p> 17 <h2>Potential Uses</h2> 18 <p>Although there are some restrictions on how much information can be 19 stored in a cookie and the type of that information (it must be a plain 20 Python string), the mechanism is useful for identifying users or 21 remembering simple things about the operations that the user has been 22 performing. Some applications use cookies to remember the state 23 of their user interfaces, such as which parts of a navigational 24 menu have been opened by the user, for example.</p> 25 <div class="WebStack"> 26 <h3>WebStack API - Using Cookies</h3> 27 <p>The <a 28 href="../apidocs/public/WebStack.Generic.Transaction-class.html">transaction</a> 29 object provides the following methods for setting cookie information 30 and accessing it on later occasions:</p> 31 <dl> 32 <dt><code>set_cookie_value</code></dt> 33 <dd>This method stores a piece of information associated with a given 34 name and having a given plain Python string value as a cookie. Other 35 information can also be specified which controls the way the 36 cookie is used, notably the path (to which applications the cookie is 37 sent) and expiry time (a UNIX time style number which states when the 38 cookie should stop being exchanged).</dd> 39 <dt><code>set_cookie</code></dt> 40 <dd>This method stores an existing cookie object as a cookie in 41 future communications with the user concerned. The form of such objects 42 is described below.</dd> 43 <dt><code>get_cookies</code></dt> 44 <dd>This method returns a dictionary mapping names to cookie objects.</dd> 45 <dt><code>get_cookie</code></dt> 46 <dd>This method returns a specific cookie object for a given name.</dd> 47 <dt><code>delete_cookie</code></dt> 48 <dd>This method deletes a cookie, ensuring that the information 49 within it is not exchanged in future.</dd> 50 </dl> 51 <p><a 52 href="../apidocs/public/WebStack.Helpers.Request.Cookie-class.html">Cookie</a> 53 objects can be any objects having the following properties:</p> 54 <dl> 55 <dt><code>name</code></dt> 56 <dd>This is the name associated with the cookie. It must be a plain 57 Python string.</dd> 58 <dt><code>value</code></dt> 59 <dd>This is the information stored in the cookie. It must be a plain 60 Python string.</dd> 61 </dl> 62 </div> 63 <h2>How and When to Get and Set Cookies</h2> 64 <p>Cookies which were set in previous interactions are always available 65 straight away unless they were deleted at some earlier point in time. 66 Typically, your application will have reserved a cookie name and will 67 then access the cookie using that name; for example:</p> 68 <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> 69 <p>It is possible to modify the cookie object, but on its own this has 70 no effect on the value exchanged between the application and the user. 71 To update the cookie in that way, you must also use the <code>set_cookie</code> 72 method, or instead use the <code>set_cookie_value</code> method:</p> 73 <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> 74 <p>Note that changing a cookie's value directly using <code>set_cookie_value</code> 75 will not necessarily change the value found in cookie objects returned 76 by subsequent calls to <code>get_cookie</code> during the handling 77 of the same request.</p> 78 <p>To delete cookies, actual cookie objects must be provided:</p> 79 <pre> # In the respond method after getting the cookie...<br /> trans.delete_cookie(my_cookie)</pre> 80 <p>This does not necessarily remove the cookie from the dictionary 81 returned by <code>get_cookies</code> or prevent <code>get_cookie</code> 82 returning a cookie object for the name specified in the deleted 83 cookie during the handling of the same request.</p> 84 </body> 85 </html>