This tutorial is intended to be a straight to the point and forward introduction to the python web framework Django.

If you do not have Django and Python already setup on your system, please follow this tutorial. Even though it is intended for windows, basically the same steps apply to linux and mac (Excluding the Python Installation section)

Creating a new django project

To create a new Django project simply:

1. Open the CMD/Terminal
2. CD to the place where you want your project to live
3. Type in the following command:

   django-admin.py startproject testProject

4. A folder called testProject will be created with the following structure:

   testProject/
       manage.py
       testProject/
           __init__.py
           settings.py
           urls.py
           wsgi.py

5. Run the server by executing the following:

   cd testProject
   python manage.py runserver

   You should then see the following in the console:

   Validating models...
   0 errors found.
   
   Django version 1.4, using settings 'mysite.settings'
   Development server is running at http://127.0.0.1:8000/
   Quit the server with CONTROL-C.

6. Open your browser and navigate to: http://127.0.0.1:8000/ you should see the following:
   

Setting up the database

To setup the database you must open settings.py and modify the databases section. Django supports MYSQL, SQLite, Oracale and PostgreSQL. In this tutorial we will setup a SQLite database.

1. Modify your database settings as such:

   DATABASES = {
       'default': {
           'ENGINE': 'django.db.backends.sqlite3',
           'NAME': 'database.db', # path to database file if using sqlite3.
           'USER': '',
           'PASSWORD': '',
           'HOST': '',
           'PORT': '',
       }
   }

   Please note the NAME specified above, is the path to the database file with respect to settings.py

2. To actually create the database and populate it with the corresponding tables, run this command:

   python manage.py syncdb

   What it does is create all nessascry databases and tables for all the applications specified in INSTALLED_APPS. This is found in settings.py

Creating the guestbook application

Now we have created a project called testProject and connected it to a database. We will now create an application within that project called guestbook.

1. To create a new application type in the following command:

   python manage.py startapp guestbook

   This will create an application inside testProject with the following structure:

   guestbook/
       __init__.py
       models.py
       tests.py
       views.py

2. Now open settings.py and add guestbook to the list INSTALLED_APPS:

   INSTALLED_APPS = (
       'django.contrib.auth',
       'django.contrib.contenttypes',
       'django.contrib.sessions',
       'django.contrib.sites',
       'django.contrib.messages',
       'django.contrib.staticfiles',
       'guestbook'
   )

Creating the models

For our guestbook application, we will create to models: Guestbook and Comment. Each guestbook belongs to one user and has many comments. While each comment belongs to one and only one guestbook, it has the fields: Name, time posted and content.

1. This is what models.py should look like:

   from django.db import models
   from django.contrib.auth.models import User
   
   class Guestbook(models.Model):
       owner_name = models.CharField(null = False, blank =  False, max_length = 20)
   
   class Comment(models.Model):
       content = models.CharField(null = False, blank = False, max_length = 140)
       owner_name = models.CharField(null = False, blank = False, max_length = 20)
       posted = models.DateTimeField('date Posted')
       guestbook = models.ForeignKey(Guestbook)

2. In order to see the SQL that model.py conforms to type in:

   python manage.py sql guestbook

   The output should be:

   BEGIN;
   CREATE TABLE "rating_guestbook" (
       "id" integer NOT NULL PRIMARY KEY,
       "owner_name" varchar(20) NOT NULL)
   )
   ;
   CREATE TABLE "rating_comment" (
       "id" integer NOT NULL PRIMARY KEY,
       "content" varchar(140) NOT NULL,
       "owner_name" varchar(20) NOT NULL,
       "posted" datetime NOT NULL,
       "guestbook_id" integer NOT NULL REFERENCES "rating_guestbook" ("id")
   )
   ;

3. Now we need to re-sync the databases so that the new SQL is executed:

   python manage.py syncdb

Creating your first view

Now before we starting writing code for the views. Let us first understand how views, urls and templates work.
So first a user types in a url in the address bar. The system then tries to pattern match this url against all the urls defined in urls.py. When it finds one that it conforms to it then executes the corresponding view function which is defined in urls.py. The view function then does some backend processing and renders a template. The template is the HTML that you see in your browser.

Now we know how everything works, let’s create a view that shows “Hello World”.

1. Open views.py
2. Add the following code:

   from django.template import RequestContext
   from django.shortcuts import render_to_response
   
   def home(request):
           return render_to_response('index.html', RequestContext(request))

   This is just a view method that renders the template file index.html

