jon 00/08/26 11:38:46
Modified: xdocs design.xml
Log:
added some documentation. needs to be better line wrapped and cleaned up.
also, i like stylebook, but i don't have an easy way to generate it which
is frustrating.
Revision Changes Path
1.2 +43 -0 jakarta-velocity/xdocs/design.xml
Index: design.xml
===================================================================
RCS file: /home/cvs/jakarta-velocity/xdocs/design.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- design.xml 2000/08/24 21:42:49 1.1
+++ design.xml 2000/08/26 18:38:46 1.2
@@ -24,6 +24,49 @@
to provide a template service that will enable a true MVC model
by which web applications may be developed.
</p>
+
+<p>The fundamental design of Velocity is around the idea that there are a
+few
+ useful tag elements that you embed within your HTML code that work in
+conjunction
+ with a Context object that is populated in your Java code. The purpose
+of the
+ Context object is to provide a "hook" from your Java code to
+your
+ WebMacro code. Essentially a Context object is simply a Hashtable which
+provides
+ get and set methods for retrieving and setting objects by name within
+the Context.
+ These tag elements provide enough basic functionality to allow you to
+retrieve
+ objects from the Context and put them into your page as text values with
+some
+ degree of control over looping (for each) and conditional statements
+(if/else).
+</p>
+
+<p>For people who are not familiar with MVC style of development, at first
+glance,
+ it will appear as though Velocity is missing a large set of
+functionality. It
+ turns out that this is actually the strength of Velocity. For example,
+unlike
+ JSP, there is no way to embed Java code within your page and the tag
+elements
+ provide little more than basic looping and conditional
+statements. Another example
+ is the PHP model where every single feature is implemented with another
+function.
+ So, how is this better than the alternatives? The answer is that by
+using Velocity, you are enforcing a MVC style of development which defines that your
+Java code and your HTML template code should be separate. This style of
+development sometimes takes slightly longer (especially if you are new to MVC), but results in
+much more maintainable code over the long term (believe us, we have been
+ doing this for a long time now). It also provides an abstraction that
+prevents page
+designers from messing with software engineer's Java code. In other words, it
+provides an enforcement of a contract that defines what roles people play in the
+development process.</p>
</s1>