Reference Manual (v2.0.2)

Step 4: Configure the web server

• See Foswiki:Support.ApacheConfigGenerator.
• This is the easiest and best way to generate a smooth-running and secure configuration file.
• After installing the config file as per your distribution's guidelines, remember to restart or reload Apache each time you edit the file to apply your changes.

• A sample config file called foswiki_httpd_conf.txt can be found in the root of the foswiki installation.
• This is provided in case you can not access the online configuration generator.
• Instructions are provided in the file for tailoring the configuration to you server.
• Be carefull! The configuration shipped with Foswiki is for Apache 2.2 or earlier. Apache 2.4 has changed the syntax of the configuration file. Ensure that mod_access_compat is enabled for backwards compatibility when using Apache 2.4
• As with Method 1, remember to restart or reload Apache each time you edit the file to apply your changes.

• Sample .htaccess files for the Foswiki root and each subdirectory are included in the root of your installation. Each file contains instructions on modifying it for your installation. For more information, see Foswiki:Support.SupplementalDocuments.

General points to keep in mind with any of the above Apache configuration approaches:

• For security purposes, it's important to check that web access is denied to all Foswiki subdirectories other than bin and pub. All three of the approaches described above (Foswiki:Support.ApacheConfigGenerator, the sample foswiki_httpd_conf.txt file included in the distribution, or .htaccess files) should provide for this but it should be confirmed by using web browser to confirm that direct access to the other directories is blocked.
• Also for security purposes, be sure to turn off any kind of PHP, Perl, Python, Server Side Includes, or other software execution mechanisms supported by your web server in the pub directory. Again, the three approaches described above all provide for this. However, different script execution mechanisms are disabled in different ways so refer see your web server configuration and documentation for more details.
• The configuration shipped with Foswiki is for Apache 2.2 or earlier. Apache 2.4 has changed the syntax of the configuration file. Ensure that mod_access_compat is enabled for backwards compatibility when using Apache 2.4, or use the updated Foswiki:Support.ApacheConfigGenerator24 config generator.
• New with Foswiki 2.0 The configure script no longer needs any special protection within the Apache configuration.

Step 5: Bootstrap your configuration

1. Using your web browser, enter the default "view" url for your site. Depending upon your Apache configuration, this might look something like:
   • http://yoursite.com/foswiki/bin/view
   • http://yoursite.com/bin/view
   • http://yoursite.com
     This will Bootstrap your configuration and help Foswiki determine whether or not you are using Short URLs. It also logs you in as a the admin user. Don't close your browser until you've completed the configuration process and registered your first user.
2. Follow the link to configure rendered in the Bootstrap banner. (Do not manually enter the bin/configure URL or Foswiki will not correctly detect the URL configuration).
3. Make any required changes, and save the settings.
   • This will create the initial configuration and end the bootstrap process.
   • Configuration items which may require further attention will be highlighted.
   • Save as soon as possible, especially if your site is exposed. Anyone accessing Foswiki before the configuration has been saved will be granted admin rights.

Step 6: Configure email

1. Select the Mail tab in left bar of confgiure and fill out the following parameters:
   • The {WebMasterEmail} should be set to a valid e-mail address. This will be the From: ID used to send Foswiki Emails and will also appear on webmaster mailto: links.
     If you are running on a *nix server with a configured local mail transport agent, you can try pressing the "auto-configure email" button. If auto-configure succeeds, proceed to the next step, to send a test email. If your server is a Windows server, if auto-configure failed, or you know a local transport agent is not available, continue with the SMTP e-mail configuration:
   • The {SMTP}{MAILHOST} should be set to your e-mail server hostame: ex: smtp.gmail.com
   • On most systems, you will also have to configure {SMTP}{Username} and {SMTP}{Password}. These are used so that Foswiki can sign into the e-mail server for purposes of sending e-mail.
   • Click the "auto-configure email" button. (This can run a long time as Foswiki probes all possible e-mail configurations) This will probe the mail server to discover it's configuration, and will finish the configuration. If all goes well, the settings will have been fine tuned for your e-mail server and e-mail is automatically enabled.
2. Once auto-configure completes, Click the "Send test email" button. located on the {WebMasterEmail} field This will verify if the configuration is correct and able to send mail. If e-mail is enabled, but not functional, you will be unable to register users.
3. Click the Save button in the upper right corner of the configuration page.

Step 7: Check Authentication and Register Yourself

After completing initial installation, you are strongly encouraged to read System.UserAuthentication and Foswiki:Support.UserAuthenticationSupplement for further information about managing users and access controls for your Foswiki site.

Step 8: Establish an Administrator user

The steps outlined below are recommended for initial configuration. You should complete this before closing the browser after the bootstrap process. Once you close the browser you will lose your temporary admin status. Later on, you can review the further notes below regarding about administrators and options to protect configure and consider one of the more restrictive options.

1. Scroll down to the "Administration" section and click on "Add Members" link.
   • If you do not see the Admistration section, then you don't have authorization to change this group. See InstallationGuide#InternalAdmin for instructions on establishing an internal admin user.
2. Enter your WikiName as defined when you registered yourself.
3. Click the Add Member button
4. Return to the AdminGroup by clicking the group name on the confirmation page and look under "Members" to confirm you have been added.

Step 9. Save your configuration!

Congratulations! Your Foswiki Installation is Ready to Use!

Troubleshooting

• Review the System.PerlDependencyReport and sure all dependencies are correctly resolved.
• Run the configure script and ensure you have resolved all errors and are satisfied that you understand any warnings.
  • You can also access the dependency report from the command line:

    cd /path/to/foswiki
    perl tools/dependencies 

