Proposal: Individual Templates by Action

new 4.0 proposal up to support to individual templates by
action ...

http://cwiki.apache.org
/confluence/display/ROLLER/Proposal+Individual+Templates+by+
Action

Abstract:
This is a proposal to support a way to define individual or
separate 
template files for various weblog page actions. Actions
would be things 
like search results page (<weblog>/search) or tags
index page 
(<weblog>/tags/).

Currently Roller does all of its page rendering via a single
template, 
the Weblog template, and quite frankly that is just not good
enough. 
Blogs have many pages which will often times have fairly
different 
designs and Roller should support that. A great example is
the search 
results page which typically has a much different layout and
design than 
a blog homepage and yet Roller doesn't make it easy to
accomplish that. 
It is the goal of this proposal to make it possible for
users to have 
individual templates to control the page designs for various
weblog actions.

please review and comment.

-- Allen

+1 (obviously non-binding  ...). 
I've been going through the
exercise of implementing a new UI template for our internal
blogs and
this has definitely come up as an issue.  I would caution,
however,
against going too far with breaking things out.

- James

Allen Gilliland wrote:
> new 4.0 proposal up to support to individual templates
by action ...
> 
> http://cwiki.apache.org
/confluence/display/ROLLER/Proposal+Individual+Templates+by+
Action
> 
> 
> Abstract:
> This is a proposal to support a way to define
individual or separate
> template files for various weblog page actions. Actions
would be things
> like search results page (<weblog>/search) or
tags index page
> (<weblog>/tags/).
> 
> Currently Roller does all of its page rendering via a
single template,
> the Weblog template, and quite frankly that is just not
good enough.
> Blogs have many pages which will often times have
fairly different
> designs and Roller should support that. A great example
is the search
> results page which typically has a much different
layout and design than
> a blog homepage and yet Roller doesn't make it easy to
accomplish that.
> It is the goal of this proposal to make it possible for
users to have
> individual templates to control the page designs for
various weblog
> actions.
> 
> please review and comment.
> 
> -- Allen
> 

James M Snell wrote:
> +1 (obviously non-binding  ...). 
I've been going through the
> exercise of implementing a new UI template for our
internal blogs and
> this has definitely come up as an issue.  I would
caution, however,
> against going too far with breaking things out.

I agree that we want to choose carefully what actions get
their own 
template and which ones don't and that's why in the section
of the 
proposal where I talked about what actions to support i
technically only 
added 2 new actions to the ones Roller currently has, search
results, 
and tags index.

the rest are possible but may be more baggage than they are
really 
worth, so we have to decide where to draw the line,
hopefully finding 
the right balance between flexibility/features and
simplicity/usability.

-- Allen


> 
> - James
> 
> Allen Gilliland wrote:
>> new 4.0 proposal up to support to individual
templates by action ...
>>
>> http://cwiki.apache.org
/confluence/display/ROLLER/Proposal+Individual+Templates+by+
Action
>>
>>
>> Abstract:
>> This is a proposal to support a way to define
individual or separate
>> template files for various weblog page actions.
Actions would be things
>> like search results page (<weblog>/search) or
tags index page
>> (<weblog>/tags/).
>>
>> Currently Roller does all of its page rendering via
a single template,
>> the Weblog template, and quite frankly that is just
not good enough.
>> Blogs have many pages which will often times have
fairly different
>> designs and Roller should support that. A great
example is the search
>> results page which typically has a much different
layout and design than
>> a blog homepage and yet Roller doesn't make it easy
to accomplish that.
>> It is the goal of this proposal to make it possible
for users to have
>> individual templates to control the page designs
for various weblog
>> actions.
>>
>> please review and comment.
>>
>> -- Allen
>>

Reminder, please comment on proposals if you have something
to say.  I 
plan to start implementing my 4.0 proposals very soon.

-- Allen


Allen Gilliland wrote:
> new 4.0 proposal up to support to individual templates
by action ...
> 
> http://cwiki.apache.org
/confluence/display/ROLLER/Proposal+Individual+Templates+by+
Action 
> 
> 
> Abstract:
> This is a proposal to support a way to define
individual or separate 
> template files for various weblog page actions. Actions
would be things 
> like search results page (<weblog>/search) or
tags index page 
> (<weblog>/tags/).
> 
> Currently Roller does all of its page rendering via a
single template, 
> the Weblog template, and quite frankly that is just not
good enough. 
> Blogs have many pages which will often times have
fairly different 
> designs and Roller should support that. A great example
is the search 
> results page which typically has a much different
layout and design than 
> a blog homepage and yet Roller doesn't make it easy to
accomplish that. 
> It is the goal of this proposal to make it possible for
users to have 
> individual templates to control the page designs for
various weblog 
> actions.
> 
> please review and comment.
> 
> -- Allen

