Feature Proposal: Upgrades are easier if you use MAINWEB%.TWikiPreferences

Motivation & Description

it's easier to keep track of your local preference customisations if you use Main.TWikiPreferences instead of TWiki.TWikiPreferences. This allows for easier upgrades as you don't need to worry about the shipped preferences clobbering yours.

-- MattWilkie - 19 Jul 2005

Impact and Available Solutions

Documentation & Implementation

This is just a documentation "best practices" fix. The code already works like this, and has worked like this for at least four years. The diffs just add a little explanatory text to the beginning of each preference topic.

• Main.TWikiPreferences.txt: diff for MAINWEB TWikiPreferences
• TWiki.TWikiPreferences.txt: diff for TWIKIWEB TWikiPreferences

Special thanks to MichaelSparks who first brought the overriding functionality to our attention.

matt, these didn't directly apply to SVN. here are the changes i made by manually applying the patches files. please verify. -- WillNorris - 21 Jul 2005

Index: Main/TWikiPreferences.txt
===================================================================
--- Main/TWikiPreferences.txt   (revision 4677)
+++ Main/TWikiPreferences.txt   (working copy)
@@ -1,7 +1,7 @@
 %META:TOPICINFO{author="TWikiContributor" date="1111931141" format="1.0" version="$Rev$"}%

+| Site-level preferences are located in [[%TWIKIWEB%.%TOPIC%]], however this [[%MAINWEB%.%TOPIC%]] prefs topic has overrride priority and should be used for local customisations. This allows for easier upgrades as you don't need to worry about the shipped preferences clobbering yours. It's easier to keep a handle on if you only copy over the settings you actually change.|

-The site-level preferences are located in [[%TWIKIWEB%.%TOPIC%]]
 <!-- keep this as a security measure:
        * <nop>Set ALLOWTOPICCHANGE = TWikiAdminGroup
        * <nop>Set ALLOWTOPICRENAME = TWikiAdminGroup
Index: TWiki/TWikiPreferences.txt
===================================================================
--- TWiki/TWikiPreferences.txt  (revision 4677)
+++ TWiki/TWikiPreferences.txt  (working copy)
@@ -2,6 +2,8 @@

 ---+!! <nop>%WIKITOOLNAME% Site-Level Preferences

+| This [[%TWIKIWEB%.%TOPIC%]] is the as-shipped site-level preferences, however the [[%MAINWEB%.%TOPIC%]] prefs topic has overrride priority and should be used for local customisations. This allows for easier upgrades as you don't need to worry about the shipped preferences clobbering yours.|
+
 The following are __site-level__ settings that affect all users in all webs on this TWikiSite. They can be selectively overwritten on the __individual web level__ (see %WEBPREFSTOPIC% in each web), __topic level__ (the topic being rendered), and on the __user level__ (create preferences in your user account topic in the %MAINWEB% web, ex: %WIKIUSERNAME%).
        * %X% *NOTE:* You can lock individual settings at the site or web levels using User & Group Access Control - see section below.
 <form method="post" action="https://twiki.org/cgi-bin/viewauth/Codev/UseMainTWikiPrefs#EditPreferences" enctype="multipart/form-data" name="editpreferences"><input name="prefsaction" type="hidden" value="edit" /><input type="submit" name="edit" value="Edit Preferences" class="twikiButton" /></form>

Discussion:

checked into SVN:4679 (ignore the <nop> as sven had to put them in to unlock this topic after i put the patch inline. i don't know what's supposed to happen to such directives inside verbatim blocks...?

-- WillNorris - 21 Jul 2005

Wow, thanks for such a quick response Will. Your changes look fine over here.

It might be nice to pre-populate with some of the most frequently changed settings (just append this to the existing topic text):

*Some of the most frequently customised settings are:*

TWiki site name:
   * Set WIKITOOLNAME = TWiki

Site logo image, URL and alternate tooltip. Activate by attaching =logo.png= to this page. They can be overwridden in !WebPreferences for individual webs by defining these variables there.
   * Set WIKILOGOIMG = %PUBURL%/%WEB%/%WIKIPREFSTOPIC%/logo.png
   * Set WIKILOGOURL = http://your.company.com/
   * Set WIKILOGOALT = go to homepage of your.company.com

Default site-wide [[http://favicon.org][favicon]], to activate attach a =favicon.ico= to this page. You can also set a separate  =FAVICON= for earch web, using their respective WebPreferences
   * Set FAVICON = %PUBURL%/%WEB%/%WIKIPREFSTOPIC%/favicon.ico
   
TWiki webmaster full name and email address 
   * Set WIKIWEBMASTERNAME = Noah Body
   * Set WIKIWEBMASTER = webmaster@your.company

LynnwoodBrown and I worked out cleaner way to support alternate main preferences in DEVELOP. You can now define {LocalSitePreferences} in configure to any Web.Topic, and it will pick that up and use any preferences in it to override preferences set in TWikiPreferences (though someone needs to check it works for FINALPREFERENCES...)

-- CrawfordCurrie - 22 Jul 2005

• Main.TWikiPreferences.txt: diff for MAINWEB TWikiPreferences

• TWiki.TWikiPreferences.txt: diff for TWIKIWEB TWikiPreferences