• Consult the topics at Foswiki:Support.SupplementalDocuments and Foswiki:Support.AskedQuestions.
• Ask for help on IRC (irc.freenode.net, channel #foswiki). There are often a number of people waiting to help.
• Ask a question in the Foswiki:Support web

Supplemental Information For Installation

System Requirements

Server Requirements

cd /path/to/foswiki
perl tools/dependencies

Specific distribution details

Ubuntu and other Debian derived distributions

RedHat, SuSE, CentOS and other RPM based distributions

Gentoo (ebuild) based distributions

Installation with cpanminus

curl -L http://cpanmin.us | perl - App::cpanminus    (optional - install cpanminus if not available )
cpanm Algorithm::Diff Archive::Tar Authen::SASL CGI CGI::Session Crypt::PasswdMD5 DBI DBD::mysql DBD::Pg DBD::SQLite Digest::SHA Error Encode File::Copy::Recursive HTML::Parser HTML::Tree IO::Socket::IP IO::Socket::SSL JSON Locale::Maketext  Locale::Maketext::Lexicon Locale::Msgfmt LWP version URI

cpanm -l foswikideps Algorithm::Diff Archive::Tar ...   (install libraries into =/home/foswiki/foswikideps=)

# @localPerlLibPath = ( '/path/to/dir', '/path/to/another/dir', );
@localPerlLibPath = ( '/home/foswiki/foswikideps/lib/perl5', );

Client Requirements

• XHTML 1.0 Transitional compliant
• Cookies, if persistent sessions are required
• Javascript, is required for configure, edit save and upload functionality. Foswiki is viewable without javascript.

Uploading the Foswiki distribution to your web server host

• Using the table below, create a directory structure on your host server
• Upload the Foswiki files by FTP (transfer as text except for the image files in pub directory.)
• Note: Don't worry if you are not able to put the lib directory at the same level as the bin directory. You can create this directory elsewhere and configure the bin/setlib.cfg file.

  Foswiki dir:	What it is:	Where to copy:	Example:
  foswiki	start-up pages	root Foswiki dir	/home/smith/public_html/foswiki/
  foswiki/bin	CGI bin	CGI-enabled dir	/home/smith/public_html/foswiki/bin
  foswiki/lib	library files	same level as bin	/home/smith/public_html/foswiki/lib
  foswiki/locale	language files	dir secure from public access	/home/smith/public_html/foswiki/locale
  foswiki/pub	public files	htdoc enabled dir	/home/smith/public_html/foswiki/pub
  foswiki/data	topic data	dir secure from public access	/home/smith/public_html/foswiki/data
  foswiki/templates	web templates	dir secure from public access	/home/smith/public_html/foswiki/templates
  foswiki/tools	Foswiki utlilities	dir secure from public access	/home/smith/public_html/foswiki/tools
  foswiki/working	Temporary and internal files	dir secure from public access	/home/smith/public_html/foswiki/working

About Administrators

Options to Protect the Configure Script

• Option 1 Restrict configure to members of the AdminGroup:
  • This is the default configuration. You don't need to set anything special from within configure.
  • After you save your configuration, be sure to register a user and add them to the AdminGroup before you log out from the initial super admin login. Once you log out, you'll be blocked from any further configure access unless you can log in as a user in the AdminGroup. The default behaviour is that members of the AdminGroup have access to bin/configure

• Option 2 Restrict configure to a defined list of users:
  • Visit the "Security and Authentication" tab, "Access control" sub-tab.
  • Set {FeatureAccess}{Configure} to a list of WikiNames that will be allowed access to configure.
  • This setting overrides use of the AdminGroup, and these users do not have to be members of the AdminGroup.
  • If you want the admin super-user to also have access to configure, you need to include "BaseUserMapping_333" in that list.

• Option 3 Define a "super user" ID and allow it access to configure (This is not recommended)
  • Visit the "Security and Authentication" tab, "Passwords" tab. Enable "Expert" options. Set the {Password} field to a hashed ApacheMD5 encoded password.
  • See #InternalAdmin for more information.

Establishing an internal admin login (optional)

• Setting password from bin/configure interface: The password can be set in configure, in the "Security and Authentication" -> "Passwords" tab. Enter the password in plain text. It will be automatically hashed when saved, and cannot be recovered.
• Setting the password from the command line: The password can also be set via command line configuration tool, using the following command:

  tools/configure -save -set {Password}='adminpass'

• Manually setting admin user in LocalSite.cfg: Follow these steps: ( Caution: This procedure only works for plain ascii passwords, it does not handle international characters.)
  1. Generate the hashed password using the Apache htpasswd tool: (replacing {password} with your password)

     htpasswd -bn  admin {password}

  2. Copy the password hash that's generated. (The part after admin: ex: $apr1$Oc.PLq8V$wslABA3mWXfYT/wH0Hsom0)
  3. Search LocalSite.cfg for $Foswiki::cfg{Password}, Replace the existing line, or if not found, insert a new line in the file, as shown:

     $Foswiki::cfg{Password} = '{password hash}';

User Authentication Options

• Template Login can be set up without any web server configuration, and users can log off without restarting the browser. As the login page is just a Wiki page, you can customize it to suit your needs.
• Apache Login allows you to use any Apache-module based authentication scheme, such as mod_auth_ldap or mod_auth_mysql. However, as your browser is caching your login, you must restart the browser to log out.

Template Login authentication

Enabling Template Login

By default, your Foswiki installation is probably already using TemplateLogin, HtPasswdUser and TopicUserMappingContrib as the default Login, Password and user mapping options.

1. Using configure, Security And Authentication tab
   1. Navigate to the Login tab on the Security and Authentication panel. Select the Foswiki::LoginManager::TemplateLogin login manager.
   2. Navigate to the Passwords tab. Select the appropriate PasswordManager for your system - the default is Foswiki::Users::HtPasswdUser.
      There is an EXPERT configure setting {TemplateLogin}{PreventBrowserRememberingPassword} that you can set to prevent Browsers from remembering username and passwords if you are concerned about public terminal usage.
      There is an EXPERT configure setting {TemplateLogin}{AllowLoginUsingEmailAddress} that you can set to allow users to login using their password system registered e-mail addresses.

Apache Login authentication

Do not use the Apache htpasswd program to modify .htpasswd files generated by Foswiki! htpasswd wipes out e-mail addresses that Foswiki saves in the info fields of this file.

Apache Login is required for Apache-based login methods such as mod_ldap

You can use any Apache authentication module that sets the REMOTE_USER environment variable.

1. Configure Apache Login. Under the Security and Authentication pane on the Login tab in configure:
   1. Select Foswiki::LoginManager::ApacheLogin for {LoginManager}.
   2. Select Foswiki::Users::HtPasswdUser for {PasswordManager}.
   3. Select Foswiki::Users::TopicUserMapping for {UserMappingManager}.
   4. Save your settings.
   5. Configure your Apache settings for HTTP authentication. Use the Foswiki:Support.ApacheConfigGenerator tool or the foswiki/bin-htaccess.txt file to set the following Apache directives on the bin scripts:(This example is for Apache 2.2, there are changes required if using Apache 2.4)

       AuthType Basic
       <FilesMatch "(attach|edit|manage|rename|save|upload|mail|logon|.*auth).*">
       require valid-user
       </FilesMatch>

      You can also refer to the sample foswiki_httpd_conf.txt and bin-htaccess.txt files to see how the appropriate Apache directives are specified.

Testing your authentication configuration:

1. Verify that registration works by registering yourself with the System.UserRegistration topic. If there are problems, try these troubleshooting tips:
   1. Note: If e-mail is enabled in configure, Foswiki will not allow any new registrations unless e-mail is functional. In order to avoid issues, return to the Mail and Proxies, Email Test tab in configure and verify that Foswiki can successfully send e-mail.
   2. If your PasswordManager is HtPasswdUser (the default), check the .htpasswd file is being updated correctly with a new entry. If not, check {Htpasswd}{FileName} is correct (under Security and Authentication on the Password tab in configure), and that the webserver user has write permission.
2. Create a new topic (in Sandbox web for example) to confirm that authentication works.
3. Add users to the Main.AdminGroup. Edit the Main.AdminGroup topic in the Main web to include users that should have administrator status. Read defining adminstrator user(s) for more information.
   This is a very important step, as users in this group can access all topics, independent of Foswiki access controls.

Configuring Foswiki manually (without using the configure page)

$ tools/configure -save

LocalSite.cfg load failed
AUTOCONFIG: Found Bin dir: /var/www/foswiki/distro/core/tools, Script name:
configure using FindBin
AUTOCONFIG: PubDir = /var/www/foswiki/distro/core/pub
AUTOCONFIG: DataDir = /var/www/foswiki/distro/core/data
AUTOCONFIG: WorkingDir = /var/www/foswiki/distro/core/working
AUTOCONFIG: ToolsDir = /var/www/foswiki/distro/core/tools
AUTOCONFIG: TemplateDir = /var/www/foswiki/distro/core/templates
AUTOCONFIG: LocalesDir = /var/www/foswiki/distro/core/locale
AUTOCONFIG: ScriptDir = /var/www/foswiki/distro/core/bin
AUTOCONFIG: Unable to use PlainFileStore: ,v files were found in data or pub,
which indicates this installation is already configured for RCS e.g.
/var/www/foswiki/distro/core/data/WFWeb/WebChanges.txt,v
AUTOCONFIG: Store configured for RcsLite
AUTOCONFIG: {Store}{SearchAlgorithm} set to Forking
AUTOCONFIG: Detected OS UNIX:  DetailedOS: linux
** Enter values for critical configuration items.
** type a new value or hit return to accept the value in brackets.

This is the root of all Foswiki URLs.
For example, =http://myhost.com:123=
(do not include the trailing slash.)

{DefaultUrlHost} (http://localhost): http://myhost.com

This is the 'cgi-bin' part of URLs used to access the Foswiki bin
directory. For example =/foswiki/bin=.
See [[http://foswiki.org/Support/ShorterUrlCookbook][ShorterUrlCookbook]]
for more information on setting up Foswiki to use shorter script URLs.

{ScriptUrlPath} (/foswiki/bin):

...

tools/configure -save -noprompt
tools/configure -save -set {DefaultUrlHost}='http://mysite.com'
tools/configure -save -set {ScriptUrlPath}='/bin'
tools/configure -save -set {ScriptUrlPaths}{view}=''
tools/configure -save -set {PubUrlPath}='/pub'
tools/configure -save -set {Password}='adminpass' 

tools/configure -save -set {WebMasterEmail}='user@email.com'
tools/configure -save -set {SMTP}{MAILHOST}='smtpserver.email.com'
tools/configure -save -set {SMTP}{Username}='userid'
tools/configure -save -set {SMTP}{Password}='password'
tools/configure -save -wizard AutoConfigureEmail -method autoconfigure

tools/configure -check -verbose

tools/configure -search Umask
tools/configure -getcfg {Store}

TWiki Compatibility

Foswiki Upgrade Guide

Overview

Upgrade requirements

• Please review the Foswiki:System.AdminSkillsAssumptions before you upgrade your site.
• Carefully review Foswiki:System.SystemRequirements. Foswiki no longer ships with CPAN libraries. CPAN dependencies must be installed prior to upgrade.
• Before upgrading, a backup of your topics is strongly recommended.
• Once the upgrade has been applied, an existing earlier installation will still be able to read all the topics, but should not be used to write.

Upgrading to a new patch release

If you use the Foswiki PageCaching feature, be sure to refresh the cache after upgrading to a new Foswiki version. Visit your site with the Query parameter ?refresh=all

Upgrade procedure: upgrading to a new major or minor version

1. Before the upgrade
2. Prepare for all upgrade steps.
3. Install the new Foswiki version and configure it with the same settings as the old version.
   
   • Windows server users: Don't forget to rerun tools/rewriteshebang.pl to fix up the Perl locations
4. Install any additional extensions (Plugins) used by your old installation. Make sure to use the latest Foswiki versions.
5. Convert all the non-default webs from the old installation to the new one. (Encoding and Store changes)
6. Convert the users, groups, and site customizations from the old installation to the Main web in the new installation, including all user topics.
7. Apply preferences from the old installation.
8. Apply your site customizations: skin, logos, menu bars, forms for personal information, and so forth.
9. Validate your Wiki applications and other key functionality.
10. Switch your production site from the old installation to the new installation.

• <oldwiki> refers to the directory in which the old installation is located
• <newwiki> refers to the directory in which the new installation is located; it is assumed to be immediately below the root directory of your web server
• <old_users_web> refers to the web in which the user topics are located in the old installation. The default value is the Main web. The web is specified in the Store settings pane of the configure page, in the {UsersWebName} setting (visible when Expert mode is enabled).
• <old_system_web> refers to the web used for documentation and default preferences in the old installation. In Foswiki, the default value is the System web. The web is specified in the Store settings pane of the configure page, in the {SystemWebName} setting (visible when Expert mode is enabled).

Before the upgrade

• Prior to the upgrade, reduce the Expires tags to a short duration, for example 1 hour.
  • Examine your Apache configuration for statements like: ExpiresDefault "access plus 11 days", change it to ExpiresDefault "access plus 1 hour"
• Defer the upgrade until the longest expiration time has passed. If the longest time was 2 weeks, delay the upgrade for 2 weeks.
• Complete the upgrade.
• Once confident that further upgrades, or fallback are not required, restore the original far future expiration.

Prepare for all upgrade steps

• Foswiki:System.ReleaseNotes01x01 if upgrading from a release prior to Foswiki 1.1.9, and
• Foswiki:System.ReleaseNotes01x00 if upgrading from an older release of Foswiki 1.0.x

• The EditTablePlugin has been deprecated and is not shipped with Foswiki 2.0. It is replaced by the EditRowPlugin. If you are upgrading an existing site, and have that plugin installed, only one of EditTablePlugin or EditRowPlugin should be enabled.
• Review the deprecated jQuery javascript plugins. The JQueryPlugin has several changes in available jQuery JavaScript plugins. Determine if any of these will impact your JavaScript enabled topics.

• Previous versions of Foswiki defaulted to iso-8859-1 encoding (The "Latin Alphabet 1, intended for US and Western European languages).
• Foswiki 2.0 defaults to UTF-8 encoding, which provides better support for international character sets.

• Case 1: Your existing site is already using utf-8 encoding. Character set conversion is not needed. Proceed to chosing your store.
• Case 2: Your existing site uses the default iso-8859-1 or any other common encoding. All topics are consistent with this encoding. You have two options:
  1. Recommended, use the bulk_copy.pl script to migrate your existing 1.1.x store over to Foswiki 2.0. Each topic will be converted from the 1.1.x {Site}{CharSet} encoding to the 2.0 {Store}{Encoding}. We recommend you leave 2.0 {Store}{Encoding} as undefined (utf-8). or
  2. Set the 2.0 {Store}{Encoding} to match your 1.1.x {Site}{Encoding} and copy the data into Foswiki 2.0 unmodified.
• Case 3: Your site contains a mix of encodings. This can happen if users manually paste in encoded data into topics, or topics are created / modified external to Foswiki.
  • In this case, any topics with unusual encodings will display corrupted. Use Foswiki:Extensions.CharsetConverterContrib to modify the character encoding of your Foswiki 1.1.x system in place. Changes in character encoding must be done using the RCS based store. When this tool is run with the -r (repair) option, the tool attempts to detect the encoding and can convert individual topics based upon their content. This is rather unpredictable and may require manual intervention.
  • We *strongly recommend that a backup be taken before attempting to use the CharsetConverterContrib. As it modifies topics and attachments in-place, it can cause damage and data loss. The recommended bulk_copy.pl script does not modify existing topics.
  • Note that it's possible that some data cannot be cleanly converted, for ex, if the Charset encoding was changed, so that different topic revisions use different encoding. In this case you may need to remove the topic history.

• RcsStoreContrib is compatible with topics created in prior versions of Foswiki.
• PlainFileStoreContrib requires that topic histories be converted to a new history format. This can be done at the same time you convert the character set. perl -I lib tools/bulk_copy.pl --help for more information on conversion.

• Empty DENYTOPICxxxx rules are deprecated They are disabled by default. We recommend converting any existing rules into    * Set ALLOWTOPICxxxx = * wildcard allow rules. Use perl tools/convertTopicSettings.pl -help for further information on the conversion process.

Installation

• For public or otherwise sensitive installations, ensure that your web server configuration is set to deny access to the new Foswiki installation for anyone except you.
• Configure Foswiki using the configure page.
  • (Not recommended!) If you are upgrading from an older Foswiki release, first copy your <oldwiki>/lib/LocalSite.cfg file to <newwiki>/lib/LocalSite.cfg in order to preserve your existing configuration settings (Not recommended). Alternatively, you can reconfigure the new installation from scratch (you can use your old LocalSite.cfg file as a reference).
  • Verify all of the configuration settings on the configure page, including any new settings added in the new version. Save the configuration after you have completed your changes.
  • To wipe out all your settings and start configuring from a fresh installation, just delete the <newwiki>/lib/LocalSite.cfg file and visit your default view URL. From there follow the link to configure.
• Additional resources
  • Foswiki:System.InstallationGuide
  • Foswiki:Support.InstallingOnSpecificPlatforms
  • Foswiki:Support.ApacheConfigGenerator
  • Foswiki:Support.SettingFileAccessRightsLinuxUnix
  • Foswiki:Support.UpgradingFromOlderTWikiReleases - upgrading TWiki from older TWiki releases

Caution: If you intend to copy data from an older installation without using bulk_copy.pl to change Stores, you should select the RcsStoreContrib in the configuration. Once topic history has been created with the wrong store, it has to either be removed, or old data should be migrated with bulk_copy.pl. If Foswiki encounters mixed RCS and PlainFile topic history, it will "die" to prevent topic history corruption.

Install extensions

• CommentPlugin - DEFAULT_TYPE
• EditTablePlugin Deprecated! Replaced with EditRowPlugin - CHANGEROWS, QUIETSAVE, EDITBUTTON
• InterwikiPlugin - RULESTOPIC
• InterWikis - If you added your own rules, make sure you copy over the rules to the new installation. Use of a local rules topic is the preferred way to customize the links.
• SlideShowPlugin - If you changed the embedded 'Default Slide Template', then copy your customized template to the topic in the new installation. You should prefer creating your own slide show template in a separate topic, so you will not have to take special steps over upgrades to preserve your modifications to the default slide template.
• SmiliesPlugin - If you added your own smileys, make sure you copy over your customizations to the topic in the new installatin.
• TablePlugin - TABLEATTRIBUTES

Copy parts of the working directory

Copy the data using tools/bulk_copy.pl

• Existing: /var/www/f119
• New: /var/www/f120

cd /var/www/f120/tools
perl bulk_copy.pl --xweb System --xweb _default --xweb _empty --latest '*.WebStatistics' /var/www/f119/bin /var/www/f120/bin

• Stay on the RCS style store
• Use CharsetConverterContrib to change encoding if desired.

Manual copy steps (not recommended)

Content should be copied using the tools/bulk_copy.pl script. This will allow conversion to utf-8 and the PlainFile Store. Only proceed with this step if you will be remaining on the RCS store with your existing character encoding.

Copy content from non-default webs in old installation to the new installation

Be sure to select an "RCS Store" RcsWrap or RcsLite on the new installation. The PlainFile store is not compatible with topic history written on previous versions of Foswiki. If you have created or updated topics using PlainFileStore, you should either start over, or plan to to remove all ,pfv directories from the system so that there is no history in the PlainFileStore format.

Copy your local webs over to the data and pub directories of the new installation. Do not copy the default webs: <old_system_web> System, Main, Trash, Sandbox, _default, and _empty.

• Make sure the data and pub directories, as well as the files within them, are readable and writeable by the web server user.
• Note: Foswiki's WebChanges topics depend on the file timestamp. If you touch the .txt files make sure to preserve the timestamp, or change them in the same chronological order as the old file timestamps.

Verify that existing topics are operational and (if you converted to UTF-8) that any international characters have been properly converted and are displayed correctly.

Copy users, user topics, and site customizations to Main web

Copy all topics and attachments from <old_users_web>: copy all files from <oldwiki>/data/<old_users_web>/ to <newwiki>/data/Main/, and copy all files from <oldwiki>/pub/<old_users_web>/ to <newwiki>/pub/Main/ . Do not overwrite any topics already present in the <newwiki>/data/Main/ directory.

• In addition to all the user topics, if you have created <old_users_web>.NewUserTemplate in the old installation, this step will copy over your template for user topics to the new installation.
• Ensure that the topic defining the admin group in your old installation is copied over. The admin group is defined in the Security setup pane of the configure page, in the {SuperAdminGroup} setting (visible when Expert mode is enabled). You can do either of the following:
  • Set the {SuperAdminGroup} setting in your new installation to the old admin group.
  • Move the contents of the old admin group to the new admin group. To avoid having to change all references to the old admin group, you must still keep the old admin group defined: set it so its only member is the new admin group, and the new admin group is the only user who can change or rename the old admin group topic.
• If your old installation did not customize {LocalSitePreferences} on the configure page, or if you did customize {LocalSitePreferences} but kept your site preferences within the <old_users_web> web, then this step will also copy over your site preferences to the new installation.

For upgrades from an older Foswiki installation:

• Manually merge all users from the <old_users_web>.WikiUsers topic in the old installation to the Main.WikiUsers topic in the new installation. If the new installation does not yet have an initial Main.WikiUsers topic, then copy <oldwiki>/data/<old_users_web>/WikiUsers.txt to <newwiki>/data/Main/WikiUsers.txt.
• Verify that the following default users are present in the Main.WikiUsers topic:
  • ProjectContributor - the Foswiki documentation is attributed to this user
  • RegistrationAgent - special user used during the new user registration process
  • UnknownUser - used where the author of a previously stored piece of data can't be determined
  • WikiGuest - guest user; used as a fallback if the user can't be identified
• If any of the default users are missing, then add them in manually to Main.WikiUsers, using the corresponding entries in Foswiki:System.UsersTemplate as an example.
• If you use data/.htpasswd for authentication, copy this file from the old installation to the new one.
• If you have customized <old_system_web>.UserRegistration, then either copy over <oldwiki>/data/<old_system_web>/UserRegistration.txt and <oldwiki>/data/<old_system_web>/UserRegistration.txt,v to the <newwiki>/data/System/ directory, or modify System.UserRegistration in the new installation to contain your customizations.

Copy over any topics and attachments you want to preserve from the Sandbox web in the old installation: copy the desired files from <oldwiki>/data/Sandbox/ to <newwiki>/data/Sandbox and from <oldwiki>/pub/Sandbox/ to <newwiki>/pub/Sandbox . Some pages you may wish to preserve are the WebHome topic and the WebLeftBar topic (if you had created it in the old wiki installation). The Sandbox web often contains work-in-progress topics that users will want to keep.

Make sure the data and pub directories, as well as the files within them, are readable and writeable by the web server user.

Convert empty DENY ACLs to ALLOW * wildcards

Get help text for convertTopicSettings

perl tools/convertTopicSettings.pl -help

Scan all webs / topics, report any topics with empty DENY rules

perl tools/convertTopicSettings.pl

Replace all empty DENY rules with ALLOW * wildcards

perl tools/convertTopicSettings.pl -fixdeny -update

Same, but convert all ACLs into META settings from inline topic settings, for just the Sandbox web

perl tools/convertTopicSettings.pl -fixdeny -convert -update Sandbox

Convert ALL settings into META settings, not just ACLs, for the Sandbox and Customer webs

perl tools/convertTopicSettings.pl -fixdeny -convert -all -update Sandbox Customer

Apply preferences from old installation

Apply additional site customizations

Modify skin with customizations for your site

Customize pages for managing personal information

• System.ChangePassword
• System.ResetPassword
• System.ChangeEmailAddress

Validate your Wiki applications and other key functionality

Switch your production site from the old installation to the new installation

• Copy content from non-default webs in old installation to the new installation".
• Copy extension operational information from working, to the new installation

• You can rename your <newwiki>/ directory to wiki/ (renaming the directory of your old installation if necessary).
• If your operating system supports links to other directories and your web server is configured to follow links, then you can create a link called wiki/ that points to <newwiki>/ (renaming the directory of your old installation if necessary).
• You can configure your web server so that requests to /wiki/ are served from your <newwiki>/ directory.

User Authentication

Overview

• You are guest, WikiGuest,

Password Management

The default Password Manager, HtPasswdUser

Caution: By default Foswiki uses the .htpasswd file to also store the e-mail addresses of registered users. If the .htpasswd file will be shared with another application, it is critical to preserve the e-mail address stored as the last field in each line of the file.

Changing Passwords (and Email Addresses)

• The ChangePassword form ( Foswiki/ChangePassword )
• The ResetPassword form ( Foswiki/ResetPassword )

• The ChangeEmailAddress form ( Foswiki/ChangeEmailAddress )

User Mapping

The default User Mapping Manager, TopicUserMapping

User Registration

• new user verification
• optional new user approval
• single user registration via the UserRegistration page,
• bulk user registration via the BulkRegistration page (for admins only).

Custom registration page

• The first FORMAT macro is used expand the blocks that define the main body of the page.
• Further down is a block %FORMAT{ ... In that block you can enable other optional fields, such as group membership, country, organization, etc.

%SHOWPREFERENCE{"DENYWEBVIEW,ALLOWWEBVIEW,DENYWEBCHANGE,ALLOWWEBCHANGE,DENYWEBRENAME,ALLOWWEBRENAME"}%

• Set DENYWEBVIEW = ""
• Set ALLOWWEBVIEW = ""
• Set DENYWEBCHANGE = ""
• Set ALLOWWEBCHANGE = "%USERSWEB%.AdminGroup"
  • ALLOWWEBCHANGE was defined in System.WebPreferences
• Set DENYWEBRENAME = ""
• Set ALLOWWEBRENAME = "%USERSWEB%.AdminGroup"
  • ALLOWWEBRENAME was defined in System.WebPreferences

Hide control settings

<!-- 

 * Set DENYTOPICCHANGE = Main.SomeGroup 

-->

Formatting Command:	You write:	You get:
Paragraphs: Blank lines will create new paragraphs.	1st paragraph 2nd paragraph	1st paragraph 2nd paragraph
Headings: Three or more dashes at the beginning of a line, followed by plus signs and the heading text. One plus creates a top level heading, two pluses a second level heading, etc. The maximum heading depth is 6. You can create a table of contents with the %TOC% macro. If you want to exclude a heading from the TOC, put !! after the ---+. Empty headings are allowed, but won't appear in the table of contents. See the <ho> tag below for how to adjust heading levels dynamically.	---++ Sushi ---+++ Maguro ---+++!! Not in TOC	Sushi Maguro Not in TOC
Bold Text: Words get shown in bold by enclosing them in * asterisks.	*Bold*	Bold
Italic Text: Words get shown in italic by enclosing them in _ underscores.	_Italic_	Italic
Bold Italic: Words get shown in bold italic by enclosing them in __ double-underscores.	__Bold italic__	Bold italic
Fixed Font: Words get shown in fixed font by enclosing them in = equal signs.	=Fixed font=	Fixed font
Bold Fixed Font: Words get shown in bold fixed font by enclosing them in == double equal signs.	==Bold fixed==	Bold fixed
You can follow the closing bold, italic, or other (* _ __ = ==) indicator with normal punctuation, such as commas and full stops. Make sure there is no space between the text and the indicators.	_This works_, _this does not _	This works, _this does not _
Separator (Horizontal Rule): Three or more three dashes at the beginning of a line..	---
Bulleted List: Multiple of three spaces, an asterisk, and another space. For all the list types, you can break a list item over several lines by indenting lines after the first one by at least 3 spaces.	* level 1 * level 2 * back on 1 * A bullet broken over three lines * last bullet	level 1 level 2 back on 1 A bullet broken over three lines last bullet
Numbered List: Multiple of three spaces, a type character, a dot, and another space. Several types are available besides a number: Type Generated Style Sample Sequence 1. Arabic numerals 1, 2, 3, 4... A. Uppercase letters A, B, C, D... a. Lowercase letters a, b, c, d... I. Uppercase Roman Numerals I, II, III, IV... i. Lowercase Roman Numerals i, ii, iii, iv... Note that while type characters A, a, I and i must be entered exactly as specified, numbers can be any single digit 0-9. It is recommended for future compatibility that only the number 1 be used for numbered type lists.	1. Sushi 1. Dim Sum 1. Fondue A. Sushi A. Dim Sum A. Fondue i. Sushi i. Dim Sum i. Fondue	Sushi Dim Sum Fondue Sushi Dim Sum Fondue Sushi Dim Sum Fondue
Definition List: Three spaces, a dollar sign, the term, a colon, a space, followed by the definition.	$ Sushi: Japan $ Dim Sum: S.F.	Sushi Japan Dim Sum S.F.
Definition List: (deprecated) Three spaces, the term (a single word, no spaces), a colon, a space, followed by the definition.	Sushi: Japan Dim-Sum: S.F.	Sushi Japan Dim-Sum S.F.
Indented Text: Three spaces, a colon, a space, followed by the paragraph. Continue a paragraph by indenting the line with 3 spaces. Create deeper levels of indentation by using multiples of 3 spaces.	: Indented line Continued : New paragraph : 2nd level indent	Indented line Continued New paragraph 2nd level indent
Table: Each row of the table is a line containing of one or more cells. Each cell starts and ends with a vertical bar '|'. Any spaces at the beginning of a line are ignored. | *bold* | header cell with text in asterisks |   center-aligned   | cell with at least two, and equal number of spaces on either side |      right-aligned | cell with more spaces on the left | 2 colspan || and multi-span columns with multiple |'s right next to each other |^| cell with caret indicating follow-up row of multi-span rows You can split rows over multiple lines by putting a backslash '\' at the end of each line Contents of table cells wrap automatically as determined by the browser Use %VBAR% or &#124; to add | characters in tables. Use %CARET% or &#94; to add ^ characters in tables. The TablePlugin provides the |^| multiple-span row functionality and additional rendering features	| *L* | *C* | *R* | | A2 | B2 | C2 | | A3 | B3 | C3 | | multi span ||| | A5-7 | 5 | 5 | |^| six | six | |^| seven | seven | | split\ | over\ | 3 lines | | A9 | B9 | C9 | | %CARET% | B10 |%VBAR%| | &#94; | B11 |&#124;|	L C R A2 B2 C2 A3 B3 C3 multi span A5-7 5 5 six six seven seven split over 3 lines A9 B9 C9 ^ B10 | ^ B11 |
WikiWord Links: CapitalizedWordsStuckTogether (or WikiWords) will produce a link automatically if preceded by whitespace or parenthesis. If you want to link to a topic in a different web write Otherweb.TopicName. To link to a topic in a subweb write Otherweb.Subweb.TopicName. The link label excludes the name of the web, e.g. only the topic name is shown. As an exception, the name of the web is shown for the WebHome topic. Dots '.' are used to separate webs and subwebs from topic names and therefore cannot be used in topic names. It's generally a good idea to use the macros %SYSTEMWEB%, %SANDBOXWEB% and %USERSWEB% instead of System, Sandbox and Main. To prevent a word from linking, prefix it with the exclaimation mark (!) or <nop>	%STATISTICSTOPIC% %SANDBOXWEB%.WebNotify %SANDBOXWEB%.%HOMETOPIC% %SANDBOXWEB%.Subweb.TopicName	WebStatistics WebNotify Sandbox TopicName
Acronym Links: Words that are all capitals will produce a link automatically only if the topic already exists!.	ACRONYM %SYSTEMWEB%.ACRONYM	ACRONYM ACRONYM
Anchors: You can define a reference inside a topic (called an anchor name) and link to that. To define an anchor write #AnchorName at the beginning of a line. The anchor name must be a WikiWord of no more than 32 characters. To link to an anchor name use the [[MyTopic#MyAnchor]] syntax. You can omit the topic name if you want to link within the same topic.	[[WikiWord#NotThere]] [[#MyAnchor][Jump]] #MyAnchor To here	WikiWord#NotThere Jump To here
Forced Links: You can create a forced internal link by enclosing words in double square brackets. Text within the brackets may contain optional spaces; the topic name is formed by capitalizing the initial letter and by removing the spaces; for example, [[wiki word]] links to topic WikiWord. You can also refer to a different web and use anchors. To "escape" double square brackets that would otherwise make a link, prefix the leading left square bracket with an exclamation point.	[[wiki syntax]] [[Main.Wiki groups]] escaped: ![[wiki syntax]]	wiki syntax Main.Wiki groups escaped: [[wiki syntax]]
Renamed Links: You can create a link where you specify the link text and the URL separately using nested square brackets [[reference][text]]. Internal link references (e.g. WikiWord) and URLs (e.g. http://foswiki.org/) are both supported. The rules described under Forced Links apply for internal link references. Anchor names can be added as well, to create a link to a specific place in a topic.	[[WikiWord][wiki word]] [[http://gnu.org][GNU]]	wiki word GNU
Automatic links: Typed-in URLs are linked automatically. Most standard protocols are supported; if yours is missing, it can be added by the site administrator. URLs for images are automatically inserted inline. Email addresses are also linked automatically, see further details below. automatic linking of URLs and email addresses is not blocked by the noautolink setting.	* file://foswiki.org * ftp://foswiki.org * https://foswiki.org * http://foswiki.org * mailto:example@foswiki.org * news://foswiki.org * nntp://foswiki.org * telnet://foswiki.org * name@foswiki.org * %PUBURL%/%SYSTEMWEB%/ProjectLogos/foswiki-logo-icon.png	file://foswiki.org ftp://foswiki.org https://foswiki.org http://foswiki.org mailto:example@foswikiANTISPAM.org news://foswiki.org nntp://foswiki.org telnet://foswiki.org name@foswikiANTISPAM.org
Prevent an Automatic Link: Prevent a WikiWord, URL, email address or image from being linked by prepending it with an exclamation point (!) or <nop> tag. Note that you can use the <nop> tag, but any leading markup directly adjacent to a wikiword will prevent automatic linking because the word is no longer space delimitied.	!SunOS <nop>SomeWiki <b>SomeWiki</b> =SomeWiki= <b>http://foswiki.org</b> _%PUBURL%/%SYSTEMWEB%/ProjectLogos/foswiki-logo-icon.png_	SunOS SomeWiki SomeWiki SomeWiki http://foswiki.org http://141.244.188.169/foswiki/pub/System/ProjectLogos/foswiki-logo-icon.png
Disable Automatic Linking: You can disable automatic linking of WikiWords by surrounding text with <noautolink> and </noautolink> tags. You can also turn off WikiWord auto-linking with the NOAUTOLINK preference setting. The noautolink feature only applies to WikiWords. It does not stop linking of URLs, or email addresses.	<noautolink> RedHat & SuSE </noautolink>	RedHat & SuSE
Mailto Links: E-mail addresses are linked automatically. To create e-mail links that have more descriptive link text, specify subject lines or message bodies, or omit the e-mail address, you can write [[mailto:user@domain][descriptive text]]. automatic linking of email addresses is not blocked by <noautolink>, Escape with a ! to prevent auto linking.	a@b.com [[mailto:a@b.com][Mail]] [[mailto:?subject=Hi][Hi]] !a@b.com	a@bANTISPAM.com Mail Hi a@b.com
Special characters: Some characters are reserved for use by TML Display them in your output by using the HTML entities. Use HTML entities to display characters that are not supported by your site character set (e.g. special mathematical symbols). There's a complete list of named entities in Wikipedia Use numerical entities to display any unicode character (e.g. Chinese script). To prevent Foswiki from treating ! as an escape, escape it with <nop>, or use the &#33; entity	&lt; &gt; &amp; &alefsym; &#x4eb9; A <nop>!= B &#33;= C <nop>!here, !here	< > & ℵ 亹 A != B != C !here, here
Escaping Macros Prevent a Macro from being expanded by prepending it with an exclamation point. To expand the macro, but escape any wikiword it expands into, use the <nop> tag.	&#37;TOPIC% <nop>%TOPIC%	%TOPIC% EditingShorthand
Controlling how content is rendered: There are 3 ways to control how your topic content is rendered. This is done with three HTML or pseudo-HTML tags: <literal>, <verbatim> and <pre> They control whether or not: Wiki markup (TML) is rendered Macros (ex: %TOPIC%) are expanded HTML is rendered White space preserved Auto linking of WikiWords and Email addresses occurs These are explained in more details in the next sections, but are summarized to the right:	TML HTML Macros White Space Auto Link WikiWord Auto Link Email <verbatim> <literal> <pre> <noautolink>
Literal content: Foswiki generates HTML code from TML shorthand. Experts surround anything that must be output literally in the HTML code, without the application of shorthand rules, with <literal>..</literal> tags. Any HTML within literal tags must be well formed i.e. all tags must be properly closed before the end of the literal block. Macros are expanded within literal blocks.	<literal> | Not | A | Table | </literal>	| Not | A | Table |
Verbatim (Literal) Text: Surround code excerpts and other formatted text with <verbatim> and </verbatim> tags. verbatim tags disable HTML code. Use <pre> and </pre> tags instead if you want the HTML code within the tags to be interpreted. Preferences settings (* Set NAME = value) are set within verbatim tags.	<verbatim> class CatAnimal { void purr() { <code here> } } </verbatim>	class CatAnimal { void purr() { <code here> } }
Verbatim (Literal) Code Highlighting: Surround code excerpts and other formatted text e.g. with <verbatim class="bash"> and </verbatim> tags. This type of code highlighting is based on Chili - the jQuery code highlighter plugin. Please find supported class attributes in JQueryChili. verbatim tags disable HTML code. Use <pre class="bash"> and </pre> tags instead if you want the HTML code within the tags to be interpreted. Preferences settings (* Set NAME = value) are set within verbatim tags.	<verbatim class="bash"> #!/bin/bash while [ -n "$(ls . ~/ \ ~/pub* /var/www 2>/dev/null \ | fgrep foswiki )" ] ; do clear printf "\nFoswiki rules!\n" sleep 10 clear printf "\nFoswiki still rules!\n" sleep 10 done; exit 0 </verbatim>	#!/bin/bash while [ -n "$(ls . ~/ \ ~/pub* /var/www 2>/dev/null \ | fgrep foswiki )" ] ; do clear printf "\nFoswiki rules!\n" sleep 10 clear printf "\nFoswiki still rules!\n" sleep 10 done; exit 0
Protected content: Experts protect text from mangling by WYSIWYG editors using <sticky>..</sticky> tags. Sticky tags don't have any effect on normal topic display; they are only relevant when content has to be protected from a WYSIWYG editor (usually because it isn't well-formed HTML, or because it is HTML that WYSIWYG would normally filter out or modify). Protected content appears as plain text in the WYSIWYG editor. Any HTML within sticky tags must be well formed i.e. all tags must be properly closed before the end of the sticky block. Macros are expanded within sticky blocks.	<sticky> <div> This div %RED%is%ENDCOLOR% required </div> </sticky>	This div is required
Adjust heading levels: You can adjust heading levels for headings generated using ---+ markup and also HTML <h> tags using the <ho> tag. The %INCLUDE and %SEARCH macros also have a headingoffset parameter to do this for you in included content. Heading levels are limited to the range 1..6 after any offset is applied.	---++ offset is 0 <ho off="1"> ---++ H2 becomes H3 <ho off="-1"> ---++ offset was 1, so offset is now 0	offset is 0 H2 becomes H3 offset was 1, so offset is now 0

Macros

%MACRONAME%
%MACRONAME{ parameter="value" }%

1. Preference settings: May be defined and modified by the user
2. Registered macros: Defined by the system or by Plugins (for example, the SpreadSheetPlugin introduces a %CALC{}% macro)

Using Macros

• type %T% to get (a predefined preference setting)
• type %TOPIC% to get Macros (a predefined macro)
• type %CALC{ "$UPPER(Text)" }% to get TEXT (CALC is a macro defined by SpreadSheetPlugin)

• To leave a macro unexpanded, precede it with an exclamation mark, e.g. type !%TOPIC% to get %TOPIC%
  • Alternatively, insert a <nop> anywhere in the macro, Eg. %<nop>TOPIC%
• Macros are expanded relative to the topic they are used in, not the topic they are defined in
• Type %ALLVARIABLES% to get a full listing of all macros defined for a particular topic
• If a macro is not defined, then it will be left in the text unless it is called with a default parameter, in which case the value of the default parameter will replace the macro call in the output. For example, %UNDEFINED{default="blank"}% will expand to blank.

Order of expansion

• Preference settings
• Most macros provided by plugins (notable exceptions include CALC, TABLE and any other macros that are expanded in commonTagsHandler())
• Most built-in Foswiki macros (exceptions include TOC and macros that have start/stop parts e.g: STARTSECTION/ENDSECTION, STARTINCLUDE/STOPINCLUDE)

Standard form

%MACRO1{
   something="%MACRO2{
      somethingelse="%MACRO3%, %MACRO4%"
   }%"
}%

Step-by-Step Example

%INCLUDE{
    "%QUERY{
        "'%THETOPIC%'/%THEFIELD%"
    }%"
    section="Summary"
}%
   * Set THETOPIC = %SYSTEMWEB%.FAQWhatIsWikiWiki
   * Set THEFIELD = TopicClassification

%INCLUDE{
    "%QUERY{
        "'%SYSTEMWEB%.FAQWhatIsWikiWiki'/%THEFIELD%"
    }%"
    section="Summary"
}%
   * Set THETOPIC = %SYSTEMWEB%.FAQWhatIsWikiWiki
   * Set THEFIELD = TopicClassification

%INCLUDE{
    "%QUERY{
        "'%SYSTEMWEB%.FAQWhatIsWikiWiki'/TopicClassification"
    }%"
    section="Summary"
}%
   * Set THETOPIC = %SYSTEMWEB%.FAQWhatIsWikiWiki
   * Set THEFIELD = TopicClassification

%INCLUDE{
    "%QUERY{
        "'System.FAQWhatIsWikiWiki'/TopicClassification"
    }%"
    section="Summary"
}%
   * Set THETOPIC = %SYSTEMWEB%.FAQWhatIsWikiWiki
   * Set THEFIELD = TopicClassification

%INCLUDE{
    "FrequentlyAskedQuestion"
    section="Summary"
}%
   * Set THETOPIC = %SYSTEMWEB%.FAQWhatIsWikiWiki
   * Set THEFIELD = TopicClassification

These topics are for frequently
asked questions including answers.

   * Set THETOPIC = %SYSTEMWEB%.FAQWhatIsWikiWiki
   * Set THEFIELD = TopicClassification

These topics are for frequently
asked questions including answers.

   * Set THETOPIC = System.FAQWhatIsWikiWiki
   * Set THEFIELD = TopicClassification

Delayed form

When working with a given macro, consult its documentation to determine which parameters support the $percent/$percnt format tokens. Generally only output parameters like header, format and footer support format tokens.

%MACRO1{
   format="$percentMACRO2{
      format=\"%MACRO3%, %MACRO4%\"
   }$percent"
}%

