Django-fr | Documentation | Les vues génériques

Django-fr

Documentation Django

Les vues génériques

Écrire des applications web peut être monotone, parce qu'on répète certains motifs en permanence. Dans Django, les plus courants de ces motifs ont fait l'objet d'une abstraction dans des « vues génériques » qui vous permettent d'obtenir rapidement des vues classiques d'objets sans écrire de code Python.

Les vues génériques de Django contiennent :

  • Un ensemble de vues pour faire des pages de liste ou de détail (par exemple, les pages index de la documentation et pages de détail sur le site de Django).
  • Un ensemble de vues pour les pages d'archives par jour/mois/année et les pages de détail associées, ainsi que les pages présentant les derniers objets (billets, messages, etc.) -- par exemple, sur le site Django, les pages du blog année, mois, jour, détail et derniers billets.
  • Un ensemble de vues pour créer, éditer ou effacer des objets.

Toutes ces vues sont utilisées en créant des dictionnaires de configuration dans vos fichiers URLconf et en passant ces dictionnaires comme troisième membre du tuple d'URLconf pour un modèle d'URL donné. Par exemple, voici l'URLconf de l'application de blog qui est utilisé pour celui de djangoproject.com:

from django.conf.urls.defaults import *
from django_website.apps.blog.models import Entry

info_dict = {
    'queryset': Entry.objects.all(),
    'date_field': 'pub_date',
}

