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