Step-by-Step Example

Step 1

%SEARCH{
  "info.date >= d2n('2009-01-01') AND info.date <= d2n('2009-12-31')"
  type="query"
  limit="2"
  nonoise="on"
  format="   * $percentICON{
    \"$percentIF{
      \"'$topic'/parent.name='%PARENT%'\"
      then=\"info\" else=\"gear\"
    }$percent\"
  }$percent [[$topic]]"
}%
----
   * Set PARENT = UserDocumentationCategory

Step 2

%SEARCH{
  "info.date >= d2n('2009-01-01') AND info.date <= d2n('2009-12-31')"
  type="query"
  limit="2"
  nonoise="on"
  format="   * $percentICON{
    \"$percentIF{
      \"'$topic'/parent.name='UserDocumentationCategory'\"
      then=\"info\" else=\"gear\"
    }$percent\"
  }$percent [[$topic]]"
}%
----
   * Set PARENT = UserDocumentationCategory

Step 3

<pre class="tml">
%SEARCH{
  "info.date >= d2n('2009-01-01') AND info.date <= d2n('2009-12-31')"
  type="query"
  limit="2"
  nonoise="on"
  format="   * $percent<nop>ICON{
    \"$percent<nop>IF{
      \"'$topic'/parent.name='UserDocumentationCategory'\"
      then=\"info\" else=\"gear\"
    }$percent\"
  }$percent [[$topic]]"
}%
----
   * Set PARENT = UserDocumentationCategory
