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>
--
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.
