Building Web Applications with Django and AngularJS

Learning Django and AngularJS

In this tutorial you will build a simplified Google+ clone called “Not Google Plus” with Django and AngularJS.

Before we hit the proverbial books and learn to build a rich, modern web application with Django and Angular, let's take a moment to explore the motivations behind this tutorial and how you can get the most out of it.

What is the goal of this tutorial?

Here at Thinkster, we strive to create high value, in depth content while maintaining a low barrier to entry. We release this content for free with the hope that you find it both exciting as well as informative.

Each tutorial we release has a specific goal. In this tutorial, that goal is to give you a brief overview of how Django and AngularJS play together and how these technologies can be combined to build amazing web applications. Furthermore, we place a heavy emphasis on building good engineering habits. This includes everything from considering the tradeoffs that come from making architectural decisions, to maintaining high quality code throughout your project. While these things may not sound like fun, they are key to becoming a well-rounded software developer.

Who is this tutorial for?

Every author must answer this difficult question. Our goal is to make this tutorial useful for novices as well as experienced developers.

For those of you who are in the early days of your software development careers, we have tried to be thorough and logical in our explanations as possible, while still making the text flow fluidly; we try to avoid making intuitive leaps where doing so makes sense.

For those of you who have been around the block a few times, and perhaps are just interested in learning more about Django or AngularJS, we know you don't need the basics explained to you. One of our goals when writing this tutorial was to make it easy to skim. This allows you to use your existing knowledge to speed up the reading process and identify where unfamiliar concepts are presented so you can grok them quickly and move on.

We want to make this tutorial accessible to anyone with enough interest to take the time necessary to learn and understand the concepts presented.

A brief interlude about formatting

Throughout this tutorial, we strive to maintain consistent formatting. This section details what that formatting looks like and what it means.

When presenting a new code snippet, we will present the snippet in it's entirety and then walk through it line-by-line as necessary to cover new concepts.

A humble request for feedback

At the risk of sounding cliche, we would not have a reason to make this tutorial if not for you. Because we believe that your success is our success, we invite you to contact us with any thoughts you have about the tutorial. You can reach us via Twitter at @jamesbrwr or @GoThinkster, or by emailing support@thinkster.io.

We welcome criticism openly and accept praise if you believe it is warranted. We're interested in knowing what you like, what you don't like, what you want to know more about, and anything else you feel is relevant.

If you are too busy to reach out to us, that's OK. We know that learning takes a lot of work. If, on the other hand, you want to help us build something amazing, we await your mail.

A final word before we begin

It is our experience that the developers who gain the most from our tutorials are the ones who take an active approach to their learning.

We strongly recommend you type out the code for yourself. When you copy and paste code, you don’t interact with it and that interaction is in turn what makes you a better developer.

In addition to typing the code yourself, do not be afraid to get your hands dirty; jump in and play around, break things and build missing features. If you encounter a bug, explore and figure out what is causing it. These are the obstacles we as engineers must tackle multiple times a day, and have thus learned to embrace these explorations as the best source of learning.

Let's build some software.

Setting up your environment

The application we will be building requires a non-trivial amount of boilerplate. Instead of spending time setting up your environment, which is not the purpose of this tutorial, we have created a boilerplate project to get you started.

Checkpoint

If all went well running the server with python manage.py runserver should allow you to visit http://localhost:8000/ in your browser. The page will be blank except for the navigation bar at the top. The links in the navigation bar currently do nothing.

Extending Django's built-in User model

Django has a built-in User model that offers a lot of functionality. The problem with User is that the model cannot be extended to include more information. For example, we will be giving our users a tagline to display on their profile. User does not have a tagline attribute and we cannot add one ourselves.

User inherits from AbstractBaseUser. That is where User gets most of it's functionality. By creating a new model called Account and inheriting from AbstractBaseUser, we will get the necessary functionality of User (password hashing, session management, etc) and be able to extend Account to include extra information, such as a tagline.

In Django, the concept of an "app" is used to organize code in a meaningful way. An app is a module that houses code for models, view, serializers, etc that are all related in some way. By way of example, our first step in building our Django and AngularJS web application will be to create an app called authentication. The authentication app will contain the code relevent to the Account model we just talked about as well as views for logging in, logging out and register.

Make a new app called authentication by running the following command:

$ python manage.py startapp authentication

Creating the Account model

To get started, we will create the Account model we just talked about.

Open authentication/models.py in your favorite text editor and edit it to reflect the following:

Django's built-in User requires a username. That username is used for logging the user in. By contrast, our application will use the user's email address for this purpose.

