diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/intro/tutorial01.txt | 41 | ||||
| -rw-r--r-- | docs/ref/urls.txt | 34 |
2 files changed, 34 insertions, 41 deletions
diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt index 3f89220949..d45fa6bcb6 100644 --- a/docs/intro/tutorial01.txt +++ b/docs/intro/tutorial01.txt @@ -275,6 +275,8 @@ include the URLconf defined in ``polls.urls``. To do this, add an import for path("admin/", admin.site.urls), ] +The :func:`~django.urls.path` function expects at least two arguments: +``route`` and ``view``. The :func:`~django.urls.include` function allows referencing other URLconfs. Whenever Django encounters :func:`~django.urls.include`, it chops off whatever part of the URL matched up to that point and sends the remaining string to the @@ -307,45 +309,6 @@ text "*Hello, world. You're at the polls index.*", which you defined in the If you get an error page here, check that you're going to http://localhost:8000/polls/ and not http://localhost:8000/. -The :func:`~django.urls.path` function is passed four arguments, two required: -``route`` and ``view``, and two optional: ``kwargs``, and ``name``. -At this point, it's worth reviewing what these arguments are for. - -:func:`~django.urls.path` argument: ``route`` ---------------------------------------------- - -``route`` is a string that contains a URL pattern. When processing a request, -Django starts at the first pattern in ``urlpatterns`` and makes its way down -the list, comparing the requested URL against each pattern until it finds one -that matches. - -Patterns don't search GET and POST parameters, or the domain name. For example, -in a request to ``https://www.example.com/myapp/``, the URLconf will look for -``myapp/``. In a request to ``https://www.example.com/myapp/?page=3``, the -URLconf will also look for ``myapp/``. - -:func:`~django.urls.path` argument: ``view`` --------------------------------------------- - -When Django finds a matching pattern, it calls the specified view function with -an :class:`~django.http.HttpRequest` object as the first argument and any -"captured" values from the route as keyword arguments. We'll give an example -of this in a bit. - -:func:`~django.urls.path` argument: ``kwargs`` ----------------------------------------------- - -Arbitrary keyword arguments can be passed in a dictionary to the target view. We -aren't going to use this feature of Django in the tutorial. - -:func:`~django.urls.path` argument: ``name`` --------------------------------------------- - -Naming your URL lets you refer to it unambiguously from elsewhere in Django, -especially from within templates. This powerful feature allows you to make -global changes to the URL patterns of your project while only touching a single -file. - When you're comfortable with the basic request and response flow, read :doc:`part 2 of this tutorial </intro/tutorial02>` to start working with the database. diff --git a/docs/ref/urls.txt b/docs/ref/urls.txt index 2ef873d348..95eb03f35a 100644 --- a/docs/ref/urls.txt +++ b/docs/ref/urls.txt @@ -25,6 +25,9 @@ Returns an element for inclusion in ``urlpatterns``. For example:: ..., ] +``route`` +--------- + The ``route`` argument should be a string or :func:`~django.utils.translation.gettext_lazy()` (see :ref:`translating-urlpatterns`) that contains a URL pattern. The string @@ -33,16 +36,43 @@ URL and send it as a keyword argument to the view. The angle brackets may include a converter specification (like the ``int`` part of ``<int:section>``) which limits the characters matched and may also change the type of the variable passed to the view. For example, ``<int:section>`` matches a string -of decimal digits and converts the value to an ``int``. See +of decimal digits and converts the value to an ``int``. + +When processing a request, Django starts at the first pattern in +``urlpatterns`` and makes its way down the list, comparing the requested URL +against each pattern until it finds one that matches. See :ref:`how-django-processes-a-request` for more details. +Patterns don't match GET and POST parameters, or the domain name. For example, +in a request to ``https://www.example.com/myapp/``, the URLconf will look for +``myapp/``. In a request to ``https://www.example.com/myapp/?page=3``, the +URLconf will also look for ``myapp/``. + +``view`` +-------- + The ``view`` argument is a view function or the result of :meth:`~django.views.generic.base.View.as_view` for class-based views. It can -also be an :func:`django.urls.include`. +also be a :func:`django.urls.include`. + +When Django finds a matching pattern, it calls the specified view function with +an :class:`~django.http.HttpRequest` object as the first argument and any +"captured" values from the route as keyword arguments. + +``kwargs`` +---------- The ``kwargs`` argument allows you to pass additional arguments to the view function or method. See :ref:`views-extra-options` for an example. +``name`` +-------- + +Naming your URL lets you refer to it unambiguously from elsewhere in Django, +especially from within templates. This powerful feature allows you to make +global changes to the URL patterns of your project while only touching a single +file. + See :ref:`Naming URL patterns <naming-url-patterns>` for why the ``name`` argument is useful. |