.. _cookie-label:


Working with Sessions/Cookies in Django
==============================

Django provides a session framework that lets you store and retrieve data on a per-site-visitor basis. Django abstracts the process of sending and receiving cookies, by placing a session ID cookie on the client side, and storing all the related data on the server side. So the data itself is not stored client side. This is nice from a security perspective.

Also since the Django sessions framework is cookie-based, session IDs are not put in the URLs (as is often the case with PHP). According to the Django documentation this was an intentional design decision, which means that URLs remain clean and the site is less vulnerable to session ID theft via the "Referer" header.


Setting up Sessions
-------------------
To enable the session functionality, you'll need to make sure that the MIDDLEWARE_CLASSES in settings.py has 'django.contrib.sessions.middleware.SessionMiddleware' activated. 

There are different ways in which you can configure the session engine which controls how it stores sessions, i.e. in a database or in a cache. The simplest way is to use the default option and store the data in a model/database (i.e. django.contrib.sessions.models.Session), is by adding 'django.contrib.sessions'  to your INSTALLED_APPS.

You will have to run *python manage.py syncdb* to create the session database table.


Testing Cookies
---------------
To test out whether cookies work on your client, you can use some convenience methods provided by Django's request object (set_test_cookie(), test_cookie_worked(), delete_test_cookie() ). In one view you will need to set a cookie and in another view you'll need to test it. The reason you need to set the cookie in one view and test it in another is that you need to wait to see if the client has actually accepted the cookie.

In views.py, set the test cookie in the *index* view, and test the cookie in your *about* view. 

::

	def index(request):
		
		...
		
		request.session.set_test_cookie()
		
		...


	def about(request):
	
		...
		
		if request.session.test_cookie_worked():
			print "The test cookie worked!!!"
			request.session.delete_test_cookie()
		
		...
		

Visit the index page, and then visit the about page. Examine the output in the console, hopefully, you'll see that "The test cookie worked!!!" has been printed out to the console.


Add and Using Cookies
---------------------

TODO(leifos): complete this subsection



Browser-length sessions vs. persistent sessions
You can control whether the session framework uses browser-length sessions vs. persistent sessions with the SESSION_EXPIRE_AT_BROWSER_CLOSE setting.

By default, SESSION_EXPIRE_AT_BROWSER_CLOSE is set to False, which means session cookies will be stored in users' browsers for as long as SESSION_COOKIE_AGE. Use this if you don't want people to have to log in every time they open a browser.

If SESSION_EXPIRE_AT_BROWSER_CLOSE is set to True, Django will use browser-length cookies -- cookies that expire as soon as the user closes his or her browser. Use this if you want people to have to log in every time they open a browser.

This setting is a global default and can be overwritten at a per-session level by explicitly calling the set_expiry() method of request.session as described above in using sessions in views.