image: http://djangopony.com/

.. rst-class:: build

• Persistence via the Django ORM
• CRUD content editing via the automatic Django Admin
• URL Mapping via urlpatterns
• Templating via the Django Template Language
• Caching with levels of configurability
• Internationalization via i18n hooks
• Form rendering and handling
• User authentication and authorization

Pretty much everything you need to make a solid website quickly

What is Django's killer feature

.. rst-class:: centered

The Django Admin

You write the models, it provides the UI

You've seen this in action. Pretty neat, eh?

.. rst-class:: centered

80% of the problems can be solved by 20% of the effort

The converse also holds true:

.. rst-class:: centered

Fixing the last 20% of the problems will take the remaining 80% of the effort.

Popularity translates into:

.. rst-class:: build

• Active, present community
• Plethora of good examples to be found online
• Rich ecosystem of apps (encapsulated add-on functionality)

.. rst-class:: centered

Jobs

.. rst-class:: build

• 1.9 (December 2015)
• 1.8.7 (November 2015)
• 1.7.11 (November 2015)
• 1.8.5 (October 2015)
• 1.7.10 (August 2015)
• 1.8.3 (July 2015)
• 1.8 (April 2015)
• 1.7.7 (March 2015)
• 1.7.4 (January 2014)

Django 1.8 is the second Long Term Support version, with a guaranteed support period of three years.

Led the way to better documentation for all Python

Read The Docs - built in connection with Django, sponsored by the Django Software Foundation.

Write documentation as part of your python package.

Render new versions of that documentation for every commit.

.. rst-class:: centered

this is awesome

You also took some time to get familiar with the basic workings of the Django ORM.

You made a minor modification to our model class and wrote a test for it.

And you installed the Django Admin site and added your app to it.

Let's add this feature to our blog!

To do so, we'll be adding a new model, and making some changes to existing code.

.. rst-class:: build

This means that we'll need to change our database schema.

And you've created your first migration in setting up the Post model.

This is an example of altering the database schema using Python code.

Starting in Django 1.7, this ability is available built-in to Django.

Before verson 1.7 it was available in an add-on called South.

This model will need to have:

.. rst-class:: build

• a name for the category
• a longer description
• a relationship to the Post model

# in models.py
class Category(models.Model):
    name = models.CharField(max_length=128)
    description = models.TextField(blank=True)
    posts = models.ManyToManyField(Post, blank=True,
                                   related_name='categories')

This models the situation in which a single author can have many posts, while each post has only one author.

We call this a Many to One relationship.

But any given Post might belong in more than one Category.

And it would be a waste to allow only one Post for each Category.

Enter the ManyToManyField

We use the makemigrations management command to do so:

(djangoenv)$ ./manage.py makemigrations
Migrations for 'myblog':
  0002_category.py:
    - Create model Category

(djangoenv)$ ./manage.py migrate
Operations to perform:
  Apply all migrations: sessions, contenttypes, admin, myblog, auth
Running migrations:
  Rendering model states... DONE
  Applying myblog.0002_category... OK

You can even look at the migration file you just applied, myblog/migrations/0002_category.py to see what happened.

add this to tests.py:

# another import
from myblog.models import Category

# and the test case and test
class CategoryTestCase(TestCase):

    def test_string_representation(self):
        expected = "A Category"
        c1 = Category(name=expected)
        actual = str(c1)
        self.assertEqual(expected, actual)

(djangoenv)$ ./manage.py test myblog
Creating test database for alias 'default'...
...

Ran 2 tests in 0.011s

FAILED (failures=1)

Do you remember how you made that change for a Post?

class Category(models.Model):
    #...

    def __str__(self):
        return self.name

Simply add the following line to myblog/admin.py

# a new import
from myblog.models import Category

# and a new admin registration
admin.site.register(Category)

Point your browser at http://localhost:8000/admin/, log in and play.

Add a few categories, put some posts in them. Visit your posts, add new ones and then categorize them.

What do you see?

Why?

We need to add some public pages for our blog.

In Django, the code that builds a page that you can see is called a view.

This should sound pretty familiar to you.

Classically, Django views were functions.

