Wee Web Framework

Copyright and License

Copyright © 2004, 2005 by Michael Neumann ([email protected]).

Released under the same terms of license as Ruby. Some files under directory examples/ might be copyrighted by third parties and licensed under different terms.

Status and Bugs

Wee is now considered pretty stable (if you don’t use continuations). Nevertheless I wouldn’t use it yet for mission-critical applications ;-)

Known Bugs:

  • Using continuations might leak memory, at least they did in the past. The latest memory stress-test has not showed up any memory problems, but since I haven’t changed anything at the continuation implementation, I can’t say for sure whether the problem has been fixed or not.

Introduction

Wee is a light-weight, very high-level and modern web-framework that makes Web engineering easy. It mainly inherits many ideas and features from Seaside2, but was written from scratch without ever looking at the Seaside (or any other) sources. All code was developed from ideas and lots of discussions with Avi Bryant.

Features

Reusable components

Wee has real components, which are like widgets in a GUI. Once written, you can use them everywhere. They are completely independent and do not interfere with other components. Components encapsulate state, a view and actions. Of course you can use an external model or use templates for rendering.

Backtracking

See the What is backtracking? section below. In short, backtracking lets the browser’s back and forward-button play well together with your application.

Clean and concise

Wee is well thought out, is written in and supports clean and concise code. Furthermore I think most parts are now very well documented.

Abstract core

The core of Wee is completely independent of both HTTP and HTML. That means, with little effort, you should be able to render other formats than HTML and use other communication protocols like SOAP, XML-RPC, Email, GUI or Console.

Templating-independent

Wee does not depend on a special templating-engine. You can use a different templating engine for each component if you want.

Powerful programmatic HTML generation

Wee ships with an easy to use and very powerful programmatic html-generation library. For example you can create a select list easily with this piece of code:

# select an object from these items
items = [1, 2, 3, 4]

# the labels shown to the user
labels = items.map {|i| i.to_s}

# render it
r.select_list(items).labels(labels).callback {|choosen| p choosen}

# render a multi-select list, with objects 2 and 4 selected
r.select_list(items).multi.labels(labels).selected([2,4])

The callback is called with the selected objects from the items array. Items can be any object, e.g. whole components:

labels = ["msg1", "msg2"]
items = labels.collect {|m| MessageBox.new(m)}
r.select_list(items).labels(labels).callback {|choosen| call choosen.first}

Optional use of Continuations

IMPORTANT: The current implementation of continuations in Ruby (or their use in Wee) might lead to memory leaks, if you use continuations. Furthermore, if you use continuations, it’s no longer possible to store the session state to disk.

Continuation-based frameworks are also known as modal frameworks. You can write code like the one shown below (taken from one of Avi’s emails) where each method displays a new page:

def checkout
  billing = getAddress("Billing Address")
  if useSeparateShippingAddress()
    shipping = getAddress("Shipping Address")
  else
    shipping = billing
  end
  payment = getPaymentInfo()
  showConfirmation(billing, shipping, payment)
end

Try to implement the same in a non-continuation based framework and show me your code… ;-)

To enable continuations, you have to require:

require 'wee/continuation'

Fully Marshallable (drops Continuation support)

If you don’t need continuations, Wee can be made fully marshallable. It is not yet fully marshallable (it was in the past), but it can be made, if required.

Observations and Limitations

  • Using continuations (might) lead to memory leaks!

  • When using continuations for cross-component calls, it’s impossible to store a session to disk (at least in Ruby). This problem is partly addressed by checkpointing provided by operating systems like DragonFly. But with this approach it’s still impossible to store sessions selectively to disk.

  • When using continuations, each session runs in it’s own (light-weigth) thread. This is not the case if you don’t use continuations.

  • Only one action callback can be invoked per request (a former version of Wee was able to invoke multiple callback, and answer even from multiple components at the same time, but this was removed, due to the unreliability of continuations in Ruby).

  • Components are thread-safe, as a fresh components-tree is created for each session and requests inside a session are serialized.

What is backtracking?

If you want, you can make the back-button of your browser work correctly together with your web-application. Imagine you have a simple counter application, which shows the current count and two links inc and dec with which you can increase or decrease the current count. Starting with an inital count of 0, you increase the counter up to 8, then click three times the back button of your browser (now displays 5) and finally decrease by one, then the counter really shows the expected 4, instead of 7 (as clicking the back button does usually not send a HTTP request, and the last state of your application was 8).

Only individual objects are backtracked, those of which you explicitly take a snapshot, not the whole component. That’s the easiest (from an application programmers perspective) and most flexible way. And its fast and uses less memory.

You can decide yourself whether you want infinite backtracking or only backtracking up to n pages, with whatever replacement strategy you want, least recently used (LRU), least frequently used (LFU) etc.

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). 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 @decoration instance variable of class Wee::Component to be able to easily backtrack it (required if you want to “undo” component calls).

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:

Action:

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

  2. invoke actions

  3. backtrack state

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

Render:

  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_callbacks_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 process_callbacks_chain invokes process_callbacks for it’s first decoration, or if the component has no decorations, the method is called for the component itself. As such, process_callbacks_chain is important to avoid entering an infinite loop (a method calling itself). What decorations are, is discussed elsewhere.

There are two “process_callbacks” tree traversals. The first invokes all input callbacks, the second the action callback.

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#do_render_chain

  • Wee::Presenter#do_render

Method Component#do_render_chain starts rendering the decoration chain by calling Presenter#do_render for the first decoration of the component or for the component itself if no decorations were specified. Method Presenter#do_render then generates the desired output which gets sent to the user. Note that method do_render might call other components’ do_render_chain 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