Documentation

Dans cet article, nous allons explorer la manière d’utiliser le module django.template.loader pour charger des templates dans Django. Ce module définit deux fonctions principales: get_template() et select_template().

Utilisation

La fonction get_template(template_name, using=None)

Cette fonction charge le template avec le nom donné et renvoie un objet Template. Le type exact de la valeur de retour dépend du moteur de template utilisé. Chaque moteur possède sa propre classe Template.

get_template() essaie chaque moteur de template dans l’ordre jusqu’à ce qu’il en trouve un qui réussisse. S’il ne parvient pas à trouver le template, il lève une exception TemplateDoesNotExist. S’il trouve le template mais qu’il contient une syntaxe invalide, il lève une exception TemplateSyntaxError.

La recherche et le chargement des templates dépendent du moteur utilisé et de sa configuration. Si vous souhaitez restreindre la recherche à un moteur de template spécifique, vous pouvez le spécifier via l’argument using.

La fonction select_template(template_name_list, using=None)

select_template() fonctionne de la même manière que get_template(), mais elle prend une liste de noms de templates. Elle essaie chaque nom dans l’ordre et renvoie le premier template qui existe.

Si le chargement d’un template échoue, les exceptions suivantes, définies dans django.template, peuvent être levées:

1. L’exception TemplateDoesNotExist(msg, tried=None, backend=None, chain=None)

Cette exception est levée lorsqu’un template ne peut pas être trouvé. Elle accepte les arguments optionnels suivants pour alimenter le post-mortem du template dans la page de débogage:

• backend: l’instance de backend de template à partir de laquelle l’exception est levée.
• tried: une liste de sources qui ont été essayées lors de la recherche du template. Cette liste est formatée comme une liste de tuples contenant (origin, status), où origin est un objet similaire à une origine et status est une chaîne contenant la raison pour laquelle le template n’a pas été trouvé.
• chain: une liste d’exceptions intermédiaires TemplateDoesNotExist levées lors de la tentative de chargement d’un template à partir de plusieurs moteurs. Cette liste est utilisée par des fonctions telles que get_template().

2. L’exception TemplateSyntaxError(msg)

Cette exception est levée lorsqu’un template est trouvé mais contient des erreurs de syntaxe.

Les objets Template renvoyés par get_template() et select_template() doivent fournir une méthode render() avec la signature suivante:

Template.render(context=None, request=None)

Cette méthode rend le template avec le contexte donné. Si le contexte est fourni, il doit être un dictionnaire. Sinon, le moteur rendra le template avec un contexte vide. Si une requête est fournie, elle doit être une instance de HttpRequest. Dans ce cas, le moteur doit également la rendre, ainsi que le jeton CSRF, disponibles dans le template. La manière dont cela est réalisé dépend de chaque backend.

Exemple d’algorithme de recherche

Voici un exemple de l’algorithme de recherche utilisé par Django. Pour cet exemple, le paramètre TEMPLATES est configuré comme suit:

TEMPLATES = [
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': [
            '/home/html/example.com',
            '/home/html/default',
        ],
        ...
    },
    {
        'BACKEND': 'django.template.backends.jinja2.Jinja2',
        'DIRS': [
            '/home/html/jinja2',
        ],
        ...
    },
]

Si vous appelez get_template(‘story_detail.html’), voici les fichiers que Django recherchera, dans cet ordre:

• /home/html/example.com/story_detail.html (moteur ‘django’)
• /home/html/default/story_detail.html (moteur ‘django’)
• /home/html/jinja2/story_detail.html (moteur ‘jinja2’)

Si vous appelez select_template([‘story_253_detail.html’, ‘story_detail.html’]), voici ce que Django recherchera:

• /home/html/example.com/story_253_detail.html (moteur ‘django’)
• /home/html/default/story_253_detail.html (moteur ‘django’)
• /home/html/jinja2/story_253_detail.html (moteur ‘jinja2’)
• /home/html/example.com/story_detail.html (moteur ‘django’)
• /home/html/default/story_detail.html (moteur ‘django’)
• /home/html/jinja2/story_detail.html (moteur ‘jinja2’)

Lorsque Django trouve un template qui existe, il cesse de chercher.

Il est possible – et préférable – d’organiser les templates dans des sous-répertoires à l’intérieur de chaque répertoire contenant des templates. La convention consiste à créer un sous-répertoire pour chaque application Django, avec des sous-répertoires supplémentaires si nécessaire.

Cela vous aidera à garder votre structure de templates bien organisée. Stocker tous les templates à la racine d’un seul répertoire peut rapidement devenir désordonné.

Pour charger un template qui se trouve dans un sous-répertoire, utilisez un slash, comme ceci:

get_template('news/story_detail.html')

En utilisant le même paramètre TEMPLATES que celui mentionné ci-dessus, cela tentera de charger les templates suivants:

• /home/html/example.com/news/story_detail.html (moteur ‘django’)
• /home/html/default/news/story_detail.html (moteur ‘django’)
• /home/html/jinja2/news/story_detail.html (moteur ‘jinja2’)

De plus, afin de réduire la répétitivité du chargement et du rendu des templates, Django propose une fonction de raccourci qui automatise le processus.

render_to_string(template_name, context=None, request=None, using=None)

La fonction render_to_string() charge un template et appelle immédiatement sa méthode render(). Elle prend les arguments suivants:

• template_name: le nom du template à charger et à rendre. S’il s’agit d’une liste de noms de templates, Django utilise select_template() au lieu de get_template() pour trouver le template.
• context: un dictionnaire à utiliser comme contexte du template pour le rendu.
• request: une instance optionnelle de HttpRequest qui sera disponible lors du processus de rendu du template.
• using: un nom optionnel de moteur de template. La recherche du template sera restreinte à ce moteur.

Exemple d’utilisation:

result = render_to_string('my_template.html', {'foo': 'bar'})

Voir également le raccourci render() qui appelle render_to_string() et utilise le résultat pour générer un HttpResponse adapté à un retour dans une vue.

Enfin, vous pouvez utiliser directement les moteurs configurés:

import django.template.engines as engines

# Disponible : moteur 'django'
django_engine = engines['django']

Les moteurs de templates sont disponibles dans le module django.template.engines. La clé de recherche – ‘django’ dans cet exemple – est le nom du moteur.

N’hésitez pas à explorer la documentation officielle de Django pour en savoir plus sur l’utilisation avancée des templates et des moteurs de template. Happy coding!