</pre>

Step 4

<pre class="tml">
%SEARCH{
  "info.date >= d2n('2009-01-01') AND info.date <= d2n('2009-12-31')"
  type="query"
  limit="2"
  nonoise="on"
  format="   * $percent<nop>ICON{
    \"$percentIF{
      \"'$topic'/parent.name='UserDocumentationCategory'\"
      then=\"info\" else=\"gear\"
    }$percent\"
  }$percent [[$topic]]"
}%
----
   * Set PARENT = UserDocumentationCategory
</pre>

Step 5

<pre class="tml">
%SEARCH{
  "info.date >= d2n('2009-01-01') AND info.date <= d2n('2009-12-31')"
  type="query"
  limit="2"
  nonoise="on"
  format="   * &lt;img src=\"$percentICONURL{
    \"$percentIF{
      \"'$topic'/parent.name='UserDocumentationCategory'\"
      then=\"info\" else=\"gear\"
    }$percent\"
  }$percent\"/&gt; [[$topic]]"
}%
----
   * Set PARENT = UserDocumentationCategory
</pre>

Macro Names

Preference Settings

[multiple of 3 spaces] * [space] Set [space] MACRONAME [space] = [space] value

Example:

   * Set WEBBGCOLOR = #FFFFC0

1. DefaultPreferences (Foswiki upgrades overwrite this topic)
2. In (some) plugin documentation topics. (Deprecated)
3. SitePreferences
4. In user topics, if the user has one (yours is Main.WikiGuest)
5. WebPreferences in each web.
6. Sub-webs inherit the WebPreferences of their parent
7. In the topic being accessed

