New Topic Template Mapping

In StopShippingTWikiUsers we learned that it is useful for an easy upgrade to have new topics created that are based on specific template topics. This can be done with a global rules table that maps new topics to template topics based on the new topic name.

Spec, using an example:

1. Define a system level rules table in TWiki.WebTopicEditTemplateMapping:

| ** | *New Topic* | *Based on Template Topic* |
| MAP | %MAINWEB%.TWikiUsers | %TWIKIWEB%.TWikiUsersTemplate |
| MAP | %LOCALSITEPREFS% | %TWIKIWEB%.LocalSitePrefsTemplate |
| MAP | %MAINWEB%.WebTopicEditTemplateMapping | %TWIKIWEB%.WebTopicEditTemplateMappingTemplate |

which renders as:

The first column has a "MAP" token that identifies a row as a mapping rule.

2. Optionally, define site level rules in Main.WebTopicEditTemplateMapping (in the Main web) that adds/overloads system level rules.

2. Optionally, define web level rules in Anyweb.WebTopicEditTemplateMapping in any web that adds/overloads rules at the site level and system level.

3. When someone creates a topic that is specified in one of the rules tables, it is based on the specified template topic, not the default one (which might be defined in TWiki.WebTopicEditTemplate or a web-local WebTopicEditTemplate). For example, when the first user registers in a brand new TWiki installation, the Main.TWikiUsers topic is created based on TWiki.TWikiUsersTemplate.

Note: The name WebTopicEditTemplateMapping is derived from the WebTopicEditTemplate topic name.

-- Contributors: PeterThoeny - 12 Jan 2007

Discussion

Question: This rules table might be handly also for TWikiApplications. For this, generic rules with wildcards or even regex might be needed? For example, you could create project management pages that consist of a base topic (e.g. BreadSlicerProject) and childrens (e.g. BreadSlicerProjectMinutes, BreadSlicerProjectRisks, BreadSlicerProjectStatus, ...). Only the base topic needs to be created in advance; when clicking on the question mark link of BreadSlicerProjectStatus, it will be based on a specific template. The rules could be:

| MAP | *Project | ProjectTemplate |
| MAP | *ProjectMinutes | ProjectMinutesTemplate |
| MAP | *ProjectRisks | ProjectRisksTemplate |
| MAP | *ProjectStatus | ProjectStatusTemplate |

-- PeterThoeny - 12 Jan 2007

This all sounds very complex, especially when you consider the number of places that would have to change in the code. I would be quite annoyed if I tried to create a topic called OverheadProject and ended up with an unexpected and inexplicable template, because some bright spark had defined that in the mapping table. If I didn't already know about mapping tables it would be the devil incarnate to track down where it was coming from. It is trivial (and more in-your-face) to write a URL that provides the template topic name, so I remain to be convinced of the value. If it can be made obvious where the template came from it wouldn't be quite so bad....

-- CrawfordCurrie - 12 Jan 2007

Why do you want to make it a twiki table in a topic? This table will change very infrequent, but induce an extra burdon to parse it. How about moving that information into LocalSite.cfg.

-- MichaelDaum - 12 Jan 2007

I have a problem / feature request which I believe overlaps this issue so I'll go ahead and post it here, although it may pertinent to move it to it's own topic since I believe what you're trying to solve is slightly different.

I have a very similar need to this where I have basically three or so different types of templates I need to use at any given time. Since there is only one TWiki template, I basically have to put everything into that and then delete what I don't need every time. This is much easier than not having it there at all, but is more difficult than being able to select the specific template I want and having everything customized. My ideas were to make it possible for the user to select somehow which template to use, if the default wasn't the one they wanted... either a selection dialog on the way to editing a new topic (if the option is enabled for template selection), or perhaps a template drop down on the actual edit page that would append the edit box with the selected template. The latter option would also give an advantage to have easy access to the template while editing an existing topic if perhaps it wasn't created with the correct template, or if part of the template was not needed and deleted, only to be needed later.

Again, it seems that this partially overlaps with what is laid out above, but not completely, given that it wouldn't be an automatic thing.

-- JoshuaJohnston - 12 Jan 2007

That feature is there. Look at http://develop.twiki.org/~twiki4/cgi-bin/view/Sandbox/WebHome. And then click the Create New Topic link in the left bar. You can then select the desired template topic.

-- KennethLavrsen - 12 Jan 2007

Michael: It is true that the we have fixed mapping rule for the few system topics, adding the rules to LocalSite.cfg would be OK for those. My idea is to allow end users to define rules, so that you get a quick collaboration experience: Click on a questionmark link and you get a custom template without going to an intermediate template selection process.

For TWikiApplications it is useful to have a form to create a topic based on a specific template; adding the mapping feature to get a specific template when clicking on a questionmark makes it even easier for end users. "Don't make me think".

Although some might see this implicit template selection as a "bad idea", (1) we already have it with TWiki.WebTopicEditTemplate and web specific WebTopicEditTemplate (and also with skin search path), (2) only WikiChampions are likely to create mapping rules, (3) it makes it easier for end users who just want to get their work done.

-- PeterThoeny - 12 Jan 2007

We can define the rules table as follows, based on the idea I stated in StopShippingTWikiUsers of automatically creating topics on first run of the view script after upgrade (in order to create all topics that need to exist but can't be overwritten on an upgrade):

| *Action* | *Web* | *New Topic* | *Based on Template Topic* |
| CREATE | %MAINWEB% | TWikiUsers | %TWIKIWEB%.TWikiUsersTemplate |
| CREATE | %MAINWEB% | %LOCALSITEPREFS% | %TWIKIWEB%.LocalSitePrefsTemplate |
| CREATE | %MAINWEB% | %HOMETOPIC% | %TWIKIWEB%.MainWebHomeTemplate |
| CREATE | all, exclude %MAINWEB% | %HOMETOPIC% | %TWIKIWEB%.WebHomeTemplate |
| CREATE | all | %NOTIFYTOPIC% | %TWIKIWEB%.WebNotifyTemplate |
| MAP | %MAINWEB% | TWikiTopicTemplateMapping | %TWIKIWEB%.TWikiTopicTemplateMappingTemplate |

• Column 1:
  • a CREATE token identifies a "create topic if not exist on first view" rule
  • a MAP token identifies a "create topic based on template topic" rule
• Column 2:
  • name of web
  • comma-space delimited list of webs
  • an all keyword specifies all webs
  • an exclude prefix excludes a web
  • if empty, it means "current web", or the web specified in column 3 (if any)
• Column 3:
  • name of new topic
  • may be of Web.Topic format (as in %LOCALSITEPREFS%)
• Column 4:
  • name of template topic; must be of Web.Topic format

If we offer this functionality, we better name the system level mapping topic TWiki.TWikiTopicTemplateMapping, and the optional site level topic Main.TWikiTopicTemplateMapping.

-- PeterThoeny - 13 Jan 2007