Tags:
create new tag
, view all tags

Feature Proposal: Create a new $TWiki::cfg{HomeWebName} configure variable

Motivation

This variable is needed both for symmetry with the HomeTopicName and because in TWiki code, the functionality of the "Home web" is currently randomly spread between the Main and TWiki webs. It allows to build new functionalities on top of it like ShorterUrlSupport

Description and Documentation

This proposal introduce

  • a perl var $TWiki::cfg{HomeWebName} , in bin/configure, defaulting to Home
  • a TWiki var %HOMEWEB%, created from the above
  • replaces in the TWiki perl code the references to Main or TWiki web to Home when relevant.
  • It also provides a sample new Home web in the distribution

Examples

See http://wiki.koalaz.net/ where the patch is installed

Impact

WhatDoesItAffect: Documentation, Install, Prefs, Usability, Vars

Implementation

The attached patch 420-homeweb.diff should be applied with -p1 to a 4.2.0 distribution to create changes to the code, documentation, and to create a sample Home web

My working dir for this is availabe on the mercurial repository: http://hg.colas.nahaboo.net/twiki-colas/42-homeweb/

-- Contributors: ColasNahaboo - 10 Feb 2008

Discussion

Accepted by 14 day rule

-- KennethLavrsen - 28 Feb 2008

This proposal does not specify the default for the {HomeWebName}. For compatibility I suggest %MAINWEB%, e.g. the Main web.

-- PeterThoeny - 02 Mar 2008

No, the proposal creates a new "Home" web shipped in the distrib, and makes it the default for {HomeWebName}. This allows to clearly separate the roles as they now tend to be: Home is the root, the landing page, Main is the admin, backoffice space with site-specific stuff, TWiki is the "engine" coming from TWiki.org, normally unmodified.

For instance, in most sites you want to exclude Main,TWiki,Sandbox from search engines via robots.txt as Home is where you put the actual contents of your site. You do not want users to start building their wiki sites in Main, among the user pages and site settings.

A nice modification however, would be for the new Home web not be shipped as is, but be created (from _default) by running bin/configure on save if it does not found an existing web matching the contents of $TWiki::cfg{HomeWebName}. This would keep the important property of not having the user be forced to modified any file shipped in the distrib (for upgrades). I'll see how I can do this.

-- ColasNahaboo - 02 Mar 2008

I would appreciate also if the Home web is NOT distributed. I had not noticed that this was part of the proposal.

I already have a web called Home and do not want it overwritten each time I upgrade. I have trouble enough merging the Main web.

Having a HOMEWEB variable that defaults to Main that you can change to Home is backwards compatible and does not cause trouble for existing customers when upgrading.

-- KennethLavrsen - 03 Mar 2008

Peter & Kenneth, I agree on the compatibility & upgrade issues. But I also would like new installs to be right "out the box", so as not to require mandatory tweaking. So perhaps the best of both worlds could not to ship the Home web, but still default $TWiki::cfg{HomeWebName} to Home and either:

  1. in configure signal in red (warning) when the web named in $TWiki::cfg{HomeWebName} do not exist yet, and propose to create it
  2. same, but do not propose to create it, but will propose to create on first attempted access, if this is understandable enough.
Note that we could do this for more things. For instance the Main web.

I will take some time to experiment with these proposals (and others?) to see what they imply in practice.

-- ColasNahaboo - 03 Mar 2008

Wait a moment: why would you normally hesitate to build the site in Main? That's because the user pages and the site configuration is in there. THESE need to be moved out, i.e. have a User web for all homepages. I don't really understand the benefit of a %HOMEWEB% variable. Maybe I need to read the proposal again. A %USERWEB% variable would make much more sense and leave the Main web to be use for whatever purpose you want. Isn't it that what you are aiming at, Colas?

-- MichaelDaum - 03 Mar 2008

%USERSWEB% already exists... ( $TWiki::cfg{UsersWebName} ) but anyways nobody is using it as this would need you would have to rewrite a ton of documentation pages that refer to Main, so it is even discouraged. And "Home" is really the natural name for the Home Web... The home topic is WebHome, not WebMain ...

-- ColasNahaboo - 03 Mar 2008

So what reasons remain not to create the site in Main and have a separate Home web, once the users are out?

-- MichaelDaum - 04 Mar 2008

  1. compatibility: why changing what exist (users in Main). Better have the newcomer use the new var rather than introduce tons of changes that will imply changing docs, training (the slides I made for ILOG uses), FAQs, user habits...
  2. Home is a much more natural name than Main for a ... Home web.

-- ColasNahaboo - 04 Mar 2008

Some points for consideration. The Main web is currently overloaded to perform three functions:

  1. Hosting Site preferences
  2. Hosting Users topics for the TWikiUserMapping module
  3. Hosting the root topic(s) for unqualified URLs (those with no web specifier)

It seems to me that the proposal needs to focus on the best way to achieve clean separation of these three functions.

The obvious approach is to support separation in configure, by setting defaults that reflect the current default configuration:

  1. Support redirecting the "start web" - the default web that an unqualified URL goes to. The default would be $TWiki::cfg{DefaultWebName} = 'Main'
  2. Support an alternate location for site preferences. The default would be $TWiki::cfg{SitePreferences} = '$TWiki::cfg{DefaultWebName}.TWikiPreferences';
  3. Support redirecting the TWikiUserMapping to a different web. The default would be $TWiki::cfg{Extensions}{TWikiUserMapping}{WebName} = '$TWiki::cfg{DefaultWebName}'
I do not favour adding more 'system' TWiki variables that point to these webs. I'd much prefer to replace %USERSWEB% and %MAINWEB% with some generic config-fetching mechanism. Compatibility can be maintained if TWikiPreferences contains (for example)
  • Set MAINWEB = %CFG{"{DefaultWebName}"}%
  • Set TWIKIWEB = %CFG{"{SystemWebName}"}%
Yes, I appreciate that the hardest part is fixing up documentation. But that's an issue regardless of which approach is taken.

-- CrawfordCurrie - 05 Mar 2008

Crawford, I wasnt saying the hardest part is changing the TWiki shipped documentation. The hardest part is inconsistencies with the documentation you cannot change:

  • user habits, word of mouth, site-local FAQs, slides, training materials...
  • books(*) (peter's one), blogs posts on the web providing hints, howtos
  • 3rd party scripts, addons, connectors, ... It also raises a bit more the complexity barrier for new developers
In this way, too much flexibility can be detrimental. It was lethal to unix (how can I ship an application on unix systems as each unix system is different from the other one?) . If I was benevolent dictator, I would remove all the variables and make all the system web names fixed smile

BTW I agree with your analysis. But your %CFG proposal - that I find nice - seems an orthogonal one, deserving a proposal of its own?

(*) I was bitten by this on Mercurial. I began to read the book, tried its examples... which didnt work because mercurial changed in incompatible ways with this not-changeable-doc... I was really pissed off and didnt use the book anymore.

-- ColasNahaboo - 06 Mar 2008

I started reading my "KDE 2.0 Development book" I bought "some time ago", and found out that its examples won't work on KDE-4.0 anymore wink

There are TWiki haters out there because its configuration management is so bad: too many variables, in different places, bad configure gui, bad documentation, being a performance hog, well you name it. We will need to change & break stuff to move ahead....

-- MichaelDaum - 06 Mar 2008

Just an update to say that in my opinion this proposal is nearly ready to commit in subversion, except for the issue of not shipping a Home web but having configure build it on the fly if not present. I intent to implement it, and then will commit in trunk

-- ColasNahaboo - 24 Sep 2008

Ok, the 423-homeweb.diff implements auto-creating the home web as defined in the configuration ($TWiki::cfg{HomeWebName} and thus %HOMEWEB%) by the bin/configure script if the web do not exists yet (thus upgrading TWiki will not clobber an installed Home web). We do not thus need to ship an Home web, I have removed it from the patch.

If not problem found or objection raised, I will commit the changes in some days. However, I would like to find a solution before this to Kenneth remark: What about the case of users upgrading their TWiki install who already have built their homeweb in Main? I guess a solution could be that configure would first try to see if Main's WebHome was identical to the _default one, and set the initial value of $TWiki::cfg{HomeWebName} to Home if identical and Main if not.

And of course, if someday a refactoring of all the configuration variables is done (CDot proposal) my added code would be refactored as the rest of TWiki...

-- ColasNahaboo - 25 Sep 2008

That would not be so simple, the home we could contain a lot of topics (like department info) that cannot be identified by checking against _default.

I think that to be safe we should enumerate the possible scenarios (new user and upgrade users) and discuss the most troublesome ones.

I can start... later

-- RafaelAlvarez - 26 Sep 2008

Raphael, what I wanted is to detect is if the user has begun to use Main as a Home page. Detecting a change of Main.WebHome seems the best solution.

Another idea, though would be to have configure detect if this is a new install (no LocalSite.cfg exists), and make Home the default setting of the variable in this case. Otherwise, just use "Main?" as the default for the variable, but then display a warning for this to push the user to ponder the question. Then, if he decides that he really wants the home web be Main, instruct him to use "Main" to remove the warning (My code removes all non-alphanumeric chars so "Main?" will be translated to Main anyways in the actual use)

Variant: test the presence of a marker file in twiki dir (or lib/),e.g. homeweb_created not shipped with the distrib, but created on the creation of the home web, and display "Main?" as long as this file do not exists (and display a warning as long as there are non-alphanumeric chars in the variable value)

-- ColasNahaboo - 26 Sep 2008

No owner after 1.5 years, and IMHO no clear need since the home URL can be defined by the WIKILOGOURL and WWEBLOGOURL (used in logo URL and breadcrumb home.) Therefore I am setting this proposal to "parked".

-- PeterThoeny - 2010-06-06

Topic attachments
I Attachment History Action Size Date Who Comment
Unknown file formatdiff 420-homeweb.diff r1 manage 78.9 K 2008-02-10 - 21:57 ColasNahaboo apply with -p1 to Twiki-4.2.0
Unknown file formatdiff 423-homeweb.diff r1 manage 13.9 K 2008-09-25 - 22:55 ColasNahaboo Apply to 4.2.3 with patch -p1 <423-homeweb.diff
Edit | Attach | Watch | Print version | History: r19 < r18 < r17 < r16 < r15 | Backlinks | Raw View | Raw edit | More topic actions
Topic revision: r19 - 2010-08-01 - PeterThoeny
 
  • 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-2017 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.