Getting Started with DJ Templates

You can get started with DJ Templates by following these steps:

1. Install Django Templates

You can install DJ Templates using pip. Run the following command in your terminal:

pip install dj-templates

Alternatively you can also install it directly from the source code by cloning the repository and installing it with poetry or with pip:

pip install git+https://codeberg.org/c9mos/django-templates.git

2. Add DJ Templates to your Django project

In your Django project's settings.py file, add 'dj_templates' to the INSTALLED_APPS list, and add the dj_templates.context_processors.templates context processor to the TEMPLATES setting:

INSTALLED_APPS = [
    ...
    'dj_templates',
    ...
]
... 
TEMPLATES = [
    {
        ...
        'OPTIONS': {
            'context_processors': [
                ...
                'dj_templates.context_processors.templates',
                ...
            ],
        },
    },
]

You can also provide additional configuration options for DJ Templates in your settings.py file. For example, you can specify the default theme to use and the default base-template for your project:

THEME = 'bootstrap5'  # Default theme to use

# Lookup the base template in the current theme's templates directory,
# if not found, fallback to the default base template
BASE_TEMPLATE = '@myproject/base.html'

See the Configuration page for more details on how to configure DJ Templates in your Django project.

3. Use DJ Templates in your Views

To use DJ Templates in your views, you need to define your own templates for your views. You can create a new template file in your Django app's templates directory, then create a file named 'dj_templates.py' in your app's directory, and define a TEMPLATES dictionary that maps the templates to your theme. You should always define a template for the HTML-Theme as a fallback, and then for your other themes. If the TEMPLATES variable is set to a str in or a Pathobject, it is expected to be an absolute path to a JSON or YAML file that contains the templates dictionary.

A sample dictionary for a Django app named myapp:

TEMPLATES = {
    'html': {
        'templates': {
            'myapp/index': 'myapp/html/index.html',
            'myapp/detail': 'myapp/html/detail.html',
            'myapp/include': 'myapp/bootstrap5/include.html',
        },
        'static_files': {
            'myapp/css/style.css': 'myapp/html/css/style.css',
            'myapp/js/script.js': 'myapp/html/js/script.js',
        },
        'js_files': [
            "@myapp/js/script.js",
        ],
    },
    'bootstrap5': {
        'templates': {
            'myapp/index': 'myapp/bootstrap5/index.html',
            'myapp/detail': 'myapp/bootstrap5/detail.html',
        },
        'static_files': {
            'myapp/css/style.css': 'myapp/bootstrap5/css/style.css',
            'myapp/js/script.js': 'myapp/bootstrap5/js/script.js',
            'myapp/js/body_script.js': 'myapp/bootstrap5/js/body_script.js',
        },
        'js_files': [
            "@myapp/js/script.js",
        ],
        'body_js_files': [
            "@myapp/js/body_script.js",
        ],
    },
}

And in your view you can use the ThemeMixin class and optionally the HtmxMixin class to handle theme-specific templates and HTMX requests.

from django.views import View
from django.shortcuts import render
from dj_templates.mixins.theme import ThemeMixin
from dj_templates.mixins.htmx import HtmxMixin

class MyView(ThemeMixin, HtmxMixin, View):
    # Base template name without theme prefix
    # Start with '@' to indicate that it is a template key,
    # to be looked up in the TEMPLATES dictionary and
    # not a direct path to a template file.
    template_name = '@myapp/index'  

    def get(self, request, *args, **kwargs):
        context = self.get_context_data()
        return render(request, self.get_template_name(), context)

In your Templates you can do the following to include static files and other templates:

{% extends base_template %}{# Use the base template defined in settings.py #}
{% load templates %}

{% block content %}
    {% include 'myapp/include'|template:theme %}
{% endblock %}