3. In order to use templates we must define the template directory inside settings.py. To do so we must first import the os module. Which is added at the top of settings.py.

   import os

   Now we must update the TEMPLATE_DIR as follows:

   TEMPLATE_DIRS = (
       os.path.join( os.path.dirname( __file__ ), 'templates' )
   )

   This basically states that the templates folder is in the same folder as settings.py

4. Create a folder called templates in the same folder as settings.py
5. Inside templatescreate an HTML file that says ‘Hello World!’

   <!DOCTYPE html>
   <html>
   <body>
       <h1>Hello World!</h1>
   </body>

6. Final step is to create the url that goes to this view, so open urls.py. And update it as such:

   from django.conf.urls import patterns, include, url
   
   urlpatterns = patterns('',
       url(r'^home/$', 'guestbook.views.home', name='home'),
   )

   This means that if the user types in http://127.0.0.1:8000/home/, they should see “Hello World!”

7. Restart the server and in your browser navigate to http://127.0.0.1:8000/home/ to see the effect.

GuestBook Creation View

In this view we want the user to be able to create a new guestbook by clicking a button. In order to do this, redo the steps in the previous section and change the following:

1. Change the URL to be

   url(r'^create/guestbook/$', 'guestbook.views.create_guestbook', name='create guestbook'),

2. Rename the view function name and HTML file name to something appropriate.
3. The HTML file will be updated to contain a form that takes a user’s name as input.

   <form action="/create/guestbook/" method="POST">
       {% csrf_token %}
       <label for="name">What is your name?</label>
       <input type="text" name="owner_name" />
       <input type="submit" value="create" />
   </form>

   To understand what CSRF is, and what is {% csrf_token%} please read the following links:
   https://docs.djangoproject.com/en/dev/ref/contrib/csrf/
   http://en.wikipedia.org/wiki/Cross-site_request_forgery

4. We will now write a view function called create_guestbook. If you noticed we are using the same url for viewing the form and submitting the form. This is because we can execute different code depending on the TYPE of the request. See Below:

   form models import Guestbook
   
   def create_guestbook(request):
       if request.POST:
           guestbook = Guestbook.objects.create(owner_name = request.POST['name'])
           return render_to_response('index.html', RequestContext(request))
       else:
           return render_to_response('create_guestbook.html', RequestContext(request))

5. Now try out your new code. You should see something like this:
   

Guestbook Read view

Now that we can successfully create new guestbooks. We want to be able to view all the guestbooks we have. Again we will do the same steps as the section titled “Creating your first view”. Now rename everything accordingly like the last section. And change the following:

1. In the HTML file we need to loop over all the guestbooks that appear in our database, to do this we use the {% for item in lits %} HTML here {% endfor %}template tags. This loop over a list of items, so the HTML within is re-written for each item. See code below:

   <!DOCTYPE html>
   <html>
   <body>
   <h1>Avaliable Guestbooks</h1>
   {% if guestbooks %}
       <ul>
       {% for guestbook in guestbooks %}
   	<li>{{ guestbook.owner_name }}'s Guestbook<li>
        {% endfor %}
   </ul>   
       {% else %}
           Sorry no one has created any guestbooks yet  
       {% endif %}
   </body>
   </html>

2. Make the view function fetch all the guestbook objects and render them to the template. See code below:

   def guestbooks(request):
       guestbooks = Guestbook.objects.all()
       return render_to_response('guestbooks.html', { 'guestbooks' : guestbooks },RequestContext(request))

3. Now try out your new code. You should see something like this:
   
   or
   

Single Guestbook Read/Delete View

Now that we can view all the guestbooks available on the system. We want the users to start posting some content! This part I think you can do on your own, all you need to do is show all the comments that belong to a certain guestbook, and add a create comment form.

Hints:

1. In order to access all the comments that belong to the guestbook with id = 3, simple do as follows:
   • Method 1 in views:

         guestbook = Guestbook.objects.get(id = 3)
         comments = guestbook.comment_set.all()

   • Method 2 in views:

         comments = Comment.objects.fetch(guestbook = 3)

   • In HTML:

         {{ guestbook.comment_set.all }}

2. To capture the id from a url pattern write it as follows:

   url(r'^guestbook/(\d+)/$', 'guestbook.views.guestbook', name='guestbook'),

   When you put anything between () in a url pattern, it acts as a view function input. Example:

       def guestbooks(request,id):
           pass

   Moreover url patterns are done using regular expressions. So in this case \d+ means a number of at least 1 digit.

3. To delete an object you just call the .delete()method on it. Example:

       comment = Comment.objects.get(id = 1)
       comment.delete()