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