To tell Django that we want to treat the email field as the username for this model, we set the USERNAME_FIELD attribute to email. The field specified by USERNAME_FIELD must be unique, so we pass the unique=True argument in the email field.

username = models.CharField(max_length=40, unique=True)

Even though we will log in with our email address, we still want the user to have a username. We need some to display on their posts and profile page. We will also use the username in our URLs, so the username must be unique. To this end, we pass the unique=True argument in the username field.

Ideally we should have a more personal way to reference our users. Because we understand that not all users are comfortable giving out their personal details, we make the first_name and last_name fields optional by passing the blank=True argument.

tagline = models.CharField(max_length=140, blank=True)

As mentioned before, the tagline attribute will be displayed on the user's profile. This gives the profile a hint of the user's personally, so it is worth including.

The created_at field records the time that the Account object was created. By passing auto_now_add=True to models.DateTimeField, we are telling Django that this field should be automatically set when the object is created and non-editable after that.

Similar to created_at, updated_at is automatically set by Django. The difference between auto_now_add=True and auto_now=True is that auto_now=True causes the field to update each time the object is saved.

objects = AccountManager()

When you want to get a model instance in Django, you use an expression of the form Model.objects.get(**kwargs). The objects attribute here is a Manager class whose name typically follows the <model name>Manager convention. In our case, we will create an AccountManager class. We will do this momentarily.

REQUIRED_FIELDS = ['username']

We will be displaying the username in multiple places. To this end, having a username is not optional, so we include it in the REQUIRED_FIELDS list. Normally the required=True argument would accomplish this goal, but because this model is replacing the User model, Django requires us to specify required fields in this way.

def __unicode__(self):
return self.email

When working in the shell, as we will see shortly, the default string representation of an Account object looks something like <Account: Account>. Because we will have many different accounts, this is not very helpful. Overwriting __unicode__() will change this default behavior. Here we choose to show the user's email instead. The string representation of an account with the email james@notgoogleplus.com will now look like <Account: james@notgoogleplus.com>.

Since we haven't defined a model attribute on the AccountManager class, self.model refers to the model attribute of BaseUserManager. This defaults to settings.AUTH_USER_MODEL, which we will change in just a moment to point to the Account class.

Writing the same thing more than once sucks. Instead of copying all of the code from create_account and pasting it in create_superuser, we simply let create_user handle the actual creation. This frees up create_superuser to only worry about turning an Account into a superuser.

Changing the Django AUTH_USER_MODEL setting

Even though we have created this Account model, the command python manage.py createsuperuser (which we will talk more about shortly) still creates User objects. This is because, at this point, Django still believes that User is the model we want to use for authentication.

To set things straight and start using Account as our authentication model, we have to update settings.AUTH_USER_MODEL.

Open thinkster_django_angular_tutorial/settings.py and add the following to the end of the file:

AUTH_USER_MODEL = 'authentication.Account'

This line tells Django to look in the authentication app and find a model named Account.

Installing your first app

In Django, you must explicitly declare which apps are being used. Since we haven't added our authentication app to the list of installed apps yet, we will do that now.

Open thinkster_django_angular_boilerplate/settings.py and append 'authentication', to INSTALLED_APPS like so:

INSTALLED_APPS = (
...,
'authentication',
)

Migrating your first app

When Django 1.7 was released, it was like Christmas in September! Migrations had finally arrived!

Anyone with a background in Rails will find the concept of migrations familiar. In short, migrations handle the SQL needed to update the schema of our database so you don't have to. By way of example, consider the Account model we just created. These models need to be stored in the database, but our database doesn't have a table for Account objects yet. What do we do? We create our first migration! The migration will handle adding the tables to the database and offer us a way to rollback the changes if we make a mistake.

When you're ready, generate the migrations for the authentication app and apply them:

{info}
From now on, the output from migration commands will not be included for brevity.

Making yourself a superuser

Let's talk more about the python manage.py createsuperuser command from a few minutes ago.

Different users have different levels of access in any given application. Some users are admins and can do anywhere, while some are just regular users whose actions should be limited. In Django, a super user is the highest level of access you can have. Because we want the ability to work will all facets of our application, we will create a super user. That is what python manage.py createsuperuser does.

After running the command, Django will prompt you for some information and create an Account with superuser access. Go ahead and give it a try.

$ python manage.py createsuperuser

Checkpoint

To make sure everything is properly configured, let's take a quick break and open Django's shell:

$ python manage.py shell

You should see a new prompt: >>>. Inside the shell, we can get the Account we just created like so:

If everything went well, you should be able to access the various attributes of your Account object:

>>> a
>>> a.email
>>> a.username

Serializing the Account Model

The AngularJS application we are going to build will make AJAX requests to the server to get the data it intends to display. Before we can send that data back to the client, we need to format it in a way that the client can understand; in this case, we choose JSON. The process of transforming Django models to JSON is called serialization and that is what we will talk about now.

As the model we want to serialize is called Account, the serializer we will create is going to be called AccountSerializer.

Django REST Framework

As part of the boilerplate project you cloned earlier, we have included a project called Django REST Framework. Django REST Framework is a toolkit that provides a number of features common to most web applications, including serializers. We will make use of these features throughout the tutorial to save us both time and frustration. Our first look at Django REST Framework starts here.

Instead of including password in the fields tuple, which we will talk about in a few minutes, we explicitly define the field at the top of the AccountSerializer class. The reason we do this is so we can pass the required=False argument. Each field in fields is required, but we don't want to update the user's password unless they provide a new one.

confirm_pssword is similar to password and is used only to make sure the user didn't make a typo on accident.

Also note the use of the write_only=True argument. The user's password, even in it's hashed and salted form, should not be visible to the client in the AJAX response.

class Meta:

The Meta sub-class defines metadata the serializer requires to operate. We have defined a few common attributes of the Meta class here.

model = Account

Because this serializers inherits from serializers.ModelSerializer, it should make sense that we must tell it which model to serialize. Specifying the model creates a guarantee that only attributes of that model or explicitly created fields can be serialized. We will cover serializing model attributes now and explicitly created fields shortly.

The fields attribute of the Meta class is where we specify which attributes of the Account model should be serialized. We must be careful when specifying which fields to serialize because some fields, like is_superuser, should not be available to the client for security reasons.

read_only_fields = ('created_at', 'updated_at',)

If you recall, when we created the Account model, we made the created_at and updated_at fields self-updating. Because of this feature, we add them to a list of fields that should be read-only.

Earlier we mentioned that we sometimes want to turn JSON into a Python object. This is called deserialization and it is handled by the .create() and .update() methods. When creating a new object, such as an Account, .create() is used. When we later update that Account, .update() is used.

We will let the user update their username and tagline attributes for now. If these keys are present in the arrays dictionary, we will use the new value. Otherwise, the current value of the instance object is used. Here, instance is of type Account.

Before updating the user's password, we need to confirm they have provided values for both the password and password_confirmation field. We then check to make sure these two fields have equivelant values.

After we verify that the password should be updated, we must use Account.set_password() to perform the update. Account.set_password() takes care of storing passwords in a secure way. It is important to note that we must explicitly save the model after updating the password.

{info}
This is a naive implementation of how to validate a password. I would not recommend using this in a real-world system, but for our purposes this does nicely.

update_session_auth_hash(self.context.get('request'), instance)

When a user's password is updated, their session authentication hash must be explicitly updated. If we don't do this here, the user will not be authenticated on their next request and will have to log in again.

Checkpoint

By now we should have no problem seeing the serialized JSON of an Account object. Open up the Django shell again by running python manage.py shell and try typing the following commands:

Registering new users

At this point we have the models and serializers needed to represent users. Now we need to build an authentication system. This involves creating the various views and interfaces for registering, logging in and logging out. We will also touch on an Authentication service with AngularJS and a few different controllers.

Because we can't log in users that don't exist, it makes sense to start with registration.

To register a user, we need an API endpoint that will create an Account object, an AngularJS service to make an AJAX request to the API and a registration form. Let's make the API endpoint first.

Making the account API viewset

Open authentication/views.py and replace it's contents with the following code:

Django REST Framework offers a feature called viewsets. A viewset, as the name implies, is a set of views. Specifically, the ModelViewSet offers an interface for listing, creating, retrieving, updating and destroying objects of a given model.

Here we define the query set and the serialzier that the viewset will operate on. Django REST Framework uses the specified queryset and serializer to perform the actions listed above. Also note that we specify the lookup_field attribute. As mentioned earlier, we will use the username attribute of the Account model to look up accounts instead of the id attribute. Overriding lookup_field handles this for us.

The only user that should be able to call dangerous methods (such as update() and delete()) is the owner of the account. We first check if the user is authenticated and then call a custom permission that we will write in just a moment. This case does not hold when the HTTP method is POST. We want to allow any user to create an account.

If the HTTP method of the request ('GET', 'POST', etc) is "safe", then anyone can use that endpoint.