On 3/12/07, Allen Gilliland <allen.gillilandsun.com> wrote:
> Reminder, please comment on proposals if you have
something to say.  I
> plan to start implementing my 4.0 proposals very soon.

Overall, I think this is a good idea. I do share James
concern about
going too far and defining too many actions -- so I like
your core
set.

Here are a couple of questions about the proposal:

* What is the schema for the new ROLLER_ACTION table you are
adding
and please include it's relationships with other tables.

* How is the mapping from URL to Action Name defined and can
it be
changed via configuration properties?

* Does this change any of the existing URL structure? (I
hope not)

* What classes in the rendering/request-mapping system do
you expect
to change? Just the PageServet?

* What are the implications for customizable feeds? I assume
we'd use
actions to define them too w/actions like entryfeed,
commentfeed.

* What's the difference between an "entry index"
and a "permalink" action?


Thanks,
- Dave

Dave wrote:
> On 3/12/07, Allen Gilliland <allen.gillilandsun.com> wrote:
>> Reminder, please comment on proposals if you have
something to say.  I
>> plan to start implementing my 4.0 proposals very
soon.
> 
> Overall, I think this is a good idea. I do share James
concern about
> going too far and defining too many actions -- so I
like your core
> set.

yep.  we should definitely discuss which ones we think are
worth doing 
and which ones are not, i don't have any strong opinions
about that 
except for the 2 i included by default, which are the search
results 
page and a tags index page.

my thinking right now is that it's best to start simple and
build from 
there.  there is no reason to try and add lots of custom
actions right 
from the start and once the code is in place and working it
should be 
very easy to add support for new actions.


> 
> Here are a couple of questions about the proposal:
> 
> * What is the schema for the new ROLLER_ACTION table
you are adding
> and please include it's relationships with other
tables.

I think you misread that part, there aren't any new tables,
only a 
single new column in the existing webpage table.


> 
> * How is the mapping from URL to Action Name defined
and can it be
> changed via configuration properties?

That's a very good question.  The way I was going to define
the mappings 
was simply in the code, and most specifically the code which
parses our 
urls.  So the logic would go in the various WeblogXXXRequest
objects 
under rendering.util.*

Making them configurable could be a cool idea, but I'm not
sure exactly 
how it would work.  The other problem with making it
configurable is 
that it creates a potential for users to mess things up. 
I'll think 
about this one a bit more though.


> 
> * Does this change any of the existing URL structure?
(I hope not)

nope, no changes to any urls.  it just allows us to assign a
specific 
template to be used for certain urls or possibly groups of
urls so that 
we don't have to keep using the Weblog template for
rendering all views.


> 
> * What classes in the rendering/request-mapping system
do you expect
> to change? Just the PageServet?

pretty close, the changes are actually fairly minor.  the
first change 
will be in the various WeblogXXXRequest objects which we use
to 
represent a parsed weblog request.  those classes will be
updated to 
support an 'action' attribute so that when a url is parsed
into one of 
these objects we determine what type of action is
represents.

then the second change is in the PageServlet and
SearchServlet where 
we'll update it's rendering logic so that it looks at the
'action' 
attribute from the parsed request and chooses the
appropriate template 
for rendering based on the action value.  right now the
logic is pretty 
simple ...

if(custom page) {
   // lookup custom template and render
} else {
   // get 'Weblog' template and render
}

... that logic will be expanded to include other
alternatives like ...

} else if(action == tagsIndex) {
   // look for special tags index template
}


> 
> * What are the implications for customizable feeds? I
assume we'd use
> actions to define them too w/actions like entryfeed,
commentfeed.

This doesn't actually change the situation with customizable
feeds and 
to be honest I'm still not sure what we really want to do
regarding the 
idea of customizable feeds.  But that should probably be a
separate 
discussion.

This proposal isn't currently planning to make any changes
with the way 
that feeds are rendered.  It could if we wanted it to, but I
wasn't 
planning on it.  If we decided that we did want to allow for
custom feed 
actions then I think it would work like you suggest above
where we 
define some special actions to represent customized feeds
which could be 
edited on the Template Editing UI.


> 
> * What's the difference between an "entry
index" and a "permalink" action?

