Create and run your first Django project

Before you start

Creating a new project

Exploring project structure

Launching Django server

Creating a model

Django models define the fields and behaviors of your data. They are represented by Python classes, which are subclasses of the django.db.models.Model class.

Let's create a ToDoItem model for our to-do app. To do that, open todo/models.py, and fill it with the following code:

from django.db import models
from django.utils import timezone


class ToDoItem(models.Model):
    text = models.CharField(max_length=100)
    due_date = models.DateField(default=timezone.now)

Running migrations

By default, PyCharm automatically creates an SQLite database for a Django project. We need to create tables in the database for the todo application and the ToDoItem model. In Django, that's done by using migrations. Migrations are human-editable files, in which changes to data models are stored.

Writing a view

from django.views.generic import ListView
from .models import ToDoItem


class AllToDos(ListView):
    model = ToDoItem
    template_name = "todo/index.html"

Here we've defined the AllToDos class which inherits from the Django ListView basic view class. We'll use this view to display all available to-do's.

Creating a template

You can see that todo/index.html in views.py is highlighted as an unresolved reference:

PyCharm suggests a quick-fix: if you hover over index.html or press, you can choose to create the corresponding template file in the templates folder:

PyCharm creates and opens todo/index.html. To fill it with some basic html code, type html:5 followed by:

Let's add the content with the Django template language elements to the template. Paste the following code between the body tags:

<h1>Things to do:</h1>
<table>
    {% for item in object_list %}
    <tr>
        <td>{{ item.text }}</td>
        <td>{{ item.due_date }}</td>
    </tr>
    {% endfor %}
</table>

There's an h1 heading and a table. We're using a for cycle to iterate through the items of object_list which will be passed from the AllToDos view. For each item, Django will render a row in the table containing the values of text and due_date.

Configuring urls

Now we need to configure the way how we will access the AllToDos view in the browser.

In the todo directory, create the file urls.py and fill it with the following code:

from django.urls import path
from . import views

urlpatterns = [
    path("", views.AllToDos.as_view(), name="index")
]

Next, open the file myDjangoProject/urls.py (which PyCharm has already created for you) and configure it to include the paths from todo/urls.py. You should end up with the following code:
```
from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path("todo/", include("todo.urls")),
    path("admin/", admin.site.urls),
]
```
Don't forget to import django.urls.include!
Open the page http://127.0.0.1:8000/todo/ in your browser. You should see the following text:

Using Django admin

After you log in, the administration page is displayed. It has the Authentication and Authorization (Groups and Users) section, but there's no way to add to-do's. To be able to do that, we must register the ToDoItem model in the admin interface.

Adding content

Open the file todo/admin.py, and type the following code:

from django.contrib import admin
from .models import ToDoItem


admin.site.register(ToDoItem)

Refresh the page in the browser. The TODO section with To do items should appear:
Click Add to create a to-do:
When you a ready, click SAVE.

The newly created to-do appears in the list as ToDoItem object (1). Such naming makes content management complicated, as you have to open each task to read its description.

Let's fix that by adding a __str__() method to the ToDoItem model. Open todo/models.py and add the following:

def __str__(self):
    return f"{self.text}: due {self.due_date}"

from django.db import models
from django.utils import timezone


class ToDoItem(models.Model):
    text = models.CharField(max_length=100)
    due_date = models.DateField(default=timezone.now)

    def __str__(self):
        return f"{self.text}: due {self.due_date}"

Providing features

Go to views.py and add the TodayToDos class with the following code:

class TodayToDos(ListView):
    model = ToDoItem
    template_name = "todo/today.html"

    def get_queryset(self):
        return ToDoItem.objects.filter(due_date=date.today())

This class is very similar to AllToDos, except that it uses another template (which we will create later) and implements the get_queryset method to return only those ToDoItem objects whose due_date is today.

date should be highlighted with a red squiggly line. Hover over it, click Import this name, and select datetime.date to add the corresponding import statement at the beginning of the file.

Create base.html in myDjangoProject/templates by right-clicking templates in the Project tool window and selecting New | HTML File from the context menu.