When you create an object using the serializer's .save() method, the object's attributes are set literally. This means that a user registering with the password 'password' will have their password stored as 'password'. This is bad for a couple of reasons: 1) Storing passwords in plain text is a massive security issue. 2) Django hashes and salts passwords before comparing them, so the user wouldn't be able to log in using 'password' as their password.

We solve this problem by overriding the .create() method for this viewset and using Account.objects.create_user() to create the Account object.

Making the IsAccountOwner permission

Let's create the IsAccountOwner() permission from the view we just made.

Create a file called authentication/permissions.py with the following content:

This is a pretty basic permission. If there is a user associated with the current request, we check whether that user is the same object as account. If there is no user associated with this request, we simply return False.

Adding an API endpoint

Now that we have created the view, we need to add it to the URLs file. Open thinkster_django_angular_boilerplate/urls.py and update it to look like so:

{info}
It is very important that the last URL in the above snippet always be the last URL. This is known as a passthrough or catch-all route. It accepts all requests not matched by a previous rule and passes the request through to AngularJS's router for processing. The order of other URLS is normally insignificant.

An Angular service for registering new users

With the API endpoint in place, we can create an AngularJS service that will handle communication between the client and the server.

Make a file in static/javascripts/authentication/services/ called authentication.service.js and add the following code:

{info}
Feel free to leave the comments out of your own code. It takes a lot of time to type them all out!

AngularJS supports the use of modules. Modularization is a great feature because it promotes encapsulation and loose coupling. We make thorough use of Angular's module system throughout the tutorial. For now, all you need to know is that this service is in the thinkster.authentication.services module.

.factory('Authentication', Authentication);

This line registers a factory named Authentication on the module from the previous line.

