New page models and macros for Roller 3.0

[Dave Johnson <sn...@gmail.com>]

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.

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.

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


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


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


That's all I have so far.

- Dave

Re: New page models and macros for Roller 3.0

[Allen Gilliland <al...@sun.com>]

Dave Johnson wrote:
> On 6/13/06, Allen Gilliland <al...@sun.com> wrote:
>> comments inline ...
>>
>> Dave Johnson wrote:
>> > We've discussed problems with Roller's rendering system before. 
>> Folks have
> ...
>> > 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?
> 
> I'm not sure if separate weblog and weblog entry models are necessary 
> either.
> 
> 
>> > 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?
> 
> I'll look into that as I design PageUtilities.
> 
> 
>> 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 methodss
>>
>> 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.
> 
> Yes. I really like that approach.
> 
> On the question of the new macros. I think we can get along with a
> much smaller number of macros. I think these are all we need for
> user-facing macros:
> 
> ---------------------------
> *** Weblog entry and comment macros
> 
> #showWeblogEntryPager($catNames $entryTemplate)
>   - Shows either day, entry or search page with next/prev links
>   - Does not show comments or comment form
>   - optionally uses template for entry display
> 
> #showWeblogEntryDayPager($catNames $dayTemplate)
>   - Same as #showWeblogEntryPager(), but with day grouping
>   - Does not show comments or comment form
>   - optionally uses template for day display
> 
> #showEntryText($entry)
>   - shows either text or summary depending on context, applies plugins
> 
> #showCommentForm($entry $commentTemplate)
>   - shows comment form for entry plus comment authenticator
>   - may show preview for one entry, optionally using template
> 
> #showTrackbackAutodiscovery($entry)
>   - shows Trackback autodiscovery information (an RDF format)
> 
> ---------------------------
> *** Other weblog macros
> 
> #showAutodiscoveryLinks()
>   - Shows standard <head> links for feed and RSD autodiscovery
> 
> #showSearchForm()
>   - shows search form for weblog
> 
> #showBookmarks()
>   - Shows <li> list of bookmarks in top level folder of blogroll
> 
> #showBookmarkFolder($folder $recursive $expanding)
>   - Shows <li> list of bookmarks and folders in folder
> 
> #showCategoryLinksMenu()
>   - Shows list of categories in weblog, with links
> 
> #showPageLinksMenu()
>   - Shows list of visible pages in weblog, with links
> 
> #showAuthorMenu()
>   - Shows authoring menu and login/logout links
> 
> #includePage($pageName)
>   - Includes and evaluates the weblog template page specified by name

If we can get by with only those macros then that would be excellent. 
That's a much more manageable list than what we have now.

-- Allen


> 
> 
> - Dave

Re: New page models and macros for Roller 3.0

[Dave Johnson <sn...@gmail.com>]

On 6/13/06, Allen Gilliland <al...@sun.com> wrote:
> comments inline ...
>
> Dave Johnson wrote:
> > We've discussed problems with Roller's rendering system before. Folks have
...
> > 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?

I'm not sure if separate weblog and weblog entry models are necessary either.


> > 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?

I'll look into that as I design PageUtilities.


> 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 methodss
>
> 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.

Yes. I really like that approach.

On the question of the new macros. I think we can get along with a
much smaller number of macros. I think these are all we need for
user-facing macros:

---------------------------
*** Weblog entry and comment macros

#showWeblogEntryPager($catNames $entryTemplate)
   - Shows either day, entry or search page with next/prev links
   - Does not show comments or comment form
   - optionally uses template for entry display

#showWeblogEntryDayPager($catNames $dayTemplate)
   - Same as #showWeblogEntryPager(), but with day grouping
   - Does not show comments or comment form
   - optionally uses template for day display

#showEntryText($entry)
   - shows either text or summary depending on context, applies plugins

#showCommentForm($entry $commentTemplate)
   - shows comment form for entry plus comment authenticator
   - may show preview for one entry, optionally using template

#showTrackbackAutodiscovery($entry)
   - shows Trackback autodiscovery information (an RDF format)

---------------------------
*** Other weblog macros

#showAutodiscoveryLinks()
   - Shows standard <head> links for feed and RSD autodiscovery

#showSearchForm()
   - shows search form for weblog

#showBookmarks()
   - Shows <li> list of bookmarks in top level folder of blogroll

#showBookmarkFolder($folder $recursive $expanding)
   - Shows <li> list of bookmarks and folders in folder

#showCategoryLinksMenu()
   - Shows list of categories in weblog, with links

#showPageLinksMenu()
   - Shows list of visible pages in weblog, with links

#showAuthorMenu()
   - Shows authoring menu and login/logout links

#includePage($pageName)
   - Includes and evaluates the weblog template page specified by name


- Dave

Re: New page models and macros for Roller 3.0

[Allen Gilliland <al...@sun.com>]

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