comments inline ...
Dave Johnson wrote:
We've discussed problems with Roller's rendering system before. Folks have
complained that the view technology is not pluggable, preventing the use of
FreeMarker or JSP or other template languages. Another common complaint
is that
we place a confusing and difficult to document array values and objects
into
the rendering context. And we all seem to agree that we went overboard by
defining too many small and/or unncessary macros. On top of that and
perhaps as
a result of that, the themes we've built on top of the current sytem are
inconsistent and, with a couple exceptions, of generally poor quality.
definitely agree.
So now, with Roller 3.0, the URL restructing work is going to address the
pluggable view issue. At the same time the new Atlas frontpage work is
going
to introduce some new page models and a system for configuring them. We're
introducing a lot of changes in the rendering sytem and the issues are
clear in our minds, so now might be the very best time to address the rest
of our problems with page rendering.
I'd like to start fresh and introduce a new rendering system in Roller 3.0.
I'm working on a proposal to create: 1) a set of new page models to
replace the
old PageModel and PageHelper, 2) a new set of macros, a redesigned
subset of
what have now and 3) ports of 2-3 Roller themes to this new system.
i'm certainly on board for all of that work.
As Allen suggested, I'm going to propose that we keep the old rendering
sytem
around, but make it optional. Moving forward new Roller installs will
use the
new system and new theme development will use it too.
So, before I start churning up recent changes it the wiki, I'd like to get
some feedback on my ideas so far. So please let me know what you think
of the
below.
New page models
We're using the notion of a "page model" in both the JSP authoring UI
and in
the rendering system, but I'm not sure if everybody agrees on what a page
model is. So let's define it.
A Page Podel is an read-only object that is placed into a Template
View context,
such as a Servlet request or a Velocity context, to provide data for
display in
template output.
* Page models serve several purposes:
- Clearly define data and data types available to template
- Keep context's namespace free of clutter
* Page models follow these rules
- Page models are read only
- Page models don't do HTML or other page generation
I think that definition is right on and the new PageModel interface
looks good.
What page models do we need?
Different pages in Roller need access to different types of data. Let's
review
the different types of pages generated by Roller's rendering system.
* All pages: need base URLs for site and access to some configs
* Weblog pages: pages within a weblog need access to one weblog's data
(Some also need access to site wide and planet wide data)
* Weblog entry pages: Same as Weblog pages, plus one specific entry
* Site wide pages: need access to Roller data across all weblogs
(site wide feeds, for example)
* Planet pages: need access to planet aggregations and groups
(planet feeds, for example)
With that in mind, consider these new proposed page models:
* ConfigPageModel: provides access to selected config data
- Available as $config to all pages
- Access to runtime properties not declared "sensitive" in config def
- Access to absolute URL of Roller and site
- Roller version number and timestamp
* WeblogPageModel: provides access to one weblog's data
- Available as $pageModel in weblog pages
* WeblogEntryPageModel: extends WeblogPageModel for single entry page
- Available as $pageModel in single entry weblog pages
* SitePageModel: provides access to site-wide weblog data
- Available as $site to site-wide pages and to selected Weblog pages
* PlanetPageModel: provides access to planet groups and subscriptions
- Available as $planet to planet pages and selected Weblog pages
* User defined page models
- Can be defined for site-wide and specific weblog levels
The only one of these that I am unsure about is the
WeblogEntryPageModel. In what ways are we planning to use that one to
extends the WeblogPageModel?
Other objects needed in context
There are still a couple of objects that we need in context that are not
page models. Here's the current list:
* PageUtilities: small number of utilities needed by pages
- Available as $utilities to all pages
- Subset of those available in Roller 2.X utilities class
* Text toolbox: allows access to I18N strings defined by Roller
- Available as $text to all pages
* Calendar: displays weblog calendar
- Available as $calendarTag to weblog pages
* EditorMenu: displays authoring menu (defined by editor-menu.xml)
- Available as $authoringTag to weblog pages
sounds good to me. is there any benefit to renaming $utilities to
something else and redefining that PageUtilities class? mainly to be
able to remove/redo some of its methods without breaking backwards
compatability for old themes?
That's all I have so far.
you didn't talk much about how the macros will change, so maybe this is
premature, but one thought that i believe we should consider while we
are doing this work is the idea of extending some of our pojos to
provide rendering specific methods.
i think one of the key ways to get away from overusing the macros is to
put a little more of the logic in the code. i don't want to put
anything that actually prints out html or other formatting code, but i
do think it's worthwhile to use the code for things like constructing
urls, applying weblog entry plugins, obfuscating email addresses, etc.
we don't want this logic directly in the pojo because it's only useful
at rendering time, so the approach would be to extend some pojos and
add/overload/override any methods that we want to behave differently at
rendering time. example ..
UIWeblogEntry extends WeblogEntryData {
getPermalink() - return full permalink value
getText() - return entry text *with* plugins applied
getWeblogUrl() - return permalink url to weblog
}
etc, etc. this way we can focus on reusing our pojos and our code and
encouraging users to use our object hierarchy in their templates, rather
than having to figure out all the right combinations of macros to apply
which we have found to be hard to manage and extend over time.
-- Allen
- Dave
