root/docs/trunk/shortcuts.txt

=================================
Fonctions de raccourcis de Django
=================================

Le module ``django.shortcuts`` contient un ensemble de fonctions et de classes
d'aide couvrant de multiples niveau de l'architecture MVC. En d'autres termes,
ces fonctions/classes introduisent un couplage contrÎlé, pour notre
commodité.

``render_to_response()``
========================

``django.shortcuts.render_to_response`` rend un gabarit donné avec un
dictionnaire contextuel et retourne un objet ``HttpResponse`` de ce texte
rendu.

Arguments obligatoires
----------------------

``template``
    Le nom complet du gabarit à utiliser.

Arguments optionnels
--------------------

``dictionary``
    Un dictionnaire de données à ajouter au contexte du gabarit. Par défaut,
    il s'agit d'un dictionnaire vide. Si une valeur du dictionnaire est
    exécutable, la vue l'appellera juste avant le rendu du gabarit.

``context_instance``
    L'instance contextuelle avec laquelle rendre le gabarit. Par défaut, le
    gabarit sera rendu avec une instance ``Context`` (remplie avec les valeurs
    de ``dictionary``). Si vous avez besoin d'un `context processors`_, 
    utilisez à la place une instance ``RequestContext`` pour rendre le 
    gabarit. Votre code ressemblera à quelque chose comme::

        return render_to_response('mon_gabarit.html',
                                  mon_dictionaire_de_donnees,
                                  context_instance=RequestContext(request))

``mimetype``
    **Nouveau dans la version de développement de Django:** Le type MIME à 
    utiliser pour le document résultant. Par défaut utilise la valeur de la 
    propriété ``DEFAULT_CONTENT_TYPE``.

.. _`context processors`: ../templates_python/#subclassing-context-requestcontext

Exemple
-------

L'exemple suivant rend le gabarit ``monapp/index.html`` avec le type MIME
``application/xhtml+xml``::

    from django.shortcuts import render_to_response

    def ma_vue(request):
        # Code de la vue...
        return render_to_response('monapp/index.html', {"foo": "bar"},
            mimetype="application/xhtml+xml")

Cet exemple est équivalent à ::

    from django.http import HttpResponse
    from django.template import Context, loader

    def ma_vue(request):
        # Code de la vue...
        t = loader.get_template('monapp/template.html')
        c = Context({'foo': 'bar'})
        r = HttpResponse(t.render(c),
            mimetype="application/xhtml+xml")

``get_object_or_404``
=====================

``django.shortcuts.get_object_or_404`` appelle `get()`_ sur un manager de 
modÚle donné, mais elle lÚve ``django.http.Http404`` au lieu de l'exception
de modÚle ``DoesNotExist``.

Arguments obligatoires
----------------------

``klass``
    Une instance de ``Model``, ``Manager`` ou ``QuerySet`` Ã  partir duquel
    récupérer l'objet.

``**kwargs``
    ParamÚtres de recherche, qui doivent être dans le format accepté par 
    ``get()`` et ``filter()``.

Exemple
-------

L'exemple suivant récupÚre un objet avec la clé primaire 1 pour ``MonModel``::

    from django.shortcuts import get_object_or_404

    def ma_vue(request):
        mon_objet = get_object_or_404(MonModel, pk=1)

Cet exemple est équivalent à ::

    from django.http import Http404

    def ma_vue(request):
        try:
            mon_objet = MonModel.objects.get(pk=1)
        except MonModel.DoesNotExist:
            raise Http404

Note: Tout comme ``get()``, une exception ``MultipleObjectsReturned`` sera
levée si plus d'un objet est retrouvé.

.. _get(): ../db-api/#get-kwargs

``get_list_or_404``
===================

``django.shortcuts.get_list_or_404`` retourne le résultat de `filter()`_ sur
une manager de modÚle donné, levant ``django.http.Http404`` si la liste 
résultante est vide.

Arguments obligatoires
----------------------

``klass``
    Une instance de ``Model``, ``Manager`` ou ``QuerySet`` Ã  partir duquel
    récupérer l'objet.

``**kwargs``
    ParamÚtres de recherche, qui doivent être dans le format accepté par 
    ``get()`` et ``filter()``.

Exemple
-------

L'exemple suivant récupÚre tous les objets publiés pour ``MonModel``::

    from django.shortcuts import get_list_or_404

    def ma_vue(request):
        mes_objets = get_list_or_404(MonModel, published=True)

Cet exemple est équivalent à ::

    from django.http import Http404

    def ma_vue(request):
        mes_objets = MonModel.objects.filter(published=True)
        if not mes_objets:
            raise Http404

.. _filter(): ../db-api/#filter-kwargs