diff options
Diffstat (limited to 'docs/narr/urldispatch.rst')
| -rw-r--r-- | docs/narr/urldispatch.rst | 86 |
1 files changed, 35 insertions, 51 deletions
diff --git a/docs/narr/urldispatch.rst b/docs/narr/urldispatch.rst index fb5b97e54..9a9769d23 100644 --- a/docs/narr/urldispatch.rst +++ b/docs/narr/urldispatch.rst @@ -6,42 +6,17 @@ URL Dispatch ============ -The URL dispatch feature of :app:`Pyramid` allows you to either augment or -replace :term:`traversal` as a :term:`resource location` mechanism, allowing -URL pattern matching to have the "first crack" at resolving a given URL to -:term:`context` resource. - -Although it is a "resource-location" mechanism, ironically, using URL -dispatch exclusively allows you to avoid thinking about your application in -terms of resources entirely. - -Many applications don't need :app:`Pyramid` features -- such as -context-sensitive declarative security via an :term:`authorization policy` -- -that benefit from having any visible separation between :term:`resource -location` and :term:`view lookup`. To this end, URL dispatch provides a -handy syntax that allows you to effectively map URLs *directly* to -:term:`view` code in such a way that you needn't think about your application -in terms of "resource location" at all. This makes developing a -:app:`Pyramid` application seem more like developing an application in a -system that is "resource-free", such as :term:`Pylons` or :term:`Django`. - -Whether or not you care about "resources", it often makes a lot of sense to -use :term:`URL dispatch` instead of :term:`traversal` in an application that -has no natural data hierarchy. For instance, if all the data in your -application lives in a relational database, and that relational database has -no self-referencing tables that form a natural hierarchy, URL dispatch is -easier to use than traversal, and is often a more natural fit for creating an -application that manipulates "flat" data. +:term:`URL dispatch` provides a simple way to map URLs :term:`view` code +using a simple pattern matching language. An ordered set of patterns is +checked one-by-one. If one of the patterns matches the path information +associated with a request, a particular :term:`view callable` is invoked. If +no route matches, :app:`Pyramid` falls back to trying to use +:term:`traversal` to map the current request to a :term:`view callable`. The presence of calls to the :meth:`pyramid.config.Configurator.add_route` method within your application is a sign that you're using :term:`URL dispatch`. -.. note:: - - Route configuration may also be added to the system via :term:`ZCML` (see - :ref:`zcml_route_configuration`). - High-Level Operational Overview ------------------------------- @@ -50,27 +25,31 @@ If route configuration is present in an application, the :app:`Pyramid` matching patterns present in a *route map*. If any route pattern matches the information in the :term:`request` provided -to :app:`Pyramid`, a route-specific :term:`context` resource will be -generated. When this happens, :app:`Pyramid` will shortcut -:term:`traversal`, and will invoke :term:`view lookup` using the context -resource and view name generated by URL dispatch. If the matched route names -a :term:`view callable` in its configuration, that view callable will be -invoked when view lookup is performed. +to :app:`Pyramid`, app:`Pyramid` will shortcut :term:`traversal`, and will +invoke :term:`view lookup` using a :term:`context` resource generated by the +route match. However, if no route pattern matches the information in the :term:`request` provided to :app:`Pyramid`, it will fail over to using :term:`traversal` to perform resource location and view lookup. +Technically, URL dispatch is a :term:`resource location` mechanism (it finds +a context object). But ironically, using URL dispatch (instead of +:term:`traversal`) allows you to avoid thinking about your application in +terms of "resources" entirely, because it allows you to directly map a +:term:`view callable` to a route. + Route Configuration ------------------- :term:`Route configuration` is the act of adding a new :term:`route` to an application. A route has a *pattern*, representing a pattern meant to match -against the ``PATH_INFO`` portion of a URL, and a *name*, which is used by -developers within a :app:`Pyramid` application to uniquely identify a -particular route when generating a URL. It also optionally has a -``factory``, a set of :term:`route predicate` parameters, and a set of -:term:`view` parameters. +against the ``PATH_INFO`` portion of a URL (the portion following the scheme +and port, e.g. ``/foo/bar`` in the URL ``http://localhost:8080/foo/bar``), +and a *route name*, which is used by developers within a :app:`Pyramid` +application to uniquely identify a particular route when generating a URL. +It also optionally has a ``factory``, a set of :term:`route predicate` +parameters, and a set of :term:`view` parameters. .. index:: single: add_route @@ -103,10 +82,11 @@ Route Configuration That Names a View Callable ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When a route configuration declaration names a ``view`` attribute, the value -of the attribute will reference a :term:`view callable`. A view callable, as -described in :ref:`views_chapter`, is developer-supplied code that "does -stuff" as the result of a request. For more information about how to create -view callables, see :ref:`views_chapter`. +of the attribute will reference a :term:`view callable`. This view callable +will be invoked when the route matches. A view callable, as described in +:ref:`views_chapter`, is developer-supplied code that "does stuff" as the +result of a request. For more information about how to create view +callables, see :ref:`views_chapter`. Here's an example route configuration that references a view callable: @@ -136,6 +116,9 @@ When a route configuration names a ``view`` attribute, the :term:`view callable` named as that ``view`` attribute will always be found and invoked when the associated route pattern matches during a request. +Route View Callable Registration and Lookup Details +!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + The purpose of making it possible to specify a view callable within a route configuration is to prevent developers from needing to deeply understand the details of :term:`resource location` and :term:`view lookup`. When a route @@ -146,11 +129,8 @@ the invocation. For most usage, you needn't understand more than this; how it works is an implementation detail. In the interest of completeness, however, we'll -explain how it *does* work in the following section. You can skip it if -you're uninterested. - -Route View Callable Registration and Lookup Details -!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! +explain how it *does* work in the this section. You can skip it if you're +uninterested. When a ``view`` attribute is attached to a route configuration, :app:`Pyramid` ensures that a :term:`view configuration` is registered that @@ -1257,3 +1237,7 @@ References A tutorial showing how :term:`URL dispatch` can be used to create a :app:`Pyramid` application exists in :ref:`bfg_sql_wiki_tutorial`. + +Route configuration may also be added to the system via :term:`ZCML` (see +:ref:`zcml_route_configuration`). + |