mneumann / wee

= Wee Web Framework

Copyright (c) 2004 by Michael Neumann (mneumann@ntecs.de)

== The anatomy of a request/response cycle

The request/response cycle in Wee is actually split into two separate phases
or steps. Depending on the point-of-view (given that a page is rendered and
the user clicks on a link or button), the first phase is to invoke an action
(a "callback"). Then in the second phase, a new page is rendered and sent
back to the user. So the two steps are:

1. invoke callbacks (action phase)

2. render new page and display (render phase)

These two phases repeat permanently. Which tasks are performed in each of them, is briefly listed below:

<b>Action:</b>

1. restore snapshot (if not up-to-date)

2. invoke actions   

3. backtrack state

4. update url -> redirect to render phase (not yet)

<b>Render:</b>

1. restore snapshot (if not up-to-date)

2. render

For each session there is at most one request handled at the same time. That
means, that there is either one action request or one render request handled.
Why? Because we have only one components tree, which we update on action
requests. As Wee allows to go back in time, we have to restore this components
tree to a certain point in time before we can handle an action or render
request. This disallows to handle e.g. two render requests simultaneous.

=== Action Phase (Invoking Callbacks)

Possible sources for callbacks are links (anchors) and all kinds of
form-elements like submit buttons, input-fields etc. There are two different
kinds of callbacks:

* Input callbacks (input-fields)

* Action callbacks (anchor, submit-button)

The distinction between input and action callbacks is important, as action
callbacks might depend on values of input-fields being assigned to instance
variables of the controlling component. Hence, Wee first invokes all input
callbacks before any action callback is triggered.

There are two methods related to callback processing:

* Wee::Component#process_callback_chain

* Wee::Presenter#process_callbacks

Note that each Wee::Component is also a Wee::Presenter, whereas a
Wee::Decoration is not a Component (but a Presenter)! 

Method <i>process_callback_chain</i> invokes <i>process_callbacks</i> for
it's first decoration, or if the component has no decorations, the method is
called for the component itself.  As such, <i>process_callback_chain</i> is
important to avoid entering an infinite loop (a method calling itself). What
decorations are, is discussed elsewhere.

Method <i>process_callbacks</i> of class Component first invokes all input
callbacks specified for this component, then calls
<i>process_callback_chain</i> for all of it's child components. This ensures,
that all input callbacks are triggered before the first action callback is
run. Finally, it invokes all of it's action callbacks.

=== Rendering Phase

The rendering phase is assumed to be side-effect free! So, you as a
programmer should take care to meet this assumption.

Similar as in the callback-step, there are two methods related to rendering a
page:

* Wee::Component#render_chain

* Wee::Presenter#render

Method <i>Component#render_chain</i> starts rendering the decoration chain by
calling <i>Presenter#render</i> for the first decoration of the component or
for the component itself if no decorations were specified.  Method
<i>Presenter#render</i> then generates the desired output which gets sent to
the user. Note that method <i>render</i> might call other components
<i>render_chain</i> methods to display those components "inside" itself
(usually a component does this for it's child components, but this has to be
implemented by the programmer). 

=== Further Reads

In this order:

* Wee::Presenter
* Wee::Component
* Wee::Decoration
* Wee::Delegate
* Wee::AnswerDecoration

== Decorations

Decorations are used to modify the look and behaviour of a component, without
modifying the components tree. A component can have more than one decoration.
This is implemented as a linked list of decorations (Wee::Decoration#owner
points to the next decoration), where Wee::Component#decoration points to the
first decoration in the chain or to the component itself, if no decorations
were specified. We actually use a Wee::ValueHolder for the <tt>@decoration</tt>
instance variable of class Component to be able to easily backtrack it
(required if you want to "undo" component calls).