Writing preference settings

   * Set MYSETTING = My setting value

   * Set MACRONAME = value starts here
     and continues here

• To place a logo anywhere in a web by typing %MYLOGO%, define the preference settings in the web's WebPreferences topic, and upload a logo file, ex: mylogo.gif. You can upload by attaching the file to WebPreferences, or, to avoid clutter, to any other topic in the same web, e.g. LogoTopic. Sample preference setting in WebPreferences:

   * Set MYLOGO = %PUBURL%/%WEB%/LogoTopic/mylogo.gif

   * Set lower = This is LOWER
   * Set LOWER = This is UPPER
   * Set LoWeR = This is MIXED
Expand %lower%, %LOWER% and %LoWeR%

   * #Set DENYWEBCHANGE = %USERSWEB%.UnknownUser

Hiding preference settings

<!--
   * Set HIDDEN = This will be invisible in the output
-->

Caution If your topic will be used in an INCLUDE, it is recommended to not use HTML comments. instead, set preferences into the topic metadata by using the "Edit Settings for this topic" button on the "More topic actions" page. Settings in an included topic are always ignored, but nested comments will break the HTML.

Order of preference settings

Preference settings and topic revision history

Parameters

   * Set CONDITIONS = According to [[%BASETOPIC%]] the %WHAT% is %STATE% today (Set in ...).

• %CONDITIONS{WHAT="sea" STATE="choppy"}%
  • expands to %CONDITIONS{WHAT="sea" STATE="choppy"}%.

Parameter defaults

• The special parameter name DEFAULT gets the value of any unnamed parameter in the macro call.
• Parameter macros can accept a default parameter so that they expand to something even when a value isn't passed for them in the call.

   * Set WEATHER = It's %DEFAULT{default="raining"}%.

• %WEATHER% expands to %WEATHER%
• %WEATHER{"sunny"}% expands to %WEATHER{"sunny"}%

Access Control Settings

Local values for preferences

   * Set EDITBOXHEIGHT = 10
   * Local EDITBOXHEIGHT = 20

Predefined Macros

Predefined macros can be overridden by preference settings (except TOPIC and WEB)

Plugins may extend the set of predefined macros (see individual Plugins topics for details)

Take the time to thoroughly read through ALL preference macros. If you actively configure your site, review macros periodically. They cover a wide range of functions, and it can be easy to miss the one perfect macro for something you have in mind. For example, see %BASETOPIC%, %INCLUDE%, and the mighty %SEARCH%.

ACTIVATEDPLUGINS -- list of currently activated plugins

Examples

• %ACTIVATEDPLUGINS% expands to SpreadSheetPlugin, SlideShowPlugin, AutoViewTemplatePlugin, CalendarPlugin, CommentPlugin, CompareRevisionsAddonPlugin, ConfigurePlugin, EditRowPlugin, HistoryPlugin, HomePagePlugin, ImportExportPlugin, InterwikiPlugin, JQueryPlugin, MailerContribPlugin, NatEditPlugin, PreferencesPlugin, RenderListPlugin, SmiliesPlugin, SubscribePlugin, TablePlugin, TinyMCEPlugin, TwistyPlugin, UpdatesPlugin, WysiwygPlugin

ADDTOZONE -- add content to a named zone on the page

Parameters

Parameter	Description	Default
"zone"	comma-separated list of the names of zones that the content should be added to. The only zones guaranteed to exist are head and script	head
id	identifier for the text being added with the ADDTOZONE call, to be used in the requires parameter of other ADDTOZONE calls. Multiple ADDTOZONE calls with the same id parameter will simply overwrite the earlier ADDTOZONE call.
requires	comma separated string of ids of text within this zone that this content should follow when the zone is rendered. The content will be rendered even if a specified id is missing.
text	text to be added to the named zone, mutually exclusive with topic.
topic	full qualified web.topic name that contains the text to be added, mutually exclusive with text.	%BASETOPIC%
section	section of the topic to be added	the default section between STARTINCLUDE and STOPINCLUDE

What is a "Zone"?

<head>
...
%RENDERZONE{"head"}%
%RENDERZONE{"script"}%
</head>

• Create a sidebar zone to add widgets,
• Create a toolbar zone to add buttons icons
• Create a menu zone to add menu entries

Adding content to a zone

Enforcing a linear order of content within a zone

Working with {MergeHeadAndScriptZones} disabled (default)

Working with {MergeHeadAndScriptZones} enabled

{MergeHeadAndScriptZones} is provided to maintain compatibility with legacy extensions that use ADDTOHEAD to add <script> markup and require content that is now in the script zone. {MergeHeadAndScriptZones} will be removed from a future version of Foswiki.

Examples

Adding to a zone with missing dependencies

%ADDTOZONE{
  "script"
  text="
  <script type='text/javascript'>
    alert('test');
  </script>"
  requires="some-id-that-exists-in-script"
  id="MY::TEST"
}%

<script type='text/javascript'>
  alert('test');
</script>
<!-- MY::TEST: requires= missing ids: some-id-that-exists-in-script -->

Adding Javascript to a page

%JQREQUIRE{"shake"}%
%ADDTOZONE{
   "script"
   id="MyApp::ShakePart"
   text="
   <script type='text/javascript'>
      jQuery('#something').shake(3, 10, 180);
   </script>"
   requires="JQUERYPLUGIN::SHAKE"
}%

Adding CSS to a page

%ADDTOZONE{"head"
   id="MyCSS"
   text="
      <style type='text/css' media='all'>
         @import url('%PUBURLPATH%/%SYSTEMWEB%/MyCSS/foo.css');
      </style>"
}%

ATTACHURL -- full URL for attachments in the current topic

ATTACHURLPATH -- path of the attachment URL of the current topic

AUTHREALM -- authentication realm

Examples

• %AUTHREALM% expands to Enter your WikiName. (First name and last name, no space, no dots, capitalized, e.g. JohnSmith). Cancel to register if you do not have one.

BASETOPIC -- base topic where an INCLUDE started

BASEWEB -- base web where an INCLUDE started

BUTTON -- renders a nice button

Parameters

Examples

%BUTTON{
    "%MAKETEXT{"Submit"}%"
    onclick="confirm('Are your sure?')"
  }%
  %BUTTON{
    "%MAKETEXT{"Cancel"}%"
    icon="cross"
    target="%WEB%.%TOPIC%"
  }% %CLEAR%

• Expands as:
  Submit Cancel

CALC -- add spreadsheet calculations to tables and outside tables

• This macro is specifically for manipulating data in tables, and so is evaluated after the normal Macro expansion order. If you need a standard ordered evaluation see CALCULATE

Examples

• %CALC{"$SUM($ABOVE())"}% returns the sum of all cells above the current cell
• %CALC{"$EXISTS(Web.SomeTopic)"}% returns 1 if the topic exists
• %CALC{"$UPPER(Collaboration)"}% returns COLLABORATION

CALCULATE -- add spreadsheet formulae calls using standard Macro evaluation order.

Examples

• • %CALCULATE{"$EXISTS(Web.SomeTopic)"}% returns 1 if the topic exists
  • %CALCULATE{"$UPPER(Collaboration)"}% returns COLLABORATION

Related

COMMENT -- insert an edit box into the topic to easily add comments.

Parameters

• The following standard attributes are recognized

  Name	Description	Default
  type	This is the name of the template to use for this comment. Comment templates are defined in a Foswiki template - see Customisation, below. If this attribute is not defined, the type is whatever is defined by COMMENTPLUGIN_DEFAULT_TYPE preference setting.	below
  default	Default text to put into the prompt.
  target	Name of the topic to add the comment to	the current topic
  mode	For compatibility with older versions only, synonymous with type
  nonotify	Set to "on" to disable change notification for target topics	off
  noform	Set to "on" to disable the automatic form that is generated around your comment prompt if you don't provide a FORM template. See CommentPluginExamples:noform for an example.	off
  nopost	Set to "on" to disable insertion of the posted text into the topic.	off
  remove	Set to "on" to remove the comment prompt after the first time it is clicked.	off
  button	Button label text	Add comment

Examples

• A %COMMENT% without parameters shows a simple text box.

COVER -- current skin cover

Examples

• %COVER% currently expands to HomeGuest (it will only expand when a cover is actually set)

DATE -- signature format date

Examples

• %DATE% expands to 21 Dec 2025
• Date format defined as {DefaultDateFormat} in configure
  When used in a template topic, this variable will be expanded when the template is used to create a new topic. See TemplateTopics#TemplateTopicsVars for details.

DISPLAYTIME -- display formatted time

Parameters

Examples

• %DISPLAYTIME% expands to 21 Dec 2025 - 16:41
• %DISPLAYTIME{"$hou:$min"}% expands to 16:41

ENCODE -- encode characters in a string

Parameters

Parameter	Description	Default
"string"	String to encode	"" (empty string)
type	Use a predefined encoding (see below).	Default is 'url'. Parameter type not be used if old or new are given.
old	Comma-separated list of tokens to replace. Tokens are normally single characters, but can also be sequences of characters. The standard format tokens may be used in this list. Each token must be unique - you cannot list the same token twice.	May not be used with type; required if new is used
new	comma-separated list of replacement tokens. The elements in this list match 1:1 with the elements in the old list. Again, the standard format tokens may be used. An empty element in the new list will result in the corresponding token in the old list being deleted from the string. If the new list is shorter than the old list it will be extended to the same length using the empty element. Tokens do not have to be unique. When using old and new, be aware that the results of applying earlier tokens are not processed again using later tokens. (see examples below)	May not be used with type; required if old is used

Predefined encodings

