Foswiki Upgrade Guide

This guide covers upgrading from a previous version of Foswiki or TWiki (such as Cairo or TWiki4.0) to Foswiki 1.0

On this page:

Overview

Foswiki is in reality the TWiki project continued under a new name.

The brand name change has had a large impact on many things that also impact an upgrader. They are however mostly visible "under the hood" and a TWikiCompatibilityPlugin is provided that makes Foswiki compatible with most Plugins made for TWiki.

Foswiki is 100% compatible with all content of existing TWikis which is the most important factor when you upgrade.

Upgrading from TWiki to Foswiki

If you upgrade from TWiki to Foswiki, you are strongly adviced to read the Foswiki:System.ReleaseNotes01x00 (also available in HTML version in the root of your installation) where all the changes from TWiki 4.2.3 to Foswiki 1.0.0 are listed.

Upgrade Requirements

Upgrade Procedure

The following steps are a rough guide to upgrading only. It is impossible to give detailed instructions, as what you have to do may depend on whether you can configure the webserver or not, and how much you have changed distributed files in your current TWiki or Foswiki release.

The main steps are:

  1. Install the new Foswiki version, configure it, and get it to work similar to the old version
  2. Install additional extensions (Plugins). Make sure to use the latest Foswiki versions
  3. Copy all the non-default webs from the old installation to the new
  4. Copy the users from old installation to the new incl all their topics from Main
  5. Apply tailorings to your Skin (logos, menu bars etc)
  6. Apply preferences from old installation

Installation

Install Extensions

Copy your old webs to new Foswiki

Copy Users And Their Topics From Main Web

Apply Customizations To The Skin

Apply Preferences From Old Installation

Customization of Special Pages

Some pages in the Foswiki web are meant to be customized after choice of authentication. If you do not use the internal Foswiki password manager the topics that contains the features for changing and resetting passwords and changing the email address should be changed to a note describing how to perform these tasks in your organization. If you have made such customizations remember to replace these topics in the System web with the tailored versions from your old installation. If you upgrade from TWiki remember that the old TWiki web is called System web in Foswiki. The topics are:

Upgrading from TWiki Cairo to Foswiki (additional advice)

Favicon

Foswiki's PatternSkin use the favicon feature which most browsers use to show a small icon in front of the URL and for bookmarks.

By default the same favicon is used in all webs and stored in %PUBURLPATH%/%SYSTEMWEB%/ProjectLogos/favicon.ico

You can replace this globally by attaching a favicon to any topic and point to it with a setting in %USERSWEB%.SitePreferences

You can also have a unique favicon for each web by applying similar setting in WebPreferences in each web.

The setting you need must look similar to this

   * Set FAVICON = %PUBURLPATH%/webname/topicname/favicon.ico

WikiUsers topic in Main web

As part of the rebranding from TWiki to Foswiki, the TWikiUsers topic was renamed to WikiUsers but the format is the exact same.

Your Cairo TWikiUsers topic will work in Foswiki but you will need to ensure that these 4 users from the default Foswiki version of WikiUsers are copied to the existing WikiUsers topic. WikiGuest is probably already there but the others are new

Important Changes since TWiki 4.0.5

Supported Perl version

TWiki 4.0.5 worked on Perl version 5.6.X. Reports from users has shown that unfortunately Foswiki does not support Perl versions older then 5.8.0. It is especially the Wysiwyg editor and support for international character sets that requires new features in Perl 5.8.X.

Template spec changed

