2 Ways to Configure your Django Project Templates.

Django is built on an architecture known as MVT– Model View Template. The Template part is equally important as the rest of the other parts because there is no website without a front end. The front end is important because users interact with our Django app through it. One question that most Django beginners often asks is ‘where to put templates in a Django project?’ This post is going to show the 2 most popular ways to configure your Django template files.

Table of Contents

• What is a Django template?
• Where to put templates in Django?
• Does Django need a folder called ‘templates’
• How to Configure your Django Templates.
  • Create a templates folder for each app In the Django project.
  • Create a templates folder in the root of the project and register it in settings.py
    • Create templates at the root of your Django project:
    • Register the templates in the settings.py
• Takeaways
  • Parent templates and child templates
  • Using Both Methods
  • Always naming the folder ‘templates’

What is a Django template?

A Django template is a file that contains code that defines the front-end part of a Django website. These files are usually HTML files but they are written in a language known unofficially as DTL – Django Templating Language. DTL makes use of a combination of HTML tags and Django template tags.

Where to put templates in Django?

There are two places you can place your template files in a Django project. The one recommended by Django is to create a templates folder for each of the apps in your project and inside that template another folder with the name of the app. All the files in that template folder will be automatically regarded as template files with no other configuration you have to do.

The one that has been adopted by most Django developers is to create a single templates folder at the root of your Django project and register the folder in the settings.py of your project.

Both of these methods have their own pros and cons. We’re going to look at how to configure template files in a Django project using each one of the methods in detail.

Does Django need a folder called ‘templates‘

Yes, giving a folder the name ‘templates‘ is the convention for naming a folder that contains template files of a Django project. When Django is looking for a templates folder, it will start at the app level and searches for a folder with the name ‘templates’. If it does not find one, it will go to the TEMPLATES list in the settings.py of the project and the folder specified there will be used as the templates folder.

How to Configure your Django Templates.

The two ways to configure your Django templates are:

1. Create a templates folder for each app In the Django project.
2. Create a templates folder in the root of the project and register it in settings.py

Let’s get see how to use these methods in detail:

Create a templates folder for each app In the Django project.

To use this method, create a folder called templates in an app. Each app should have a folder named templates. Then in that template folder, another folder with the same name as the app. When Django looks for a templates folder, it will start at the app level and searches for a folder with the name templates. So your project structure should look something like the below:

[project_name]
├── config
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   ├── wsgi.py
│   └── templates
|          └── config
├── blog #django app
|  ...
|   └── templates  
|          └── blog
├── shop #django app
|  ...
|   └── templates
|          └── shop
├── accounts #django app
|  ...
|   └── templates  
|          └── accounts
└── manage.py

As you can see, there is a templates folder in each of the apps available and each of them contains another with the same name as the app.

You could also have done this without including the sub-directory with the same name as the app name. It still works fine. The problem arises when there are template files of different apps with the same name. For example, there is an index.html in the shop app and another index.html in the accounts app. So as long as you’re using different names for different template files, you can exclude the extra sub-directories. Like this:

...
├── accounts #django app
|  ...
|   └── templates  
|          └── accounts
└── manage.py

Django developers like this method because you don’t have to configure anything. You just create a templates folder and then you start adding the files. This method also makes your Django project presentable and easy to scale and manage because there is no single folder for all the many template files that a single Django project will require.

This method is not favored by some Django developers for the very fact of creating a templates folder for each and every app on your project when you can create a single folder for all the templates of your project. Then after that, you create another sub-directory of the same name as the app. Some regard it as repetitive and others as tedious.

If you prefer to use this method, it is a very good one. Sometimes, it just depends on the project you’re doing. But if you do not like this one, maybe the next one will be the good one for you.

Create a templates folder in the root of the project and register it in settings.py

This method of configuring Django templates involves creating a single templates folder in the root of your Django project, then registering it in the TEMPLATES list in the settings.py file of your project. Let’s see how this is done:

Create templates at the root of your Django project:

First, create a folder called templates at the root of your Django project. Root, in this case, is the base directory of your Django project; the folder that contains the manage.py file.

[project_name]
├── config
│   ├── __init__.py
│   ├── settings.py
│   ├── urls.py
│   └── wsgi.py
├── blog #app
|   ├── migrations
│   ├── _init_.py
│   ├── admin.py
│   ├── apps.py
│   ├── models.py
|   ├── views.py
|   └── tests.py  
├── templates
└── manage.py

Register the templates in the settings.py

Next, what you have to do is to register the newly created templates folder in the settings.py file of your Django project. This way Django will be able to tell that the folder is the official templates directory for your project.

In the settings.py, locate the TEMPLATES list and in DIRS add the path of the templates folder.

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [BASE_DIR / 'templates'], # here
        'APP_DIRS': True,
        'OPTIONS': {
            'context_processors': [
                'django.template.context_processors.debug',
                'django.template.context_processors.request',
                'django.contrib.auth.context_processors.auth',
                'django.contrib.messages.context_processors.messages',
            ],
        },
    },
]

Note that the templates folder here does not always have to be in the root of the project folder, but it is best practice to do it that way. If you decide to do otherwise, make sure you put the correct path in the settings.py file. For example, if you decided that the templates folder of your Django project will leave in the config folder, then in the settings.py you have to do it like this:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [BASE_DIR / 'config/templates'], # here
...

This project has gained a lot of traction from most Django developers because of how easy it is to use.

Takeaways

Here is what you have to note:

Parent templates and child templates

You should also note that there is a templates folder in the project folder of the Django project (config) of the first method. When you use this method to configure Django templates, you are more likely going to place your parent templates in the project folder. And what are parent templates? So, if you look at a website, you will see that there are many designs and parts of the website that are repeating themselves across multiple pages. Like navigation bars, sidebars, and footers.

These designs are of course repeating on the websites but definitely not in the code, you don’t have to repeat yourself you know. So parent templates are these templates that contain code for designs that are common for all pages. Styles that are specific to a page are the ones that you’ll put in their dedicated templates folders for each app they serve.

Using Both Methods

You can use both of these methods simultaneously in the same app. For example, you can create a templates folder and register it to your settings.py as your main templates folder, but at the same time have some templates folders in the other apps.

Always naming the folder ‘templates‘

The third thing is that, for the second method, the folder does not always have to be called templates. This is because you register it to Django manually, while this happens automatically for the first method.

Thanks for stopping, that was all for this post. If you find out it helpful, please share it with other Django developers. If you have any questions, please let me know in the comments section below.