--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/parts/django/docs/topics/http/shortcuts.txt Sat Jan 08 11:20:57 2011 +0530
@@ -0,0 +1,229 @@
+=========================
+Django shortcut functions
+=========================
+
+.. module:: django.shortcuts
+ :synopsis:
+ Convience shortcuts that spam multiple levels of Django's MVC stack.
+
+.. index:: shortcuts
+
+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``
+======================
+
+.. function:: render_to_response(template[, dictionary][, context_instance][, mimetype])
+
+ Renders a given template with a given context dictionary and returns an
+ :class:`~django.http.HttpResponse` object with that rendered text.
+
+Required arguments
+------------------
+
+``template``
+ The full name of a template to use or sequence of template names. If a
+ sequence is given, the first template that exists will be used. See the
+ :ref:`template loader documentation <ref-templates-api-the-python-api>`
+ for more information on how templates are found.
+
+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 :class:`~django.template.Context` instance (filled
+ with values from ``dictionary``). If you need to use :ref:`context
+ processors <subclassing-context-requestcontext>`, render the template with
+ a :class:`~django.template.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``
+ 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'})
+ return HttpResponse(t.render(c),
+ mimetype="application/xhtml+xml")
+
+``redirect``
+============
+
+.. function:: redirect(to[, permanent=False], *args, **kwargs)
+
+ .. versionadded:: 1.1
+
+ Returns an :class:`~django.http.HttpResponseRedirect` to the appropriate URL
+ for the arguments passed.
+
+ The arguments could be:
+
+ * A model: the model's `get_absolute_url()` function will be called.
+
+ * A view name, possibly with arguments: `urlresolvers.reverse()` will
+ be used to reverse-resolve the name.
+
+ * A URL, which will be used as-is for the redirect location.
+
+ By default issues a temporary redirect; pass ``permanent=True`` to issue a
+ permanent redirect
+
+Examples
+--------
+
+You can use the :func:`redirect` function in a number of ways.
+
+ 1. By passing some object; that object's
+ :meth:`~django.db.models.Model.get_absolute_url` method will be called
+ to figure out the redirect URL::
+
+ def my_view(request):
+ ...
+ object = MyModel.objects.get(...)
+ return redirect(object)
+
+ 2. By passing the name of a view and optionally some positional or
+ keyword arguments; the URL will be reverse resolved using the
+ :func:`~django.core.urlresolvers.reverse` method::
+
+ def my_view(request):
+ ...
+ return redirect('some-view-name', foo='bar')
+
+ 3. By passing a hardcoded URL to redirect to::
+
+ def my_view(request):
+ ...
+ return redirect('/some/url/')
+
+ This also works with full URLs::
+
+ def my_view(request):
+ ...
+ return redirect('http://example.com/')
+
+By default, :func:`redirect` returns a temporary redirect. All of the above
+forms accept a ``permanent`` argument; if set to ``True`` a permanent redirect
+will be returned::
+
+ def my_view(request):
+ ...
+ object = MyModel.objects.get(...)
+ return redirect(object, permanent=True)
+
+``get_object_or_404``
+=====================
+
+.. function:: get_object_or_404(klass, *args, **kwargs)
+
+ Calls :meth:`~django.db.models.QuerySet.get()` on a given model manager,
+ but it raises :class:`~django.http.Http404` instead of the model's
+ :class:`~django.core.exceptions.DoesNotExist` exception.
+
+Required arguments
+------------------
+
+``klass``
+ A :class:`~django.db.models.Model`, :class:`~django.db.models.Manager` or
+ :class:`~django.db.models.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()``, a
+:class:`~django.core.exceptions.MultipleObjectsReturned` exception
+will be raised if more than one object is found.
+
+``get_list_or_404``
+===================
+
+.. function:: get_list_or_404(klass, *args, **kwargs)
+
+ Returns the result of :meth:`~django.db.models.QuerySet.filter()` on a
+ given model manager, raising :class:`~django.http.Http404` if the resulting
+ list is empty.
+
+Required arguments
+------------------
+
+``klass``
+ A :class:`~django.db.models.Model`, :class:`~django.db.models.Manager` or
+ :class:`~django.db.models.query.QuerySet` instance from which to get the
+ list.
+
+``**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