diff --git a/docs/ref/views.txt b/docs/ref/views.txt index 8c9c3e3ed8..dfe9506ab9 100644 --- a/docs/ref/views.txt +++ b/docs/ref/views.txt @@ -9,7 +9,7 @@ Several of Django's built-in views are documented in :doc:`/topics/http/views` as well as elsewhere in the documentation. Serving files in development ----------------------------- +============================ .. function:: static.serve(request, path, document_root, show_indexes=False) @@ -46,3 +46,104 @@ ships with a small URL helper function :func:`~django.conf.urls.static.static` that takes as parameters the prefix such as :setting:`MEDIA_URL` and a dotted path to a view, such as ``'django.views.static.serve'``. Any other function parameter will be transparently passed to the view. + +.. _error-views: + +Error views +=========== + +Django comes with a few views by default for handling HTTP errors. To override +these with your own custom views, see :ref:`customizing-error-views`. + +.. _http_not_found_view: + +The 404 (page not found) view +----------------------------- + +.. function:: defaults.page_not_found(request, template_name='404.html') + +When you raise :exc:`~django.http.Http404` from within a view, Django loads a +special view devoted to handling 404 errors. By default, it's the view +:func:`django.views.defaults.page_not_found`, which either produces a very +simple "Not Found" message or loads and renders the template ``404.html`` if +you created it in your root template directory. + +The default 404 view will pass one variable to the template: ``request_path``, +which is the URL that resulted in the error. + +Three things to note about 404 views: + +* The 404 view is also called if Django doesn't find a match after + checking every regular expression in the URLconf. + +* The 404 view is passed a :class:`~django.template.RequestContext` and + will have access to variables supplied by your + :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting (e.g., ``MEDIA_URL``). + +* If :setting:`DEBUG` is set to ``True`` (in your settings module), then + your 404 view will never be used, and your URLconf will be displayed + instead, with some debug information. + +.. _http_internal_server_error_view: + +The 500 (server error) view +--------------------------- + +.. function:: defaults.server_error(request, template_name='500.html') + +Similarly, Django executes special-case behavior in the case of runtime errors +in view code. If a view results in an exception, Django will, by default, call +the view ``django.views.defaults.server_error``, which either produces a very +simple "Server Error" message or loads and renders the template ``500.html`` if +you created it in your root template directory. + +The default 500 view passes no variables to the ``500.html`` template and is +rendered with an empty ``Context`` to lessen the chance of additional errors. + +If :setting:`DEBUG` is set to ``True`` (in your settings module), then +your 500 view will never be used, and the traceback will be displayed +instead, with some debug information. + +.. _http_forbidden_view: + +The 403 (HTTP Forbidden) view +----------------------------- + +.. function:: defaults.permission_denied(request, template_name='403.html') + +In the same vein as the 404 and 500 views, Django has a view to handle 403 +Forbidden errors. If a view results in a 403 exception then Django will, by +default, call the view ``django.views.defaults.permission_denied``. + +This view loads and renders the template ``403.html`` in your root template +directory, or if this file does not exist, instead serves the text +"403 Forbidden", as per :rfc:`2616` (the HTTP 1.1 Specification). + +``django.views.defaults.permission_denied`` is triggered by a +:exc:`~django.core.exceptions.PermissionDenied` exception. To deny access in a +view you can use code like this:: + + from django.core.exceptions import PermissionDenied + + def edit(request, pk): + if not request.user.is_staff: + raise PermissionDenied + # ... + +.. _http_bad_request_view: + +The 400 (bad request) view +-------------------------- + +.. function:: defaults.bad_request(request, template_name='400.html') + +When a :exc:`~django.core.exceptions.SuspiciousOperation` is raised in Django, +it may be handled by a component of Django (for example resetting the session +data). If not specifically handled, Django will consider the current request a +'bad request' instead of a server error. + +``django.views.defaults.bad_request``, is otherwise very similar to the +``server_error`` view, but returns with the status code 400 indicating that +the error condition was the result of a client operation. + +``bad_request`` views are also only used when :setting:`DEBUG` is ``False``. diff --git a/docs/topics/http/views.txt b/docs/topics/http/views.txt index 28f2abdc9a..41853b76ca 100644 --- a/docs/topics/http/views.txt +++ b/docs/topics/http/views.txt @@ -133,132 +133,27 @@ called ``404.html`` and located in the top level of your template tree. Customizing error views ======================= -.. _http_not_found_view: +The default error views in Django should suffice for most Web applications, +but can easily be overridden if you need any custom behavior. Simply specify +the handlers as seen below in your URLconf (setting them anywhere else will +have no effect). -The 404 (page not found) view ------------------------------ +The :func:`~django.views.defaults.page_not_found` view is overridden by +:data:`~django.conf.urls.handler404`:: -.. function:: django.views.defaults.page_not_found(request, template_name='404.html') + handler404 = 'mysite.views.my_custom_page_not_found_view' -When you raise :exc:`~django.http.Http404` from within a view, Django loads a -special view devoted to handling 404 errors. By default, it's the view -:func:`django.views.defaults.page_not_found`, which either produces a very -simple "Not Found" message or loads and renders the template ``404.html`` if -you created it in your root template directory. - -The default 404 view will pass one variable to the template: ``request_path``, -which is the URL that resulted in the error. - -The ``page_not_found`` view should suffice for 99% of Web applications, but if -you want to override it, you can specify :data:`~django.conf.urls.handler404` -in your root URLconf (setting ``handler404`` anywhere else will have no -effect), like so:: - - handler404 = 'mysite.views.my_custom_404_view' - -Behind the scenes, Django determines the 404 view by looking for -``handler404`` in your root URLconf, and falling back to -``django.views.defaults.page_not_found`` if you did not define one. - -Three things to note about 404 views: - -* The 404 view is also called if Django doesn't find a match after - checking every regular expression in the URLconf. - -* The 404 view is passed a :class:`~django.template.RequestContext` and - will have access to variables supplied by your - :setting:`TEMPLATE_CONTEXT_PROCESSORS` setting (e.g., ``MEDIA_URL``). - -* If :setting:`DEBUG` is set to ``True`` (in your settings module), then - your 404 view will never be used, and your URLconf will be displayed - instead, with some debug information. - -.. _http_internal_server_error_view: - -The 500 (server error) view ----------------------------- - -.. function:: django.views.defaults.server_error(request, template_name='500.html') - -Similarly, Django executes special-case behavior in the case of runtime errors -in view code. If a view results in an exception, Django will, by default, call -the view ``django.views.defaults.server_error``, which either produces a very -simple "Server Error" message or loads and renders the template ``500.html`` if -you created it in your root template directory. - -The default 500 view passes no variables to the ``500.html`` template and is -rendered with an empty ``Context`` to lessen the chance of additional errors. - -This ``server_error`` view should suffice for 99% of Web applications, but if -you want to override the view, you can specify -:data:`~django.conf.urls.handler500` in your root URLconf, like so:: +The :func:`~django.views.defaults.server_error` view is overridden by +:data:`~django.conf.urls.handler500`:: handler500 = 'mysite.views.my_custom_error_view' -Behind the scenes, Django determines the 500 view by looking for -``handler500`` in your root URLconf, and falling back to -``django.views.defaults.server_error`` if you did not define one. - -One thing to note about 500 views: - -* If :setting:`DEBUG` is set to ``True`` (in your settings module), then - your 500 view will never be used, and the traceback will be displayed - instead, with some debug information. - -.. _http_forbidden_view: - -The 403 (HTTP Forbidden) view ------------------------------ - -.. function:: django.views.defaults.permission_denied(request, template_name='403.html') - -In the same vein as the 404 and 500 views, Django has a view to handle 403 -Forbidden errors. If a view results in a 403 exception then Django will, by -default, call the view ``django.views.defaults.permission_denied``. - -This view loads and renders the template ``403.html`` in your root template -directory, or if this file does not exist, instead serves the text -"403 Forbidden", as per :rfc:`2616` (the HTTP 1.1 Specification). - -``django.views.defaults.permission_denied`` is triggered by a -:exc:`~django.core.exceptions.PermissionDenied` exception. To deny access in a -view you can use code like this:: - - from django.core.exceptions import PermissionDenied - - def edit(request, pk): - if not request.user.is_staff: - raise PermissionDenied - # ... - -It is possible to override ``django.views.defaults.permission_denied`` in the -same way you can for the 404 and 500 views by specifying a -:data:`~django.conf.urls.handler403` in your root URLconf:: +The :func:`~django.views.defaults.permission_denied` view is overridden by +:data:`~django.conf.urls.handler403`:: handler403 = 'mysite.views.my_custom_permission_denied_view' -.. _http_bad_request_view: - -The 400 (bad request) view --------------------------- - -.. versionadded:: 1.6 - -.. function:: django.views.defaults.bad_request(request, template_name='400.html') - -When a :exc:`~django.core.exceptions.SuspiciousOperation` is raised in Django, -it may be handled by a component of Django (for example resetting the session -data). If not specifically handled, Django will consider the current request a -'bad request' instead of a server error. - -``django.views.defaults.bad_request``, is otherwise very similar to the -``server_error`` view, but returns with the status code 400 indicating that -the error condition was the result of a client operation. - -Like ``server_error``, the default ``bad_request`` should suffice for -99% of Web applications, but if you want to override the view, you can specify -:data:`~django.conf.urls.handler400` in your root URLconf, like so:: +The :func:`~django.views.defaults.bad_request` view is overridden by +:data:`~django.conf.urls.handler400`:: handler400 = 'mysite.views.my_custom_bad_request_view' - -``bad_request`` views are also only used when :setting:`DEBUG` is ``False``.