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 %}