urlpatterns = patterns('django.views.generic.date_based',
   (r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/(?P<day>\w{1,2})/(?P<slug>[-\w]+)/$', 'object_detail', info_dict),
   (r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/(?P<day>\w{1,2})/$',               'archive_day',   info_dict),
   (r'^(?P<year>\d{4})/(?P<month>[a-z]{3})/$',                                'archive_month', info_dict),
   (r'^(?P<year>\d{4})/$',                                                    'archive_year',  info_dict),
   (r'^$',                                                                    'archive_index', info_dict),
)

Comme vous pouvez le voir, cet URLconf définit quelques valeurs dans info_dict. 'queryset' fournit à la vue générique un QuerySet d'objets à utiliser (dans ce cas précis, tous les objets Entry) et indique à la vue générique quel modèle est utilisé.

La documentation de toutes les vues génériques suit, avec la liste de tous les arguments que ces vues attendent. Rappelez-vous que, comme dans l'exemple ci-dessus, les arguments peuvent venir soit du motif de l'URL (comme month, day, year etc. dans l'exemple), soit du dictionnaire d'informations complémentaires (comme pour queryset, date_field, etc.).

La plupart des vues génériques requièrent l'argument queryset, qui est une instance de QuerySet ; voir la documentation de l'API de base de données pour plus d'informations sur les objets QuerySet.

La plupart des vues acceptent également un dictionnaire optionnel extra_context que vous pouvez utiliser pour passer les informations additionnelles que vous souhaitez à la vue. Les valeurs du dictionnaires extra_context peuvent être des fonctions (ou autres objets appelables) ou d'autres objets. Les fonctions sont évaluées juste avant d'être passées au template. Notez cependant que les QuerySets récupèrent et cachent leurs données quand ils sont évalués pour la première fois, ce qui signifie que si vous voulez passer un QuerySet qui soit toujours à jour via extra_context, vous devez l'encapsuler dans une fonction ou un lambda qui renvoie le QuerySet.

Vues génériques simples

Le module django.views.generic.simple contient des vues simples qui permettent de gérer des cas classiques : afficher un template quand il n'y a pas de logique particulière au niveau de la vue, et émettre une redirection.

django.views.generic.simple.direct_to_template

Description :

Affiche le template donné, en lui passant la variable de template {{ params }}, qui est un dictionnaire des paramètres capturés dans l'URL.

Paramètres requis :

  • template: Le nom complet du template à utiliser.

Paramètres optionnels :

  • extra_context: un dictionnaire de valeurs à ajouter au contexte du template. Par défaut, c'est un dictionnaire vide. Si une valeur du dictionnaire est appelable (callable), la vue générique l'appellera juste avant le rendu du template.
  • mimetype: le type MIME à utiliser pour le document résultant. La valeur par défaut est celle du réglage DEFAULT_CONTENT_TYPE.

Exemple :

Soient les motifs d'URL suivants:

urlpatterns = patterns('django.views.generic.simple',
    (r'^foo/$',             'direct_to_template', {'template': 'foo_index.html'}),
    (r'^foo/(?P<id>\d+)/$', 'direct_to_template', {'template': 'foo_detail.html'}),
)

Une requête à /foo/ provoquerait le rendu du template foo_index.html, et une requête à /foo/15/ celui de foo_detail.html avec une variable de contexte {{ params.id }} qui aurait la valeur 15.

django.views.generic.simple.redirect_to

Description :

Redirige vers une URL donnée.

L'URL donnée peut contenir des instructions de formatage de chaîne qui seront interpolées avec les paramètres capturés dans l'URL d'origine.

Si l'URL donnée est None, Django renverra HttpResponseGone (410).

Paramètres requis :

  • url: l'URL vers laquelle rediriger, sous la forme d'une chaîne de caractères, ou la valeur None pour lever une erreur HTTP 410 (Gone).

Exemple :

Cet exemple redirige de /foo/<id>/ vers /bar/<id>/:

urlpatterns = patterns('django.views.generic.simple',
    ('^foo/(?P<id>\d+)/$', 'redirect_to', {'url': '/bar/%(id)s/'}),
)

Cet exemple renvoie une erreur HTTP aux requêtes à /bar/:

urlpatterns = patterns('django.views.generic.simple',
    ('^bar/$', 'redirect_to', {'url': None}),
)

Vues génériques basées sur des dates

Les vues génériques basées sur des dates (dans le module django.views.generic.date_based) sont destinées à l'affichage de pages contenant des données fondées sur des dates ou groupées par date.

django.views.generic.date_based.archive_index

Description :

Une page d'index qui affiche les "derniers" objets, classés par date. Les objets dont la date est dans le futur ne seront pas inclus, sauf si vous positionnez la variable allow_future à True.

Paramètres requis :

  • queryset: un QuerySet d'objets pour lesquels la page sera utilisée.
  • date_field: le nom du champ DateField ou DateTimeField dans le modèle du QuerySet que la page basée sur les dates doit utiliser pour déterminer quels objets seront affichés.

Paramètres optionnels :

  • num_latest: le nombre d'objets à envoyer au contexte du template. La valeur par défaut est 15.
  • template_name: le nom complet du template à utiliser pour rendre la page. Cela permet de passer outre le nom du template par défaut (voir ci-dessous).
  • template_loader: le chargeur de template à utiliser pour charger le template. Par défaut, c'est django.template.loader.
  • extra_context: un dictionnaire de valeurs à ajouter au contexte du template. Par défaut, c'est un dictionnaire vide. Si une valeur du dictionnaire est appelable (callable), la vue générique l'appellera juste avant le rendu du template.
  • allow_empty: Une valeur booléenne qui indique s'il faut afficher la page si aucun objet n'est disponible. Si la valeur est False et qu'aucun objet n'est disponible, la vue enverra une erreur 404 au lieu d'envoyer une page vide. La valeur par défaut est True.
  • context_processors: une liste de processeurs de contexte de template à appliquer au template de la vue. Voir la documentation de RequestContext.
  • mimetype: le type MIME à utiliser pour le document résultant. La valeur par défaut est celle du réglage DEFAULT_CONTENT_TYPE.
  • allow_future: une valeur booléenne indiquant s'il faut inclure les objets "futurs" sur la page, où futur signifie des objets pour lesquels le champ spécifié dans date_field est plus grand que la date et l'heure courantes. La valeur par défaut est False.
  • Nouveau dans la version de développement de Django : template_object_name: désigne le nom de la variable de template à utiliser dans le contexte du template. La valeur par défaut est 'latest'.

Nom du template :

Si template_name n'est pas précisé, la vue utilisera le template <app_label>/<model_name>_archive.html par défaut, où :

  • <model_name> est le nom de votre modèle en minuscules. Pour un modèle appelé StaffMember, ce serait donc staffmember.
  • <app_label> est la partie la plus à droite du chemin vers l'application de votre modèle. Par exemple, si le chemin de votre modèle est apps/blog/models.py, ce serait blog.

Contexte du template :

En plus de extra_context, le contexte du template sera :

  • date_list: une liste d'objets datetime.date représentant toutes les années pour lesquelles le ` queryset`` renverra des objets, triée en descendant. C'est équivalent à queryset.dates(date_field, 'year')[::-1].

  • latest: les num_latest objets du système, triés en ordre descendant sur date_field. Par exemple, si num_latest vaut 10, latest sera la liste des 10 objets les plus récents du queryset.

    Nouveau dans la version de développement de Django : le nom de cette variable dépend du paramètre template_object_name, qui est 'latest' par défaut. Si template_object_name est 'foo', le nom de cette variable sera 'foo'.

django.views.generic.date_based.archive_year

Description :

Une page d'archive annuelle, montrant tous les mois avec des objets disponibles pour une année donnée. Les objets dont la date est dans le futur ne seront pas affichés sauf si vous positionnez allow_future à True.

Paramètres requis :

  • year: l'année de l'archive sur 4 chiffres.
  • queryset: un QuerySet d'objets à renvoyer dans l'archive.
  • date_field: le nom du champ DateField ou DateTimeField dans le modèle de QuerySet que l'archive doit utiliser pour déterminer les objets à renvoyer dans la page.

Paramètres optionnels :

  • template_name: le nom complet du template à utiliser pour rendre la page. Cela permet de passer outre le nom du template par défaut (voir ci-dessous).
  • template_loader: le chargeur de template à utiliser pour charger le template. Par défaut, c'est django.template.loader.
  • extra_context: un dictionnaire de valeurs à ajouter au contexte du template. Par défaut, c'est un dictionnaire vide. Si une valeur du dictionnaire est appelable (callable), la vue générique l'appellera juste avant le rendu du template.
  • allow_empty: Une valeur booléenne qui indique s'il faut afficher la page si aucun objet n'est disponible. Si la valeur est False et qu'aucun objet n'est disponible, la vue enverra une erreur 404 au lieu d'envoyer une page vide. La valeur par défaut est True.
  • context_processors: une liste de processeurs de contexte de template à appliquer au template de la vue. Voir la documentation de RequestContext.
  • template_object_name: indique le nom de la variable de template à utiliser dans le contexte du template. Par défaut, c'est object. La vue ajoutera le suffixe '_list' à la valeur de ce paramètre pour déterminer le nom de la variable.
  • make_object_list: un booléen indiquant s'il faut retrouver la totalité de la liste des objets pour cette année et la passer au template. Si True, la liste d'objets sera passée au template sous le nom de object_list. (Le nom object_list peut être différent, voir les précisions sur object_list dans la section "Contexte du template" ci-dessous). La valeur par défaut est False.
  • mimetype: le type MIME à utiliser pour le document résultant. La valeur par défaut est celle du réglage DEFAULT_CONTENT_TYPE.
  • allow_future: une valeur booléenne indiquant s'il faut inclure les objets "futurs" sur la page, où futur signifie des objets pour lesquels le champ spécifié dans date_field est plus grand que la date et l'heure courantes. La valeur par défaut est False.

Nom du template :

Si template_name n'est pas précisé, la vue utilisera le template <app_label>/<model_name>_archive_year.html par défaut.

Contexte du template :

En plus de extra_context, le contexte du template sera :

  • date_list: une liste d'objets datetime.date représentant tous les mois pour lesquels le queryset a renvoyé des objets pour l'année considérée, dans l'ordre ascendant.

  • year: l'année considérée, sous forme d'une chaîne de 4 chiffres.

  • object_list: si le paramètre make_object_list vaut True, renverra une liste des objets disponibles pour l'année considérée, triée sur le champ date. Le nom de cette variable dépend du paramètre template_object_name, qui est object par défaut. Si template_object_name est foo, le nom de la variable sera foo_list.

    Si make_object_list vaut False, object_list sera passé au template comme une liste vide.

django.views.generic.date_based.archive_month

Description :

Une page d'archive mensuelle affichant tous les objets pour un mois donné. Les objets dont la date est dans le futur ne seront pas affichés sauf si vous positionnez allow_future à True.

Paramètres requis :

  • year: l'année pour laquelle l'archive est recherchée (une chaîne de 4 chiffres).
  • month: le mois pour lequel l'archive est recherchée, au format indiqué par le paramètre month_format.
  • queryset: un QuerySet d'objets à renvoyer dans l'archive.
  • date_field: le nom du champ DateField ou DateTimeField dans le modèle de QuerySet que l'archive doit utiliser pour déterminer les objets à renvoyer dans la page.

Paramètres optionnels :

  • month_format: une chaîne de format qui indique celui qui doit être utilisé par le paramètre month. Doit utiliser la syntaxe acceptée par la fonction Python time.strftime. (Voir la documentation de strftime). La valeur par défaut est "%b", qui est le nom du mois abrégé sur trois lettres. Pour utiliser le numéro du mois, utilisez "%m".
  • template_name: le nom complet du template à utiliser pour rendre la page. Cela permet de passer outre le nom du template par défaut (voir ci-dessous).
  • template_loader: le chargeur de template à utiliser pour charger le template. Par défaut, c'est django.template.loader.
  • extra_context: un dictionnaire de valeurs à ajouter au contexte du template. Par défaut, c'est un dictionnaire vide. Si une valeur du dictionnaire est appelable (callable), la vue générique l'appellera juste avant le rendu du template.
  • allow_empty: Une valeur booléenne qui indique s'il faut afficher la page si aucun objet n'est disponible. Si la valeur est False et qu'aucun objet n'est disponible, la vue enverra une erreur 404 au lieu d'envoyer une page vide. La valeur par défaut est False.
  • context_processors: une liste de processeurs de contexte de template à appliquer au template de la vue. Voir la documentation de RequestContext.
  • template_object_name: indique le nom de la variable de template à utiliser dans le contexte du template. Par défaut, c'est object. La vue ajoutera le suffixe '_list' à la valeur de ce paramètre pour déterminer le nom de la variable.
  • mimetype: le type MIME à utiliser pour le document résultant. La valeur par défaut est celle du réglage DEFAULT_CONTENT_TYPE.
  • allow_future: une valeur booléenne indiquant s'il faut inclure les objets "futurs" sur la page, où futur signifie des objets pour lesquels le champ spécifié dans date_field est plus grand que la date et l'heure courantes. La valeur par défaut est False.

Nom du template :

Si template_name n'est pas précisé, la vue utilisera le template <app_label>/<model_name>_archive_month.html par défaut.

Contexte du template :

En plus de extra_context, le contexte du template sera :

  • month: un objet datetime.date représentant le mois considéré.
  • next_month: un objet datetime.date représentant le premier jour du mois suivant le mois considéré. Si le mois suivant est dans le futur, la valeur sera None.
  • previous_month: un objet datetime.date représentant le premier jour du mois précédent. A l'inverse de next_month, ne vaudra jamais None.
  • object_list: une liste d'objets disponibles pour le mois considéré. Le nom de cette variable dépend du paramètre template_object_name, qui est object par défaut. Si template_object_name est foo, le nom de la variable sera foo_list.

django.views.generic.date_based.archive_week

Description :

Une page d'archive hebdomadaire affichant tous les objets pour une semaine donnée. Les objets dont la date est dans le futur ne seront pas affichés sauf si vous positionnez allow_future à True.

Paramètres requis :

  • year: l'année pour laquelle l'archive est recherchée (une chaîne de 4 chiffres).
  • week: la semaine pour laquelle l'archive est recherchée (une chaîne). Les semaines commencent le dimanche.
  • queryset: un QuerySet d'objets à renvoyer dans l'archive.
  • date_field: le nom du champ DateField ou DateTimeField dans le modèle de QuerySet que l'archive doit utiliser pour déterminer les objets à renvoyer dans la page.

Paramètres optionnels :

  • template_name: le nom complet du template à utiliser pour rendre la page. Cela permet de passer outre le nom du template par défaut (voir ci-dessous).
  • template_loader: le chargeur de template à utiliser pour charger le template. Par défaut, c'est django.template.loader.
  • extra_context: un dictionnaire de valeurs à ajouter au contexte du template. Par défaut, c'est un dictionnaire vide. Si une valeur du dictionnaire est appelable (callable), la vue générique l'appellera juste avant le rendu du template.
  • allow_empty: Une valeur booléenne qui indique s'il faut afficher la page si aucun objet n'est disponible. Si la valeur est False et qu'aucun objet n'est disponible, la vue enverra une erreur 404 au lieu d'envoyer une page vide. La valeur par défaut est False.
  • context_processors: une liste de processeurs de contexte de template à appliquer au template de la vue. Voir la documentation de RequestContext.
  • template_object_name: indique le nom de la variable de template à utiliser dans le contexte du template. Par défaut, c'est object. La vue ajoutera le suffixe '_list' à la valeur de ce paramètre pour déterminer le nom de la variable.
  • mimetype: le type MIME à utiliser pour le document résultant. La valeur par défaut est celle du réglage DEFAULT_CONTENT_TYPE.
  • allow_future: une valeur booléenne indiquant s'il faut inclure les objets "futurs" sur la page, où futur signifie des objets pour lesquels le champ spécifié dans date_field est plus grand que la date et l'heure courantes. La valeur par défaut est False.

Nom du template :

Si template_name n'est pas précisé, la vue utilisera le template <app_label>/<model_name>_archive_week.html par défaut.

Contexte du template :

En plus de extra_context, le contexte du template sera :

  • week: un objet datetime.date représentant le premier jour de la semaine considérée.
  • object_list: une liste d'objets disponibles pour la semaine considérée. Le nom de cette variable dépend du paramètre template_object_name, qui est object par défaut. Si template_object_name est foo, le nom de la variable sera foo_list.

django.views.generic.date_based.archive_day

Description :

Une page d'archive quotidienne affichant tous les objets pour un jour donné. Les objets dont la date est dans le futur renverront une erreur 404 indépendamment du fait qu'il existe des objets pour des jours futurs, sauf si vous positionnez allow_future à True.

Paramètres requis :

  • year: l'année pour laquelle l'archive est recherchée (une chaîne de 4 chiffres).
  • month: le mois pour lequel l'archive est recherchée, au format indiqué par le paramètre month_format.
  • day: le jour pour lequel l'archive est recherchée, au format indiqué par le paramètre day_format.
  • queryset: un QuerySet d'objets à renvoyer dans l'archive.
  • date_field: le nom du champ DateField ou DateTimeField dans le modèle de QuerySet que l'archive doit utiliser pour déterminer les objets à renvoyer dans la page.

Paramètres optionnels :

  • month_format: une chaîne de format qui indique celui qui doit être utilisé par le paramètre month. Doit utiliser la syntaxe acceptée par la fonction Python time.strftime. (Voir la documentation de strftime). La valeur par défaut est "%b", qui est le nom du mois abrégé sur trois lettres. Pour utiliser le numéro du mois, utilisez "%m".
  • day_format: comme month_format, mais pour le paramètre day. La valeur par défaut est "%d" (quantième du jour du mois, 01-31).
  • template_name: le nom complet du template à utiliser pour rendre la page. Cela permet de passer outre le nom du template par défaut (voir ci-dessous).
  • template_loader: le chargeur de template à utiliser pour charger le template. Par défaut, c'est django.template.loader.
  • extra_context: un dictionnaire de valeurs à ajouter au contexte du template. Par défaut, c'est un dictionnaire vide. Si une valeur du dictionnaire est appelable (callable), la vue générique l'appellera juste avant le rendu du template.
  • allow_empty: Une valeur booléenne qui indique s'il faut afficher la page si aucun objet n'est disponible. Si la valeur est False et qu'aucun objet n'est disponible, la vue enverra une erreur 404 au lieu d'envoyer une page vide. La valeur par défaut est False.
  • context_processors: une liste de processeurs de contexte de template à appliquer au template de la vue. Voir la documentation de RequestContext.
  • template_object_name: indique le nom de la variable de template à utiliser dans le contexte du template. Par défaut, c'est object. La vue ajoutera le suffixe '_list' à la valeur de ce paramètre pour déterminer le nom de la variable.
  • mimetype: le type MIME à utiliser pour le document résultant. La valeur par défaut est celle du règlage DEFAULT_CONTENT_TYPE.
  • allow_future: une valeur booléenne indiquant s'il faut inclure les objets "futurs" sur la page, où futur signifie des objets pour lesquels le champ spécifié dans date_field est plus grand que la date et l'heure courantes. La valeur par défaut est False.

Nom du template :

Si template_name n'est pas précisé, la vue utilisera le template <app_label>/<model_name>_archive_day.html par défaut.

Contexte du template :

En plus de extra_context, le contexte du template sera :

  • day: un objet datetime.date représentant le jour considéré.
  • next_day: un objet datetime.date représentant le jour suivant. Si le jour suivant est dans le futur, vaudra None.
  • previous_day: un objet datetime.date représentant le jour précédent. Contrairement à next_day, ne vaudra jamais None.
  • object_list: une liste d'objets disponibles pour le jour considéré. Le nom de cette variable dépend du paramètre template_object_name, qui est object par défaut. Si template_object_name est foo, le nom de la variable sera foo_list.

django.views.generic.date_based.archive_today

Description :

Une page d'archive quotidienne affichant tous les objets pour aujourd'hui. C'est exactement la même que archive_day, mais les paramètres year/month/day ne sont pas pris en compte, et la date du jour est utilisée à la place.

django.views.generic.date_based.object_detail

Description :

Une page pour afficher un objet individuel. Si la date de l'objet est dans le futur, renverra une erreur 404 par défaut, sauf si vous positionnez allow_future à True.

Paramètres requis :

  • year: l'année de l'objet (une chaîne de 4 chiffres).

  • month: le mois de l'objet, au format indiqué par le paramètre month_format.

  • day: le jour de l'objet, au format indiqué par le paramètre day_format.

  • queryset: un QuerySet de l'objet à renvoyer dans l'archive.

  • date_field: le nom du champ DateField ou DateTimeField dans le modèle de QuerySet que la vue générique doit utiliser pour déterminer l'objet à renvoyer en fonction de year, month et day.

  • Soit object_id, soit (slug et slug_field) sont requis.

    Si object_id est fourni, ce doit être la valeur du champ de clé primaire pour l'objet affiché sur la page.

    Sinon, slug doit être le slug de l'objet choisi, et slug_field doit être le nom du champ slug dans le modèle de QuerySet. La valeur par défaut de slug_field est 'slug'.

Paramètres optionnels :

  • month_format: une chaîne de format qui indique celui qui doit être utilisé par le paramètre month. Doit utiliser la syntaxe acceptée par la fonction Python time.strftime. (Voir la documentation de strftime). La valeur par défaut est "%b", qui est le nom du mois abrégé sur trois lettres. Pour utiliser le numéro du mois, utilisez "%m".

  • day_format: comme month_format, mais pour le paramètre day. La valeur par défaut est "%d" (quantième du jour du mois, 01-31).

  • template_name: le nom complet du template à utiliser pour rendre la page. Cela permet de passer outre le nom du template par défaut (voir ci-dessous).

  • template_name_field: le nom d'un champ de l'objet dont la valeur est le nom du template à utiliser. Cela vous permet de stocker le nom du template dans les données. En d'autres termes, si votre objet a un champ appelé 'the_template' qui contient la chaîne 'foo.html', et si vous positionnez template_name_field à la valeur 'the_template', la vue générique de votre objet utilisera le template 'foo.html'.

    Ça fait un peu mal à la tête, mais c'est parfois utile.

  • template_loader: le chargeur de template à utiliser pour charger le template. Par défaut, c'est django.template.loader.

  • extra_context: un dictionnaire de valeurs à ajouter au contexte du template. Par défaut, c'est un dictionnaire vide. Si une valeur du dictionnaire est appelable (callable), la vue générique l'appellera juste avant le rendu du template.

  • context_processors: une liste de processeurs de contexte de template à appliquer au template de la vue. Voir la documentation de RequestContext.

  • template_object_name: indique le nom de la variable de template à utiliser dans le contexte du template. Par défaut, c'est object.

  • mimetype: le type MIME à utiliser pour le document résultant. La valeur par défaut est celle du réglage DEFAULT_CONTENT_TYPE.

  • allow_future: une valeur booléenne indiquant s'il faut inclure les objets "futurs" sur la page, où futur signifie des objets pour lesquels le champ spécifié dans date_field est plus grand que la date et l'heure courantes. La valeur par défaut est False.

Nom du template :

Si template_name n'est pas précisé, la vue utilisera le template <app_label>/<model_name>_detail.html par défaut.

Contexte du template :

En plus de extra_context, le contexte du template sera :

  • object: l'objet lui-même. Le nom de cette variable dépend du paramètre template_object_name, qui est object par défaut. Si la valeur de template_object_name est 'foo', le nom de la variable sera 'foo'.

Vues génériques liste/détail

Le framework de vues liste/détail (dans le module django.views.generic.list_detail) est similaire à celui qui est basé sur les dates, sauf qu'il procure simplement deux vues : une liste d'objets et une page d'objet individuel.

django.views.generic.list_detail.object_list

Description :

Une page affichant une liste d'objets.

Paramètres requis :

  • queryset: un QuerySet représentant les objets à afficher.

Paramètres optionnels :

  • paginate_by: un entier précisant combien d'objets doivent être affichés par page. Si ce paramètre est fourni, la vue paginera les objets avec paginate_by objets par page. La vue attendra soit un paramètre page (via GET), soit une variable page spécifiée dans l'URLconf. Voir les notes sur la pagination ci-dessous.
  • page: le numéro de la page courante. C'est un entier et la numérotation commence à 1. Voir les notes sur la pagination ci-dessous.
  • template_name: le nom complet du template à utiliser pour rendre la page. Cela permet de passer outre le nom du template par défaut (voir ci-dessous).
  • template_loader: le chargeur de template à utiliser pour charger le template. Par défaut, c'est django.template.loader.
  • extra_context: un dictionnaire de valeurs à ajouter au contexte du template. Par défaut, c'est un dictionnaire vide. Si une valeur du dictionnaire est appelable (callable), la vue générique l'appellera juste avant le rendu du template.
  • allow_empty: Une valeur booléenne qui indique s'il faut afficher la page si aucun objet n'est disponible. Si la valeur est False et qu'aucun objet n'est disponible, la vue enverra une erreur 404 au lieu d'envoyer une page vide. La valeur par défaut est False.
  • context_processors: une liste de processeurs de contexte de template à appliquer au template de la vue. Voir la documentation de RequestContext.
  • template_object_name: indique le nom de la variable de template à utiliser dans le contexte du template. Par défaut, c'est object. La vue ajoutera le suffixe '_list' à la valeur de ce paramètre pour déterminer le nom de la variable.
  • mimetype: le type MIME à utiliser pour le document résultant. La valeur par défaut est celle du réglage DEFAULT_CONTENT_TYPE.

Nom du template :

Si template_name n'est pas précisé, la vue utilisera le template <app_label>/<model_name>_list.html par défaut.

Contexte du template :

En plus de extra_context, le contexte du template sera :

  • object_list: la liste d'objets. Le nom de cette variable dépend du paramètre template_object_name, qui est object par défaut. Si template_object_name est 'foo', le nom de la variable sera 'foo_list'.
  • is_paginated: un booléen indiquant si les résultats doivent être paginés. Plus précisément, vaudra False si le nombre d'objets à représenter est inférieur ou égal à paginate_by.

Si les résultats sont paginés, le contexte contiendra ces variables supplémentaires :

  • Nouveau dans la version de développement de Django : paginator : Une instance de django.core.paginator.Paginator.
  • Nouveau dans la version de développement de Django : page_obj : Une instance de django.core.paginator.Page.

Dans les anciennes versions de Django, avant que paginator et page_obj ne soient ajoutés au contexte de ce template, le template contenait plusieurs autres variables liées à la pagination. Notez que vous ne devez PLUS utiliser ces variables ; utilisez paginator et page_obj à la place, parce qu'elles vous permettent de faire tout ce que faisaient les anciennes variables (et bien plus !). Mais pour le suivi des installations plus anciennes, voici une liste de ces anciennes variables de template :

  • results_per_page: le nombre d'objets par page. (Identique au paramètre paginate_by.)

  • has_next: un booléen indiquant s'il y a une page suivante.

  • has_previous: un booléen indiquant s'il y a une page précédente.

  • page: le numéro de la page courante sous la forme d'un entier. La numérotation commence à la page 1.

  • next: le numéro de la page suivante sous la forme d'un entier. S'il n'y a pas de page suivante, contiendra toujours un entier indiquant le numéro théorique de la page suivante. La numérotation commence à la page 1.

  • previous: le numéro de la page précédente sous la forme d'un entier. La numérotation commence à la page 1.

  • last_on_page: le numéro du dernier objet résultat sur la page courante. La numérotation commence à 1.

  • first_on_page: le numéro du premier objet résultat sur la page courante. La numérotation commence à 1.

  • pages: le nombre total de pages, sous la forme d'un entier.

  • hits: le nombre total d'objets sur toutes les pages (pas seulement la page courante).

  • page_range: la liste des numéros de page disponibles. La numérotation

    commence à 1.

Notes sur la pagination

Si paginate_by est précisé, Django paginera les résultats. Vous pouvez spécifier le numéro de la page dans l'URL de deux façons :

  • En utilisant le paramètre page dans l'URLconf. Par exemple:

    (r'^objects/page(?P<page>[0-9]+)/$', 'object_list', dict(info_dict))

  • En passant le numéro de page par le paramètre page dans l'URL. Par exemple:

    /objects/?page=3

  • Pour boucler sur tous les numéros de pages disponibles, utilisez la variable page_range. Vous pouvez parcourir la liste fournie par page_range pour créer un lien vers chaque page de résultats.

Ces listes et valeurs démarrent toujours la numérotation à 1 et non à 0, donc la première page sera toujours représentée comme la page 1.

Pour plus d'informations sur la pagination, lisez la documentation sur la pagination.

Nouveau dans la version de développement de Django :

Vous pouvez également utiliser last comme cas particulier de valeur pour la variable page:

/objects/?page=last

Cela vous permet d'accéder à la dernière page des résultats sans avoir à déterminer auparavant le nombre de pages.

Notez que page doit être un numéro de page valide ou la valeur last, toute autre valeur résultera en une erreur 404.

django.views.generic.list_detail.object_detail

Description :

Une page représentant un seul objet.

Paramètres requis :

  • queryset: un QuerySet contenant l'objet.

  • Soit object_id, soit (slug et slug_field) sont requis.

    Si object_id est fourni, ce doit être la valeur du champ de clé primaire pour l'objet affiché sur la page.

    Sinon, slug doit être le slug de l'objet choisi, et slug_field doit être le nom du champ slug dans le modèle de QuerySet.

Paramètres optionnels :

  • template_name: le nom complet du template à utiliser pour rendre la page. Cela permet de passer outre le nom du template par défaut (voir ci-dessous).

  • template_name_field: le nom d'un champ de l'objet dont la valeur est le nom du template à utiliser. Cela vous permet de stocker le nom du template dans les données. En d'autres termes, si votre objet a un champ appelé 'the_template' qui contient la chaîne 'foo.html', et si vous positionnez template_name_field à la valeur 'the_template', la vue générique de votre objet utilisera le template 'foo.html'.

    Ça fait un peu mal à la tête, mais c'est parfois utile.

  • template_loader: le chargeur de template à utiliser pour charger le template. Par défaut, c'est django.template.loader.

  • extra_context: un dictionnaire de valeurs à ajouter au contexte du template. Par défaut, c'est un dictionnaire vide. Si une valeur du dictionnaire est appelable (callable), la vue générique l'appellera juste avant le rendu du template.

  • context_processors: une liste de processeurs de contexte de template à appliquer au template de la vue. Voir la documentation de RequestContext.

  • template_object_name: indique le nom de la variable de template à utiliser dans le contexte du template. Par défaut, c'est object.

  • mimetype: le type MIME à utiliser pour le document résultant. La valeur par défaut est celle du réglage DEFAULT_CONTENT_TYPE.

Nom du template :

Si template_name n'est pas précisé, la vue utilisera le template <app_label>/<model_name>_detail.html par défaut.

Contexte du template :

En plus de extra_context, le contexte du template sera :

  • object: l'objet lui-même. Le nom de cette variable dépend du paramètre template_object_name, qui est object par défaut. Si la valeur de template_object_name est 'foo', le nom de la variable sera 'foo'.

Vues génériques de création/mise à jour/effacement

Le module django.views.generic.create_update contient un ensemble de fonctions pour créer, éditer et effacer des objets.

Modifié dans la version de développement de Django

django.views.generic.create_update.create_object et django.views.generic.create_update.update_object utilisent désormais les newforms pour construire et afficher le formulaire.

django.views.generic.create_update.create_object

Description :

Une page affichant un formulaire de création pour un objet, avec éventuellement un réaffichage du formulaire avec les erreurs de validation s'il y en a, et la sauvegarde de l'objet.

Paramètres requis :

  • Soit form_class, soit model sont requis.

    Si vous fournissez form_class, ce doit être une sous-classe de django.newforms.ModelForm. Utilisez cet argument si vous devez personnaliser le formulaire du modèle. Voir la documentation des ModelForm pour plus d'information.

    Sinon, model doit être une classe de modèle Django et le formulaire utilisé sera un ModelForm standard pour model.

Paramètres optionnels :

  • post_save_redirect: l'URL vers laquelle la vue redirigera après la sauvegarde de l'objet. Par défaut, object.get_absolute_url().

    post_save_redirect peut contenir des variables d'interpolation de chaînes, qui seront interpolées contre les champs attributs de l'objet. Par exemple, vous pourriez utiliser post_save_redirect="/polls/%(slug)s/".

  • login_required: un booléen indiquant si l'utilisateur doit être authentifié pour voir la page et enregistrer ses changements. Fait référence à et utilise le système d'authentification de Django. La valeur par défaut est False.

    Si la valeur est True, et qu'un utilisateur non authentifié tente de visiter cette page ou de valider le formulaire, Django le redirigera vers /accounts/login/.

  • template_name: le nom complet du template à utiliser pour afficher la page. Cela permet de passer outre le nom du template par défaut (voir ci-dessous).

  • template_loader: le chargeur de template à utiliser pour charger le template. Par défaut, c'est django.template.loader.

  • extra_context: un dictionnaire de valeurs à ajouter au contexte du template. Par défaut, c'est un dictionnaire vide. Si une valeur du dictionnaire est appelable (callable), la vue générique l'appellera juste avant le rendu du template.

  • context_processors: une liste de processeurs de contexte de template à appliquer au template de la vue. Voir la documentation de RequestContext.

Nom du template :

Si template_name n'est pas précisé, la vue utilisera le template <app_label>/<model_name>_form.html par défaut.

Contexte du template :

En plus de extra_context, le contexte du template sera :

  • form: une instance de django.newforms.ModelForm représentant le formulaire à utiliser pour créer l'objet. Cela permet de facilement faire référence au formulaire dans le système de template.

    Par exemple, si le modèle possède deux champs, name et address:

    <form action="" method="post">
<p>{{ form.name.label_tag }} {{ form.name }}</p>
<p>{{ form.address.label_tag }} {{ form.address }}</p>
</form>

    Voir la documentation des newforms pour plus d'informations sur l'utilisation des objets Form dans les templates.

django.views.generic.create_update.update_object

Description :

Une page affichant un formulaire d'édition pour un objet existant, avec éventuellement un réaffichage du formulaire avec les erreurs de validation s'il y en a, et la sauvegarde des modifications de l'objet. Utilise les manipulateurs automatiques fournis avec les modèles Django.

Paramètres requis :

  • Soit form_class, soit model sont requis.

    Si vous fournissez form_class, ce doit être une sous-classe de django.newforms.ModelForm. Utilisez cet argument si vous devez personnaliser le formulaire du modèle. Voir la documentation des ModelForm pour plus d'information.

    Sinon, model doit être une classe de modèle Django et le formulaire utilisé sera un ModelForm standard pour model.

  • Soit object_id, soit (slug et slug_field) sont requis.

    Si object_id est fourni, ce doit être la valeur du champ de clé primaire pour l'objet affiché sur la page.

    Sinon, slug doit être le slug de l'objet choisi, et slug_field doit être le nom du champ slug dans le modèle de QuerySet. La valeur par défaut de slug_field est 'slug'.

Paramètres optionnels :

  • post_save_redirect: l'URL vers laquelle la vue redirigera après la sauvegarde de l'objet. Par défaut, object.get_absolute_url().

    post_save_redirect peut contenir des variables d'interpolation de chaînes, qui seront interpolées contre les champs attributs de l'objet. Par exemple, vous pourriez utiliser post_save_redirect="/polls/%(slug)s/".

  • login_required: un booléen indiquant si l'utilisateur doit être authentifié pour voir la page et enregistrer ses changements. Fait référence à et utilise le système d'authentification de Django. La valeur par défaut est False.

    Si la valeur est True, et qu'un utilisateur non authentifié tente de visiter cette page ou de valider le formulaire, Django le redirigera vers /accounts/login/.

  • template_name: le nom complet du template à utiliser pour rendre la page. Cela permet de passer outre le nom du template par défaut (voir ci-dessous).

  • template_loader: le chargeur de template à utiliser pour charger le template. Par défaut, c'est django.template.loader.

  • extra_context: un dictionnaire de valeurs à ajouter au contexte du template. Par défaut, c'est un dictionnaire vide. Si une valeur du dictionnaire est appelable (callable), la vue générique l'appellera juste avant le rendu du template.

  • context_processors: une liste de processeurs de contexte de template à appliquer au template de la vue. Voir la documentation de RequestContext.

  • template_object_name: indique le nom de la variable de template à utiliser dans le contexte du template. Par défaut, c'est object.

Nom du template :

Si template_name n'est pas précisé, la vue utilisera le template <app_label>/<model_name>_form.html par défaut.

Contexte du template :

En plus de extra_context, le contexte du template sera :

  • form: une instance de django.newforms.ModelForm représentant le formulaire à utiliser pour éditer l'objet. Cela permet de facilement faire référence au formulaire dans le système de template.

    Par exemple, si le modèle possède deux champs, name et address:

    <form action="" method="post">
<p>{{ form.name.label_tag }} {{ form.name }}</p>
<p>{{ form.address.label_tag }} {{ form.address }}</p>
</form>

    Voir la documentation des newforms pour plus d'informations sur l'utilisation des objets Form dans les templates.

  • object: l'objet original à éditer. Le nom de cette variable dépend du paramètre template_object_name, qui est object par défaut. Si la valeur de template_object_name est 'foo', le nom de la variable sera 'foo'.

django.views.generic.create_update.delete_object

Description :

Une vue qui affiche une page de confirmation et efface un objet existant. L'objet ne sera effacé que si la méthode de requête est POST. Si cette vue est requise via GET, elle affichera une page de confirmation qui doit contenir un formulaire qui utilise POST vers la même URL.

Paramètres requis :

  • model: la classe de modèle Django de l'objet que le formulaire va effacer.

  • Soit object_id, soit (slug et slug_field) sont requis.

    Si object_id est fourni, ce doit être la valeur du champ de clé primaire pour l'objet affiché sur la page.

    Sinon, slug doit être le slug de l'objet choisi, et slug_field doit être le nom du champ slug dans le modèle de QuerySet. La valeur par défaut de slug_field est 'slug'.

  • post_delete_redirect: une URL vers laquelle la vue redirigera après effacement de l'objet.

Paramètres optionnels :

  • login_required: un booléen indiquant si l'utilisateur doit être authentifié pour voir la page et enregistrer ses changements. Fait référence à et utilise le système d'authentification de Django. La valeur par défaut est False.

    Si la valeur est True, et qu'un utilisateur non authentifié tente de visiter cette page ou de valider le formulaire, Django le redirigera vers /accounts/login/.

  • template_name: le nom complet du template à utiliser pour rendre la page. Cela permet de passer outre le nom du template par défaut (voir ci-dessous).

  • template_loader: le chargeur de template à utiliser pour charger le template. Par défaut, c'est django.template.loader.

  • extra_context: un dictionnaire de valeurs à ajouter au contexte du template. Par défaut, c'est un dictionnaire vide. Si une valeur du dictionnaire est appelable (callable), la vue générique l'appellera juste avant le rendu du template.

  • context_processors: une liste de processeurs de contexte de template à appliquer au template de la vue. Voir la documentation de RequestContext.

  • template_object_name: indique le nom de la variable de template à utiliser dans le contexte du template. Par défaut, c'est object.

Nom du template :

Si template_name n'est pas précisé, la vue utilisera le template <app_label>/<model_name>_confirm_delete.html par défaut.

Contexte du template :

En plus de extra_context, le contexte du template sera :

  • object: l'objet original qui va être effacé. Le nom de cette variable dépend du paramètre template_object_name, qui est object par défaut. Si la valeur de template_object_name est 'foo', le nom de la variable sera 'foo'.

Informations

Accès rapide

Traducteur(s)

Liens (peut-être) en rapport