On Nov 24, 2:41 am, Mike Orr <sluggos...@gmail.com> wrote:
> On Tue, Nov 23, 2010 at 8:21 PM, Mike Orr <sluggos...@gmail.com> wrote:
> > On Tue, Nov 23, 2010 at 8:00 PM, Chris McDonough <chr...@plope.com> wrote:
> >> On Tue, 2010-11-23 at 19:35 -0800, Mike Orr wrote:
> >>> I wonder if it would be clearer to to put the URL Dispatch chapter
> >>> before Context Finding and Traversal in the manual.
>
> >> I sympathize with this, and I think we can probably organize it better.
> >> Casey Duncan is currently working on editing the book as a for-pay sort
> >> of thing. I'm hoping he'll come up with some concrete suggestions as to
> >> how to reorganize things, but maybe I can put a bug in his ear along the
> >> lines of your suggestion.
>
> >> FTR, it would be more technically accurate to say that users *will* be
> >> using a root object, a context object, and context finding when he uses
> >> URL dispatch, but he can mostly ignore their existence. URL dispatch
> >> literally is a context finding mechanism. This is why the docs are
> >> organized as they are now.
>
> >> OTOH, users do indeed need to know about view lookup even if they only
> >> use URL dispatch. A matched route doesn't always imply the lookup of
> >> one single canonical view. For example, if a route matches, it might go
> >> to one view if the request method is POST, another if the request method
> >> is GET.
>
> > OK, I think we can handle this in a short paragraph at the beginning
> > of the URL Dispatch chapter. Just quickly explain in passing what
> > these are and that the'll be covered more in depth in the following
> > chapters.
>
> Ignore this, I misunderstood your message. You said the user could
> remain blissfully unaware of these until they're ready to use them.
>
> How about an outline like this, roughly.
>
> CONTEXT FINDING AND VIEW LOOKUP
> --------------------------------------------------
> This section is about how Pyramid maps a user request (the URL plus
> certain other info included in the request) to a *view callable*. A
> view callable is a piece of code that takes a request and produces a
> response, such as an HTML page or a multimedia object. In Pyramid, the
> request and response are instances of Request and Response classes.
> Most Pyramid applications have several view callables, each one
> corresponding to a different kind of URL. View callables can also be
> grouped into *handlers*, where the handler is a class and the view
> callables are methods in that class.
>
> Pyramid provides two different ways to map a URL to a view callable.
> One is called URL Dispatch, familiar to Pylons and Routes users. It
> matches the entire URL against a set of rules known as *routes*, and
> the first matching route specifies which view callable to invoke. The
> other way is called Traversal, which is familiar to BFG, TurboGears,
> and Zope users. Traversal matches each URL component against keys of a
> dict-like root object, recursively mapping components to keys until a
> view callable is identified. An application can use one way, the other
> way, or both in different situations. The next chapter explains URL
> Dispatch; the following chapter covers Traversal. The N+3 chapter
> discusses hybrid applications using both URL Dispatch and Traversal.
> The N+4 chapter explains view callables in detail.
>
> [Move "What good is a context finding subsystem" and "Should I use
> traversal or URL dispatch" to traversal chapter.]
>
> URL DISPATCH
> -------------------
> Simple example mentioning 'add_route' and 'add_handler' (for both URL
> dispatch and traversal readers, so they recognize the methods when
> they see them)
>
> Traversal readers can now skip to the next chapter
>
> API, basic, and advanced usages
>
> It may be helpful to introduce a minimal view callable and handler, so
> that people can get a concrete feel for how the routing and view
> callables interact.
>
> Mention that a *context* exists, and explain it in URL Dispatch terms.
> The context contains additional information about the user's
> environment not included in the request. The context is mainly useful
> with Traversal, Normally all URL Dispatch requests use the same
> default context, but if you're using auth you may have to explicity
> specify a context; see the Auth chapter for details.
>
> TRAVERSAL AND HYBRID USAGE
> -------------------------------------------
>
> Start with a concise, concrete example, something as easy to grasp as
> a CherryPy root. Mention the characteristic methods: 'add_view'.
> ('add_model'?)
>
> Explain that Traversal is most useful when the URL refers to an
> arbitrary hierachical structure such as an object database (ZODB).
> [This replaces the "Should I use Traversal or URL Dispatch" section,
> but can be much shorter.]
>
> Shorten the Unix conceptual example. Don't get into shell commands and
> what the "inexperienced user" doesn't know. Just show a directory tree
> (the complete tree), and imagine cd'ing into each directory and
> looking for the next component. .__getitem__ is too abstract;
> introduce it by saying the root object is dict-like.
>
> The rest of the chapter can stay pretty much the same.
>
> Most of the context stuff goes here.
>
> HYBRID URL DISPATCH
> ------------------------------
>
> The "URL Dispatch only" and "Traversal Only" sections move to the
> beginning of their respective chapters. Deductive readers like me need
> to see concrete syntax early in order to relate to the abstract
> concepts.
>
> The rest of the chapter can remain as is, but keep in mind that URL
> Dispatch is the default way and Traversal is the alternative way, so
> 'add_route' should be shown first and then 'add_view' explained in
> that context.
>
> OTHER STUFF
> -------------------
>
> You'll need to go into detail about contexts, context finding, and the
> view lookup subsystem. That can go into either the first chapter or
> the traversal chapter, or perhaps into a separate chapter after
> hybrid. In the latter case, the first four chapters would explain just
> enough to use the systems, and the extra chapter would explain the
> conceptual underpinnings, or the reason they are that way.
>
> --
> Mike Orr <sluggos...@gmail.com>
Definitely a +1
I remember Travesal and context as being the hardest parts for me to
gasp back when I tried repoze.bfg and I also remember it's the most
complex part of the system when you just want to get a view to show at
a URL.
--
You received this message because you are subscribed to the Google Groups
"pylons-devel" group.
To post to this group, send email to pylons-de...@googlegroups.com.
To unsubscribe from this group, send email to
pylons-devel+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/pylons-devel?hl=en.
