django/docs/topics/http/shortcuts.txt

.. _topics-http-shortcuts:

=========================
Django shortcut functions
=========================

The package ``django.shortcuts`` collects helper functions and classes that
"span" multiple levels of MVC. In other words, these functions/classes
introduce controlled coupling for convenience's sake.

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

``django.shortcuts.render_to_response`` renders a given template with a given
context dictionary and returns an ``HttpResponse`` object with that rendered
text.

Required arguments
------------------

``template``
    The full name of a template to use.

Optional arguments
------------------

``dictionary``
    A dictionary of values to add to the template context. By default, this
    is an empty dictionary. If a value in the dictionary is callable, the
    view will call it just before rendering the template.

``context_instance``
    The context instance to render the template with. By default, the template
    will be rendered with a ``Context`` instance (filled with values from
    ``dictionary``). If you need to use :ref:`context processors
    <subclassing-context-requestcontext>`, render the template with a
    ``RequestContext`` instance instead. Your code might look something like
    this::

        return render_to_response('my_template.html',
                                  my_data_dictionary,
                                  context_instance=RequestContext(request))

``mimetype``

    .. versionadded:: 1.0

    The MIME type to use for the resulting document. Defaults to the value of
    the :setting:`DEFAULT_CONTENT_TYPE` setting.

Example
-------

The following example renders the template ``myapp/index.html`` with the
MIME type ``application/xhtml+xml``::

    from django.shortcuts import render_to_response

    def my_view(request):
        # View code here...
        return render_to_response('myapp/index.html', {"foo": "bar"},
            mimetype="application/xhtml+xml")

This example is equivalent to::

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

    def my_view(request):
        # View code here...
        t = loader.get_template('myapp/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`` calls
:meth:`~django.db.models.QuerySet.get()` on a given model manager, but it raises
``django.http.Http404`` instead of the model's ``DoesNotExist`` exception.

Required arguments
------------------

``klass``
    A ``Model``, ``Manager`` or ``QuerySet`` instance from which to get the
    object.

``**kwargs``
    Lookup parameters, which should be in the format accepted by ``get()`` and
    ``filter()``.

Example
-------

The following example gets the object with the primary key of 1 from
``MyModel``::

    from django.shortcuts import get_object_or_404

    def my_view(request):
        my_object = get_object_or_404(MyModel, pk=1)

This example is equivalent to::

    from django.http import Http404

    def my_view(request):
        try:
            my_object = MyModel.objects.get(pk=1)
        except MyModel.DoesNotExist:
            raise Http404

Note: As with ``get()``, an ``MultipleObjectsReturned`` exception will be
raised if more than one object is found.

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

``django.shortcuts.get_list_or_404`` returns the result of
:meth:`~django.db.models.QuerySet.filter()` on a given model manager, raising
``django.http.Http404`` if the resulting list is empty.

Required arguments
------------------

``klass``
    A ``Model``, ``Manager`` or ``QuerySet`` instance from which to get the
    object.

``**kwargs``
    Lookup parameters, which should be in the format accepted by ``get()`` and
    ``filter()``.

Example
-------

The following example gets all published objects from ``MyModel``::

    from django.shortcuts import get_list_or_404

    def my_view(request):
        my_objects = get_list_or_404(MyModel, published=True)

This example is equivalent to::

    from django.http import Http404

    def my_view(request):
        my_objects = list(MyModel.objects.filter(published=True))
        if not my_objects:
            raise Http404