docs/shortcuts.txt

   1 =========================
   2 Django shortcut functions
   3 =========================
   4
   5 The package ``django.shortcuts`` collects helper functions and classes that
   6 "span" multiple levels of MVC. In other words, these functions/classes
   7 introduce controlled coupling for convenience's sake.
   8
   9 ``render_to_response()``
  10 ========================
  11
  12 ``django.shortcuts.render_to_response`` renders a given template with a given
  13 context dictionary and returns an ``HttpResponse`` object with that rendered
  14 text.
  15
  16 Required arguments
  17 ------------------
  18
  19 ``template``
  20     The full name of a template to use.
  21
  22 Optional arguments
  23 ------------------
  24
  25 ``context``
  26     A dictionary of values to add to the template context. By default, this
  27     is an empty dictionary. If a value in the dictionary is callable, the
  28     view will call it just before rendering  the template.
  29
  30 ``mimetype``
  31     **New in Django development version:** The MIME type to use for the
  32     resulting document. Defaults to the value of the ``DEFAULT_CONTENT_TYPE``
  33     setting.
  34
  35 Example
  36 -------
  37
  38 The following example renders the template ``myapp/index.html`` with the
  39 MIME type ``application/xhtml+xml``::
  40
  41     from django.shortcuts import render_to_response
  42
  43     def my_view(request):
  44         # View code here...
  45         return render_to_response('myapp/index.html', {"foo": "bar"},
  46             mimetype="application/xhtml+xml")
  47
  48 This example is equivalent to::
  49
  50     from django.http import HttpResponse
  51     from django.template import Context, loader
  52
  53     def my_view(request):
  54         # View code here...
  55         t = loader.get_template('myapp/template.html')
  56         c = Context({'foo': 'bar'})
  57         r = HttpResponse(t.render(c),
  58             mimetype="application/xhtml+xml")
  59
  60 .. _an HttpResponse object: ../request_response/#httpresponse-objects
  61
  62 ``get_object_or_404``
  63 =====================
  64
  65 ``django.shortcuts.get_object_or_404`` calls `get()`_ on a given model
  66 manager, but it raises ``django.http.Http404`` instead of the model's
  67 ``DoesNotExist`` exception.
  68
  69 Required arguments
  70 ------------------
  71
  72 ``klass``
  73     A ``Model``, ``Manager`` or ``QuerySet`` instance from which to get the
  74     object.
  75
  76 ``**kwargs``
  77     Lookup parameters, which should be in the format accepted by ``get()`` and
  78     ``filter()``.
  79
  80 Example
  81 -------
  82
  83 The following example gets the object with the primary key of 1 from
  84 ``MyModel``::
  85
  86     from django.shortcuts import get_object_or_404
  87
  88     def my_view(request):
  89         my_object = get_object_or_404(MyModel, pk=1)
  90
  91 This example is equivalent to::
  92
  93     from django.http import Http404
  94
  95     def my_view(request):
  96         try:
  97             my_object = MyModel.object.get(pk=1)
  98         except MyModel.DoesNotExist:
  99             raise Http404
 100
 101 Note: As with ``get()``, an ``AssertionError`` will be raised if more than
 102 one object is found.
 103
 104 .. _get(): ../db-api/#get-kwargs
 105
 106 ``get_list_or_404``
 107 ===================
 108
 109 ``django.shortcuts.get_list_or_404`` returns the result of `filter()`_ on a
 110 given model manager, raising ``django.http.Http404`` if the resulting list is
 111 empty.
 112
 113 Required arguments
 114 ------------------
 115
 116 ``klass``
 117     A ``Model``, ``Manager`` or ``QuerySet`` instance from which to get the
 118     object.
 119
 120 ``**kwargs``
 121     Lookup parameters, which should be in the format accepted by ``get()`` and
 122     ``filter()``.
 123
 124 Example
 125 -------
 126
 127 The following example gets all published objects from ``MyModel``::
 128
 129     from django.shortcuts import get_list_or_404
 130
 131     def my_view(request):
 132         my_objects = get_list_or_404(MyModel, published=True)
 133
 134 This example is equivalent to::
 135
 136     from django.http import Http404
 137
 138     def my_view(request):
 139         my_objects = MyModels.object.filter(published=True)
 140         if not my_objects:
 141             raise Http404
 142
 143 .. _filter(): ../db-api/#filter-kwargs