OO crib sheet

If you have mangled TWiki for you own purposes, or written a plugin or add-on that pokes into the core, then you need this crib sheet. In the shift from Cairo to Dakar, a large number of internal interfaces have changed. This will not affect you if you used only the Func interface but if you short-circuited that interface, some functions you used may have changed or disappeared entirely. This crib sheet shows the mapping between functions in Cairo and their equivalents in Dakar, to assist in porting.

One important thing to understand is the effect of eliminating global variables, in order to support mod_perl. This has been done by creating objects with only one instance that represent the packages in TWiki - for example, instead of there being a "Prefs module" that holds preferences in global variables, there is now a "preferences object" that contains those preferences.

Global data in the TWiki module has also been formally split into "site" and "session" data. Site data comes from the TWikiDotCfg file, and is not expected to change, so it is still in the old global variables, but these must be treated as _constants. Session data is specific to a single query, and has been moved into the TWiki "session object", henceforth referred to as $TWiki (from a plugin, the session object can be obtained via TWiki::Plugins::SESSION. This session object also contains references to a number of other session-specific objects corresponding to the different TWiki modules; for example,

• Store - $TWiki->{store}
• Access - $TWiki->{security}
• Prefs - $TWiki->{prefs}
• etc

From a programmer perspective the main impact this has is to change the way you call core functions and refer to session global variables. Instead of calling functions using syntax like "TWiki::Prefs::getPreferencesVariable", you now have to indirect via the TWiki session object. e.g. $TWiki->{prefs}->getPreferencesValue(...)=. Per-session variables such as the old $TWiki::webName are now accessed via $TWiki->{webName}.

Not all packages are affected, only those with data in global variables, and not all functions in the affected packages - some are purely static (do not refer to global data), and have been left that way. If you are unsure, look at the core code. If the method you want to use has a new first parameter $this or $self it has become an object method and must be called via the session object.

Having said all that, if your extension is referring to TWiki::Plugins::SESSION you are probably doing something wrong. You should probably be using the FuncDotPm module, or campaigning to get that module extended to support your extension! And a word of warning; if you module has any session-specific global variables it will probably not work under mod_perl.

There are also changes to the location and/or naming of many methods. The table below gives the approximate mapping. It has been generated during the changes and may be inaccurate in some ways, but you should be able to resolve any unknowns by reading the code. Note that any methods that now start with an underscore are now private to the module and must not be called from outside that module, even by other core modules. No mapping has been given for methods that were private in Cairo; you are on your own if you've been crazy enough to call these.

-- CrawfordCurrie - 08 Dec 2004