• type="entity" or type="entities" Encode special characters into HTML entities, like a double quote into &#34;
  • all non-printable ASCII characters below space, except newline ("\n") and carriage return ("\r").
  • HTML special characters "<", ">", "&", single quote (') and double quote (")
  • TML special characters "%", "[", "]", "@", "_", "*", "=", "$" and "|"
• type="html" As type="entity" except it also encodes \n (newline) and carriage return ("\r").
• type="safe" Encode just the characters '"<>% into HTML entities.
• type="quote" or type="quotes" Escapes double quotes with backslashes (\"), does not change any other characters
• type="url" (default) Encode special characters for use in URL parameters, like a double quote into %22.

Examples

• %ENCODE{"spaced name"}% expands to spaced%20name
• %ENCODE{"| Blah | | More blah |" old="|,$n" new="&#124;,<br />"}% expands to =| Blah | | More blah | - this encoding is useful to protect special TML characters in tables.
• %ENCODE{"10xx1x01x" old="1,x,0" new="A,,B"}% expands to ABABA
• %ENCODE{"1,2" old="$comma" new=";"}% expands to 1;2

<input type="text" name="address" value="%ENCODE{ "any text" type="entity" }%" />

%SEARCH{ "%ENCODE{ "string with "quotes"" type="quotes" }%" noheader="on" }%

When using old and new, be aware that the results of applying earlier tokens are not processed again using later tokens. For example:

   %ENCODE{"A" old="A,B" new="B,C"}% will result in 'B' (not 'C'),
   %ENCODE{"asd" old="as,d" new="d,f"}% will yield 'df', and
   %ENCODE{"A" old="A,AA" new="AA,B"}% will give 'AA' and.
   %ENCODE{"asdf" old="a,asdf" new="a,2"}% will give 'asdf'

ENDINCLUDE -- end position of topic text if included

ENDSECTION -- marks the end of a named section within a topic

Parameters

Examples

• %ENDSECTION{"X" type="expandvariables"}%

ENDTAB -- ending marker for a tab of a tabpane

ENDTABPANE -- ending tag for tabpane widget

ENDTWISTY -- complements an opening TWISTY tag to close a twisty

ENDTWISTYTOGGLE -- Twisty closure

Examples

ENV -- inspect the value of an environment variable

Examples

• %ENV{MOD_PERL}% displays as: not set

EXAMPLETAG -- example macro tag

Parameters

Examples

• %EXAMPLETAG{"hello" format="| $topic: $summary |"}%

EXPAND -- expand macros in a string as if they were used in another topic

Parameters

Examples

   * Set MYPREFERENCE = value

%EXPAND{"$percentMYPREFERENCE$percent" scope="SettingsTopic"}%

%EXPAND{"$percentMYPREFERENCE$percent" scope="%OTHERTOPIC%"}%

%EXPAND{"$percentMYPREFERENCE{$quotdefault$quot param=$quotvalue$quot}" scope="SettingsTopic"}%

EXPAND is not very efficient, and should be used sparingly.

To expand a web preference (for example, a web access control) then set scope="Theotherweb.%WEBPREFSTOPIC%"

FAILEDPLUGINS -- debugging for plugins that failed to load

Examples

• %FAILEDPLUGINS%

FORMAT -- format a list of objects

Parameters

Examples

   %FORMAT{"one,two,three" type="string" format="   * $item"}%
   %FORMAT{"%SKIN%"
      header="the Skin setting is evaluated in this order:"
      format="   1 =$topic="
      footer="   1 =default="
   }%

Supported formatting tokens

For more sophisticated handling of string lists, consider installing Foswiki:Extensions.FilterPlugin

FORMFIELD -- renders a field in the form attached to some topic

Parameters

• $value expands to the raw field value
• $value(display) is the form field value after mapping the stored value to the display value (use with +values form fields). If the field type does not support value mapping, renders the same as $value
• $name is the field name
• $title expands to the field title
• $formname gives the name of the form the field is in. $form is maintained for compatibility, but is deprecated
• $attributes - from the field definition
• $type - from the field definition
• $size - from the field definition
• $definingTopic - topic in which the field is defined
• The standard format tokens are also expanded

Examples

 %FORMFIELD{"ProjectName"
   topic="Projects.SushiProject"
   default="(no project name given)"
   alttext="ProjectName field not found in form"
 }%

GMTIME -- formatted Greenwich Mean Time (UTC)

Parameters

Supported special format tokens:

Examples

• %GMTIME% expands to 21 Dec 2025 - 15:41
• %GMTIME{"$day $month, $year - $hour:$min:$sec"}% expands to 21 Dec, 2025 - 15:41:26
  When used in a template topic, this macro will be expanded when the template is used to create a new topic. See TemplateTopics#TemplateTopicsVars for details.

GROUPINFO -- retrieve details about a group

Parameters

Note: GROUPINFO will not list members that are hidden from the current authenticated user. If the current user does not have VIEW authority for a user's topic, then the user will not be shown as a group member.

Examples

• %GROUPINFO% expands to == (comma-separated list of all groups)
• %GROUPINFO{AdminGroup"}% expands to == (comma-separated list of users in the requested group)
• groupname can optionally be qualified with the Main prefix, any other web prefix will return an empty list.

HISTORY -- control attributes of tables and sorting of table columns

Parameters

Additional macros

• %HISTORY_REV1%: Oldest revision from the printed history
• %HISTORY_REV2%: Latest revision from the printed history
• %HISTORY_NREV%: Number of the printed revisions
• %HISTORY_MAXREV%: Latest available revision of the topic

HOMETOPIC -- home topic in each web

Examples

• %HOMETOPIC% expands to WebHome, renders as WebHome

HTTP -- get HTTP headers

• Called with the name of an HTTP header field, returns its value. Capitalization and the use of hyphens versus underscores are not significant.

Parameters

Examples

You can see the HTTP headers your browser sends to the server on a number of sites e.g. http://www.ericgiguere.com/tools/http-header-viewer.html

HTTP_HOST -- environment variable

Examples

• %HTTP_HOST% expands to 141.244.188.169

HTTPS -- get HTTPS headers

Parameters

ICON -- small documentation graphic or icon of common attachment types

Parameters

Examples

• %ICON{"flag-gray"}% displays as
• %ICON{"pdf"}% displays as
• %ICON{"docx" default="doc"}% displays as
• %ICON{"smile.pdf"}% displays as
• %ICON{"/dont/you/dare/smile.pdf"}% returns
• %ICON{"data.unknown" alt="Unknown file type"}% displays as
• %ICON{"data.unknown"}% displays as
• %ICON{"http://trunk.foswiki.org/pub/System/DocumentGraphics/xsl.gif"}% displays

• Graphics: arrowbright, bubble, choice-yes, hand
• File types: bmp, doc, gif, hlp, html, mp3, pdf, ppt, txt, xls, xml, zip

• %ICON{"pdf" quote="'"}%

ICONURL -- URL of small documentation graphic or icon

Parameters

Examples

• %ICONURL% returns http://141.244.188.169/foswiki/pub/System/DocumentGraphics/else.png
• %ICONURL{"arrowbright"}% returns http://141.244.188.169/foswiki/pub/System/DocumentGraphics/arrowbright.png
• %ICONURL{"novel.pdf"}% returns http://141.244.188.169/foswiki/pub/System/DocumentGraphics/pdf.png
• %ICONURL{"notanicon" default="ram"}% returns http://141.244.188.169/foswiki/pub/System/DocumentGraphics/ram.png
• %ICONURL{"/queen/boheme.mp3"}% returns http://141.244.188.169/foswiki/pub/System/DocumentGraphics/mp3.png

ICONURLPATH -- URL path of small documentation graphic or icon

Parameters

Examples

• %ICONURLPATH{"locktopic"}% returns /foswiki/pub/System/DocumentGraphics/locktopic.png
• %ICONURLPATH{"eggysmell.xml"}% returns /foswiki/pub/System/DocumentGraphics/xml.png
• %ICONURLPATH{"notanicon" default="ram"}% returns /foswiki/pub/System/DocumentGraphics/ram.png
• %ICONURLPATH{"/doc/xhtml.xsl"}% returns /foswiki/pub/System/DocumentGraphics/xsl.png

IF -- simple conditionals

Examples

• %IF{"CONDITION" then="THEN" else="ELSE"}% shows
  "THEN" if "CONDITION" evaluates to TRUE, otherwise "ELSE" will be shown

 %IF{"defined FUNFACTOR"
   then="FUNFACTOR is defined"
   else="FUNFACTOR is not defined"
 }%

FUNFACTOR is not defined

INCLUDE -- include another topic, or subsection of a topic, or a URL, or Foswiki embedded documentation

(Including a topic) Parameters

• Examples: See IncludeTopicsAndWebPages

(Including a web page) Parameters

Parameter	Description	Default
"http://..."	A full qualified URL, i.e. %INCLUDE{"http://foswiki.org:80/index.html"}%. Supported content types are text/html and text/plain. If the URL resolves to an attachment file on the server this will automatically translate to a server-side include.
pattern	Include a subset of a topic or a web page. Specify a RegularExpression that contains the text you want to keep in parenthesis, e.g. pattern="(from here.*?to here)". IncludeTopicsAndWebPages has more.	none
raw	When a page is included, normally Foswiki will process it, doing the following: 1) Alter relative links to point back to originating host, 2) Remove some basic HTML tags (html, head, body, script) and finally 3) Remove newlines from HTML tags spanning multiple lines. If you prefer to include exactly what is in the source of the originating page set this to on. raw="on" is short for disableremoveheaders="on", disableremovescript="on", disableremovebody="on", disablecompresstags="on" and disablerewriteurls="on".	disabled
literal	While using the raw option will indeed include the raw content, the included content will still be processed and rendered like regular topic content. To disable parsing of the included content, set the literal option to "on".	off
disableremoveheaders	Bypass stripping headers from included HTML (everything until first </head> tag)	off
disableremovescript	Bypass stripping all <script> tags from included HTML	off
disableremovebody	Bypass stripping the </body> tag and everything around over and below it	off
disablecompresstags	Bypass replacing newlines in HTML tags with spaces. This compression step rewrites unmatched <'s into &lt; entities unless bypassed	off
disablerewriteurls	Bypass rewriting relative URLs into absolute ones	off
warn	Warn if URL include fails: Fail silently (if off); output default warning (if set to on); else, output specific text (use $topic for topic name) appended with the http error information.	%INCLUDEWARNING% preferences setting

JavaScript in included webpages is filtered out as a security precaution per default (disable filter with disableremovescript parameter)

Foswiki by default is configured to deny URL format includes.

• Examples: See IncludeTopicsAndWebPages

(Including Foswiki embedded module documentation) Parameters

• Examples: See System/PerlDoc?module=Foswiki::Func

INCLUDINGTOPIC -- name of topic that includes current topic

Be careful of the subtle difference between INCLUDINGTOPIC and BASETOPIC. You probably should be using BASETOPIC

INCLUDINGWEB -- web that includes current topic

Be careful of the subtle difference between INCLUDINGWEB and BASEWEB. You probably should be using BASEWEB

JQICON -- render an image

Parameters

%JQICON{"tick" alt="alternative content" title="this is a tick icon"}%
%JQICON{"cross"}%
%JQICON{"disk"}%
%JQICON{"star"}%
%JQICON{"lightbulb"}%
%JQICON{"camera"}%
%JQICON{"date"}%
     

%JQICON{"fa-pagelines" style="font-size:1em;color:#00BF00"}%
%JQICON{"fa-pagelines" style="font-size:2em;color:#0FAF0F"}%
%JQICON{"fa-pagelines" style="font-size:3em;color:#1F9C1F"}%
%JQICON{"fa-pagelines" style="font-size:4em;color:#2D812D"}%
%JQICON{"fa-pagelines" style="font-size:5em;color:#315C31"}%
     

JQICONPATH -- render the urlpath to an image

%JQICON{"name" format="$iconPath"}%

Examples

• %JQICONPATH{"tick"}% expands to /foswiki/pub/System/FamFamFamSilkIcons/tick.png

JQPLUGINS -- display a summary of available plugins

Parameters

Examples

 %JQPLUGINS{
   "treeview|slimbox"
   header="   * JQuery Plugins:$n"
   format="      * [[$documentation][$name]] v$version was developed by [[$homepage][$author]]"
 }%

• JQuery Plugins:
  • Slimbox v2.05 was developed by Christophe Beyls
  • Treeview v1.4 was developed by Joern Zaefferer

JQREQUIRE -- enable a plugin on the current page

in case of an error JQREQUIRE will produce an inline HTML error message.

Parameters

Examples

• %JQREQUIRE{"easing,sliding,falling"}%

JQTHEME -- switch jQuery UI theme

in case of an error JQTHEME will produce an inline HTML error message.

Parameters

LANG -- the language specified by the server locale

• In templates the lang attribute is defined like this:

  <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="%LANG%" lang="%LANG%">

• Do not confuse LANG with LANGUAGE

Examples

• %LANG% expands to en

LANGUAGE -- language code for the current user

Avoid defining LANGUAGE in a non- per-user way, otherwise users will not be able to choose their preferred language.

Examples

• %LANGUAGE% expands to en

LANGUAGES -- list available languages

Parameters

Examples

• %LANGUAGES% expands to
  * English
• <select>%LANGUAGES{format="<option $marker value='$langtag'>$langname</option>" selection="%LANGUAGE%"}%</select> creates an option list of the available languages with the current language selected

LOCALSITEPREFS -- web.topicname of site preferences topic

• The full name of the local site preferences topic. These local site preferences overload the system level preferences defined in System.DefaultPreferences.

Examples

• %LOCALSITEPREFS% expands to Main.SitePreferences, renders as SitePreferences

LOGIN -- present a full login link

Examples

• %LOGIN% expands to Log In

