django/docs/shortcuts.txt

=========================
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
------------------

``context``
    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.

``mimetype``
    **New in Django development version:** The MIME type to use for the
    resulting document. Defaults to the value of the ``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")

.. _an HttpResponse object: ../request_response/#httpresponse-objects

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

``django.shortcuts.get_object_or_404`` calls `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.object.get(pk=1)
        except MyModel.DoesNotExist:
            raise Http404

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

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

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

``django.shortcuts.get_list_or_404`` returns the result of `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 = MyModels.object.filter(published=True)
        if not my_objects:
            raise Http404

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