diff options
Diffstat (limited to 'parts/django/docs/topics/http/shortcuts.txt')
| -rw-r--r-- | parts/django/docs/topics/http/shortcuts.txt | 229 |
1 files changed, 229 insertions, 0 deletions
diff --git a/parts/django/docs/topics/http/shortcuts.txt b/parts/django/docs/topics/http/shortcuts.txt new file mode 100644 index 0000000..315460e --- /dev/null +++ b/parts/django/docs/topics/http/shortcuts.txt @@ -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 |