LOGOUT -- present a full logout link

You are already logged out, so %LOGOUT expands to an empty string

Examples

• %LOGOUT% expands to

MAKETEXT -- creates text using Foswiki's I18N infrastructure

Parameters

Examples

• %MAKETEXT{string="Edit"}% expands to Edit
• %MAKETEXT{"If you have any questions, please contact [_1]." args="%WIKIWEBMASTER%"}% expands to If you have any questions, please contact gottschall@bokuANTISPAM.ac.at.
• %MAKETEXT{"Did you want to [[[_1]][reset [_2]'s password]]?" args="%SYSTEMWEB%.ResetPassword,%WIKIUSERNAME%"}% expands to Did you want to reset Main.WikiGuest's password?

Notes

• [_n] brackets are validated to a positive integer from 1 to 100.
• Missing arguments are replaced with an empty string ''.
• An ampersand (&) followed by one ascii alphabetic character (a...z, A...Z) in the translatable string will be expanded to an access key string. For example, &X will expand to <span class='foswikiAccessKey'>X</span>. If you want to write an actual ampersand, either follow it with a non-alphabetic character or write two consecutive ampersands (&&).
• Translatable strings starting with underscores (_) are reserved. You cannot use translatable phrases starting with an underscore.
• Make sure that the translatable string is constant. Do not include %MACROS% inside the translatable strings as they will be expanded before the %MAKETEXT{...}% itself is handled. You can, however, use macros in the args, as shown in the examples above.
• The string will be output in English if no mapping can be found in the .po translation file for the current user's selected language.

Plurals

• %MAKETEXT{string="Edit [*,_1,file]" args="4"}% expands to Edit 4 files

Notes on plurals

• Only 3 arguments are supported.
• The first parameter must be an asterisk. Literals quant, numf or # are not supported.
• The 2nd parameter must be the argument number
• The 3rd parameter is the word or phrase to be made plural.

META -- displays meta-data

Parameters

"form"

"attachments"

"moved"

"parent"

"formfield"

Related

NONCE -- generate a nonce (developers only)

NOP -- template text not to be expanded in instantiated topics

• %NOP%
  • In normal topic text, expands to <nop>, which prevents expansion of adjacent macros and wikiwords
  • When the topic containing this is used as a template for another topic, it is removed.
• %NOP{...}% deprecated
  • In normal topic text, expands to whatever is in the curly braces (if anything).
    This is deprecated. Do not use it. Use %STARTSECTION{type="templateonly"}% .. %ENDSECTION{type="templateonly"}% instead (see TemplateTopics for more details).

NOTIFYTOPIC -- name of the notify topic

Examples

• %NOTIFYTOPIC% expands to WebNotify, renders as WebNotify

PERLDEPENDENCYREPORT -- report perl module dependencies

Parameters

PLUGINDESCRIPTIONS -- list of plugin descriptions

Examples

• %PLUGINDESCRIPTIONS% expands to
  • SpreadSheetPlugin (1.20, 1.20): Add spreadsheet calculations like "$SUM($ABOVE())" to Foswiki tables and other topic text
  • SlideShowPlugin (08 Sep 2015, 2.3): Create web based presentations based on topics with headings
  • AutoViewTemplatePlugin (2015-08-18, 1.22): Automatically sets VIEW_TEMPLATE and EDIT_TEMPLATE
  • CalendarPlugin (2.010, 2.010): Show a monthly calendar with highlighted events
  • CommentPlugin (29 Sep 2015, 2.7): Quickly post comments to a page without an edit/save cycle
  • CompareRevisionsAddonPlugin (1.114, 1.114):
  • ConfigurePlugin (8 Sep 2015, 1.02): configure interface using json-rpc
  • EditRowPlugin (30 Sep 2015, 3.311): Inline edit for tables
  • HistoryPlugin (1.13, 1.13): Shows a complete history of a topic
  • HomePagePlugin (1.23, 1.23): Allow User specified home pages - on login
  • ImportExportPlugin (0.0.8, $Rev: 14300 (2012-03-13) $): Import and export wiki data
  • InterwikiPlugin (1.22, 1.22): Link ExternalSite:Page text to external sites based on aliases defined in a rules topic
  • JQueryPlugin (24 Sep 2015, 6.30): jQuery JavaScript library for Foswiki
  • MailerContribPlugin (2.82, 2.82): Supports e-mail notification of changes
  • NatEditPlugin (08 Sep 2015, 9.06): A Wikiwyg Editor
  • PreferencesPlugin (1.16, 1.16): Allows editing of preferences using fields predefined in a form
  • RenderListPlugin (2.27, 2.27): Render bullet lists in a variety of formats
  • SmiliesPlugin (17 Sep 2015, 2.03): Render smilies like as icons
  • SubscribePlugin (27 Jul 2015, 3.4): This is a companion plugin to the MailerContrib. It allows you to trivially add a "Subscribe me" link to topics to get subscribed to changes.
  • TablePlugin (10 Sep 2015, 1.151): Control attributes of tables and sorting of table columns
  • TinyMCEPlugin (1.30, 1.30): Integration of the Tiny MCE WYSIWYG Editor
  • TwistyPlugin (1.62, 1.62): Twisty section Javascript library to open/close content dynamically
  • UpdatesPlugin (1.01, 1.01): Checks Foswiki.org for updates
  • WysiwygPlugin (14 Jun 2015, 1.31): Translator framework for WYSIWYG editors

PLUGINVERSION -- the version of a Foswiki Plugin, or the Foswiki Plugins API

Examples

• %PLUGINVERSION{"InterwikiPlugin"}% expands to 1.22
• %PLUGINVERSION% to get the version of the API, expands to 2.3

POPUPWINDOW -- opens a topic or url in a new window

Parameters

Examples

• Example with topic link:

  %POPUPWINDOW{"CompleteDocumentation" label="Open this topic in a new window"}%

  Generates: Open this topic in a new window
• Example with URL:

  %POPUPWINDOW{url="http://foswiki.org"}%

  Generates: http://foswiki.org
• Enable POPUPWINDOW by writing %JQREQUIRE{"popupwindow"}% on the page

PUBURL -- generate an URL for an attachment

Parameters

Examples

• %PUBURL% expands to http://141.244.188.169/foswiki/pub
• %PUBURL{"icon_plus.png"}% expands to =%PUBURL{"icon_plus.png"}%
• %PUBURL{web="System"}% expands to http://141.244.188.169/foswiki/pub/System
• %PUBURL{topic="System.MainFeatures"}% expands to http://141.244.188.169/foswiki/pub/System/MainFeatures
• %PUBURL{web="System" topic="MainFeatures"}% expands to http://141.244.188.169/foswiki/pub/System/MainFeatures
• %PUBURL{topic="System.MainFeatures"}% expands to http://141.244.188.169/foswiki/pub/System/MainFeatures
• %PUBURL{topic="System.MainFeatures" "icon_plus.png"}% expands to http://141.244.188.169/foswiki/pub/System/MainFeatures/icon_plus.png
• Also supports topic_version and attachment_version parameters. These can be used with advanced store implementations to select specific attachment versions. However simple file-based stores do not normally support them.
  The 'old' way of building URLs using PUBURL involved concatenating the web and topic names to the PUBURL e.g. %PUBURL%/Main/SystemFeatures. This practice is strongly discouraged, as it does not correctly handle encoding of the parts of the URL. At the first opportunity you should replace all such URLs with the equivalent %PUBURL%{topic="System.MainFeatures"}%, which will handle URL encoding for you.
  
  ATTACHURL provides a shorter way to refer to the attachments on the current topic.

PUBURLPATH -- generate a relative URL for an attachment

Parameters

Examples

• %PUBURLPATH% expands to /foswiki/pub
• %PUBURLPATH{"icon_plus.png"}% expands to =%PUBURLPATH{"icon_plus.png"}%
• %PUBURLPATH{web="System"}% expands to /foswiki/pub/System
• %PUBURLPATH{topic="System.MainFeatures"}% expands to /foswiki/pub/System/MainFeatures
• %PUBURLPATH{web="System" topic="MainFeatures"}% expands to /foswiki/pub/System/MainFeatures
• %PUBURLPATH{topic="System.MainFeatures" "icon_plus.png"}% expands to /foswiki/pub/System/MainFeatures/icon_plus.png
• Also supports topic_version and attachment_version parameters. These can be used with advanced store implements to select specific attachment versions. However simple file-based stores do not normally support them.

This macro will only generate a relative URL if the store supports them, and the context allows it. Otherwise it will generate the same as PUBURL

The 'old' way of building URLs using PUBURLPATHPATH involved concatenating the web and topic names to the PUBURLPATH e.g. %PUBURLPATH%/%WEB%/%TOPIC%. This practice is strongly discouraged, as it does not correctly handle encoding of the parts of the URL. At the first opportunity you should replace all such URLs with the equivalent %PUBURLPATH%{topic="System.MainFeatures"}%, which will handle URL encoding for you.

ATTACHURLPATH provides a shorter way to refer to the attachments on the current topic.

QUERY -- get the value of meta-data

• supports formatted access to formfields and other meta-data in topics using the same syntax as is used in IF and SEARCH statements,
• gives access to all meta-data, including that added by extensions,
• supports reporting values using JSON and other standards, simplifying the retrieval of meta-data for REST applications,
• replaces the FORMFIELD macro for most applications.

Parameters

Examples

      Get the name of the form in the current topic:
      %QUERY{"form.name"}%

      Get the value of the 'Firstname' form field in
        the current topic:
      %QUERY{"fields[name='Firstname'].value"}%

      Get the value of the 'Firstname' form field in
        the current topic (shorthand version):
      %QUERY{"Firstname"}%

      Get a list of all the names of attachments on
        the topic 'System.DocumentGraphics':
      %QUERY{"'System.DocumentGraphics'/attachments.name"}%

      Get configuration setting {NameFilter}:
      %QUERY{"{NameFilter}"}%

      List all the installed DataForm field types {FormTypes}:
      %QUERY{"{FormTypes}[].types"}%
        

• style="perl" - generates values as Perl code strings generated by running through CPAN:Data::Dumper
• style="json" - generates values as JSON strings, suitable for reading by browsers.

QUERYPARAMS -- show parameters to the query

Parameters

Examples

   %QUERYPARAMS{
     format="<input type='hidden' name='$name' value='$value' encoding="entity" />"
   }%

Security warning!

Using QUERYPARAMS can easily be misused for cross-site scripting unless specific characters are entity encoded. By default QUERYPARAMS encodes the characters '"<>% into HTML entities (same as encoding="safe") which is relatively safe. The safest is to use encoding="entity". When passing QUERYPARAMS inside another macro always use double quotes ("") combined with using QUERYPARAMS with encoding="quote". For maximum security against cross-site scripting you are advised to install the Foswiki:Extensions.SafeWikiPlugin.

QUERYSTRING -- full, unprocessed string of parameters to this URL

• String of all the URL parameters that were on the URL used to get to the current page. For example, if you add ?name=Samantha;age=24;eyes=blue to this URL you can see this in action. This string can be appended to a URL to pass parameter values on to another page.
  URLs built this way are typically restricted in length, typically to 2048 characters. If you need more space than this, you will need to use an HTML form and =%QUERYPARAMS%=

Examples

• %QUERYSTRING% expands to section=content

REMOTE_ADDR -- environment variable

Examples

• %REMOTE_ADDR% expands to 216.73.216.123

REMOTE_PORT -- environment variable

Examples

• %REMOTE_PORT% expands to

REMOTE_USER -- environment variable

Examples

• %REMOTE_USER% expands to
  Displays the user identity established by the Web Server. Not available when using Template Autentication. The REMOTE_USER variable only expands when the active script is configured to Require valid-user in the Apache configuration. Eg. If your site uses Apache authentication and allows guest access, view this page with bin/view and bin/viewauth to see the effect.

RENDERLIST -- render bullet lists in a variety of formats

Examples

%RENDERLIST{"org" focus="Sales.WestCoastTeam"}%
      * [[Eng.WebHome][Engineering]]
         * [[Eng.TechPubs][Tech Pubs]]
      * [[Sales.WestCoastTeam][Sales]]
         * [[Sales.EastCoastTeam][East Coast]]
         * [[Sales.WestCoastTeam][West Coast]]

Expands as:

Sales

East Coast

West Coast

RENDERZONE - render the content of a zone

Parameters

$item <!--<literal> $id $missing</literal>-->

$id: requires= missing ids: $missingids

