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 ``dictionary``
  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 ``context_instance``
  31     The context instance to render the template with. By default, the template
  32     will be rendered with a ``Context`` instance (filled with values from
  33     ``dictionary``). If you need to use `context processors`_, render the
  34     template with a ``RequestContext`` instance instead. Your code might look
  35     something like this::
  36
  37         return render_to_response('my_template.html',
  38                                   my_data_dictionary,
  39                                   context_instance=RequestContext(request))
  40
  41 ``mimetype``
  42     **New in Django development version:** The MIME type to use for the
  43     resulting document. Defaults to the value of the ``DEFAULT_CONTENT_TYPE``
  44     setting.
  45
  46 .. _`context processors`: ../templates_python/#subclassing-context-requestcontext
  47
  48 Example
  49 -------
  50
  51 The following example renders the template ``myapp/index.html`` with the
  52 MIME type ``application/xhtml+xml``::
  53
  54     from django.shortcuts import render_to_response
  55
  56     def my_view(request):
  57         # View code here...
  58         return render_to_response('myapp/index.html', {"foo": "bar"},
  59             mimetype="application/xhtml+xml")
  60
  61 This example is equivalent to::
  62
  63     from django.http import HttpResponse
  64     from django.template import Context, loader
  65
  66     def my_view(request):
  67         # View code here...
  68         t = loader.get_template('myapp/template.html')
  69         c = Context({'foo': 'bar'})
  70         r = HttpResponse(t.render(c),
  71             mimetype="application/xhtml+xml")
  72
  73 ``get_object_or_404``
  74 =====================
  75
  76 ``django.shortcuts.get_object_or_404`` calls `get()`_ on a given model
  77 manager, but it raises ``django.http.Http404`` instead of the model's
  78 ``DoesNotExist`` exception.
  79
  80 Required arguments
  81 ------------------
  82
  83 ``klass``
  84     A ``Model``, ``Manager`` or ``QuerySet`` instance from which to get the
  85     object.
  86
  87 ``**kwargs``
  88     Lookup parameters, which should be in the format accepted by ``get()`` and
  89     ``filter()``.
  90
  91 Example
  92 -------
  93
  94 The following example gets the object with the primary key of 1 from
  95 ``MyModel``::
  96
  97     from django.shortcuts import get_object_or_404
  98
  99     def my_view(request):
 100         my_object = get_object_or_404(MyModel, pk=1)
 101
 102 This example is equivalent to::
 103
 104     from django.http import Http404
 105
 106     def my_view(request):
 107         try:
 108             my_object = MyModel.objects.get(pk=1)
 109         except MyModel.DoesNotExist:
 110             raise Http404
 111
 112 Note: As with ``get()``, an ``MultipleObjectsReturned`` exception will be
 113 raised if more than one object is found.
 114
 115 .. _get(): ../db-api/#get-kwargs
 116
 117 ``get_list_or_404``
 118 ===================
 119
 120 ``django.shortcuts.get_list_or_404`` returns the result of `filter()`_ on a
 121 given model manager, raising ``django.http.Http404`` if the resulting list is
 122 empty.
 123
 124 Required arguments
 125 ------------------
 126
 127 ``klass``
 128     A ``Model``, ``Manager`` or ``QuerySet`` instance from which to get the
 129     object.
 130
 131 ``**kwargs``
 132     Lookup parameters, which should be in the format accepted by ``get()`` and
 133     ``filter()``.
 134
 135 Example
 136 -------
 137
 138 The following example gets all published objects from ``MyModel``::
 139
 140     from django.shortcuts import get_list_or_404
 141
 142     def my_view(request):
 143         my_objects = get_list_or_404(MyModel, published=True)
 144
 145 This example is equivalent to::
 146
 147     from django.http import Http404
 148
 149     def my_view(request):
 150         my_objects = MyModel.objects.filter(published=True)
 151         if not my_objects:
 152             raise Http404
 153
 154 .. _filter(): ../db-api/#filter-kwargs