They are just different urls.  So the entry index url is
...

<weblog>/entry/

... and the permalink url is ...

<weblog>/entry/<anchor>

... with the difference being that in a permalink you
actually have the 
anchor part of the url and are therefore pointing to a
specific entry, 
which the entry index page would be the index page for that
section.

the reason for having an entry index page would be if you
wanted to 
provide some kind of entry archive navigation.  i.e. if you
go to the 
entry index page you may get a very short and simple list of
all entry 
titles, or possibly a big calendar or something.  i'm not
really sure it 
would be useful enough to be worth supporting, it's just one
of our urls 
which we currently don't allow.

-- Allen


> 
> 
> Thanks,
> - Dave

As an aside, we've had quite a few requests for a simple
entry index as
part of our default blog template.  It seems to be quite
useful for
quickly finding old posts.

- James

Allen Gilliland wrote:
> 
> [snip]
> ... with the difference being that in a permalink you
actually have the
> anchor part of the url and are therefore pointing to a
specific entry,
> which the entry index page would be the index page for
that section.
> 
> the reason for having an entry index page would be if
you wanted to
> provide some kind of entry archive navigation.  i.e. if
you go to the
> entry index page you may get a very short and simple
list of all entry
> titles, or possibly a big calendar or something.  i'm
not really sure it
> would be useful enough to be worth supporting, it's
just one of our urls
> which we currently don't allow.
> 
> -- Allen
> 
> 
>>
>>
>> Thanks,
>> - Dave
> 

I've committed the initial support for this feature to the
trunk and 
it's working now.  I still need to refine the UI, but the
functional 
parts are there.  2 things though ...

1. We need to decide what actions we are going to support. 
I'll go 
ahead and propose this list right now ...

weblog - The default template, same as 'Weblog' template
now.
search - The search results page.
permalink - The entry permalink page.
tags-index - The tags section index page
(/<weblog>/tags/).

2. There is one somewhat yucky issue that has come up after
I did the 
implementation work.  Since these templates are optional and
may not all 
be present in all themes there is a potential problem with
action 
templates being left around from previous themes when the
user changes 
their theme multiple times.

For example, assume ThemeA defines a 'permalink' template. 
The user 
chooses ThemeA and decides to customize it, so the templates
are copied. 
  Then the user changes their mind and decides to use
ThemeB, which does 
not have a 'permalink' template.  At this point the user has
a 
'permalink' template in their templates section left over
from their 
previous theme which will likely cause problems when
rendering their new 
theme.  So, how should we handle this?

1. When rendering templates by action from a theme we ignore
custom 
templates from the weblog for specific actions.  This
prevents the 
scenario above because when using a shared theme we would
not look for 
the 'permalink' template in the users custom templates.  The
drawback is 
that this prevents the user from creating a template for a
specific 
action if their theme doesn't do it for some reason.

2. Accept that this is a potential problem and let users
deal with it 
themselves by deleting these left over templates.  Not
exactly a pretty 
solution :/

3. Force all themes to implement all action templates moving
forward. 
This is probably the cleanest and most ideal solution.  Also
remember 
that with the new theme metadata file it's entirely
acceptable to define 
2 templates in the theme using the same physical file, so
the templates 
for 'weblog' and 'permalink' actions could both use the same
Weblog.vm file.

Those are the main scenarios I am seeing right now.  There
are a few 
others that I had thought of but they didn't really solve
any more of 
the problem than these options.

Right now I am thinking that option #3 is sounding the best.
 It may 
seem a little harsh to force all themes to implement all the
various 
actions we are going to define, but remember that as I said
you can use 
a single template to do that.

thoughts?  opinions?

-- Allen


James M Snell wrote:
> As an aside, we've had quite a few requests for a
simple entry index as
> part of our default blog template.  It seems to be
quite useful for
> quickly finding old posts.
> 
> - James
> 
> Allen Gilliland wrote:
>> [snip]
>> ... with the difference being that in a permalink
you actually have the
>> anchor part of the url and are therefore pointing
to a specific entry,
>> which the entry index page would be the index page
for that section.
>>
>> the reason for having an entry index page would be
if you wanted to
>> provide some kind of entry archive navigation. 
i.e. if you go to the
>> entry index page you may get a very short and
simple list of all entry
>> titles, or possibly a big calendar or something. 
i'm not really sure it
>> would be useful enough to be worth supporting, it's
just one of our urls
>> which we currently don't allow.
>>
>> -- Allen
>>
>>
>>>
>>> Thanks,
>>> - Dave