diff options
Diffstat (limited to 'docs/narr/contextfinding.rst')
| -rw-r--r-- | docs/narr/contextfinding.rst | 71 |
1 files changed, 26 insertions, 45 deletions
diff --git a/docs/narr/contextfinding.rst b/docs/narr/contextfinding.rst index 491113e62..74d9e3cc5 100644 --- a/docs/narr/contextfinding.rst +++ b/docs/narr/contextfinding.rst @@ -70,57 +70,40 @@ describe how view lookup interacts with context finding. Should I Use Traversal or URL Dispatch for Context Finding? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:term:`URL dispatch` can easily handle URLs such as -``http://example.com/members/Chris``, where it's assumed that each -item "below" ``members`` in the URL represents a member in the system. -You just match everything "below" ``members`` to a particular -:term:`view callable`. For example, you might configure URL dispatch -within :mod:`repoze.bfg` to match against the following URL patterns: - -.. code-block:: text - - members/:membername - archives/:year/:month/:day +:term:`URL dispatch` is very straightforward. When you limit your +application to using URL dispatch, you know every URL that your +application might generate or respond to, all the URL matching +elements are listed in a single place, and you needn't think about +:term:`context finding` or :term:`view lookup` at all. -In this configuration, there will be exactly two types of URLs that -will be meaningful to your application: URLs that start with -``/members`` which are followed by a path segment containing a -member's name. And URLs that start with ``/archives`` and have -subsequent path elements that represent a year, month, and day. Each -route pattern will be mapped to a specific :term:`view callable`. - -URL dispatch is very straightforward. When you limit your application -to using URL dispatch, you know every URL that your application might -generate or respond to, and all the URL matching elements are listed -in a single place. +URL dispatch can easily handle URLs such as +``http://example.com/members/Chris``, where it's assumed that each +item "below" ``members`` in the URL represents a single member in some +system. You just match everything "below" ``members`` to a particular +:term:`view callable`, e.g. ``/members/:memberid``. -URL dispatch is not very good, however, at inferring the difference -between sets of URLs such as these: +However, URL dispatch is not very convenient if you'd like your URLs +to represent an arbitrary hierarchy. For example, if you need to +infer the difference between sets of URLs such as these, where the +``document`` in the first URL represents a PDF document, and +``/stuff/page`` in the second represents an OpenOffice document in a +"stuff" folder. .. code-block:: text http://example.com/members/Chris/document http://example.com/members/Chris/stuff/page -If you'd like the ``document`` in the first URL above to represent a -PDF document, and ``/stuff/page`` in the second to represent an -OpenOffice document in a "stuff" folder, it's hard to express this -using URL dispatch. It takes more pattern matching assertions to be -able to make hierarchies like these work in URL-dispatch based -systems, and some assertions just aren't possible. Essentially, -URL-dispatch based systems just don't deal very well with URLs that -represent arbitrary-depth hierarchies. - -However, the other URL mapping mode supported by :mod:`repoze.bfg`, -named :term:`traversal`, *does* work well for URLs that represent -arbitrary-depth hierarchies. When traversal is used, each URL segment -represents a single traversal step through an edge of a graph, so a -URL like ``http://example.com/a/b/c`` can be thought of as a graph -traversal on the ``example.com`` site through the edges ``a``, ``b``, -and ``c``. Since the path segments that compose a URL are addressed -separately, it becomes very easy to form URLs that represent arbitrary -depth hierarchies in a system that uses traversal. +It takes more pattern matching assertions to be able to make +hierarchies work in URL-dispatch based systems, and some assertions +just aren't possible. Essentially, URL-dispatch based systems just +don't deal very well with URLs that represent arbitrary-depth +hierarchies. +But :term:`traversal`, *does* work well for URLs that represent +arbitrary-depth hierarchies. Since the path segments that compose a +URL are addressed separately, it becomes very easy to form URLs that +represent arbitrary depth hierarchies in a system that uses traversal. When you're willing to treat your application models as a graph that can be traversed, it also becomes easy to provide "instance-level security": you just attach a security declaration to each instance in @@ -136,6 +119,4 @@ hierarchical data store, using traversal can provide significant advantages over using URL-based dispatch. Since :mod:`repoze.bfg` provides support for both approaches, you can -use either as you see fit; you can even combine them together if -necessary. - +use either exclusively or combine them as you see fit. |