Metadata-Version: 2.4
Name: dj-templates
Version: 0.0.2
Summary: Minimal django project
License-Expression: BSD-1-Clause
License-File: LICENSE
License-File: LICENSE.md
Author: Christian Moser
Author-email: devel@c-moser.at
Requires-Python: >=3.13,<3.15
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: django (>=6.0.6,<7.0.0)
Requires-Dist: orjson (>=3.11.9,<4.0.0)
Description-Content-Type: text/markdown

# django-templates

*django-templates* is a Django app that provides a centralized registry for
accessing the dictionary of templates used in a request.
It also provides a context processor for accessing the registry.

## Installation

Add *django_templates* to the list of *INSTALLED_APPS* in your project's settings.py.

```python
INSTALLED_APPS = [
    ...
    django_templates,
    ...
]
```

Add the *templates* context processor to your project's settings.py.

```python
TEMPLATES = [
    {
        ...
        "APP_DIRS": True,
        # Optionally add the global templates directory if it is not in an app's templates directory.
        "DIRS": [
            "/path/to/global/templates",
        ],
        ...
        # Add the templates context processor to the list of context processors.
        "OPTIONS": {
            "context_processors": [
                ...
                "django_templates.context_processors.templates",
                ...
            ],
        },
    },
]
...

```

Then you can use the *DJANGO_TEMPLATES* setting in settings.py to override the
templates of apps using this library.


```python
DJANGO_TEMPLATES = {
    "html": {
        "app_name/index": "app_name/templates/app_name/index.html",
        ...
    }
}
```

You can also use a *filename* or `Path` object to load the templates from a YAML
or JSON file.

Set the global THEME variable to the default theme for your project.

The default theme is "html", but you can change it to any other theme provided
in the "django_templates/themes" directory.

Themes provided in the "django_templates/themes" directory are:

- html
- bootstrap5 (Work in progress)
- tailwindcss (Work in progress)

```python
THEME = "html"
```

Set the global GET_THEME_FUNCTION variable to the function that will be used to
get the theme for a request. This allows you to implement theming in your app by
providing a function that returns the theme for a request.

```python
GET_THEME_FUNCTION = 'myapp.module.get_theme_for_request'
```

...
## Usage

To use the template registry in your app, create the file
"your_app/django_templates.py" and define your templates there.
  
Set the `DJANGO_TEMPLATES` variable, which should contain your default template
dictionary or a *filename* or `Path` object.

If passing a filename it should be an absolute path to a YAML or JSON file
containing the template dictionary.

```python
DJANGO_TEMPLATES = {
    "html": {
        "app_name/index": "app_name/templates/app_name/index.html"
    }
    ...
}
```

### Accessing the registry in your templates

You can access the registry in your templates by using the `template` filter
from the `django_templates` template tag library.
The templates filter requires the `request` object to be passed to it, which is
available in the template context if you have added the
`django_templates.context_processors.templates` context processor to your
project's settings.py or a theme name.

```django
{% extends base_template %}
...
{% load templates %}
{{ "template_name"|template:request }}
...
```

### Accessing the registry un your views

```python
from django.shortcuts import render
from django_templates.utils import get_template

def my_view(request):
    template_name = get_template("template_key", request=request)
    ...
    render(request, template_name, context)
```

#### Getting the theme for a request

```python
from django_templates.utils import get_theme

current_theme = get_theme(request)
```

### Accessing the registry in your app

You can access the registry in your app by using the `get_template_name`
function from the `django_templates.utils` module.

An optional `theme` argument can be passed to the function to get the template
name for a specific theme. You can also pass a `request` object to the function
to get the template name for the current theme.

```python
from django_templates.utils import get_template

template_name = get_template("template_key")
```

