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

Requirements

• define a list of supported weblog actions which will have associated templates.
• provide a way for packaged themes to make use of these individual templates.
• maintain backwards compatability for upgrading customers, so these templates cannot be required.

Issues

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.

Design

First we will introduce one new db column to the webpage database table named "action". During the upgrade process all existing 'Weblog' templates will be updated to action "weblog" while all other pages will be given action "custom". Then moving forward we can add support for any new actions we need. This will be the only change required in the data model.

• Templates which are used for specific actions will always have a standardized name, description, and link, so those things cannot be controlled by users. This will behave the same way the current standardized templates (Weblog, _day, _css, _decorator) do, where users may not edit the name, description, or link value for that template.

For changes to the rendering system the WeblogPageRequest will be updated to be capable of extracting an "action" based on the request url parsing. this can be accessed and used by the PageServlet (or other servlets) to make the right choice of template to lookup for rendering. if the individaul template for an action is not found then we either use the default Weblog template (search) or respond with a 404 (tags index) depending on how the functionality works now.

We can optionally define new Model objects to provide methods which are targeted for use specifically on the various action templates. The best example is how there is a specific SearchResultsModel to be used for displaying search results.

• We can build on this portion of the design after defining exactly what custom actions will be supported and whether or not those actions would benefit from a custom Model.

On the publishing UI the template editing section would remain mostly the same except that the templates list would be changed to highlight those templates which are attached to specific actions. This would be done by something simple like putting these templates at the top of the list and highlighting them in a different color, or something to that effect. This gives us the chance to provide focus to Roller's main templates and hopefully improve the usability of the template editing experience.

Also, the "add page" action will be updated to include a drop down list of potential action pages which can be created. if a weblog already has a template for a specific action then it will not show up in the list. the default option will be "custom" which creates a custom template to live under "/page/*" just as the current functionality works.

Any new urls which will be enabled to support a new template action will require some updating in the url mapping process and servlets. An example would be the tags index page (weblog/tags/) which currently is not supported and returns a 404 page.

Proposed Actions to Support

• weblog - this will be the default action and ultimately the same thing as the Weblog template now.
• custom - represents custom user templates like a stylesheet or an about page.
• search - used to render the search results page ... <weblog>/search?q=<query>
• tags index - used to render the tags section index page, the ideal place for a tag cloud ... <weblog>/tags/

The actions above I believe are basically essential and expect everyone will agree on. The rest are just possibilities and up for debate, so I am interested in opinions ...

• entry index - used to render an individual entry index page ... <weblog>/entry/
• permalink - used to render an individual entry page ... <weblog>/entry/<anchor>
• date index - used to reneder a date based index page ... <weblog>/date/
• category index - used to render a category based index page ... <weblog>/category/
• page index - used to render a custom templates index page ... <weblog>/page/

Comments

Comments ...