archive_me1Add my vote for this tag create new tag
, view all tags

Feature Proposal: Support topic-specific templates


Many TWikiApplications need to provide a different topic layout than given by the standard view template. The only feasible way to do such currently is to create a separate web per application where one uses a customized template. The downsides of this are

  • users cannot create their own topic layout, as it requires access to the templates directory and the ability to create subdirectories there
  • applications often need different layout for different topics, e.g., documentation pages and data pages, which are laid out differently.


Cairo implemented the ability to read templates from user specified locations, but did not provide a simple way to access these (only through the skin mechanism, but unless all templates were reimplemented in the custom format, the topic would default to ClassicSkin).

This enhancement provides enhanced capabilities to define the template for a topic:

  1. by passing a template parameter in the Url which defines the template to be used
  2. by storing a template name in meta data for each topic

-- ThomasWeigert - 02 May 2005

Impact and Available Solutions

Not visible unless feature is used.


The view script has the following additional Url parameter:

Parameter Description Default
template Defines the template to be used. This can be either Web.Topic or Topic which is parsed following the algorithm documented. (undefined)

The algorithm for locating the template to be used, based on a template name, is as follows:

  1. looks for file $name.$skin.tmpl (for each skin)
    1. in templates/$web
    2. in templates, look for
  2. looks for file $name.tmpl
    1. in templates/$web
    2. in templates, look for
  3. if a template is not found, tries in this order
    1. parse $name into a web name (default to $web) and a topic name and looks for this topic
    2. looks for topic ${skin}Skin${name}Template
      1. in $web (for each skin)
      2. in TWiki::cfg{SystemWebName} (for each skin)
    3. looks for topic ${name}Template
      1. in $web (for each skin)
      2. in TWiki::cfg{SystemWebName} (for each skin)
In the event that the read fails (template not found, access permissions fail) returns the empty string ''.

$skin, $web and $name are forced to an upper-case first character when composing user topic names.

An additional preference setting is supported:

parameter Description Default
VIEW_TEMPLATE Template used for defining the layout of this topic. This can be either Web.Topic or Topic which is parsed following the algorithm documented. (undefined)


  • Simple example: Say you want to modify the view template for topic MyTopic to have the form above the text area. You could define a topic ViewTemplate in the current web and view the topic with MyTopic?template=View
  • More elaborate: Define an alternative view template (AlternateTemplate) which shows some heading text, then the text area, then the form with a button allowing to edit form, and then the actions, but instead of the edit button have a button that edits the text only.


Passing the template name as parameter is in SVN 4220. This includes bug fixes to the template location algorithm, which was not analogous to system templates for templates defined by user topics. Defining the template name as preference is in 4237.


I'd like to implement the second mechanism (defining templates in meta data) but am waiting for feedback first.

I also think that the algorithm for finding templates would be better if we were to look in the user topic before falling back to the template topic without the skin to allow intercapting a basic lookup. The second example above could then be called as MyTopic?skin=new which would make this completely transparent to the user.

-- ThomasWeigert - 02 May 2005

I have this code working now. I just defined a preference variable to be used to select the template.

Now I want to create an interface to set those in the more screen, rather than having them visible in the form if so desired.

-- ThomasWeigert - 02 May 2005

