<?xml version="1.0"?>

<!--
 Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
-->

<document>

 <properties>
  <title>Pull vs. Push</title>
  <author email="jon@latchkey.com">Jon S. Stevens</author>
 </properties>

 <body>

<section name="Pull vs. Push">

<p>By: <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
<br/>
$Date$
</p>

<p>
This document is to explain a different type of philosophy for working with
Context based MVC tools like WebMacro (WM) and <a
href="http://velocity.apache.org/engine/">Velocity</a> (V) than I think that
the Turbine community is used to. The requirement for this philosophy has come
up recently during <a href="http://scarab.tigris.org/">Scarab</a>
development and I would like to share and document it with you all. Many thanks
to Brian B for being patient with me and trying to explain exactly what he wants
to see. So, let me start off by giving a little bit of history and then moving
on from there...
</p>

<p>
The current encouragement that Turbine gives to developers is to do a mapping
between one Screen (Java) and one Template (WM or V). The way it works is that
you build up a Context object that is essentially a Hashtable that contains all
of the data that is required to render a particular template. Within the
template, you refer to that data in order to format it for display. I will refer
to this as the "Push MVC Model." This IMHO is a perfectly acceptable, easy to
understand and implement approach.
</p>

<p>
We have solved the problem of being able to display the data on a template
without requiring the engineer to make modifications to the Java code. In other
words, you can modify the look and feel of the overall website without the
requirement of having a Java engineer present to make the changes. This is
a very good step forward.
</p>

<p>
However, it has a shortcoming in that it makes it more difficult to allow the
template designer (ie: a non programmer) the ability to move information on a
template from one template to another template because it would require the
logic in the Java code to be modified as well. For example, say you have a set
of "wizard" type screens and you want to change the order of execution of those
screens or even the order of the fields on those screens. In order to do so, you
can't simply change the Next/Back links you need to also change the Java code.
</p>

<p>
Another example of this is if you have a form on a page and you want to be
able to split that form across several steps across several pages. In the
current model, you would have to potentially write/modify several Java classes.
In reality, this should be something that is easily modifiable by just a single
template engineer who doesn't necessarily even know Java.
</p>

<p>
There are several considerations that one must take into consideration regarding
the design of a system to provide this level of abstraction. For example, when
someone submits the form and there is an error. Proper UI would suggest that you
should re-display the page with the previous form data filled in as well as an
error message that details the problems. You also need to consider the ability
to display the same form that may be pre-populated with information from the
database instead of as an error from the user.
</p>

<p>
So, beginning with Scarab, we are going to try another model which I will
describe as the "Pull MVC Model". What this entails is the ability to create an
object that is able to "pull" the required information out at execution time
within the template. Thus, it becomes the job of the template designer to
understand the API of objects available to him/her to take advantage of.
</p>

<p>
Instead of the developer telling the designer what Context names to use for each
and every screen, there is instead a set of a few objects available for the
template designer to pick and choose from. These objects will provide methods to
access the underlying information either from the database or from the
previously submitted form information.
</p>

<p>
Gone are the days where one would have a Java class that would be responsible
for building the context up for the template. Instead, there would be a single
base class that places the few objects into the context for every request and
there is a documented API that the template designer can refer to in order to
access the information that he/she needs to get at. Of course this information
is only retrieved when requested and can also be managed in a cache for reuse.
</p>

<p>
By moving to a "Pull" model, it becomes possible to more easily achieve complete
independence from the Java engineers in order to not only change the look and
feel (UI) of the site but also the information architecture (IA) layout and flow
of the site.
</p>

<p>
While this puts more requirements on the Java engineer to make sure that the
template designer has a well defined API, it will save the Java engineer many
hours further down the road when the client requests IA changes because now the
responsibility is on the template designer to make the changes. Therefore the
increased initial developer time is justified in order to realize the long term
goals of the project.
</p>

<p>
I hope that this makes sense to everyone. I'm sure that some of you are probably
saying "well, duh!." However, this is really not the model that has been
encouraged so far within Turbine nor within other products such as XMLC (which
actually operates *only* on the Push model), so I believe that it is somewhat
uncharted territory for some people. The only products that I can think of right
now that encourage this is JSP taglibs and Tea, however, I still feel as though
they have missed the boat on this in one way or another.
</p>

<p>
Comments are appreciated. Please post them to the Turbine
<a href="http://turbine.apache.org/contact.html">mailing list</a>.
</p>

</section>

</body>
</document>