• • $id - id of the ADDTOZONE call within the zone currently being rendered.
  • $item - text of the ADDTOZONE call within the zone currently being rendered.
  • $zone - the "zone" currently being rendered.
  • $missing - if the ADDTOZONE call being rendered required any id which was not found, then $missing is the missingtoken parameter; empty string otherwise.
  • $missingids - comma separated list of ids that were required by the ADDTOZONE call currently being rendered but weren't found within this zone.

header and footer are not output if there is no content in the zone (nothing has been ADDTOZONEd ). However they are output if the output is the empty string (at least one ADDTOZONE has been processed).

Zones are cleared after being rendered; they are only ever rendered once.

head and script are automatic zones. They don't require a corresponding RENDERZONE anywhere in the templates - they are automatically inserted before the </head> tag in the output HTML page.

Normally, dependencies between individual ADDTOZONE statements are resolved within each zone. However, if {MergeHeadAndScriptZones} is enabled in configure, then head content which requires an id that only exists in script will be re-ordered to satisfy this dependency. {MergeHeadAndScriptZones} will be removed from a future version of Foswiki.

REVINFO -- revision information of current topic

Examples

• %REVINFO% expands to r3 - 06 Nov 2025 - 16:27:38 - UnknownUser
• %REVINFO{"format"}% expands to r3 - 06 Nov 2025 - 16:27:38 - UnknownUser

Parameters

Examples

• %REVINFO{"$date - $wikiusername" rev="43"}%

• To get the latest revision, even when looking at an older revision:

  %REVINFO{"$rev" rev="-1"}%

REVTITLE -- The requested revision as displayed in topic breadcrumbs

Examples

• %REVTITLE% expands to (simulated) (r3) (actual)

SCRIPTNAME -- name of current script

• The name of the current script is shown, including script suffix, if any (for example viewauth.cgi)

Examples

• %SCRIPTNAME% expands to view

SCRIPTSUFFIX -- script suffix

• Some Foswiki installations require a file extension for CGI scripts, such as .pl or .cgi

Examples

• %SCRIPTSUFFIX% expands to

SCRIPTURL -- URL of script(s)

Parameters

Examples

• %SCRIPTURL{"view" topic="Cartoons.EvilMonkey"}% will expand to http://141.244.188.169/foswiki/bin/view/Cartoons/EvilMonkey?topic=Cartoons.EvilMonkey
• %SCRIPTURL{"view" web="Cartoons"}% will expand to http://141.244.188.169/foswiki/bin/view/Cartoons?web=Cartoons
• %SCRIPTURL{"view" topic="Cartoons.EvilMonkey" rev="1"}% will expand to http://141.244.188.169/foswiki/bin/view/Cartoons/EvilMonkey?rev=1;topic=Cartoons.EvilMonkey
• %SCRIPTURL{"edit" web="Cartoons" topic="EvilMonkey" t="%GMTIME{"$epoch"}%"}% expands to http://141.244.188.169/foswiki/bin/edit/Cartoons/EvilMonkey?t=1766331686;topic=EvilMonkey;web=Cartoons
• %SCRIPTURL% expands to http://141.244.188.169/foswiki/bin
• %SCRIPTURL{script}% expands to http://141.244.188.169/foswiki/bin/script

In most cases you should use SCRIPTURLPATH instead, as it works much better with URL rewriting

The edit script should always be used in conjunction a t="%GMTIME{"$epoch"}%" parameter to ensure pages about to be edited are not cached in the browser

The 'old' way of building URLs using SCRIPTURL involved concatenating the web and topic names to the SCRIPTURL e.g. %SCRIPTURL{"script"}%/Cartoons/EvilMonkey. This practice is strongly discouraged, as it does not correctly handle encoding of the parts of the URL. At the first opportunity you should replace all such URLs with the equivalent %SCRIPTURL%{"script" topic="Cartoons.EvilMonkey"}%, which will handle URL encoding for you.

SCRIPTURLPATH -- URL path of script(s)

Parameters

Examples

• %SCRIPTURLPATH{"view" topic="Cartoons.EvilMonkey"}% expands to /foswiki/bin/view/Cartoons/EvilMonkey?topic=Cartoons.EvilMonkey
• %SCRIPTURLPATH{"view" web="Cartoons"}% expands to /foswiki/bin/view/Cartoons?web=Cartoons
• %SCRIPTURLPATH{"view" topic="Cartoons.EvilMonkey" rev="1"}% will expand to /foswiki/bin/view/Cartoons/EvilMonkey?rev=1;topic=Cartoons.EvilMonkey
• %SCRIPTURLPATH{"edit" web="Cartoons" topic="EvilMonkey" t="%GMTIME{"$epoch"}%"}% expands to /foswiki/bin/edit/Cartoons/EvilMonkey?web=Cartoons;topic=EvilMonkey;t=1766331686
• %SCRIPTURLPATH% expands to /foswiki/bin
• %SCRIPTURLPATH{script}% expands to /foswiki/bin/script

The edit script should always be used in conjunction with a t="%GMTIME{"$epoch"}%" parameter to ensure pages about to be edited are not cached in the browser

See SCRIPTURL if you expect to need the protocol and host e.g. if you are saving the HTML of the page and using it on a different host.

The 'old' way of building URLs using SCRIPTURLPATH involved concatenating the web and topic names to the SCRIPTURLPATH e.g. %SCRIPTURLPATH{"script"}%/Cartoons/EvilMonkey. This practice is strongly discouraged, as it does not correctly handle encoding of the parts of the URL. At the first opportunity you should replace such URLs with the equivalent %SCRIPTURLPATH%{"script" topic="Cartoons.EvilMonkey"}%, which will handle URL encoding for you.

SEARCH -- search content

Parameters

Examples

• %SEARCH{"wiki" web="%USERSWEB%" scope="topic"}%

• %SEARCH{
      "FAQ"
      nonoise="on"
      header="| *Topic: * | *Summary: * |"
      format="| $topic    | $summary    |"
  }%

  (displays results in a table with header - details)

The appearance of the table emitted by the SEARCH may be controlled with TablePlugin's %TABLE{}% macro placed just before the %SEARCH{}%. Example: %TABLE{ tablewidth="90%" }%

SERVERINFORMATION -- report detailed web server information

Parameters

SERVERTIME -- formatted server time

Examples

• %SERVERTIME% elsnds to 21 Dec 2025 - 16:41
• %SERVERTIME{"$hou:$min"}% expands to 16:41

Note: When used in a template topic, this macro will be expanded when the template is used to create a new topic. See TemplateTopics#TemplateTopicsVars for details.

SESSIONID -- unique ID for this session

Examples

• %SESSIONID% expands to e501f734f061da60cd1ec12910acc4e3

SESSIONVAR -- name of CGI and session variable that stores the session ID

Examples

• %SESSIONVAR% expands to FOSWIKISID

SESSION_VARIABLE -- get, set or clear a session variable

Parameters

The users ID is in the AUTHUSER session variable, and is read-only

Examples

• %SESSION_VARIABLE{"MYVAR" set="myval"}%
• %SESSION_VARIABLE{"MYVAR" clear=""}%

SET -- set a preference setting during runtime

   * Set foo = %SEARCH{...

%SET{"foo" value="%SEARCH{..."}%

Parameters

Examples

SHOWPREFERENCE -- show where preferences are defined.

Parameters

Examples

• %SHOWPREFERENCE% will show all preferences
• %SHOWPREFERENCE{"ATTACHFILESIZELIMIT"}% expands to

   * Set ATTACHFILESIZELIMIT = "10000"
      * ATTACHFILESIZELIMIT was *finalised* in System.DefaultPreferences

• %SHOWPREFERENCE{"DENYWEBCHANGE,ALLOWWEBCHANGE"}% expands to

   * Set DENYWEBCHANGE = ""
   * Set ALLOWWEBCHANGE = "%USERSWEB%.AdminGroup"
      * ALLOWWEBCHANGE was defined in System.WebPreferences

SKIN -- current skin

Examples

• %SKIN% expands to natedit,pattern
• See Skins for more information

SLIDESHOWEND -- end slideshow

Examples

SLIDESHOWSTART -- convert a topic with headings into a slideshow

Parameters

Examples

 %SLIDESHOWSTART%
 ---++ Sample Slide 1
    * Bullet 1
    * Bullet 2
 ---++ Sample Slide 2
    * Bullet 1
    * Bullet 2
 %SLIDESHOWEND%

• Expands as:

Slide 1: Sample Slide 1

• Bullet 1
• Bullet 2

Slide 2: Sample Slide 2

• Bullet 1
• Bullet 2

SPACEDTOPIC -- topic name, spaced and URL-encoded deprecated

Examples

• %SPACEDTOPIC% expands to Var%20*SPACEDTOPIC
  This is a deprecated macro. It can be duplicated with %ENCODE{%SPACEOUT{"%TOPIC%" separator=" *"}%}%

SPACEOUT -- renders string with spaces inserted in sensible places

Examples

• %SPACEOUT{"WebHome"}% expands to: Web Home

Parameters

Spaced out WikiWords are not automatically linked. To SPACEOUT a WikiWord but preserve the link use "double bracket" format. For example, [[WebHome][%SPACEOUT{"WebHome"}%]] expands to Web Home

STARTINCLUDE -- start position of topic text if included

If you want more than one part of the topic included, use %STARTSECTION{type="include"}% instead

STARTSECTION -- marks the start of a section within a topic

• • type="section" - the default, used for a generic section, such as a named section used by INCLUDE.
  • type="include" - like %STARTINCLUDE% ... %STOPINCLUDE% except that you can have as many include blocks as you want which are all merged into one when included (%STARTINCLUDE% is restricted to only one). Sections of type include may not be given a name.
  • type="expandvariables" - all macros inside an "expandvariables" type section gets expanded when a new topic based on the template topic is created. See TemplateTopics for more information.
  • type="templateonly" - start position of text to be removed when a template topic is used. This is used to embed text that you do not want expanded when a new topic based on the template topic is created. See TemplateTopics for more information.

Parameters

If a section is not given a name, it will be assigned one. Unnamed sections are assigned names starting with _SECTION0 for the first unnamed section in the topic, _SECTION1 for the second, etc..

You can define nested sections. It is not recommended to overlap sections, although it is valid in Foswiki. Use named sections to make sure that the correct START and ENDs are matched. Section markers are not displayed when a topic is viewed.

Examples

• %STARTSECTION{"name"}% ................... %ENDSECTION{"name"}%
• %STARTSECTION{"name" type="section"}% .... %ENDSECTION{"name" type="section"}% (type="section" is the default)
• %STARTSECTION{type="include"}% ........... %ENDSECTION{type="include"}%
• %STARTSECTION{type="expandvariables"}% ... %ENDSECTION{type="expandvariables"}%
• %STARTSECTION{type="templateonly"}% ...... %ENDSECTION{type="templateonly"}%

STATISTICSTOPIC -- name of statistics topic

Examples

• %STATISTICSTOPIC% expands to WebStatistics, renders as WebStatistics

STOPINCLUDE -- Alias for ENDINCLUDE

STOPSECTION -- Alias for ENDSECTION

SYSTEMWEB -- name of documentation web

Examples

• %SYSTEMWEB% expands to System

TAB -- tab inside a tabpane widget

Parameters

TABLE -- control attributes of tables and sorting of table columns

Attributes for tables

Attributes for table sorting

Attributes for table cells

Attributes for data cells

Attributes for headers

Other attributes

Examples

 %TABLE{ sort="off" tableborder="0" cellpadding="4" cellspacing="3" cellborder="0" }%
 | *A1* | *B1* |
 | A2   | B2   |

• Expands as:

  A1	B1
  A2	B2

TABPANE -- tabpane widget

%TABPANE%
 %TAB{"tab 1"}%
   ...
 %ENDTAB%
 %TAB{"tab 2"}%
   ...
 %ENDTAB%
%ENDTABPANE%

%TABPANE%
 %TAB{"tab 1"}%
   %TABPANE%
     %TAB{"tab 1.1"}%
       ...
     %ENDTAB%
     %TAB{"tab1.2"}%
       ...
     %ENDTAB%
   %ENDTABPANE%
 %ENDTAB%
 %TAB{"tab 2"}%
   ...
 %ENDTAB%
%ENDTABPANE%

Parameters

Examples

TOC -- table of contents

Parameters

Examples

%TOC{depth="2"}%
%TOC{"CompleteDocumentation" web="%SYSTEMWEB%" title="Contents:"}%

If multiple headers have the exact same text, the anchors for the 2nd, 3rd etc will be suffixed by _AN1, _AN2 etc so the anchors become unique.

If other topics are included using INCLUDE then any headingoffset will not be seen by TOC.