function Authentication($cookies, $http) {

Here we define the factory we just registered. We inject the $cookies and $http services as a dependency. We will be using $cookies later.

var Authentication = {
register: register
};

This is personal preference, but I find it's more readable to define your service as a named object and then return it, leaving the details lower in the file.

function register (username, password, email) {

At this point, the Authentication service has only one method: register, which takes a username, password, and email. We will add more methods to the service as we move forward.

As mentioned before, we need to make an AJAX request to the API endpoint we made. As data, we include the username, password and email parameters this method received. We have no reason to do anything special with the response, so we will let the caller of Authentication.register handle the callback.

Making an interface for registering new users

Let's begin creating the interface users will use to register. Begin by creating a file in static/templates/authentication/ called register.html with the following content:

We won't go into much detail this time because this is pretty basic HTML. A lot of the classes come from Bootstrap, which is included by the boilerplate project. There are only two lines that we are going to pay attention to:

<form role="form" ng-submit="vm.register()">

This is the line responsible for calling $scope.register, which we set up in our controller. ng-submit will call vm.register when the form is submitted. If you have used Angular before, you are probably used to using $scope. In this tutorial, we choose to avoid using $scope where possible in favor of vm for ViewModel. See the Controllers section of John Papa's AngularJS Style Guide for more on this.

On each <input />, you will see another directive, ng-model. ng-model is responsible for storing the value of the input on the ViewModel. This is how we get the username, password, and email when vm.register is called.

Controlling the interface with RegisterController

With a service and interface in place, we need a controller to hook the two together. The controller we create, RegisterController will allow us to call the register method of the Authentication service when a user submits the form we've just built.

Create a file in static/javascripts/authentication/controllers/ called register.controller.js and add the following:

Angular, like just about any framework you can imagine, allows you to edit it's configuration. You do this with a .config block.

function config($routeProvider) {

Here, we are injecting $routeProvider as a dependency, which will let us add routing to the client.

$routeProvider.when('/register', {

$routeProvider.when takes two arguments: a path and an options object. Here we use /register as the path because thats where we want the registration form to show up.

controller: 'RegisterController',
controllerAs: 'vm',

One key you can include in the options object is controller. This will map a certain controller to this route. Here we use the RegisterController controller we made earlier. controllerAs is another option. This is required to use the vm variable. In short, we are saying that we want to refer to the controller as vm in the template.

templateUrl: '/static/templates/authentication/register.html'

The other key we will use is templateUrl. templateUrl takes a string of the URL where the template we want to use for this route can be found.

}).otherwise('/');

We will add more routes as we move forward, but it's possible a user will enter a URL that we don't support. When this happens, $routeProvider.otherwise will redirect the user to the path specified; in this case, '/'.

Setting up AngularJS modules

Let us quickly discuss modules in AngularJS.

In Angular, you must define modules prior to using them. So far we need to define thinkster.authentication.services, thinkster.authentication.controllers, and thinkster.routes. Because thinkster.authentication.services and thinkster.authentication.controllers are submodules of thinkster.authentication, we need to create a thinkster.authentication module as well.

Create a file in static/javascripts/authentication/ called authentication.module.js and add the following:

This syntax defines the module thinkster.authentication with thinkster.authentication.controllers and thinkster.authentication.services as dependencies.

angular
.module('thinkster.authentication.controllers', []);

This syntax defines the module thinkster.authentication.controllers with no dependencies.

Now we need define to include thinkster.authentication and thinkster.routes as dependencies of thinkster.

Open static/javascripts/thinkster.js, define the required modules, and include them as dependencies of the thinkster module. Note that thinkster.routes relies on ngRoute, which is included with the boilerplate project.

Hash routing

By default, Angular uses a feature called hash routing. If you've ever seen a URL that looks like www.google.com/#/search then you know what I'm talking about. Again, this is personal preference, but I think those are incredibly ugly. To get rid of hash routing, we can enabled $locationProvider.html5Mode. In older browsers that do not support HTML5 routing, Angular will intelligently fall back to hash routing.

Create a file in static/javascripts/ called thinkster.config.js and give it the following content:

As mentioned, enabling $locationProvider.html5Mode gets rid of the hash sign in the URL. The other setting here, $locationProvider.hashPrefix, turns the # into a #!. This is mostly for the benefit of search engines.

Because we are using a new module here, we need to open up static/javascripts/thinkster.js, define the module, and include is as a dependency for the thinkster module.

Include new .js files

In this chapter so far, we have already created a number of new JavaScript files. We need to include these in the client by adding them to templates/javascripts.html inside the {% compress js %} block.

Open templates/javascripts.html and add the following above the {% endcompress %} tag:

Handling CSRF protection

Because we are using session-based authentication, we have to worry about CSRF protection. We don't go into detail on CSRF here because it's outside the scope of this tutorial, but suffice it to say that CSRF is very bad.

Django, by default, stores a CSRF token in a cookie named csrftoken and expects a header with the name X-CSRFToken for any dangerous HTTP request (POST, PUT, PATCH, DELETE). We can easily configure Angular to handle this.

Open up static/javascripts/thinkster.js and add the following under your module definitions:

This is a longer snippet than we've seen in the past, but we will approach it the same way: by talking about what's new and ignoring what we have already encountered.

class LoginView(views.APIView):

You will notice that we are not using a generic view this time. Because this view does not perfect a generic activity like creating or updating an object, we must start with something more basic. Django REST Framework's views.APIView is what we use. While APIView does not handle everything for us, it does give us much more than standard Django views do. In particular, views.APIView are made specifically to handle AJAX requests. This turns out to save us a lot of time.

def post(self, request, format=None):

Unlike generic views, we must handle each HTTP verb ourselves. Logging in should typically be a POST request, so we override the self.post() method.

account = authenticate(email=email, password=password)

Django provides a nice set of utilities for authenticating users. The authenticate() method is the first utility we will cover. authenticate() takes an email and a password. Django then checks the database for an Account with email email. If one is found, Django will try to verify the given password. If the username and password are correct, the Account found by authenticate() is returned. If either of these steps fail, authenticate() will return None.

We want to store some information about this user in the browser if the login request succeeds, so we serialize the Account object found by authenticate() and return the resulting JSON as the response.

Adding a login API endpoint

Just as we did with AccountViewSet, we need to add a route for LoginView.

Open up thinkster_django_angular_boilerplate/urls.py and add the following URL between ^/api/v1/ and ^:

Authentication Service

Let's add some more methods to our Authentication service. We will do this in two stages. First we will add a login() method and then we will add some utility methods for storing session data in the browser.

Open static/javascripts/authentication/services/authentication.service.js and add the following method to the Authentication object we created earlier:

Much like the register() method from before, login() returns makes an AJAX request to our API and returns a promise.

Now let's talk about a few utility methods we need for managing session information on the client.

We want to display information about the currently authenticated user in the navigation bar at the top of the page. This means we will need a way to store the response returned by login(). We will also need a way to retrieve the authenticated user. We need need a way to unauthenticate the user in the browser. Finally, it would be nice to have an easy way to check if the current user is authenticated.

NOTE: Unauthenticating is different from logging out. When a user logs out, we need a way to remove all remaining session data from the client.

Given these requirements, I suggest three methods: getAuthenticatedAccount, isAuthenticated, setAuthenticatedAccount, and unauthenticate.

Let's implement these now. Add each of the following functions to the Authentication service:

function activate() {
// If the user is authenticated, they should not be here.
if (Authentication.isAuthenticated()) {
$location.url('/');
}
}

You will start to notice that we use a function called activate a lot throughout this tutorial. There is nothing inherently special about this name; we chose a standard name for the function that will be run when any given controller is instantiated.

As the comment suggests, if a user is already authenticated, they have no business on the login page. We solve this by redirecting the user to the index page.

We should do this on the registration page too. When we wrote the registration controller, we didn't have Authentication.isAuthenticated(). We will update RegisterController shortly.

Back to RegisterController

Taking a step back, let's add a check to RegisterController and redirect the user if they are already authenticated.

Open static/javascripts/authentication/controllers/register.controller.js and add the following just inside the definition of the controller:

activate();
/**
* @name activate
* @desc Actions to be performed when this controller is instantiated
* @memberOf thinkster.authentication.controllers.RegisterController
*/
function activate() {
// If the user is authenticated, they should not be here.
if (Authentication.isAuthenticated()) {
$location.url('/');
}
}

If you remember, we also talked about logging a user in automatically when they register. Since we are already updating registration related content, let's update the register method in the Authentication service.

{info}
See how you can chain calls to $routeProvider.when()? Going forward, we will ignore old routes for brevity. Just keep in mind that these calls should be chained and that the first route matched will take control.

Include new .js files

If you can believe it, we've only created one new JavaScript file since the last time: login.controller.js. Let's add it to javascripts.html with the other JavaScript files:

Controlling the navigation bar with NavbarController

There will not actually be a LogoutController or logout.html. Instead, the navigation bar already contains a logout link for authenticated users. We will create a NavbarController for handling the logout buttons onclick functionality and we will update the link itself with an ng-click attribute.

Create a file in static/javascripts/layout/controllers/ called navbar.controller.js and add the following to it:

Checkpoint

If you visit http://localhost:8000/ in your browser, you should still be logged in. If not, you will need to log in again.

You can confirm the logout functionality is working by clicking the logout button in the navigation bar. This should refresh the page and update the navigation bar to it's logged out view.

Making a Post model

In this section we will make a new app and create a Post model similar to a status on Facebook or a tweet on Twitter. After we create our model we will move on to serializing Posts and then we will create a few new endpoints for our API.

Making a posts app

First things first: go ahead and create a new app called posts.

$ python manage.py startapp posts

Remember: whenever you create a new app you have to add it to the INSTALLED_APPS setting. Open thinkster_django_angular_boilerplate/settings.py and modify it like so:

INSTALLED_APPS = (
# ...
'posts',
)

Making the Post model

After you create the posts app Django made a new file called posts/models.py. Go ahead and open it up and add the following:

Our method of walking through the code line-by-line is working well so far. Why mess with a good thing? Let's do it.

author = models.ForeignKey(Account)

Because each Account can have many Post objects, we need to set up a many-to-one relation.

The way to do this in Django is with using a ForeignKey field to associate each Post with a Account.

Django is smart enough to know the foreign key we've set up here should be reversible. That is to say, given a Account, you should be able to access that user's Posts. In Django these Post objects can be accessed through Account.post_set (not Account.posts).

Now that the model exists, don't forget to migrate.

$ python manage.py makemigrations
$ python manage.py migrate

Serializing the Post model

Create a new file in posts/ called serializers.py and add the following:

There isn't much here that's new, but there is one line in particular I want to look at.

author = AccountSerializer(read_only=True, required=False)

We explicitly defined a number of fields in our AccountSerializer from before, but this definition is a little different.

When serializing a Post object, we want to include all of the author's information. Within Django REST Framework, this is known as a nested relationship. Basically, we are serializing the Account related to this Post and including it in our JSON.

We pass read_only=True because we should not be updating an Account object with a PostSerializer. We also set required=False here because we will set the author of this post automatically.

When a Post object is created it has to be associated with an author. Making the author type in their own username or id when creating adding a post to the site would be a bad experience, so we handle this association for them with the perform_create hook. We simply grab the user associated with this request and make them the author of this Post.

Similar to the permissions we used for the Account viewset, dangerous HTTP methods require the user be authenticated and authorized to make changes to this Post. We will created the IsAuthorOfPost permission shortly. If the HTTP method is safe, we allow anyone to access this view.

class AccountPostsViewSet(viewsets.ViewSet):

This viewset will be used to list the posts associated with a specific Account.

queryset = self.queryset.filter(author__username=account_username)

Here we filter our queryset based on the author's username. The account_username argument will be supplied by the router we will create in a few minutes.

Making the IsAuthorOfPost permission

Create permissions.py in the posts/ directory with the following content:

Rendering Post objects

Until now, the index page has been empty. Now that we have handled authentication and the backend details for the Post model, it's time to give our users something to interact with. We will do this by creating a service that handles retrieving and creating Posts and some controllers and directives for handling how the data is displayed.

A module for posts

Let's define the posts modules.

Create a file in static/javascripts/posts called posts.module.js and add the following:

First, we have created a module named thinkster.posts.directives. As you probably guessed, this means we will introduce the concept of directives to our app in this chapter.

Secondly, the thinkster.posts.directives module requires the ngDialog module. ngDialog is included in the boilerplate project and handles the display of modals. We will use a modal in the next chapter when we write the code for creating new posts.

Making an interface for the index page

We will add a little more later, but not much. Most of what we need will be in the template we create for the posts directive next.

Making a Snackbar service

In the boilerplate project for this tutorial, we've included SnackbarJS. SnackbarJS is a small JavaScript library that makes showing snackbars (a concept from Google's Material Design) easy. Here, we will create a service to include this functionality in our AngularJS application.

Open static/javascripts/utils/services/snackbar.service.js and add the following:

Later, when we get around to creating a new post, we will fire off an event called post.created when the user creates a post. By catching this event here, we can add this new post to the front of the vm.posts array. This will prevent us from having to make an extra API request to the server for updated data. We will talk about this more shortly, but for now you should know that we do this to increase the perceived performance of our application.

$scope.$on('post.created.error', function () {
vm.posts.shift();
});

Analogous to the previous event listener, this one will remove the post at the front of vm.posts if the API request returns an error status code.

Making a route for the index page

With a controller and template in place, we need to set up a route for the index page.

Open static/javascripts/thinkster.routes.js and add the following route:

There are two parts of the directives API that I want to touch on: scope and restrict.

scope: {
posts: '='
},

scope defines the scope of this directive, similar to how $scope works for controllers. The difference is that, in a controller, a new scope is implicitly created. For a directive, we have the option of explicitly defining our scopes and that's what we do here.

The second line, posts: '=' simply means that we want to set $scope.posts to the value passed in through the posts attribute in the template that we made earlier.

restrict: 'E',

restrict tells Angular how we are allowed to use this directive. In our case, we set the value of restrict to E (for element) which means Angular should only match the name of our directive with the name of an element: <posts></posts>.

Another common option is A (for attribute), which tells Angular to only match the name of the directive with the name of an attribute. ngDialog uses this option, as we will see shortly.

Controller the posts directive with PostsController

The directive we just created requires a controller called PostsController.

Create static/javascripts/posts/controllers/posts.controller.js with the following content:

It isn't worth taking the time to step through this controller line-by-line. Suffice it to say that this controller presents an algorithm for ensuring the columns of posts are of approximately equal height.

Because we do not have direct access to the ViewModel that posts is stored on, we watch $scope.posts instead of vm.posts. Furthermore, we use $watchCollection here because $scope.posts is an array. $watch watches the object's reference, not it's actual value. $watchCollection watches the value of an array from changes. If we used $watch here instead of $watchCollection, the changes caused by $scope.posts.shift() and $scope.posts.unshift() would not trigger the watcher.

Making a template for the posts directive

In our directive we defined a templateUrl that doesn't match any of our existing templates. Let's go ahead and make a new one.

Checkpoint

Assuming all is well, you can confirm you're on the right track by loading http://localhost:8000/ in your browser. You should see the Post object you created at the end of the last section!

This also confirms that PostViewSet from the last section is working.

Making new posts

Given that we already have the necessary endpoints in place, the next thing we need to let users make new posts is an interface. We accomplish this by adding a button to the bottom-right corner of the screen. When this button is clicked, a modal shows up asking the user to type in their post.

We only want this button to show up on the index page for now, so open static/templates/layout/index.html and add the following snippet to the bottom of the file:

Earlier we set up an event listener in IndexController that listened for the post.created event and then pushed the new post onto the front of vm.posts. Let's look at this a little more closely, as this turns out to be an important feature of rich web applications.

What we are doing here is being optimistic that the API response from Posts.create() will contain a 200 status code telling us everything went according to plan. This may seem like a bad idea at first. Something could go wrong during the request and then our data is stale. Why don't we just wait for the response?

When I said we are increasing the perceived performance of our app, this is what I was talking about. We want the user to perceive the response as instant.

The fact of the matter is that this call will rarely fail. There are only two cases where this will reasonably fail: either the user is not authenticated or the server is down.

In the case where the user is not authenticated, they shouldn't be submitting new posts anyways. Consider the error to be a small punishment for the user doing things they shouldn't.

If the server is down, then there is nothing we can do. Unless the user already had the page loaded before the server crashed, they wouldn't be able to see this page anyways.

Other things that could possibly go wrong make up such a small percentage that we are willing to allow a slightly worse experience to make the experience better for the 99.9% of cases where everything is working properly.

Furthermore, the object we pass as the second argument is meant to emulate the response from the server. This is not the best design pattern because it assumes we know what the response will look like. If the response changes, we have to update this code. However, given what we have, this is an acceptable cost.

So what happens when the API call returns an error?

$rootScope.$broadcast('post.created.error');

If the error callback is triggered, then we will broadcast a new event: post.created.error. The event listener we set up earlier will be trigger by this event and remove the post at the front of vm.posts. We will also show the error message to the user to let them know what happened.

$scope.closeThisDialog();

This is a method provided by ngDialog. All it does is close the model we have open. It's also worth nothing that closeThisDialog() is not stored on the ViewModel, so we must call $scope.closeThisDialog() instead of vm.closeThisDialog().

Checkpoint

Visit http://localhost:8000/ and click the + button in the bottom-right corner. Fill out this form to create a new post. You will know everything worked because the new post will be displayed at the top of the page.

Displaying user profiles

We already have the Django views and routes necessary to display a profile for each user. From here we can jump into making an AngularJS service and then move on to the template and controllers.

{info}
In this section and the next, we will refer to accounts as profiles. For the purposes of our client, that is effectively what the Account model translates into: a user's profile.

Making the profile modules

We will be creating a service and a couple of controllers relating to user profiles, so let's go ahead and define the modules we will need.

Create static/javascripts/profiles/profiles.module.js with the following content:

Checkpoint

To view your profile, direct your browser to http://localhost:8000/+<username>. If the page renders, everything is good!

Updating user profiles

The last feature we will implement in this tutorial is the ability for a user to update their profile. The updates we offer will be minimal, including updating the user's first name, last name, email, and tagline, but you will get the gist of it and can add more options at will.

ProfileSettingsController

To get started, open static/javascripts/profiles/controllers/profile-settings.controller.js and add the following contents:

Here we have created two methods that will be available to the view: update and destroy. As their names suggest, update will allow the user to update their profile and destroy will destroy the user's account.

Most of this controller should look familiar, but let's go over the methods we've created for clarity.

In activate, we follow a familiar pattern. Because this page allows for dangerous operations to be performed, we must make sure the current user is authorized to see this page. We do this by first checking if the user is authenticated and then checking if the authenticated user owns the profile. If either case is false, then we redirect to the index page with a snackbar error stating that the user is not authorized to view this page.

If the authorization process succeeds, we simply grab the user's profile from the server and allow the user to do as they wish.

When a user wishes to destroy their profile, we must unauthenticate them and redirect to the index page, performing a page refresh in the process. This will make the navigation bar re-render with the logged out view.

If for some reason destroying the user's profile returns an error status code, we simply display an error snackbar with the error message returned by the server. We do not perform any other actions because we see no reason why this call should fail unless the user is not authorized to delete this profile, but we have already accounted for this scenario in the activate method.

Checkpoint

And that's our last feature! You should now be able to load up the settings page at http://localhost:8000/+:username/settings and update your settings as you wish.

Try updating your tagline. If it works, you will now see your tagline displayed on your profile page.

Congratulations, you did it!

During this tutorial you accomplished a lot.

For starters, you build an entire authentication system by yourself! You extended Django's built-in User model and added various attributes and did so in a way that makes adding other information an easy feat when it becomes necessary. You went on to built both the front and back ends for registration, logging in, logging out, and updating the user's profile.

In addition to building the authentication system you also create a way for users to add their posts to our application and view other users' posts.

This is the stuff that we do as engineers of the web. There will be times when you will need skills learned outside this tutorial and there are certainly best practices that we did not touch on, but what you've done here is the gist of web development!

Be proud of what you've accomplished here and tell you friends by tweeting about it. We hope that you enjoyed this tutorial and will come back when you want to learn more. As always, our inbox is open to your comments, suggestions, and feedback.

Happy hacking!

Contributors

Before you go, I want to give a shoutout to all of the people who were kind enough to send us emails and pull requests.

Here is a full list of contributors who helped with the current release: