Apr 2, 2013, 7:55:09 PM4/2/13
That's a good question. The templating mechanism works fine when you have a working example to use, but the mechanism isn't very clear, unless you dig down deep.
You can think of it this way:
1 app ... N modules (a module is just a set of related features, all under a given base URL '.../admin/', for example)
1 module .. N features
1 feature .. 1 java package (roughly, a single screen and its related data)
1 java package .. N classes, .sql file, and a 'body' jsp.
(It's not 100% necessary to use the above scheme, but it likely is useful for many apps to be broken down like this.)
The N features in a module can share an overall Template.jsp. Each feature has its own 'body' jsp. At run time, the Template and the body are combined together to make the final result.
Where does the Template.jsp live? Well, it should live somewhere where it can be readily referenced by all of its related features. There's no real restriction on where it lives, per se, but the example apps make use of a convention, whereby the N features in a module are all under the same 'base' url, and the Template.jsp is placed under the web app root, under that same base url. This makes it easier to wire together a body and a template, since the Action and the Template share the same base url. That's all.
The only real restriction is that your Actions need to return a ResponsePage object. If you look at the javadoc for ResponsePage, you can see that its various constructors allow for various policies. You can also see that ResponsePage is a wrapper for a URL.
It's up to you which constructor you use; the example apps provide one reasonable way of doing things. One weird thing about the example apps is that the Templates are defined 'elsewhere', in a sense, and are placed under the root of the web app itself, and are distant from the features (the code) that use it. That's a bit confusing and not very modular, but its not too bad (I hope).