I think I remember a discussion that suggested that templates should not be user specified as it will become a security problem (by allowing people to create templates that look exactly like a real template, but act differently.

Also, there is a performance hit for each topic view you do

on the other hand I'd like this kind of funtionality. Especially if you take it to it logical conclusion, doing away with the template dir, and replacing it with a admin secured TemplatesWeb.

This would make TWikiSkins true TWikiApplications, requireing only a set of topics&attachments and some TWikiPreferences.

-- SvenDowideit - 02 May 2005

Hmmm. I am not sure how templates would be different from topics, except for the HTML header. I guess we could come up with a mechanism of ruling that out in the user specified templates.

Note that the user can already specify templates in Cairo, but it is awkward to use.

-- ThomasWeigert - 02 May 2005

I don't mean that the template topic would be gotten bt TWiki using view, rather that it would be stored, and editable like a topic, but would then be read in like templates are now (though using Store..)

-- SvenDowideit - 02 May 2005

As I said, this is already in Cairo as a capability. Are you suggesting that we roll that back?

-- ThomasWeigert - 02 May 2005

This is somewhat tangential to this discussion but thought I would mention it in case solutions discussed here could be expanded to include this feature somehow. For some time I've wished one could assign a skin to a window that persists. A simple use-case can illustrate this. If one clicks on the "More formatting help" in the edit view, TextFormattingRules pops up in small window with plain skin applied (using "?skin=plain"). However, if you then click one of the links in that topic (say, to view TWikiVariables), the next topic is displayed in the default skin which doesn't work well with the small window. If I understand correctly, one option discussed above that might apply to this use-case would be to assign a skin to a whole set of help topics.

-- LynnwoodBrown - 02 May 2005

I see what you mean. That is very annoying... I think this is a separate feature that should be proposed. I'll think about it, but clearly, the popup window is not usable this way...

I cannot see a good solution, though, other than making the skin sensitive to how one is using a browser (e.g., differentiate by whether a menu bar is there or not)...

-- ThomasWeigert - 02 May 2005

See a live example of this feature: An alternate view is defined using a topic only, where we can edit the form and the topic separately, and made some other small changes to the standard view template. (Obviously, a final solution would not stick the configuration parameters into the form where they are both visible and susceptible to change. But I thought it is good to have an interim demo of the capabilities I am discussing here...)

-- ThomasWeigert - 03 May 2005

I see a checkin for this (SVN 4237) but no documentation.....?

  • Right. I wanted to demo this idea first. I personally am not very fond of having settings like this in the topic so that users can see and edit them away. So I wanted to get some feedback on the general idea first and maybe implement a different mechanism to set the configuration data (this comment actually applies to many other settings as well). But your point is well taken... I should add documentation also for 4237 above. --TW

-- CrawfordCurrie - 03 May 2005

WRT Security, appart from the issue of faking pages, there is also the issue of templates being able to link to javascript. I know we don't currently have any security to remove scripting from topic content, so it's a bit of a moot point, but if we ever do need to crack down on it or restrict it in some way to "trusted" areas then we would need to be able to do the same for templates.

  • These issues already exist for any topic --TW

-- SamHasler - 03 May 2005

Added documentation for SVN 4237

-- ThomasWeigert - 03 May 2005

can this be set to ReadyForMerge?

-- WillNorris - 23 May 2005

Updated the documentation to be consistent with changes in SkinSearchPath

-- ThomasWeigert - 23 May 2005

I suspect this also address some of the issues of ClassificationDrivenPageLayout which, was the capability missing that led to me needing to use the web/view.tmpl in Main in Dakar. I am trying to get to a place where people's home topics always have all picture attachments shown, but that this is driven by the type of the page not the web that the page is in.

-- MartinCleaver - 25 May 2005

Absolutely. This was precisely the issue I was trying to address. What you are trying to do becomes easy using this feature (except that you would have to use field VIEW_TEMPLATE rather than CLASSIFICATION to set the template you are trying to use).

-- ThomasWeigert - 25 May 2005

Is there a way I can make this apply to those topics with a given classification? It seems much more natural to me than requiring a preference setting to be repeated on every user page (I'm trying to keep such pages clear of stuff that would confuse users) or for blindly applying this in WebPreferences (in which case its no better than Main/view.pattern.tmpl)?

-- MartinCleaver - 13 Jun 2005

Theoretically yes, but it appears that everybody wants a different way of associating topic-specific templates. Using classification is only one of the many ways... Most users do not want the template setting to be visible in the view mode or easily editable. So probably putting it in the form is not the best way....

However, I do understand your point... maybe there is a way of configuring a web setting to determine what to look at for deciding what template to use... I'll study this some more...

-- ThomasWeigert - 13 Jun 2005

Thomas - could you clarify how one assigns the VIEW_TEMPLATE preference? Can one use the "six-spaces, *, space, SETTING =" method or include it as a form variable, or both, or something else?

-- LynnwoodBrown - 13 Jun 2005

Remember this is for DakarRelease... I have currently implemented a new meta data called %META:PREFERENCE{...}% which can be edited in a screen you get to off the More... screen using the standard "3 spaces *" notation.

You can see this at the develop branch. That particular page is an example... Sorry, not any longer. Apparently the Sandbox was cleaned out on DevelopBranch frown

I am thinking how we could choose dynamically a user defined flag to signal the special form, such as suggested above by Martin...

-- ThomasWeigert - 14 Jun 2005

Good example, Thomas, nice and succinct.

Now how would I apply that to a user's home page in Main to get around the objections Arthur had to Martin putting the form at the top of the page for display and it jumping to the bottom for editing?

-- AntonAylward - 23 Jun 2005

I would suggest to handle this by leveraging the ability to edit the form and the text separately. This way, the form would not be jumping around, as you would not edit it concurrently with the text. This may also be more intuitive? You also might want to format the user form differently, so that it is not confused with the standard forms (e.g., two-column layout).

-- ThomasWeigert - 10 Jul 2005

On the questions how to signal which template to choose, I believe there are the following obvious options:

  • a preference variable (either system-wide, web-specific, or topic-specific)
  • a form field

However, for the latter choice, there seems no obvious agreement on what form field to choose. One could create a preference setting that determines what form field to trigger off. But a bigger problem with this method appears to be that the value for the form field will not obviously always be a handy name that could be used for the name of the template topic. (What will happen is that the template would be the field value appended with "Template".)


-- ThomasWeigert - 10 Jul 2005

Extended this idea to EDIT_TEMPLATE. In SVN 4570. Protect %META{"formfield"}% from characters illegal in TWiki tables to allow for easier topic creations. Updated doco for MetaDataRendering. SVN 4572

-- ThomasWeigert - 10 Jul 2005

Edit | Attach | Watch | Print version | History: r30 < r29 < r28 < r27 < r26 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r30 - 2008-09-12 - TWikiJanitor
  • Learn about TWiki  
  • Download TWiki
This site is powered by the TWiki collaboration platform Powered by Perl Hosted by OICcam.com Ideas, requests, problems regarding TWiki? Send feedback. Ask community in the support forum.
Copyright © 1999-2018 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.