Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Fixed #21938 -- Restructured documentation for built-in views #2710

Closed
wants to merge 2 commits into from

2 participants

@JoLinden

Moved the reference for built-in error views to the correct
documentation page. Restructured the remaining information on
customizing error views in a less repetitive way.

docs/ref/views.txt
@@ -47,3 +47,103 @@ 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
+=======================
+
+.. _http_not_found_view:
+
+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`.
@timgraham Owner

please wrap lines at 80 characters

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/views.txt
@@ -47,3 +47,103 @@ 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
+=======================
@timgraham Owner

underline should be same length as text

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/views.txt
@@ -47,3 +47,103 @@ 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
+=======================
+
+.. _http_not_found_view:
+
+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`.
+
+The 404 (page not found) view
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@timgraham Owner

Let's use ----- for second level underline, I think that's what's use most often elsewhere in the docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/views.txt
@@ -47,3 +47,103 @@ 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
+=======================
+
+.. _http_not_found_view:
@timgraham Owner

this anchor needs to be below the paragraph below and above the heading (try building the docs to make sure there are no errors)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/topics/http/views.txt
((136 lines not shown))
-``bad_request`` views are also only used when :setting:`DEBUG` is ``False``.
+ handler400 = 'mysite.views.my_custom_bad_request_view'
@timgraham Owner

Don't remove the newline on the last line (shouldn't be that "No newline at end of file" symbol in the gihub diff)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@timgraham
Owner

Please note our commit message guidelines (include ticket number like so: "Fixed #XXXXX --"). Also a more descriptive message would be helpful. "Improved" is rather vague. :-) Thanks for working on this.

@JoLinden JoLinden changed the title from Improved docs/ref/views.txt and docs/topics/http/views.txt to Fixed #21938 -- Restructured documentation for built-in views
@JoLinden

I've updated the PR based on your review, and also edited the commit message to what I think is according to the guidelines.

Thanks for the detailed feedback! It helps a lot as a first time contributor. :)

@timgraham
Owner

merged in 5b98ba0, thanks.

@timgraham timgraham closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on May 24, 2014
  1. @JoLinden
Commits on Jun 1, 2014
  1. @JoLinden
This page is out of date. Refresh to see the latest.
Showing with 111 additions and 115 deletions.
  1. +102 −1 docs/ref/views.txt
  2. +9 −114 docs/topics/http/views.txt
View
103 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)
@@ -47,3 +47,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:: django.views.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:: 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.
+
+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
+ # ...
+
+.. _http_bad_request_view:
+
+The 400 (bad request) view
+--------------------------
+
+.. 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.
+
+``bad_request`` views are also only used when :setting:`DEBUG` is ``False``.
View
123 docs/topics/http/views.txt
@@ -133,128 +133,23 @@ 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 ``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 ``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.
-
-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 ``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
---------------------------
-
-.. 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 ``bad_request`` 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``.
Something went wrong with that request. Please try again.