Django best practices II: Project structure and HTML5 Boilerplate implementation

Posted on by Marina Mele

This is the second post about how to build a Django project from scratch, focusing on the project structure, internationalization and localization configuration, models, managers, views, forms and templates. Check the first part here.

In this post, I write about how to build an ordered project structure: where you should put your apps, libraries and templates. Moreover, I also install HTML5 Boilerplate to have a responsive template.

Separating applications and libraries

To build an ordered project, I recomend to use two separate folders: apps and libs inside your myproject folder. The first one, apps,  will contain all your project applications that have models, views, etc. The other one, libs, will contain applications that include other functionalities, but that don’t have the same structure (for example, an app that only contains template tags).

We will use these folders as packages, so we need to include an empty __init__.py in each of them:

$ cd myproject

$ mkdir apps libs

$ touch apps/__init__.py libs/__init__.py

To create an app in each of these folders, you must go inside them. For example:

$ cd myapp/apps

$ django-admin.py startapp myapp

However, we have to write the correct path when importing the apps of this folder. For example, inside the file myapp/views.py, we should import the model MyModel in the file myapp/models.py as:

from myproject.apps.myapp.models import MyModel

And also, you need to update your settings.py file to include the path of your new application:

INSTALLED_APPS = (
    …
    ‘myproject.apps.myapp’,
    …
)

Templates App

Another useful thing is to have all your templates in the same place. You can accomplish this by creating a Django app and use it to contain the templates and the template tags. Go to your project folder, at the same level of the settings.py file, and type:

$ python ../manage.py startapp mytemplates

This way, this app will be inside the myproject folder. Finally, you should include this app in the settings.py file:

INSTALLED_APPS = (
    …
    ‘myproject.mytemplates’,
    …
)

 

In mytemplates folder, where you have the usual files of a Django app, create a templates folder

$ mkdir templates

Inside this folder you should place all your project templates. A good practice is to create a different folder for each app on your project.

HTML5 Boilerplate

If you want to create a nice and responsive Django app, I recommend you install HTML5 Boilerplate. Go to the webpage and click the Download button to download a zip file (in my case, it was the version 4.3.0).

Once in your computer, unzip the file and place its contents inside myproject/mytemplates/templates folder. Note that you should override the file 404.html. Moreover, I usually change the name of the file “index.html” to “base.html“, but it’s up to you.

However, the two folders js and css, and the two images favicon.ico and apple-touch-icon-precomposed.png, contain or are static files. Go to the projects folder, at the same level of the settings.py file, and create a static folder:

$ mkdir static

$ mv mytemplates/templates/{js,css,favicon.ico,apple-touch-icon-precomposed.png} static/

Then, open the base.html file, inside mytemplates/templates, and change the urls that point to these two folders. For example, you should change the lines

<link rel=“stylesheet” href=“css/normalize.css”>
<link rel=“stylesheet” href=“css/main.css”>

<script src=“js/vendor/modernizr-2.6.2.min.js”></script>

to 

<link rel=“stylesheet” href=“{{STATIC_URL}}css/normalize.css”>
<link rel=“stylesheet” href=“{{STATIC_URL}}css/main.css”>

<script src=“{{STATIC_URL}}js/vendor/modernizr-2.6.2.min.js”></script>

and so on. To include the icon images write in the header:

<link rel=”icon” type=”image/png” href=”{{STATIC_URL}}apple-touch-icon-precomposed.png”>

<link rel=“shortcut icon” href=“{{STATIC_URL}}favicon.ico” type=“image/x-icon”>

Moreover, I usually comment the script for Google Analytics to use it later.

To see the effects and assure that everything works, edit the myproject/urls.py file:

urlpatterns = patterns(”,
    url(r’^$’, ‘myproject.views.home’, name=’home’),
)

Then, edit or create the myprojects/views.py file:

# -*- coding: utf-8 -*-
from django.shortcuts import render_to_response
from django.shortcuts import RequestContext
def home(request):
    return render_to_response(“base.html”, RequestContext(request, {}))

Note: the first line indicates the coding to use. It is a good practice to insert this line at the beginning of the files of your django application, like views.py, admin.py, models.py, and settings.py.

Moreover, to see more clearly if the static files are rendered, edit the myproject/static/css/main.css file and include:

body {

    background-color: #DAF;

}

Try your Django project locally, to see if everything works as expected.

$ python manage.py runserver

You should see the text “Hello World! This is HTML5 Boilerplate.” and a purple background.

Go to Django best practices III: Install South, Localization, Internationalization and Django-registration

Leave a Reply