Item175: Create TWiki compatibility plugin

As discussed in RebrandingPlan we need a compatibility module for existing TWiki users to get them up to speed as fast as possible.

The ideal brief is that Users should be able to install Foswiki, change the Extensions installer to point only to twiki.org and update and install anything, including core plugins.

The Plugin needs to:

Include and TWiki-specific doc topics

Even if these are only pointers to the true doc

Redirect references to TWiki-specific web names

(TWiki. and Main.) To their new brand-free name, Interwiki-style

not so simple - as its dependant on where the topics are, references to a SYSTEMWEB topic that is actually in the TWiki web needs to goto the right place.

Similarly for pub files. This will likely require some dirty regex post processing like the DistributedServersPlugin

Sven is trialing:

1. a Foswiki::Store::_getHandler hack that changes topic handlers to TWiki web if it detects that the stored data does not exist in the original place
2. change PUBURL to SCRIPTURL{viewfile} for any TWiki caused attachments? thus taking advantage of the getHandler hack?
3. a restHandler that will recurse through the TWiki web, and create a remapping Hash for pub Urls (this might also be the faster way to deal with topics too)

Contain the TWikiTerminologyMap

DONE - uses configure based hash to do the equivalent to apache's non-redirect rewriteRule.

Map TWIKIWEB to SYSTEMWEB and MAINWEB to USERSWEB

TWiki did the reverse. Should be as simple as a *Set, but that Set needs to be in SitePreferences

DONE in the plugins' earlyInit (TWIKIWEB->TWiki, MAINWEB->USERSWEB)

contain a twiki.tmpl

that does an TMPL:INCLUDE{foswiki.tmpl} DONE

Namespace mapping

The main requirement is that unreleased plugins should have as painless a time as possible. These plugins are known to depend on:

• TWiki::Func
• TWiki::Plugins
• TWiki (they often use it)
• %TWIKIWEB%, %MAINWEB%

They may also assume:

• Main, TWiki webs

ACTION: check the source tree to see what published plugins have abused

For Perl source code compatibility, an aliasing of one namespace to another can be done using Package::Alias, which basically just assigns the typeglob for the original namespace to the alias namespace.

(Nice one, Isaac! Thanks for pointing Package::Alias out).

• Package::Alias is a bit counter-intuitive to use, you might want to have a look at Aliased from Ovid, because of this, for example. -- OlivierRaginel - 19 Nov 2008 - 08:32

• Looking at the documentation and reading the thread you linked to, the Aliased module is intended specifically to provide an alias for a class and not alias a namespace, so it won't serve the needs for the Foswiki project. The confusion referred to -- that the module is not automatically imported with use/require -- is not an issue in this case; the compatibility module only needs to ensure any references to the TWiki:: symbol table will redirect to the Foswiki symbol table, and in fact it should not import anything automatically. (Using Package::Alias is just a bit of syntactic sugar; I just looked for a module that prettied up assigning one symbol table to another.) -- IsaacLin - 19 Nov 2008 - 13:32
  • Thinking about it some more: To keep the use TWiki* statements for TWiki plugins as is, stub TWiki.pm and TWiki/*.pm modules are needed; they would use the corresponding Foswiki module and then alias the namespace. (If a parent namespace is already aliased, aliasing the descendant namespace is not needed, but there is no harm, either, and the code is more straightforward.) -- IsaacLin - 19 Nov 2008 - 15:58

• yep, I ended up using Package::Alias - CDot.

I attached a shell script that renames the existing TWiki namespace to Randomnewname when run at the root of a checkout. Should be a run-once, once we have the new name. Does not touch JS or CSS, only pm. pl, bin/*.

STATUS - CDot 19/11/2008

1. I have moved the code namespace using the t2fos.sh shell script in /trunk
2. I have renamed the data/TWiki dir to data/System (it was easier than doing the move via data/Foswiki)
3. I have recoded the plugins discovery so that configure must be run to discover a plugin. And when it is discovered, the namespace it is found in is recorded. So in theory it's possible to have a Foswiki plugin and a TWiki plugin with the same name both available, and select between them in configure.

I have moved the code on /trunk over to the Foswiki namespace.

• TWiki plugins work, even ones that are just unzipped.
• I changed pseudo-install.pl to auto-enable the plugins you install that way.
• There is no "automatic mapping" of an old LocalSite.cfg to the new type. Namespace sharing doesn't seem to work for reasons I can't fathom.
• There is a new $Foswiki::cfg var {Plugins}{WebSearchPath}
• Each plugin has a {Plugins}{plugin}{Module}
• I had to disable the TWikiCompatibilityContrib, because it was rewriting references to the plugin topics in the TWiki web.

I fixed all the static strings and all the comments as well. I also moved the following into the Foswiki namespace:

• BehaviourContrib
• CommentPlugin
• EmptyPlugin
• InterwikiPlugin
• JSCalendarContrib
• MailerContrib
• PatternSkin
• PreferencesPlugin
• TinyMCEPlugin
• TopicUserMappingContrib
• TwistyContrib
• TwistyPlugin
• UnitTestContrib
• WysiwygPlugin

The others I left where they are, partly to test TWiki plugins in Foswiki.

---

To skip the syntactic sugar and just assign one symbol table to another, no strict 'refs' needs to be in effect during the assignment (so the text string can be interpreted as a reference to the variable named in the string).

Regarding problems with reading configuration from legacy LocalSite.cfg files: Perhaps namespace aliasing is happening too late? It may not be feasible to load in a plugin to do the aliasing; there may need to be a special hook so this can be done during the compile-time phase. I know the aliasing approach seems to have been abandoned, but I think assigning one symbol table to another is a very concise way to do precisely what is needed.

-- IsaacLin - 20 Nov 2008 - 17:46

Javascript and CSS

For any Javascript code contained within the TWiki simulated namespace: Namespacing in Javascript is simulated by using a variable as the namespace. As variables for objects are actually references (like in Java), the Foswiki project can have two variables pointing to the same underlying object, providing access to its properties via two separate simulated namespaces. Please also refer to Tasks.Item116.

CSS is a rule-based language, and there is no way to say that all the rules for one set of selectors applies for another set except by explicitly specifying that second set of selectors for each rule. (The cloning of the selectors could of course be automated.) See Tasks.Item113.

Status 30 Nov 2008 - The perl code has now reached a level of maturity that this catch-all task shouldn't be used for checkins any more, so I'm shutting down this report and elevating Item113 and Item116 to Urgent. - CrawfordCurrie - 30 Nov 2008