django1/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
------------------

``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 `context processors`_, you will want to
    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``
    **New in Django development version:** The MIME type to use for the
    resulting document. Defaults to the value of the ``DEFAULT_CONTENT_TYPE``
    setting.

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

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 `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(): ../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 = MyModel.objects.filter(published=True)
        if not my_objects:
            raise Http404

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