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 uses include:</p> 23 <ul> 24 <li>The use of cookies to remember the state 25 of user interfaces, such as which parts of a navigational 26 menu have been opened by the user.</li> 27 <li>The identification of users, although since cookie information is 28 transmitted back to the user potentially using an insecure network 29 communication, it is usually necessary to encrypt or encode sensitive 30 information which would identify a user or let an eavesdropper pretend 31 to be that user in their own communications with an application.</li> 32 </ul> 33 <div class="WebStack"> 34 <h3>WebStack API - Using Cookies</h3> 35 <p>The <a 36 href="../apidocs/public/WebStack.Generic.Transaction-class.html">transaction</a> 37 object provides the following methods for setting cookie information 38 and accessing it on later occasions:</p> 39 <dl> 40 <dt><code>set_cookie_value</code></dt> 41 <dd>This method stores a piece of information associated with a given 42 name and having a given plain Python string value as a cookie. Other 43 information can also be specified which controls the way the 44 cookie is used, notably the path (to which applications the cookie is 45 sent) and expiry time (a UNIX time style number which states when the 46 cookie should stop being exchanged).</dd> 47 <dt><code>set_cookie</code></dt> 48 <dd>This method stores an existing cookie object as a cookie in 49 future communications with the user concerned. The form of such objects 50 is described below.</dd> 51 <dt><code>get_cookies</code></dt> 52 <dd>This method returns a dictionary mapping names to cookie objects.</dd> 53 <dt><code>get_cookie</code></dt> 54 <dd>This method returns a specific cookie object for a given name.</dd> 55 <dt><code>delete_cookie</code></dt> 56 <dd>This method deletes a cookie, ensuring that the information 57 within it is not exchanged in future.</dd> 58 </dl> 59 <p><a 60 href="../apidocs/public/WebStack.Helpers.Request.Cookie-class.html">Cookie</a> 61 objects can be any objects having the following properties:</p> 62 <dl> 63 <dt><code>name</code></dt> 64 <dd>This is the name associated with the cookie. It must be a plain 65 Python string.</dd> 66 <dt><code>value</code></dt> 67 <dd>This is the information stored in the cookie. It must be a plain 68 Python string.</dd> 69 </dl> 70 </div> 71 <h2>How and When to Get and Set Cookies</h2> 72 <p>Cookies which were set in previous interactions are always available 73 straight away unless they were deleted at some earlier point in time. 74 Typically, your application will have reserved a cookie name and will 75 then access the cookie using that name; for example:</p> 76 <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> 77 <p>It is possible to modify the cookie object, but on its own this has 78 no effect on the value exchanged between the application and the user. 79 To update the cookie in that way, you must also use the <code>set_cookie</code> 80 method, or instead use the <code>set_cookie_value</code> method:</p> 81 <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> 82 <p>Note that changing a cookie's value directly using <code>set_cookie_value</code> 83 will not necessarily change the value found in cookie objects returned 84 by subsequent calls to <code>get_cookie</code> during the handling 85 of the same request.</p> 86 <p>To delete cookies, actual cookie objects must be provided:</p> 87 <pre> # In the respond method after getting the cookie...<br /> trans.delete_cookie(my_cookie)</pre> 88 <p>This does not necessarily remove the cookie from the dictionary 89 returned by <code>get_cookies</code> or prevent <code>get_cookie</code> 90 returning a cookie object for the name specified in the deleted 91 cookie during the handling of the same request.</p> 92 </body> 93 </html>