Version 1.3 added support for Class-based Views (a class with a __call__ method is a callable)

It will be a stub for our public UI. Add this to views.py in myblog

from django.http import HttpResponse, HttpResponseRedirect, Http404

def stub_view(request, *args, **kwargs):
    body = "Stub View\n\n"
    if args:
        body += "Args:\n"
        body += "\n".join(["\t%s" % a for a in args])
    if kwargs:
        body += "Kwargs:\n"
        body += "\n".join(["\t%s: %s" % i for i in kwargs.items()])
    return HttpResponse(body, content_type="text/plain")

We used our project urlconf to hook the Django admin into our project.

We want to do the same thing for our new app.

In general, an app that serves any sort of views should contain its own urlconf.

The project urlconf should mainly include these where possible.

Open it in your editor and add the following code:

from django.conf.urls import url
from myblog.views import stub_view

urlpatterns = [
    url(r'^$',
        stub_view,
        name="blog_index"),
]

Open urls.py from the mysite project package and add this:

# add this new import
from django.conf.urls import include

# then modify urlpatterns as follows:
urlpatterns = [
    url(r'^', include('myblog.urls')), #<- add this
    #... other included urls
]

Try reloading http://localhost:8000/

You should see some output now.

What should our users be able to see when they visit our blog?

.. rst-class:: build

• A list view that shows blog posts, most recent first.
• An individual post view, showing a single post (a permalink).

Let's add urls for each of these.

For now, we'll use the stub view we've created so we can concentrate on the url routing.

For the view of a single post, we'll need to capture the id of the post. Add this to urlpatterns in myblog/urls.py:

url(r'^posts/(\d+)/$',
    stub_view,
    name="blog_detail"),

(\d+) captures one or more digits as the post_id.

Load http://localhost:8000/posts/1234/ and see what you get.

Try changing the route like so:

r'^posts/(?P<post_id>\d+)/$'

Reload the same url.

Notice the change.

What's going on there?

Unlike Pyramid, Django requires regular expressions to capture segments in a route.

When we built our WSGI book app, we used this same appraoch.

There we learned about regular expression capture groups. We just changed an unnamed capture group to a named one.

How you declare a capture group in your url pattern regexp influences how it will be passed to the view callable.

We'll need tests for a list view and a detail view

add the following imports at the top of myblog/tests.py:

import datetime
from django.utils.timezone import utc

But in this blog, we have the ability to publish posts.

Unpublished posts should not be seen in the front-end views.

We set up our tests to have 5 published, and 5 unpublished posts

Let's add a test to demonstrate that the right ones show up.

We test first to ensure that each published post is visible in our view.

Note that we also test to ensure that the unpublished posts are not visible.

We begin by using the QuerySet API to fetch all the posts that have published_date set

Using the chaining nature of the API we order these posts by published_date

Remember, at this point, no query has actually been issued to the database.

Django uses configuration to determine how to find templates.

By default, Django looks in installed apps for a templates directory

It also provides a place to list specific directories.

Let's set that up in settings.py

In that same file, you'll find a list bound to the symbol TEMPLATES.

That list contains one dict with an empty list at the key DIRS. Update that empty list as shown here:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [os.path.join(BASE_DIR, 'mysite/templates')],
        ...
    },
]

This will ensure that Django will look in your mysite project folder for a directory containing templates.

Then, in that directory add a new file base.html and add the following:

<!DOCTYPE html>
<html>
  <head>
    <title>My Django Blog</title>
  </head>
  <body>
    <div id="container">
      <div id="content">
      {% block content %}
       [content will go here]
      {% endblock %}
      </div>
    </div>
  </body>
</html>

We've seen Jinja2 which was "inspired by Django's templating system".

Basically, you already know how to write Django templates.

Django templates do not allow any python expressions.

https://docs.djangoproject.com/en/1.9/ref/templates/builtins/

This template is probably specific to the blog functionality of our site

It is common to keep shared templates in your project directory and specialized ones in app directories.

Add a templates directory to your myblog app, too.

In it, create a new file list.html and add this:

Like Jinja2, django templates are rendered by passing in a context