Until TWiki 4.0.5 SkinTemplates (formerly TWikiTemplates) the text inside template definition blocks (anything between %TMPL:DEF{"block"}% and %TMPL:END% was stripped of leading and trailing white space incl new lines.

This caused a lot of problems for skin developers when you wanted a newline before or after the block text.

From TWiki 4.1.0 and continuing in Foswiki this has changed so that white space is no longer stripped. Skins like PatternSkin and NatSkin have been updated so that they work with the new behavior. But if you use an older skin or have written your own you will most likely need to make some adjustments.

It is not difficult. The general rule is - if you get mysterious blank lines in your skin, the newline after the %TMPL:DEF{"block"}% needs to be removed. Ie. the content of the block must follow on the same line as the TMPL:DEF.

The spec change have the same impact on CommentPlugin templates where you may have to remove the first line break after the TMPL:DEF. See the System.CommentPluginTemplate for examples of how comment template definitions should look like in TWiki-4.1.X

An example: A CommentPlugin template that adds a comment as appending a row to a table. Before the spec change this would work.

<verbatim>
%TMPL:DEF{OUTPUT:tabletest}%%POS:BEFORE%
|%URLPARAM{"comment"}%| -- %WIKIUSERNAME% - %DATE% |
%TMPL:END%
</verbatim>

From Twiki 4.1.0 the old template definition will add an empty line before the new table row. To fix it simply remove the new line before the table.

<verbatim>
%TMPL:DEF{OUTPUT:tabletest}%%POS:BEFORE%|%URLPARAM{"comment"}%| -- %WIKIUSERNAME% - %DATE% |
%TMPL:END%
</verbatim>

The advantage of the spec change is that now you can add leading and trailing white space including new lines. This was not possible before.

Important Changes since TWiki 4.1.0

New location for session and other temporary files

The directory for passthrough files and session files have been replaced by a common directory for temporary files used by Foswiki. Previously the two configure settings {PassthroughDir} and {Sessions}{Dir} were by default set to /tmp. These config settings have been eliminated. Foswiki creates the tmp directory and other temporary directors under the directory defined by the configure setting {WorkingDir}

Important Changes since TWiki 4.1.2

New WYSIWYG Editor

Foswiki now ships with a new WYSIWYG editor based on TinyMCE replaces the Kupu based editor.
TinyMCE is not a perfect Wysiwyg editor but it is magnitudes better than the Kupu editor

The WysiwygPlugin that drives the engine behind both TinyMCE has additionally been heavily improved so that less Foswiki Applications are negatively affected by editing WYSIWYG

When TinyMCEPlugin is enabled the Edit button per default becomes WYSIWYG editing mode. A new Raw Edit link has been added to enable application developers to edit the good old way

The WYSIWYG button has been removed.

NEWTOPICLINKSYMBOL removed

The NEWTOPICLINKSYMBOL preference which was deprecated in TWiki 4.1 has now been removed from the code. If you want to control the appearance of new links, you can use NEWLINKFORMAT.

UserForm and NewUserTemplate Customization

When a new user registers on Foswiki his user topic is created based on the NewUserTemplate and UserForm.

The NewUserTemplate was located in the TWiki web and the UserForm in the Main web. When you earlier upgraded TWiki these were some of the topics you had to take care not to overwrite.

In Foswiki the UserForm and NewUserTemplate are distributed in the System web. If you create the two in the Main web the Main web version will be used instead. So if you tailor the user topic format or the form then you should always copy the two files to the Main web and modify the ones in the Main web. When you later upgrade Foswiki your tailored template and form will not be overwritten.

WikiUsers no longer distributed

The Main.WikiUsers topic contains all the registered users. It is a topic you do not want to overwrite when you upgrade Foswiki.

This file is not included in the Foswiki distribution. When you register the first time Foswiki creates the Main.WikiUsers topic in the Main web if it does not exist already. This means that you can now upgrade Foswiki without risk of overwriting the important WikiUsers topic.

New working directory

A new directory working which per default is located in the twiki root, has been introduced which contains:

Note: Remember to restrict access to this new directory when you upgrade.

The configuration setting {WorkingDir} defines the container directory for temporary files, extensions' work areas, and intermediate registration data. The default is working under your installation root.

Take care for that change if you run your own routine to delete obsolete session files, which will now be found under working/tmp/cgisess*.

New Internal Admin Login

Foswiki has a new Internal Admin Login feature which uses "admin" (configurable) as username and the password used for configure to become temporary administrator. When you do a new installation you need to use this feature as Main.AdminGroup is now access restricted by default to avoid security attacks during the hours an installation may take. From configure there is a link to the AdminGroup topic and on AdminGroup the step by step instructions are written in a yellow box. Our advice is not to remove this help text in case you need it later.


Related Topics: AdminDocumentationCategory, Foswiki:Support.UpgradingFromOlderTWikiReleases, Foswiki:Support.UpgradingFromTWiki4x2Releases, Foswiki:Support.UpgradingPatchReleases, Foswiki:Support.ApacheConfigGenerator, Foswiki:Support.SettingFileAccessRightsLinuxUnix