Copy the code from index.html into base.html, and then replace everything between the <body> tags with the following:

{% block content %}{% endblock %}

This is what myDjangoProject/templates/base.html should look like:

<!doctype html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <meta name="viewport"
              content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
        <meta http-equiv="X-UA-Compatible" content="ie=edge">
        <title>Document</title>
    </head>
    <body>
        {% block content %}{% endblock %}
    </body>
</html>

Go to index.html, remove everything except the contents of the <h1> and <table> tags, and then enclose them in the Django template language elements as follows:

{% extends "base.html" %}
{% block content %}
    <h1>Things to do:</h1>
    <table>
        {% for item in object_list %}
        <tr>
            <td>{{ item.text }}</td>
            <td>{{ item.due_date }}</td>
        </tr>
        {% endfor %}
    </table>
{% endblock %}

Create myDjangoProject/templates/todo/today.html and fill it with the following code:

{% extends "base.html" %}
{% block content %}
    <h1>Things to do today:</h1>
    <table>
        {% for item in object_list %}
        <tr>
            <td>{{ item.text }}</td>
        </tr>
        {% endfor %}
    </table>
{% endblock %}

Note that we don't need due dates here, because this page display only those to-do's whose due dates are today.

We also need to configure the way we will access the today's tasks in the browser. Go to myDjangoProject/todo/urls.py and add path("today/", views.TodayToDos.as_view(), name="today") to urlpatterns to get the following:

from django.urls import path
from . import views

urlpatterns = [
    path("", views.AllToDos.as_view(), name="index"),
    path("today/", views.TodayToDos.as_view(), name="today")
]

Improving the experience

The easiest way to improve the look of an html page is to implement CSS. For example, we can use Simple CSS. Open base.html and put the following line anywhere between the <head> tags:

<link rel="stylesheet" href="https://cdn.simplecss.org/simple.min.css">

Now let's add some navigation elements to avoid typing addresses in the browser's address bar. In base.html, paste the following code after the opening <body> tag:

<div>
    <a class="button" href='{% url "index" %}'>All tasks</a>
    <a class="button" href='{% url "today" %}'>Today</a>
</div>

Testing the application

from datetime import date, timedelta

from django.test import TestCase
from django.urls import reverse
from .models import ToDoItem


def create_todo(todo_text, days):
    return ToDoItem.objects.create(text=todo_text, due_date=date.today() + timedelta(days=days))


class AllToDosViewTest(TestCase):

    def test_today(self):
        todo = create_todo("To be done today", 0)
        response = self.client.get(reverse("index"))
        self.assertQuerySetEqual(
            response.context["todoitem_list"],
            [todo]
        )

    def test_last_week(self):
        todo = create_todo("This task is past due", -7)
        response = self.client.get(reverse("index"))
        self.assertQuerySetEqual(
            response.context["todoitem_list"],
            []
        )

    def test_next_week(self):
        todo = create_todo("Still have some time", 7)
        response = self.client.get(reverse("index"))
        self.assertQuerySetEqual(
            response.context["todoitem_list"],
            [todo]
        )

Here, create_todo is a shortcut function to create a to-do and AllToDosViewTest is a test class with 3 methods: test_today, test_last_week, test_next_week. Each method creates a task with the corresponding due date, and then checks if the task is rendered on the application's home page. The task whose due date was 7 days before the current date shouldn't be displayed.

You can see that test_last_week has failed, because the created to-do is added to the list of items that will be displayed on the home page despite being past due.

Let's fix it by adding the get_queryset method to the AllToDos class:

def get_queryset(self):
    return ToDoItem.objects.filter(due_date__gte=date.today())

The method will filter the objects, so that the view returns only those tasks whose due dates are greater than or equal to today's date (this is what __gte stands for).

Create and run your first Django project﻿

Before you start﻿

Creating a new project﻿

Exploring project structure﻿

Launching Django server﻿

Creating a model﻿

Running migrations﻿

Writing a view﻿

Creating a template﻿

Configuring urls﻿

Using Django admin﻿

Setting up an admin site﻿

Adding content﻿

Providing features﻿

Improving the experience﻿

Testing the application﻿

Summary﻿