Django's RequestContext provides common bits, similar to the context provided automatically by Pyramid

We add our posts to that context so they can be used by the template.

Finally, we build an HttpResponse and return it.

This is, fundamentally, no different from the stub_view just above.

Update urls.py in myblog:

# import the new view
from myblog.views import list_view

# and then update the urlconf
url(r'^$',
    list_view,  #<-- Change this value from stub_view
    name="blog_index"),

Then run your tests again:

(djangoenv)$ ./manage.py test myblog
...
Ran 3 tests in 0.033s

OK

So common in fact that Django provides a shortcut for us to use:

render(request, template[, ctx][, ctx_instance])

It will need to get the id of the post to show as an argument

Like the list view, it should only show published posts

But unlike the list view, it will need to return something if an unpublished post is requested.

Let's start with the tests in views.py

This exception is actually an attribute of the Model you look for.

There's also an ObjectDoesNotExist for when you don't know which model you have.

We can use that fact to raise a Not Found exception.

Django will handle the rest for us.

We can use the url template tag (like Pyramid's request.route_url):

{% url '<view_name>' arg1 arg2 %}

In our list.html template, let's link the post titles:

{% for post in posts %}
<div class="post">
  <h2>
    <a href="{% url 'blog_detail' post.pk %}">{{ post }}</a>
  </h2>
  ...

Reload your blog index page and click around a bit.

You can now move back and forth between list and detail view.

Try loading the detail view for a post that doesn't exist

It's not very pretty, though.

We can fix that by adding some css

This gives us a chance to learn about Django's handling of static files

It will look for them in a directory named static in any installed apps.

They will be served from the url path in the STATIC_URL setting.

By default, this is /static/

To allow Django to automatically build the correct urls for your static files, you use a special template tag:

{% static <filename> %}

Create a new directory static in the myblog app.

Copy the django_blog.css file into that new directory.

{% load staticfiles %}

<title>My Django Blog</title> <!-- This is already present -->
<link type="text/css" rel="stylesheet" href="{% static 'django_blog.css' %}">

We now have a reasonable view of the posts of our blog on the front end

And we have a way to create and categorize posts using the admin

However, we lack a way to move between the two.

Let's add that ability next.

This gives us access to user in our templates

It provides access to methods about the state and rights of that user

We can use these to conditionally display links or UI elements. Like only showing the admin link to staff members.

The first step to using them is to hook them into a urlconf.

# add an import at the top
from django.contrib.auth.views import login, logout

# and update the list of urlconfs
url(r'^', include('myblog.urls')), #<- already there
url(r'^login/$',
    login,
    {'template_name': 'login.html'},
    name="login"),
url(r'^logout/$',
    logout,
    {'next_page': '/'},
    name="logout"),

Data is being sent to our application from some remote place

If that data is going to alter the state of our application, we must use POST

Even so, we are vulnerable to Cross-Site Request Forgery, a common attack vector.

In fact, for POST requests, it requires that you use it.

The Django middleware that does this is enabled by default.

All you need to do is include the {% csrf_token %} tag in your form.

However, learning more about them is beyond what we can achieve in this session.

The form system in Django is quite nice, however. I urge you to read more about it

In particular, you might want to pay attention to the documentation on Model Forms

If you fell behind at some point, the app as it now stands is in our class resources as mysite_stage_3.

There's much more we could do with this app. And for homework, you'll do some of it.

Then next session, we'll work together as pairs to implement a simple feature to extend the blog

As you created new categories and posts, and related them to each-other, how did you feel about that work?

Although from a data perspective, the category model is the right place for the ManytoMany relationship to posts, this leads to awkward usage in the admin.

It would be much easier if we could designate a category for a post from the Post admin.

Take the following steps:

1. Read the documentation about the Django admin.
2. You'll need to create a customized ModelAdmin class for the Post and Category models.
3. And you'll need to create an InlineModelAdmin to represent Categories on the Post admin view.
4. Finally, you'll need to exclude the 'posts' field from the form in your Category admin.

The trick of course is reading and finding out which fifteen lines to write.

If you complete that task in less than 3-4 hours of work, consider looking into other ways of customizing the admin.