Reference Manual (Foswiki-1.1.4, Tue, 20 Dec 2011, build 13483)

System Requirements

Server Requirements

Perl Modules

perl -e 'use FileHandle; print $FileHandle::VERSION."\n"'

Client Requirements

• XHTML 1.0 Transitional compliant
• Cookies, if persistent sessions are required
• Javascript, for edit/save/upload functionality

  Change {ValidationMethod}{Method} from strikeone to embedded in configure to allow non-javascript browsers to edit/save/upload

Important note about Plugins

• Plugins can require just about anything - browser-specific functions, stylesheets (CSS), Java applets, cookies, specific Perl modules,... - check the individual Plugin specs.

Installation Guide

Initial Installation

System Requirements

Preparing to install

Basic installation: getting Foswiki up and running

1. Download and unpack the Foswiki distribution.
2. Set the file and directory permissions for the installation.
3. Configure the locations of the Perl executable and the Foswiki modules.
4. Configure the web server.
5. Configure Foswiki.
6. Enable authentication of users (if desired).
7. Define the administrator users.

Download and unpack the Foswiki distribution

• Note: Foswiki does not support directory paths that contain spaces, so ensure that all of its directory paths do not contain any spaces (particularly on Windows).

(Not applicable on Windows) Set the file and directory permissions for the installation

• Warning: Do not just run a chmod -R 770 foswiki. Providing execute access to all files is potentially dangerous. This is a common mistake made by Foswiki installers. See Foswiki:Support.SettingFileAccessRightsLinuxUnix for a sample set of Unix commands to set the file and directory permissions.

• RedHat, Fedora, CentOS, Gentoo, Mandriva : chown -R apache:apache /path/to/foswiki
• debian/Ubuntu/Kubuntu : chown -R www-data:www-data /path/to/foswiki
• Suse : chown -R wwwrun:www /path/to/foswiki

(optional - required on Windows ) Configure the locations of the Perl executable and the Foswiki modules

cd /path/to/foswiki/tools
perl -I ../lib rewriteshebang.pl

cd C:\path\to\foswiki\tools
perl -I ..\lib  rewriteshebang.pl

cd C:\path\to\foswiki\tools
C:\path\to\perl -I ..\lib  rewriteshebang.pl

(optional) Configuration of a script suffix for the perl scripts

(optional) Configuration for non-standard library locations

• In the bin directory, copy the template file LocalLib.cfg.txt to LocalLib.cfg. Make sure the ownership and access rights of the copy are the same as LocalLib.cfg.txt.
• Edit bin/LocalLib.cfg so that $foswikiLibPath is set to the absolute file path of your lib directory. For example: /path/to/foswiki/lib.
• If you need to install additional CPAN modules, but can't update the main Perl installation files on the server, you can set $CPANBASE to point to your personal CPAN install. Don't forget that the web server user has to be able to read those files as well.

Configure the web server

• Apache config file: The recommended method is using a config file. With a config file you can put the entire Foswiki configuration in ONE file (typically named foswiki.conf). Performance is much better with a config file, and one file gives the best overview and ensures that you get a safe installation . However to use a config file you need root or sudo access to stop and start Apache. The Foswiki apache config file can be included from the main Apache config file. (Typically httpd.conf or apache.conf depending on your distribution). However most distributions have a directory from which any file that ends with .conf gets included when you restart Apache (Example RedHat/Fedora/Centos: /etc/httpd/conf.d, Gentoo: /etc/apache2/vhost.d ). If you use a virtual host setup in Apache you should include the foswiki.conf file from inside the desired virtual host config in your Apache configuration.
• .htaccess files: This method should only be used when you cannot use a config file. Performance is slower as Apache must search through all applicable directories for any .htaccess files on each page access. Normally this is the only way to control Apache in a shared host environment where you have no root or sudo privileges.

• The easiest and best way is to use the Foswiki:Support.ApacheConfigGenerator tool to generate a safe, working config file for your Foswiki installation, based on the options you choose in the tool.
• If you can't use the online configuration generator, a sample config file called foswiki_httpd_conf.txt can be found in the root of the foswiki installation.
• Ensure that web access is denied to all Foswiki subdirectories other than bin and pub.
  • The Foswiki:Support.ApacheConfigGenerator tool will generate the appropriate settings;
  • the foswiki_httpd_conf.txt file also has examples of configuring Apache appropriately.
• Ensure there is either a ScriptAlias directive for the bin subdirectory, or an Alias directive with SetHandler cgi-script and Options ExecCGI directives for the bin subdirectory, so that the bin scripts will be executed by Apache.
• Note: you must restart Apache after making changes to your config files for the changes to take effect.

• In the root of the foswiki installation, there are sample .htaccess files for various subdirectories in your installation. Each file has help text explaining how to modify it for your configuration. For more information, see Foswiki:Support.SupplementalDocuments.

  location and name of sample .htaccess file	copy sample file to the following location
  foswiki/root-htaccess.txt	foswiki/.htaccess
  foswiki/bin-htaccess.txt	foswiki/bin/.htaccess
  foswiki/pub-htaccess.txt	foswiki/pub/.htaccess
  foswiki/subdir-htaccess.txt	foswiki/<subdir>/.htaccess Copy to all other subdirectories below foswiki, including data, lib, locale, templates, tools, working. Copy to any other directories except for bin and pub addressed above.

• Ensure that web access is denied to all Foswiki subdirectories other than bin and pub. The sample .htaccess files show how to configure Apache appropriately. It is important to verify that none of these directories can be directly accessed.
• Ensure that the foswiki/bin/.htaccess files contains the line SetHandler cgi-script so that all scripts in the bin directory will be executed by Apache.
• Note: On Linux systems, files named with the leading "." like .htaccess are hidden files and will not be listed unless using the -a option, ex. ls -la

Protect the configure script!

• Caution! Do not follow these steps on an existing Foswiki .htpasswd file. It will destroy the email addresses stored in that file! If the file already exists, you can choose an existing user for access to configure.
• Change to the foswiki/data directory.
• Issue the command htpasswd -c .htpasswd <username>, where <username> is the name of the user you will use to access the configure script. Choose the username with care: the username cannot be an existing login name for your Foswiki installation, nor can it be used later on to register in Foswiki. Enter a password when prompted.

<FilesMatch "configure.*">
    SetHandler cgi-script
    Order Deny,Allow
    Deny from all
    # List of IP addresses allowed to access configure
    Allow from 127.0.0.1 192.168.1.10
    # specify username used on the "htpasswd" command above
    Require user someuserid
    # Set to "Any" to allow IP -or- userid,  set to "All" to require both match
    Satisfy Any
    ErrorDocument 401 default
</FilesMatch>

Tip: You do not have to use the same password file for both Configure and for Foswiki user registration. If you use a separate file, you can create it using the htpasswd commmand and complete segregate configure access from Foswiki access. This is probably safer, but does not allow users to change their configure password using Foswiki services. The password file has to be manually maintained..

1. Generate an alternate password file to protect configure. htpasswd -c -s /path/to/data/.htpasswd-admin configuserid
2. Add / modify and delete this alternate file using the htpasswd command. Don't mix them up and use htpasswd on the Foswiki .htpasswd file!
3. Edit the foswiki apache configuration and modify the block (shown above) that protects the configuration command. Add or modify the following statements in the block. Don't remove the other statements!

<FilesMatch "configure.*">
        AuthType Basic
        AuthName "admins only"
        AuthUserFile /path/to/data/.htpasswd-admin
        # Changing the Require user to Require valid-user allows any ID in the
        # file access to configure!
        Require valid-user
</FilesMatch>

Configure Foswiki

• When you access the configure web page for the first time, you can only edit the section General Path Settings. Make any required changes, and save the settings, whether or not you needed to make any changes. You will be prompted to set a password for the configure page: this password must be entered for all subsequent configuration changes, and is also used to log in via the internal admin link (see the section "Define the administrator user(s)").

  Note: The configure password is remembered by configure, separate to web server access controls mentioned in "Protect the configure script".

• After saving the General Path Settings, continue configuring Foswiki. Configuration items which may require further attention will be highlighted.
• If the Foswiki installation can be accessed by more than one protocol://domain, ensure the additional alternative URLs are set in {PermittedRedirectHostUrls}.

  Example: if {DefaultUrlHost} is set to https://wiki.company.com, an example {PermittedRedirectHostUrls} might contain:

  https://company.com, http://111.222.123.234

• Setup the Mail and Proxies section. Email must be available so Foswiki can send registration emails.
  • Under the "Email General" tab, If you do not want to enable sending registration emails or want to enable it later you can uncheck {EnableEmail}. Otherwise the {WebMasterEmail} parameter must be configured.
  • Under the "Email Server" tab, you can choose 3 methods of sending email. This is explained in detail under the help text for this tab.
    • MailProgram is typically suitable on most Linux systems, and no further configuration is required.
    • If you chose either of the Net::SMPT methods, you must also configure {SMTP}{MAILHOST}. Many ISPs have introduced authentication when sending emails to fight spam so you may also have to set {SMTP}{Username} and {SMTP}{Password}.
    • Net::SMTP::SSL will encrypt the connection to the e-mail server and is required for some email services like Google's GMail.
  • Under the "Proxy" tab, if your server is behind a firewall with a proxy, and you wish to install extensions via configure, you may have to set {PROXY}{HOST} and {PROXY}{PORT}.

    Note: A standard Foswiki installation will not allow any new registrations unless there is a working SMTP configuration

    SMTP authentication requires additional perl modules including Authen::SASL and MIMI::Base64,

Authentication

• 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:
   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 also 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.

2. Verify that registration works by registering yourself with the System.UserRegistration topic. If there are problems, try these troubleshooting tips:
   1. If you are reading this from the INSTALL.html file, you can enter System.UserRegistration into the 'Jump' box in the top right of any Foswiki page.
   2. Note: A standard Foswiki installation will not allow any new registrations unless there is a working SMTP configuration
   3. 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.
3. Create a new topic (in Sandbox web for example) to confirm that authentication works.
4. 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.

Foswiki AccessControls do not protect topic attachments unless the web server has been configured to do so using the viewfile script. Visit Foswiki:Support.ApacheConfigGenerator for examples using Apache.

As Template Login uses a wiki page for its login prompt, there is a great deal of flexibility in customizing the login page for your purposes.

The default new user template page is in System.NewUserTemplate. The same macros get expanded as in the template topics. You can create a custom new user topic by creating the NewUserTemplate topic in Main web, which will then override the default in System web. See System.UserForm for copy instructions.

Custom registration page

Automatic Group Membership

• Automatically enrolling users in one or more groups during registration
• Allow the user to select multiple groups from a list of eligible groups
• Allow the user to choose only one group from a list of eligible groups
• Don't do any group enrollment during registration.

• Manually by configuration. This fixed list of groups will always be listed.
• Automatically based upon CHANGE permission on the group topics.

Self-registration by Guest users

The actual registration will be processed by the special internal user Main.RegistrationAgent. Group topics must include an ALLOWTOPICCHANGE = Main.RegistrationAgent to be eligible for enrollment.

Registration by logged-in users

The registration form is filled out by some other logged-in user. In this case, the Main.RegistrationAgent is not used for Group updates. The current user must have ALLOWTOPICCHANGE permission for groups for them to be eligible for enrollment.

• Caution: If an administrator registers a user with automatic group membership enabled, the new user could potentially be added to All groups. Use caution with this feature!

Apache Login authentication

Do not use the Apache htpasswd program with .htpasswd files generated by Foswiki! htpasswd wipes out email addresses that Foswiki plants 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:

       <FilesMatch "(attach|edit|manage|rename|save|upload|mail|logon|rest|.*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.
2. Verify that registration works by registering yourself with the System.UserRegistration topic. If there are problems, try these troubleshooting tips:
   1. If you are reading this from the INSTALL.html file, you can enter System.UserRegistration into the 'Jump' box in the top right of any Foswiki page.
   2. Note: A standard Foswiki installation will not allow any new registrations unless there is a working SMTP configuration
   3. 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.
3. Create a new topic (in Sandbox web for example) to confirm that authentication works.
4. 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.

Choose an appropriate search algorithm for your Operating System

Define the administrator user(s)

About Administrators

• Users with Admin rights will have routine access to topics that might normally be denied.
• These users will be unable to test or demonstrate access controls.
• Changes made are always attributed to a unique logged in user.
• Password sharing of the bin/configure password is not required

• You don't need to grant admin rights to individual users
• All users will be subject to access controls.
• Changes made while using the internal admin login are attributed to Main.AdminUser
• The "save" password for bin/configure will need to be shared among administrators

Adding users to the Main.AdminGroup

• If you are not already logged in with your WikiName, then login.
• Go to the Main.AdminGroup topic and select the "internal admin login" link. Login using the password you set on the configure page.
• After logging as the internal admin, view the Main.AdminGroup topic. Follow the instructions on the page to add users to the AdminGroup. You do not need to edit the topic.

Congratulations!

Troubleshooting

• Re-run the configure script and make sure you have resolved all errors and are satisfied that you understand any warnings.
• Follow the steps detailed in FAQTroubleshootingExtensions
• Failing that, consult the topics at Foswiki:Support.SupplementalDocuments and Foswiki:Support.AskedQuestions.
• If you need help, ask a question in the Foswiki:Support web or on Foswiki:Community.InternetRelayChat (irc.freenode.net, channel #foswiki).

Foswiki system requirements

Server requirements

CPAN modules

Module	Preferred version	Required/Optional	Description
Algorithm::Diff		Required	Included with Foswiki
CGI	Versions 2.89, 3.37, 3.43, and 3.47 must be avoided. Most versions from 3.15 and onwards should work.	Required	Included with Perl core since Perl 5.4
Error		Required	Included with Foswiki
Apache::Htpasswd		Optional	May be required for ApacheHtpasswd password manager
Archive::Tar		Optional	May be required by the Extensions Installer in configure if command line tar or unzip is not available, since Perl 5.9.3 part of core.
Archive::Zip		Optional	Alternative to Archive::Tar, used by the Extensions Installer if Archive::Tar also unavailable
CGI::Session		Optional	Required for Sessions support, available from the CPAN archive
Digest::SHA		Optional	May be required for password encryption, since Perl 5.9.3 part of core
Digest::SHA1		Optional
Encode::compat		Optional	May be required for international characters
HTML::Entities		Optional	Required for Foswiki:Extensions.WysiwygPlugin
HTML::Parser		Optional	Required for Foswiki:Extensions.WysiwygPlugin
Lingua::EN::Sentence		Optional	May be required for generating new language files
Locale::Maketext::Lexicon	>=0	Optional	Used for I18N support
LWP		Optional	Required for the Configure Extensions Installer, and for external URL based INCLUDEs
URI		Optional	Required by the configure script
Win32::Console		Optional	May be required for Windows

perl -le 'use ModuleName; print "ModuleName"->VERSION' 

Client requirements

• HTML 3.2
• Cookie support enabled, if persistent sessions are required

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

Configuring Foswiki manually (without using the configure page)

• Copy the file lib/Foswiki.spec to lib/LocalSite.cfg
• Remove the # in front of the following settings, and ensure that they are set to the correct values: Note: The settings must not reference other $Foswiki::cfg variables.

     $Foswiki::cfg{DefaultUrlHost}
     $Foswiki::cfg{ScriptUrlPath}
     $Foswiki::cfg{ScriptDir}
     $Foswiki::cfg{PubUrlPath}
     $Foswiki::cfg{PubDir}
     $Foswiki::cfg{DataDir}
     $Foswiki::cfg{ToolsDir}
     $Foswiki::cfg{TemplateDir}
     $Foswiki::cfg{LocalesDir}
     $Foswiki::cfg{WorkingDir}
     $Foswiki::cfg{OS}

• Make sure the following settings are defined:

     $Foswiki::cfg{LoginManager}
     $Foswiki::cfg{WebMasterEmail}
     $Foswiki::cfg{SMTP}{MAILHOST}
     $Foswiki::cfg{SMTP}{SENDERHOST}

• Remove the line containing __END__ and everything following it.

Beyond the basic installation

Site configuration and maintenance

Set Foswiki Preferences

Select the desired security level

Enable Email Notification

1. Confirm the Mail and Proxies settings on the configure page.
2. Setup a cron job (or equivalent) to call the tools/mailnotify script, as described in the System.MailerContrib topic.

Enable Signed Email Notification

1. Enable e-mail as described above
2. Ensure that the system has the CPAN module Crypt::SMIME installed.
3. If necessary, convert your certificate and key files to PEM format ( openssl has all the necessary utilities)
4. Place the certificate anyplace convenient that the webserver can read. It should be protected against write. The conventional place under linux is /etc/pki/tls/certs
5. Place the key file in a secure location that only the webserver (or CGI user) can read. It must not be readable by anyone else, and must not be served by the webserver.
6. Using the configure script, change the following settings under Mail and Proxies:
   1. "Email Server" tab. Follow the directions under {MailMethod} and {MailProgram} to enable an external mail program such as sendmail. Net::SMTP is not supported.
      • {SMTP}{MAILHOST}, {SMTP}{SENDERHOST}, {SMTP}{Username} and {SMTP}{Password} are not used an may be deleted.
      • If Foswiki variable SMTPMAILHOST is defined in Main.SitePreferences it should be removed.
   2. "S/MIME" tab:
      • Enable the S/MIME checkbox
      • Enter the full path to the certificate file in the {SmimeCertificateFile} configuration variable
      • Enter the full path to the private key file in the {SmimeKeyFile} configuration variable
   3. Save the configuration
7. Re-run the configure script an resolve any errors that it identifies

Automate removal of expired sessions and lease files

Enable WebStatistics

Enable Localisation

Customizing your site

Customize pages for managing personal information

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

Customize the user topic for new users

• Customize the user topic for your site.
• Add an ALLOWTOPICCHANGE preference setting to Main.NewUserTemplate so only the user can edit their own user topic. In particular, on a public Foswiki site, restricting edit access will avoid vandalism and spam.
• Add and remove fields defined in the Main.UserForm.

Customize the appearance of your Foswiki site

Left, Top and Bottom Bars with PatternSkin

Copyright, License and Classification Statements

• Copy the WEBCOPYRIGHT preference setting from System.DefaultPreferences to Main.SitePreferences. Change the value to your desired text. This value will be your new default across all webs.
• You can create a unique message for a specific web by setting the WEBCOPYRIGHT preference in the WebPreferences topic for the given web. For example, you could add a confidential classification to a web that has restricted access.
• The WEBCOPYRIGHT preference setting in System.WebPreferences covers the documentation that comes with Foswiki, and should not be changed.

WYSIWYG vs Raw Edit

Extensions

• Plugins extend Foswiki functionality without altering the core code.
• Skins Skins overlay regular templates to give different looks and feels to Foswiki screens.
• Contribs and AddOns are any other Extension that provides added functionality beyond Plugins and Skins

Installing extensions

• the configure web interface
• the generic shell installer tools/extension_installer
• by manually downloading the extension zip or tar file

• Even if available, local Extension installers and archives are not used
• The extension is downloaded from the configured archive
  • The latest version of the Extension is always downloaded. There is no automatic means of downloading older versions.
• If the extension is already installed, a backup is taken to the working/configure/backup directory
• Dependencies on other Extensions are automatically resolved and installed
  • Dependencies are downloaded from the same archive where the Extension was found. No additional searching is performed.
• The Extension is installed.
  • By default, unless a collsion occurrs with an existing file, the Extension's topics will not be checked in to the revision control system.
  • If previous topics or attachments are found, then the topic will be checked in under the Administrators user id.
  • If the topics or attachments are flagged as !noci, disabling checkin, they will still be checked in if existing revision control files are found, suggesting that local modifications have occurred.
• CPAN dependencies and other external packages are not resolved and should be resolved manually

• The _installer package must be run from the root directory of the Foswiki installation.
• The Extension _installer module must be downloaded from the Extension repository. The extension archive will be downloaded if required.
• When the _installer is run, it will install the Extension and dependencies similar to the configure interface except:
  • You will be given the option to use local archives if available in the root of the Foswiki installation
  • You will be given the option to resolve CPAN dependencies after the Extensions and dependencies are installed.
  • Any other dependencies still need to be manually resolved.

• After installation, the Extension _installer module is saved in working/configure/pkgdata
• A complete log of the actions taken by the installer is saved in working/logs/configure/[NameOfExtension]-yyyymmdd-hhmmss-[Action].log

perl working/configure/pkgdata/X509UserPlugin_installer usage

Usage as a custom installer:

       X509UserPlugin_installer -a -n -d -r -u -c install
       X509UserPlugin_installer -a -n uninstall
       X509UserPlugin_installer manifest
       X509UserPlugin_installer dependencies

Usage as a generic installer:

       tools/extension_installer X509UserPlugin -a -n -d -r -u -c install
       tools/extension_installer X509UserPlugin -a -n uninstall
       tools/extension_installer X509UserPlugin manifest
       tools/extension_installer X509UserPlugin dependencies

If command (install, uninstall ..) is not provided, default is to 
install the extension.

Operates on the directory tree below where it is run from,
so should be run from the top level of your Foswiki installation.

Depending upon your installation, you may need to execute perl directly
  perl tools/extension_installer ...   or
  perl X509UserPlugin_installer ...

"install" will check dependencies and perform any required
post-install steps.

"uninstall" will remove all files that were installed for
X509UserPlugin even if they have been locally modified.

-a means don't prompt for confirmation before resolving
   dependencies
-d means auto-download if -a (no effect if not -a)
-r means reuse packages on disc if -a (no effect if not -a)
-u means the archive has already been downloaded and unpacked
-n means don't write any files into my current install, just
   tell me what you would have done
-c means don't try to use CPAN to install missing libraries

"manifest" will generate a list of the files in the package on
standard output. The list is generated in the same format as
the MANIFEST files used by BuildContrib.

"dependencies" will generate a list of dependencies on standard
output.

Removing (uninstalling) extensions

Caution: When removing an extension, no dependency checking is performed.

• Dependencies are not removed
• Other Extensions dependent on the removed extension may become non-operational.

• The _installer package is used to recover the manifest. If it cannot be found locally, it will be downloaded from the configured extension repository
• A backup of the previously installed files per the manifest will be taken to the configure/working/backup directory
  • Note: If download of the _uninstaller was required, the backup will be made per the current installer's manifest. It is preferable to always save the _installer modules.
• The Extension files along with any ,v revision control files will be removed, including the _installer.
  • Any additional files saved locally are not removed.
• A complete log of the steps taken is saved in working/logs/configure/[NameOfExtension]-yyyymmdd-hhmmss-[Action].log

• Plugin modules are not automatically disabled in the configuration - they must be disabled manually.

Restoring a removed, or previous version of an extension

cd /root/of/foswiki
tar -zxvf * working/configure/backup/[Extension}-backup-[yyyymmdd]-[hhmmss].tgz
# or
unzip working/configure/backup/[Extension}-backup-[yyyymmdd]-[hhmmss].zip

TWiki Compatibility

Web Acceleration (mod_perl, FastCGI, ...)

• Ensure your site is fully configured and working before enabling either of these extensions. They can be challenging to configure.
• The ApacheConfigGenerator will help creating a valid configuration for these accelerators.
• Enabling the apache configuration without installing the pre-req modules and extensions will break your site!
• The core default extensions are well tested with web acceleration, other extensions can exhibit inconsistent behaviour when accelerated.

Foswiki Upgrade Guide

Overview

Upgrade requirements

• Please review the Foswiki:System.AdminSkillsAssumptions before you upgrade your site.
• To upgrade from an old TWiki Release to the latest Foswiki production release, follow the instructions below.
• Before upgrading, you may wish to make a backup of your topics.
• 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.
• Some TWiki plugins are not compatible with Foswiki (usually ones that use a private API or execute helper scripts); you may need to migrate to the equivalent extension in the Foswiki:Extensions repository.

Upgrading from TWiki to Foswiki

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.

Upgrade procedure: upgrading to a new major or minor version, or upgrading from TWiki

1. Prepare for all upgrade steps.
2. Install the new Foswiki version and configure it with the same settings as the old version.
3. Install any additional extensions (Plugins) used by your old installation. Make sure to use the latest Foswiki versions.
4. Copy all the non-default webs from the old installation to the new one.
5. Copy the users, groups, and site customizations from the old installation to the Main web in the new installation, including all user topics.
6. Apply preferences from the old installation.
7. Apply your site customizations: skin, logos, menu bars, forms for personal information, and so forth.
8. Validate your Wiki applications and other key functionality.
9. Switch your production site from the old installation to the new installation.

   Managing caches of static .js, .css files: some parts of Foswiki use URI versioning to help web browsers obtain a current version of these files when they change, but currently other parts do not. You may need to get your users to clear their browser's cache after upgrading your site to a new major or minor release (usually not necessary for patch upgrades). An alternative approach is to manage your web server configuration to strategically set appropriate expiry times for static files (see performance supplement)

• <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; in TWiki, the default value is the TWiki web. The web is specified in the Store settings pane of the configure page, in the {SystemWebName} setting (visible when Expert mode is enabled).

Prepare for all upgrade steps

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.
  • 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. Alternatively, you can reconfigure the new installation from scratch (you can use your old LocalSite.cfg file as a reference).
  • If you are upgrading from a TWiki site, you must reconfigure your Foswiki installation from scratch. You cannot copy over your old LocalSite.cfg file (though you can use it as a reference). Run configure and set the configuration values in the new installation to match those of the old installation.
  • 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 run configure.
• Additional resources
  • Foswiki:System.InstallationGuide
  • Foswiki:Support.InstallingOnSpecificPlatforms
  • Foswiki:Support.ApacheConfigGenerator
  • Foswiki:Support.SettingFileAccessRightsLinuxUnix

Install extensions

• Note: some TWiki extensions may not work with Foswiki. By default, the TWikiCompatibilityPlugin is installed to provide backwards compatible support for TWiki plugins. However if the TWiki plugin calls private APIs or invokes helper scripts, it may still not work correctly. Check for an upgraded Foswiki version of the extension in the Foswiki:Extensions repository and install it instead.

• CommentPlugin - DEFAULT_TYPE
• EditTablePlugin - CHANGEROWS, QUIETSAVE, EDITBUTTON
• InterwikiPlugin - RULESTOPIC
• InterWikis - If you added your own rules, make sure you copy over the rules to the new installation.
• SlideShowPlugin - If you changed the embedded 'Default Slide Template', then copy your customed 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 content from non-default webs in old installation to the new installation

• find data -name '*,v' -exec rcs -u -M '{}' \;
• find pub -name '*,v' -exec rcs -u -M '{}' \;

• 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.

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

• 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.
    • The default admin group with Foswiki is AdminGroup and the default admin group with TWiki is TWikiAdminGroup. So if you are upgrading from TWiki and are using the default admin groups, then in the new installation, you must copy all members from TWikiAdminGroup to AdminGroup, and change TWikiAdminGroup so its only member is AdminGroup and so it can only be modified or renamed by AdminGroup.
• 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.

• 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.

• Manually merge all users from the <old_users_web>.TWikiUsers 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>/TWikiUsers.txt to <newwiki>/data/Main/WikiUsers.txt, and manually add the required default users (see the next steps).
• 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 are upgrading from Cairo and are using the Htpasswd login manager, run the tools/upgrade_emails.pl script to move the user emails out of the user topics and into the password file.
• If you have customized <old_system_web>.TWikiRegistration, then modify System.UserRegistration in the new installation to contain your customizations.

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

• 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.

Additional steps when upgrading from TWiki Cairo

Favicon

Important changes since TWiki 4.0.5

Supported Perl version

Template spec changed

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

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

Important changes for the upgrader - since TWiki 4.1.0

New location for session and other temporary files

Important changes for the upgrader - since TWiki 4.1.2

New WYSIWYG editor

NEWTOPICLINKSYMBOL removed

UserForm and NewUserTemplate customization

WikiUsers no longer distributed

New working directory

• registration_approvals — previously located in the data/ directory
• tmp — avoids security issues with using the /tmp directory
• work_areas — previously located in the pub/ directory.

New internal admin login

Important changes for the upgrader - since Foswiki 1.0.4

<form name="new" action="%SCRIPTURLPATH{"save"}%/Sandbox/" method="post">
    ...
</form>

Important changes for the upgrader - since Foswiki 1.0.5

• {Validation}{Method} is by default "strikeone" which is the highest level of security and requires that users have Javascript enabled. You can lower this setting to "embedded" which uses a less safe validation method but does not require javascript. If you want to disable CSRF protection set it to "none". It is highly recommended to keep it at "strikeone".
• {Validation}{ValidForTime} is the time the validation key is valid. It is by default 1 hour. If your users often edit pages longer you can increase this time. Your users can still save pages with an expired validation key but they will be asked to confirm the saving.
• {Validation}{MaxKeysPerSession} is the maximum number of validation keys to store in a session. There is one key stored for each page rendered. If the number of keys exceeds this number, the oldest keys will be force-expired to bring the number down. If you have users that are very fast at editing pages and experience expired keys, you can increase this number. The default is 1000 and should be much higher than any normal person will experience.
• {Validation}{ExpireKeyOnUse} defines if validation keys expire when they are used for storing data. This prevents an attacker from evesdropping communication between server and browser and reuse keys. Unfortunately it also means that if a user edits a page, saves it, uses the back button of the browser, corrects his previous editing, and then saves again, he is asked to confirm that he intended to save the topic. Another use case is if you create an application with multiple forms and multiple submit buttons on a topic and you submit multiple times from this topic without navigating away from it, you will be asked to confirm the submission each time. If this is not acceptable to your use of Foswiki, you can turn off {Validation}{ExpireKeyOnUse}.

User Authentication

Overview

• You are guest, Main.WikiGuest,

Password Management

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

User Mapping

User Registration

Login Management

No Login (select none)

Note: This setup is not recommended on public websites for security reasons; anyone would be able to change system settings and perform tasks usually restricted to administrators.

Template Login (select Foswiki::LoginManager::TemplateLogin)

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:
   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 also 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.

2. Verify that registration works by registering yourself with the System.UserRegistration topic. If there are problems, try these troubleshooting tips:
   1. Note: A standard Foswiki installation will not allow any new registrations unless there is a working SMTP configuration
   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.
3. Create a new topic (in Sandbox web for example) to confirm that authentication works.
4. 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.

Foswiki AccessControls do not protect topic attachments unless the web server has been configured to do so using the viewfile script. Visit Foswiki:Support.ApacheConfigGenerator for examples using Apache.

As Template Login uses a wiki page for its login prompt, there is a great deal of flexibility in customizing the login page for your purposes.

The default new user template page is in System.NewUserTemplate. The same macros get expanded as in the template topics. You can create a custom new user topic by creating the NewUserTemplate topic in Main web, which will then override the default in System web. See System.UserForm for copy instructions.

Custom registration page

Automatic Group Membership

• Automatically enrolling users in one or more groups during registration
• Allow the user to select multiple groups from a list of eligible groups
• Allow the user to choose only one group from a list of eligible groups
• Don't do any group enrollment during registration.

• Manually by configuration. This fixed list of groups will always be listed.
• Automatically based upon CHANGE permission on the group topics.

Self-registration by Guest users

The actual registration will be processed by the special internal user Main.RegistrationAgent. Group topics must include an ALLOWTOPICCHANGE = Main.RegistrationAgent to be eligible for enrollment.

Registration by logged-in users

The registration form is filled out by some other logged-in user. In this case, the Main.RegistrationAgent is not used for Group updates. The current user must have ALLOWTOPICCHANGE permission for groups for them to be eligible for enrollment.

• Caution: If an administrator registers a user with automatic group membership enabled, the new user could potentially be added to All groups. Use caution with this feature!

Enabling Apache Login

Do not use the Apache htpasswd program with .htpasswd files generated by Foswiki! htpasswd wipes out email addresses that Foswiki plants 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:

       <FilesMatch "(attach|edit|manage|rename|save|upload|mail|logon|rest|.*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.
2. Verify that registration works by registering yourself with the System.UserRegistration topic. If there are problems, try these troubleshooting tips:
   1. Note: A standard Foswiki installation will not allow any new registrations unless there is a working SMTP configuration
   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.
3. Create a new topic (in Sandbox web for example) to confirm that authentication works.
4. 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.

Logons via bin/logon

Sessions

Getting, Setting, and Clearing Session Variables

%SESSION_VARIABLE{ "varName" }%
%SESSION_VARIABLE{ "varName" set="varValue" }%
%SESSION_VARIABLE{ "varName" clear="" }%

Access controls cannot be modified in this way

Cookies and Transparent Session IDs

Username vs. Login Username

• Login Username: When you login to the intranet, you use your existing login username. This name is normally passed to Foswiki by the REMOTE_USER environment variable, and used internally. Login Usernames are maintained by your system administrator.

• Foswiki Username: Your name in WikiNotation, ex: JohnSmith, is recorded when you register using UserRegistration; doing so also generates a personal home page in the Main web.

NOTE: To correctly enter a WikiName - your own or someone else's - be sure to include the Main web name in front of the Wiki username, followed by a period, and no spaces, for example Main.WikiUsername or %USERSWEB%.WikiUsername. This points WikiUsername to the Main web, where user home pages are located, no matter which web it's entered in. Without the web prefix, the name appears as a NewTopic everywhere but in the Main web.

Changing Passwords

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

Changing E-mail Addresses

• The ChangeEmailAddress form ( Foswiki/ChangeEmailAddress )

Controlling access to individual scripts

• For Template Login, update the {AuthScripts} list using configure
• For Apache Login, add/remove the script from bin/.htaccess, or from the FilesMatch line in the Apache configuration.

How to choose an authentication method

Access Control

An important consideration

• Peer influence is enough to ensure that only relevant content is posted.
• Peer editing - the ability for anyone to rearrange all content on a page - keeps topics focused.
• In Foswiki, content is transparently preserved under revision control:
  • Edits can be undone by the administrator (per default a member of Main.AdminGroup; see #ManagingGroups).
  • Users are encouraged to edit and refactor (condense a long topic), since there's a safety net.

Permissions settings of the webs on this Foswiki site

Authentication vs. Access Control

Users and groups

Managing Users

• WikiName, encrypted password and email address are recorded using the password manager if authentication is enabled.
• A confirmation e-mail is sent to the user.
• A user home page with the WikiName of the user is created in the Main web.
• The user is added to the Main.WikiUsers topic.
• Optionally the user is added to one or more groups.

Your local Foswiki may have an alternate user mapping manager installed which doesn't support user registration. Check with your Wiki administrator if you are in doubt.

Managing Groups

• Set ALLOWTOPICCHANGE = Main.KasabianGroup
  • Caution This is set in the "Topic Settings" and not inline in the topic text!

Foswiki has strict formatting rules. Make sure you have three spaces, an asterisk, and an extra space in front of any access control rule. See below for more information about ALLOWTOPICCHANGE.

Background: A group topic is an empty topic with 3 hidden preference settings.

• GROUP: Comma separated list of users and/or groups
• ALLOWTOPICCHANGE: Comma separated list of users and groups that are allowed to add and remove users from the group
• VIEW_TEMPLATE: Always set to the value GroupView. This alters the way the topic is presented to include a nice user interface for adding and removing users.

Foswiki 1.1 introduced the smart user interface for adding and removing members of a group. Group topics from prior versions of Foswiki will still work. These have the GROUP setting visible in the topic text itself and you edit it by editing the topic. Foswiki 1.1 Main.WikiGroups will show these old group topics with an "Upgrade Group Topic button". The administrator can upgrade an old group topic to the nice new user interface with one easy click.

The Super Admin Group

• Set GROUP = Main.ElizabethWindsor, Main.TonyBlair

Restricting Access

• Restricting VIEW blocks viewing and searching of content. When you restric VIEW to a topic or web, this also restricts INCLUDE and Formatted SEARCH from showing the content of the topics.
• Restricting CHANGE blocks creating new topics, changing topics or attaching files.
• Restricting RENAME prevents renaming of topics within a web.

There is an important distinction between CHANGE access and RENAME access. A user can CHANGE a topic, but thanks to version control their changes cannot be lost (the history of the topic before the change is recorded). However if a topic or web is renamed, that history may be lost. Typically a site will only give RENAME access to administrators and content owners.

Note that ALLOWWEBxxx and DENYWEBxxx preferences can only be set in WebPreferences topics. You cannot define a site level access. Each web must be protected on their own. Subwebs inherit access settings from the parent web. See next section.

Note that ALLOWTOPICxxx and DENYTOPICxxx preferences apply only to the topic itself.

Be warned that some plugins may not respect access permissions.

FINALPREFERENCES affects access controls, allowing you to prevent changes to access control settings while still allowing edit access to topics.

Controlling access to a Web

• authenticating all webs and restricting selected webs: Topic access in all webs is authenticated, and selected webs have restricted access.
• authenticating and restricting selected webs only: Provide unrestricted viewing access to open webs, with authentication and restriction only on selected webs.

• You can define these settings in the WebPreferences topic, preferable towards the end of the topic:
  • Set DENYWEBVIEW = < comma-delimited list of users and groups >
  • Set ALLOWWEBVIEW = < comma-delimited list of users and groups >
  • Set DENYWEBCHANGE = < comma-delimited list of users and groups >
  • Set ALLOWWEBCHANGE = < comma-delimited list of users and groups >
  • Set DENYWEBRENAME = < comma-delimited list of users and groups >
  • Set ALLOWWEBRENAME = < comma-delimited list of users and groups >

Controlling access to a topic

• You can define these settings in any topic, preferable towards the end of the topic:
  • Set DENYTOPICVIEW = < comma-delimited list of users and groups >
  • Set ALLOWTOPICVIEW = < comma-delimited list of users and groups >
  • Set DENYTOPICCHANGE = < comma-delimited list of users and groups >
  • Set ALLOWTOPICCHANGE = < comma-delimited list of users and groups >
  • Set DENYTOPICRENAME = < comma-delimited list of users and groups >
  • Set ALLOWTOPICRENAME = < comma-delimited list of users and groups >

Caution! Settings are always taken from the latest (current) revision of a topic. If older revisions of a topic had more restrictive access controls, they will not be used when accessing the older revision.

• Set ALLOWTOPICVIEW =
  This means the same as not setting it at all. (This was documented wrong in versions 4.0.X, 4.1.0 and 4.1.1)

• Set DENYTOPICVIEW =
  This means do not deny anyone the right to view this topic. If DENYTOPICVIEW is set to an empty value anyone has access even if ALLOWTOPICVIEW or ALLOWWEBVIEW is defined. This allows you to have very restrictive default access rights to an entire web and still allow individual topics to have more open access.

If the same setting is defined multiple times the last one overrides the previous. They are not OR'ed together.

Setting to an empty value has caused confusion and great debate and it has been decided that the empty setting syntax will be replaced by something which is easier to understand in a later version of Foswiki. A method to upgrade will be provided. Please read the release notes carefully when you upgrade.

Controlling access to attachments

    ScriptAlias /foswiki/bin/ /filesystem/path/to/bin/
    Alias /foswiki/pub/       /filesystem/path/to/pub/

    RewriteEngine on
    RewriteCond %{REQUEST_URI} !^/+foswiki/+pub/+System/+.+
    RewriteRule ^/+foswiki/+pub/+([^/]+)((/+([^/]+))+)/+(.+) /foswiki/bin/viewfile/$1/$2?filename=$5 [L,PT]

Images embedded in topics will load much slower since each image will be delivered by the viewfile script.

Controlling who can manage top-level webs

• You can define these settings in the Main.SitePreferences topic, preferably towards the end of the topic:
  • Set DENYROOTCHANGE = < comma-delimited list of users and groups >
  • Set ALLOWROOTCHANGE = < comma-delimited list of users and groups >

How Foswiki evaluates ALLOW/DENY settings

Settings are only read from the most current (latest) revision of a topic. Settings from older revisions are never used, even when viewing an older revision with the rdiff script

1. If the user is an administrator
   • access is PERMITTED.
2. If DENYTOPIC is set to a list of wikinames
   • people in the list will be DENIED.
3. If DENYTOPIC is set to empty ( i.e. Set DENYTOPIC = )
   • access is PERMITTED i.e no-one is denied access to this topic.
     

     Attention: Use this with caution. This is deprecated and will likely change in the next release.

4. If ALLOWTOPIC is set
   1. people in the list are PERMITTED
   2. everyone else is DENIED
5. If DENYWEB is set to a list of wikinames
   • people in the list are DENIED access
6. If ALLOWWEB is set to a list of wikinames
   • people in the list will be PERMITTED
   • everyone else will be DENIED
7. If you got this far, access is PERMITTED

Access control and INCLUDE

• If the included topic B has ALLOWTOPICCHANGE set to block editing for a user, it does not prevent editing the including topic A.
• If the included topic B has ALLOWTOPICVIEW set to block view for a user, the user can still view topic A but he cannot see the included topic B. He will see a message No permission to view B

Access control quick recipes

Obfuscating webs

• Prevents the all webs search option from accessing the web
• Hides the web from the %WEBLIST% macro.

   * Set NOSEARCHALL = on

Setting NOSEARCHALL to any value other than the empty string will hide a web. Setting NOSEARCHALL = off will have the same effect as setting it to on

Obfuscating a web without setting view access control is very insecure, as anyone who knows the URL can access the web, and explicit searches naming that web will also work. For security purposes it is better to use the ALLOW or DENY VIEW settings in the WebPreferences topic. %SEARCH% and %WEBLIST% will not show any results for webs that the current user does not have permission to view.

Restrict Access to a whole Foswiki site

With this configuration, someone with access to the site needs to register new users. ResetPassword will also have to be done by administrators.

When using Apache Login

• lock down access to the whole bin and pub directories to all but valid users. In the Apache .htaccess file or the appropriate .conf file, replace the <FilesMatch "(attach|edit|... section with this:

<FilesMatch ".*">
       require valid-user
</FilesMatch>

When using Template Login

• Add all scripts in the foswiki/bin directory (except for login, logon and configure) to the list of {AuthScripts} in configure. For a default Foswiki installation:

• Default (open) site:

{AuthScripts} = 'attach,compareauth,edit,manage,previewauth,rdiffauth,rename,rest,restauth,save,statistics,upload,viewauth,viewfileauth';

• Restricted (closed) site:

{AuthScripts} = 'attach,changes,compare,compareauth,edit,manage,oops,preview,previewauth,rdiff,rdiffauth,register,rename,resetpasswd,rest,restauth,save,search,statistics,upload,view,viewauth,viewfile,viewfileauth

If you install extensions that add scripts, you must also remember to add the new scripts to this list or the new scripts will not be protected.

Authenticate all webs and restrict selected webs

1. The simple way is to add this to WebPreferences in all webs.
   • Set DENYWEBVIEW = WikiGuest
2. Restrict view access to selected users and groups. Set one or both of these settings in its WebPreferences topic:
   • Set ALLOWWEBVIEW = < list of users and groups >
   • Note: DENYWEBVIEW is evaluated before ALLOWWEBVIEW. Access is denied if the authenticated person is in the DENYWEBVIEW list, or not in the ALLOWWEBVIEW list. Access is granted if DENYWEBVIEW and ALLOWWEBVIEW are not defined.

1. Set require valid-user on your view script in .htaccess or the appropriate Apache .conf file. This looks like: FilesMatch "(attach|edit|manage|rename|save|view|upload|mail|logon|.*auth).*" (normally view is not in that list).

Authenticate and restrict selected webs only

1. Restrict view access to selected users and groups. Set one or both of these settings in its WebPreferences topic:
   • Set DENYWEBVIEW = < list of users and groups >
   • Set ALLOWWEBVIEW = < list of users and groups >
   • Note: DENYWEBVIEW is evaluated before ALLOWWEBVIEW. Access is denied if the authenticated person is in the DENYWEBVIEW list, or not in the ALLOWWEBVIEW list. Access is granted if DENYWEBVIEW and ALLOWWEBVIEW are not defined.

Show control settings

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

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

Hide control settings

<!-- 

   * Set DENYTOPICCHANGE = Main.SomeGroup 

-->

Text Formatting

Editing Shorthand

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.	---++ 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 _
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 System.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
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...	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.
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 System.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 |	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
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, %SANDBOXWEB% and Main.	WebStatistics %SANDBOXWEB%.WebNotify %SANDBOXWEB%.WebHome %SANDBOXWEB%.Subweb.TopicName	WebStatistics %SANDBOXWEB%.WebNotify %SANDBOXWEB%.WebHome TopicName
Acronym Links: Words that are all capitals will produce a link automatically only if the topic aready exists!.	ACRONYM System.ACRONYM	ACRONYM System.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 syntax]] links to topic WikiSyntax. 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]] [[%SANDBOXWEB%.My unspaced topic]] escaped: ![[wiki syntax]]	wiki syntax Main.Wiki groups escaped: [[wiki syntax]]
Specific 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. WikiSyntax) 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.	[[WikiSyntax][wiki syntax]] <span class='externalLink'><span class='externalLink'>[[http://gnu.org][GNU]]</span></span>	wiki syntax GNU
Prevent a Link: Prevent a WikiWord from being linked by prepending it with an exclamation point.	!SunOS	SunOS
Disable Links: You can disable automatic linking of WikiWords by surrounding text with <noautolink> and </noautolink> tags. It is possible to turn off all auto-linking with a NOAUTOLINK preferences setting.	<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]].	a@b.com [[mailto:a@b.com]\ [Mail]] [[mailto:?subject=\ Hi][Hi]]	a@b.com Mail Hi
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 |
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.	<sticky> <div> This div is required </div> </sticky>	This div is required

Using HTML

• On collaboration pages, it's better not to use HTML, but to use wiki syntax instead - this keeps the text uncluttered and easy to edit using the plaintext editor.
• If you must use HTML, use XHTML 1.0 Transitional syntax.
• Use <literal>..</literal> tags around blocks of HTML to avoid accidental interpretation of Wiki syntax within the HTML.

Script tags may be filtered out, at the discretion of your Wiki administrator.

• Copy only text between <body> and </body> tags.
• Remove all empty lines. Foswiki inserts <p /> paragraph tags on empty lines, which causes problems if done between HTML tags that do not allow paragraph tags, like for example between table tags.
• Remove leading spaces. Foswiki might interpret some text as lists.
• Do not span a tag over more than one line. Foswiki requires that the opening and closing angle brackets - <...> - of a HTML tag are on the same line, or the tag will be broken.
• In your HTML editing program, save without hard line breaks on text wrap.

Hyperlinks

Internal Links

• GoodStyle is a WikiWord that links to the GoodStyle topic located in the current web.

• NotExistingYet is a topic waiting to be written. Create the topic by clicking on the ?. (Try clicking, but then, Cancel - creating the topic would wreck this example!)

• ACRONYM links to a topic name consisting of only upper-case letters. Acronyms are linked only if the target topic actually exists.

External Links

• Protocols matching the configuration parameter LinkProtocolPattern, which by default is set to (file|ftp|gopher|https|http|irc|mailto|news|nntp|telnet), are linked automatically. You might change this setting to add more protocols (such as smb).

  LinkProtocolPattern is an expert setting in the Foswiki configuration and can only be changed by a systems administrator.

  Thus, all lines containing:
  • file://...
  • ftp://...
  • gopher://...
  • https://...
  • http://...
  • irc://...
  • mailto:...@...
  • news://...
  • nntp://...
  • telnet://... are linked automatically.
• E-mail addresses like name@domain.com are linked automatically.
• [[Square bracket rules]] let you easily create non-WikiWord links.
  • You can also write [[http://yahoo.com Yahoo home page]] as an easier way of doing external links with descriptive text for the link, such as Yahoo home page.

Macros

Plugin Formatting Extensions

• System.TWikiCompatibilityPlugin (1.1.2, $Rev: 13315 (2011-12-06) $): Add TWiki personality to Foswiki
• System.SpreadSheetPlugin (1.1.4, $Rev: 13315 (2011-12-06) $): Add spreadsheet calculations like "$SUM($ABOVE())" to Foswiki tables and other topic text
• System.AutoViewTemplatePlugin (10 Apr 2011, $Rev: 11364 (2011-04-10) $): Automatically sets VIEW_TEMPLATE and EDIT_TEMPLATE
• System.CommentPlugin (10 Apr 2011, $Rev: 11361 (2011-04-10) $): Quickly post comments to a page without an edit/save cycle
• System.CompareRevisionsAddonPlugin (1.1.6, $Rev: 13317 (2011-12-06) $):
• System.EditTablePlugin (4.41, $Rev: 13315 (2011-12-06) $): Edit tables using edit fields, date pickers and drop down boxes
• System.ExternalLinkPlugin (1.21, $Rev: 5906 (2009-12-31) $): Adds a visual indicator to outgoing links
• System.FilterPlugin (2.06, $Rev: 12386 (2011-08-25) $): Substitute and extract information from content by using regular expressions
• System.FindElsewherePlugin (2.2, $Rev: 13097 (2011-11-16) $): Automatically link to another web(s) if a topic isn't found in the current web.
• System.HistoryPlugin (1.10, $Rev: 13288 (2011-12-03) $): Shows a complete history of a topic
• System.IfDefinedPlugin (v2.00, $Rev: 4422 (2009-07-03) $): Render content conditionally
• System.ImagePlugin (2.40, $Rev: 11303 (2011-04-05) $):
• System.InterwikiPlugin (1.1.2, $Rev: 12957 (2011-10-31) $): Link ExternalSite:Page text to external sites based on aliases defined in a rules topic
• System.JQGridPlugin (2.02, $Rev: 12796 (2011-10-19) $): jQuery grid widget for Foswiki
• System.JQueryPlugin (4.32, $Rev: 13479 (2011-12-20) $): jQuery JavaScript library for Foswiki
• System.MailerContribPlugin (9 Jul 2010, $Rev: 13315 (2011-12-06) $): Supports e-mail notification of changes
• System.MultiTopicSavePlugin (1.7, $Rev: 9013 (2010-09-12) $): Save form data to multiple topics in one single submission
• System.PiwikPlugin ($Date: 2009-08-18 17:13:53 +0200 (Tue, 18 Aug 2009) $, $Rev: 4684 (2009-08-18) $): Empty Plugin used as a template for new Plugins
• System.PreferencesPlugin (1.1.2, $Rev: 13315 (2011-12-06) $): Allows editing of preferences using fields predefined in a form
• System.RatingPlugin ($Date: 2009-08-18 17:13:53 +0200 (Tue, 18 Aug 2009) $, $Rev: 4684 (2009-08-18) $): Expose RatingContrib as a tag
• System.RedirectPlugin (1.1, $Rev: 7923 (2010-06-26) $): Create a redirect to another topic or website.
• System.RenderListPlugin (2.2.5, $Rev: 13315 (2011-12-06) $): Render bullet lists in a variety of formats
• System.SlideShowPlugin (2.1.4, $Rev: 12410 (2011-08-28) $): Create web based presentations based on topics with headings
• System.SmiliesPlugin (05 Dec 2011, $Rev: 13315 (2011-12-06) $): Render smilies like as icons
• System.TablePlugin (1.138, $Rev: 13401 (2011-12-13) $): Control attributes of tables and sorting of table columns
• System.TinyMCEPlugin (1.1.12, $Rev: 13315 (2011-12-06) $): Integration of the Tiny MCE WYSIWYG Editor
• System.TwistyPlugin (1.6.15, $Rev: 13315 (2011-12-06) $): Twisty section Javascript library to open/close content dynamically
• System.VarCachePlugin (29 Jan 2009, $Rev: 2215 (29 Jan 2009) $): Cache Foswiki macros in selected topics for faster page rendering
• System.VotePlugin (1.33, $Rev: 4084 (2009-06-10) $): Simple way to count votes
• System.WikiAppInstallerPlugin (1.0.0, $Rev: 13199 (2011-11-23) $): Explore, install, and package wiki applications
• System.WysiwygPlugin (1.1.3, $Rev: 13315 (2011-12-06) $): Translator framework for WYSIWYG editors

Common Editing Errors

• Q: Text enclosed in angle brackets like <filename> is not displayed. How can I show it as it is?
  • A: The '<' and '>' characters have a special meaning in HTML, they define HTML tags. You need to escape them, so write '<' instead of '<', and '>' instead of '>'.
    Example: Type 'prog <filename>' to get 'prog <filename>'.

• Q: Why is the '&' character sometimes not displayed?
  • A: The '&' character has a special meaning in HTML, it starts a so called character entity, i.e. '©' is the © copyright character. You need to escape '&' to see it as it is, so write '&' instead of '&'.
    Example: Type 'This & that' to get 'This & that'.

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 preference settings)
• 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 point, 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 (those that use registerTagHandler())

  Not those that use commonTagsHandler()

• Most built-in Foswiki macros

  Notable exceptions include: CALC, STARTSECTION/ENDSECTION, STARTINCLUDE/STOPINCLUDE

Standard form

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

Animated 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"
}%

Animated Example

%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

%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

   * %ICON{
    "%IF{
      "'AccessKeys'/parent.name='UserDocumentationCategory'"
      then="info" else="gear"
    }%"
  }% [[AccessKeys]]
   * %ICON{
    "%IF{
      "'AdminSkillsAssumptions'/parent.name='UserDocumentationCategory'"
      then="info" else="gear"
    }%"
  }% [[AdminSkillsAssumptions]]
----
   * Set PARENT = UserDocumentationCategory

   * %ICON{
    "info"
  }% [[AccessKeys]]
   * %ICON{
    "gear"
  }% [[AdminSkillsAssumptions]]
----
   * Set PARENT = UserDocumentationCategory

   * <img src="http://www.foswiki.org/pub/System/DocumentGraphics/info.png"/> [[AccessKeys]]
   * <img src="http://www.foswiki.org/pub/System/DocumentGraphics/gear.png"/> [[AdminSkillsAssumptions]]
----
   * Set PARENT = UserDocumentationCategory

Macro Names

Preference Settings

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

Example:

   * Set WEBBGCOLOR = #FFFFC0

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

   * #Set DENYWEBCHANGE = %USERSWEB%.UnknownUser

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

   * 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

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

• Syntax: %ACTIVATEDPLUGINS%
• Expands to: System.TWikiCompatibilityPlugin, System.SpreadSheetPlugin, System.AutoViewTemplatePlugin, System.CommentPlugin, System.CompareRevisionsAddonPlugin, System.EditTablePlugin, System.ExternalLinkPlugin, System.FilterPlugin, System.FindElsewherePlugin, System.HistoryPlugin, System.IfDefinedPlugin, System.ImagePlugin, System.InterwikiPlugin, System.JQGridPlugin, System.JQueryPlugin, System.MailerContribPlugin, System.MultiTopicSavePlugin, System.PiwikPlugin, System.PreferencesPlugin, System.RatingPlugin, System.RedirectPlugin, System.RenderListPlugin, System.SlideShowPlugin, System.SmiliesPlugin, System.TablePlugin, System.TinyMCEPlugin, System.TwistyPlugin, System.VarCachePlugin, System.VotePlugin, System.WikiAppInstallerPlugin, System.WysiwygPlugin
• Related: PLUGINDESCRIPTIONS, FAILEDPLUGINS, PLUGINVERSION

ADDTOHEAD

ADDTOZONE

%ADDTOZONE{
  "zone"
  ...
}%

• "zone" optional, 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. Defaults to head.
• id optional, 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="..." optional, comma separated string of ids of text within this zone that this content should follow when the zone is rendered.
• text="..." optional, text to be added to the named zone, mutually exclusive with topic.
• topic="..." optional, full qualified web.topic name that contains the text to be added, mutually exclusive with text. Defaults to %BASETOPIC%
• section="..." optional, section of the topic to be added, defaults to 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.

Example: 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 -->

Example: 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"
}%

Example: Adding CSS to a page

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

ALLVARIABLES -- list of currently defined macros

• Syntax: %ALLVARIABLES%
• Expands to: a table showing all defined macros in the current context

AQUA -- start aqua colored text

• AQUA is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
  Example:

  %AQUA% aqua text %ENDCOLOR%

  Expands to: aqua text

  %<color>% text must end with %ENDCOLOR%. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%, e.g. write

  %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%

ATTACHURL -- full URL for attachments in the current topic

• Syntax: %ATTACHURL%
• Expands to: http://www.foswiki.org/pub/System/VarATTACHURL
• Example: If you attach a file you can refer to it as %ATTACHURL%/image.gif
• Related: ATTACHURLPATH, PUBURL, PUBURLPATH, SCRIPTURL, SCRIPTURLPATH, FileAttachments

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

• Syntax: %ATTACHURLPATH%
• Expands to: /pub/System/VarATTACHURLPATH
• Related: ATTACHURL, PUBURL, PUBURLPATH, SCRIPTURL, SCRIPTURLPATH, FileAttachments

AUTHREALM -- authentication realm

• String defined as {AuthRealm} expert option in configure. This is used in certain password encodings, and in login templates as part of the login prompt.
• Syntax: %AUTHREALM%
• Expands to: Enter your System.LoginName. (Typically First name and last name, no space, no dots, capitalized, e.g. JohnSmith, unless you chose otherwise). Visit System.UserRegistration if you do not have one.
• Related: UserAuthentication, SESSIONID, SESSIONVAR, LOGIN, LOGOUT, SESSION_VARIABLE

BASETOPIC -- base topic where an INCLUDE started

• The name of the topic where a single or nested INCLUDE started - same as %TOPIC% if there is no INCLUDE
• This is the name of the topic requested by the user.
• Syntax: %BASETOPIC%
• Related: BASEWEB, INCLUDINGTOPIC, INCLUDE, TOPIC

BASEWEB -- base web where an INCLUDE started

• The web name where the includes started, e.g. the web of the first topic of nested includes. Same as %WEB% in case there is no include.
• This is the name of the web requested by the user.
• Syntax: %BASEWEB%
• Related: BASETOPIC, INCLUDINGWEB, INCLUDE, WEB

BB -- bullet with line break

• Line break and bullet without indentation.
• Current value: BB =
  •
• Related: BR, BULLET, BB2, BB3, BB4, CARET, VBAR

BB2 -- level 2 bullet with line break

• Line break and bullet, level 2.
• Current value: BB2 =
    •
• Related: BR, BULLET, BB, BB3, BB4, VBAR

BB3 -- level 3 bullet with line break

• Line break and bullet, level 3.
• Current value: BB3 =
      •
• Related: BR, BULLET, BB, BB2, BB4, VBAR

BB4 -- level 4 bullet with line break

• Line break and bullet, level 4.
• Current value: BB4 =
        •
• Related: BR, BULLET, BB, BB2, BB3, VBAR

BLACK -- start black colored text

• BLACK is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
  Example:

  %BLACK% black text %ENDCOLOR%

  Expands to: black text

  %<color>% text must end with %ENDCOLOR%. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%, e.g. write

  %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%

BLUE -- start blue colored text

• BLUE is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
  Example:

  %BLUE% blue text %ENDCOLOR%

  Expands to: blue text

  %<color>% text must end with %ENDCOLOR%. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%, e.g. write

  %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%

BR -- line break

• Current value: BR =
  
• Related: BULLET, BB, BB2, BB3, BB4, CARET, VBAR

BROWN -- start brown colored text

• BROWN is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
  Example:

  %BROWN% brown text %ENDCOLOR%

  Expands to: brown text

  %<color>% text must end with %ENDCOLOR%. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%, e.g. write

  %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%

BULLET -- bullet character

• Current value: BULLET = •
• Related: BR, BB, BB2, BB3, BB4, CARET, VBAR

BUTTON{"text" ...} -- renders a nice button

• Parameters:

  Parameter:	Description:	Default:
  "text", value="text"	text to be put on this button
  accesskey	access key used for this button
  class	extra class: use foswikiRight or foswikiLeft to specify aligment; use cyan, red, green for different background colors; use simple for a non-3D button
  href	url of the click target	#
  icon	icon to be put on the left; note, this can be any icon attached to the {IconSearchPath}; see also VarJQICON
  id	html id for this button
  onclick	javascript event triggered when clicking the button
  onmouseout	javascript event triggered when the pointer leaves the button
  onmouseover	javascript event triggered when the pointer hovers over the button
  target	topic to open when clicking on the button
  title	popup title displayed when hovering over the button
  type	type of action to be performed; available actions are button: (default) normal click button, target specified in target or href parameter clear: clears all input fields in the form that contains the button reset: resets all input fields in a form to their initial value submit: submits the form that contains the button save: same as submit but takes care of extra validation steps when saving a wiki topic	button

• Example:

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

• Expands as:
  Submit Cancel
• Note: BUTTONS are floating to the left by default. Take care to add a %CLEAR% after the %BUTTON{...}% so that further content does not overlap with the button.
• Related: JQueryButton

CALC{"formula"} -- add spreadsheet calculations to tables and outside tables

• The %CALC{"formula"}% macro is handled by the SpreadSheetPlugin. There are around 90 formulae, such as $ABS(), $EXACT(), $EXISTS(), $GET()/$SET(), $IF(), $LOG(), $LOWER(), $PERCENTILE(), $TIME(), $VALUE().
• Syntax: %CALC{"formula"}%
• 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
• Related: IF, SpreadSheetPlugin

CARET -- caret symbol

• The CARET macro is useful in TML tables.
• Current value: CARET = ^
• Related: BR, BULLET, BB, BB2, BB3, BB4, VBAR

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

• A %COMMENT% without parameters shows a simple text box.
• 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, either in this topic or in your WebPreferences.	below
  default	Default text to put into the textarea of the prompt.
  target	Name of the topic to add the comment to	the current topic
  location	Regular expression specifying the comment location in the target topic. Read carefully the CommentPlugin documentation!
  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 encloses your comment block - remember to insert <form> tags yourself! 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

• See CommentPlugin for more information

COVER -- current skin cover

• %COVER% extends the skin search path. For instance, if SKIN is set to catskin, bearskin, and COVER is set to ruskin, the skin search path becomes ruskin, catskin, bearskin.
• The COVER setting can be overridden using the URL parameter cover, such as ?cover=ruskin
• Syntax: %COVER%
• Expands to: %COVER%
• See Skins for more information

DATE -- signature format date

• Syntax: %DATE%
• Expands to: 13 Feb 2012
• 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.

• Related: DISPLAYTIME, GMTIME{"format"}, SERVERTIME

DISPLAYTIME{"format"} -- formatted display time

• Formatted time - either GMT or Local server time, depending on {DisplayTimeValues} setting in configure. Same format qualifiers as %GMTIME%
• Syntax: %DISPLAYTIME% OR %DISPLAYTIME{"format"}%
• %DISPLAYTIME% The time is shown as hh:mm (24 hour clock)
  • Expands to: 13 Feb 2012 - 10:09
• Example:

  %DISPLAYTIME{"$hou:$min"}%

  expands to 10:09
• Related: GMTIME, SERVERTIME

EDITACTION -- Selects an edit template

• The EDITACTION preference setting lets you define the use of an editaction template instead of the standard edit. If EDITACTION is defined as text, then hide the form. If EDITACTION is defined as form hide the normal text area and only edit the form.
• Syntax:

     * Set EDITACTION = text|form

• Expands to: %EDITACTION%

  When EDITACTION is defined as text or form the Edit and Edit Raw buttons simply add ;action=text or ;action=form to the URL for the edit script. If you have defined an EDITACTION preference setting you can still edit the topic content or the form by removing the ;action=form or ;action=text from the edit URL in the browser and reload.

• Related: CommandAndCGIScripts#edit

EDITTABLE{ attributes } -- edit tables using edit fields and other input fields

• The %EDITTABLE{}% macro is handled by the EditTablePlugin
• Syntax: %EDITTABLE{ attributes }%

• Supported attributes:

  Attribute	Comment	Default
  header	Specify the header format of a new table like "|*Food*|*Drink*|". Useful to start a table with only a button	(no header)
  format	The format of one column when editing the table. A cell can be a text input field, or any of these edit field types: • Text input field (1 line):   | text, <size>, <initial value> | • Textarea input field:   | textarea, <rows>x<columns>, <initial value> | • Drop down box:   | select, <size>, <option 1>, <option 2>, etc* |   * only one item can be selected • Radio buttons:   | radio, <size*>, <option 1>, <option 2>, etc |   * size indicates the number of buttons per line in edit mode • Checkboxes:   | checkbox, <size*>, <option 1>, <option 2>, etc |   * size indicates the number of checkboxes per line in edit mode • Fixed label:   | label, 0, <label text> | • Row number:   | row, <offset> | • Date:   | date, <size>, <initial value>, <DHTML date format> | (see Date Field Type)	"text, 16" for all cells
  changerows	Rows can be added and removed if "on" Rows can be added but not removed if "add" Rows cannot be added or removed if "off"	CHANGEROWS plugin setting
  quietsave	Quiet Save button is shown if "on", hidden if "off"	QUIETSAVE plugin setting
  include	Other topic defining the EDITTABLE parameters. The first %EDITTABLE% in the topic is used. This is useful if you have many topics with the same table format and you want to update the format in one place. Use topic or web.topic notation.	(none)
  helptopic	Topic name containing help text shown below the table when editing a table. The %STARTINCLUDE% and %STOPINCLUDE% macros can be used in the topic to specify what is shown.	(no help text)
  headerislabel	Table header cells are read-only (labels) if "on"; header cells can be edited if "off" or "0"	"on"
  editbutton	Set edit button text, e.g. "Edit this table"; set button image with alt text, e.g. "Edit table, %PUBURL%/%SYSTEMWEB%/DocumentGraphics/edittopic.gif"; hide edit button at the end of the table with "hide" (Note: Button is automatically hidden if an edit button is present in a cell)	EDITBUTTON plugin setting
  buttonrow	Set to top to put the edit buttons above the table.	bottom
  javascriptinterface	Use javascript to directly move and delete row without page refresh. Enable with "on", disable with "off".	JAVASCRIPTINTERFACE plugin setting

%EDITTABLE{ format="| text, 20 | select, 1, one, two, three |" changerows="on" }%
| *Name* | *Type* |
| Foo    | two    |

ENCODE{"string"} -- encodes a string

• Encode character sequences in "string", by mapping characters (or sequences of characters) to an alternative character (or sequence of characters). This macro can be used to encode strings for use in URLs, to encode to HTML entities, to protect quotes, and for as many other uses as you can imagine.
• Syntax: %ENCODE{"string"}%
• Parameters:

  Parameter	Description	Default
  "string"	String to encode	"" (empty string)
  type="encodingname"	Use a predefined encoding (see below).	Default is 'url'. Parameter type not be used if old or new are given.
  old="tokenlist"	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="tokenlist"	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

• If ENCODE is called with no optional parameters (e.g. %ENCODE{"string"}%) then the default type="url" encoding will be used.
• Predefined encodings.
  • Unless otherwise specified, the type parameter encodes the following "special characters"
    • 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="entity" Encode special characters into HTML entities, like a double quote into ". Does not encode \n (newline).
  • type="html" As type="entity" except it also encodes \n (newline)
  • type="safe" Encode just the characters '"<>% into HTML entities.
  • type="quotes" Escapes double quotes with backslashes (\"), does not change any other characters
  • type="url" 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

• Values for HTML input fields must be entity encoded.
  Example:

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

• ENCODE can be used to filter user input from URL parameters and similar to help protect against cross-site scripting. The safest approach is to use type="entity". This can however prevent an application from fully working. You can alternatively use type="safe" which encodes only the characters '"<>% into HTML entities. When ENCODE is passing a string inside another macro always use double quotes ("") type="quote". For maximum protection against cross-site scripting you are advised to install the Foswiki:Extensions.SafeWikiPlugin.

• Double quotes in strings must be escaped when passed into other macros.
  Example:

  %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'

• Related: URLPARAM

ENDCOLOR -- end colored text

• ENDCOLOR is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of shortcuts.
  Example:

  %GREEN% green text %ENDCOLOR%

  Expands to: green text

  %<color>% text must end with %ENDCOLOR%. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%, e.g. write

  %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%

• Related: VarAQUA, VarBLACK, VarBLUE, VarBROWN, VarGRAY, VarGREEN, VarLIME, VarMAROON, VarNAVY, VarOLIVE, VarORANGE, VarPINK, VarPURPLE, VarRED, VarSILVER, VarTEAL, VarWHITE, VarYELLOW, DefaultPreferences, StandardColors

ENDSECTION{"name"} -- marks the end of a named section within a topic

• Syntax: %ENDSECTION{"name"}%
• Syntax: %ENDSECTION{type="include"}%
• Supported parameter:

  Parameter:	Description:
  "name"	Name of the section.
  type="..."	Type of the section being terminated; supported types "section", "include", "expandvariables", "templateonly".

• If the STARTSECTION is named, the corresponding ENDSECTION must also be named with the same name. If the STARTSECTION specifies a type, then the corresponding ENDSECTION must also specify the same type. If the section is unnamed, ENDSECTION will match with the nearest unnamed %STARTSECTION% of the same type above it.
• Related: STARTSECTION

ENDTAB -- ending marker for a tab of a tabpane

• This closes a previously opened TAB.
• no parameters
• Related: VarTAB, VarTABPANE, VarENDTAB, JQueryPlugin, JQueryTabpane

ENDTABPANE -- ending tag for tabpane widget

• This closes a previously opened TABPANE.
• no parameters
• Related: VarTAB, VarENDTAB, VarTABPANE, JQueryPlugin, JQueryTabpane

ENDTWISTY

• Syntax: %ENDTWISTY%
• Related: VarENDTWISTY, VarENDTWISTYTOGGLE, VarTWISTY, VarTWISTYBUTTON, VarTWISTYHIDE, VarTWISTYSHOW, VarTWISTYTOGGLE

ENDTWISTYTOGGLE

• Syntax: %ENDTWISTYTOGGLE%
  • Will end the most inner unclosed Twisty Toggle section, using the proper tag
• Example: %ENDTWISTYTOGGLE%
• Related: VarENDTWISTY, VarENDTWISTYTOGGLE, VarTWISTY, VarTWISTYBUTTON, VarTWISTYHIDE, VarTWISTYSHOW, VarTWISTYTOGGLE

ENV{"varname"} -- inspect the value of an environment variable

• Returns the current value of the environment variable in the CGI (Common Gateway Interface) environment. This is the environment that the CommandAndCGIScripts are running in.
• Note: For security reasons, only those environment variables whose names match the regular expression in {AccessibleENV} in the Security Settings/Miscellaneous section of configure can be displayed. Any other variable will just be shown as an empty string, irrespective of its real value.
• Example: %ENV{MOD_PERL}% displays as: not set
• If an environment variable is undefined (as against being set to the empty string) it will be returned as not set.
• Related: HTTP_HOST, REMOTE_ADDR, REMOTE_PORT, REMOTE_USER

EXAMPLETAG -- example variable

• The %EXAMPLETAG{}% variable is handled by the ExamplePlugin
• Syntax: %EXAMPLETAG{"text" format="..."}%
• Parameter text="..." - example text.
• Parameter format="..." - format of report.
• Example: %EXAMPLETAG{"hello" format="| $topic: $summary |"}%
• Related: ExamplePlugin

EXPAND{"expression" scope="topictoexpandin" ...}%

   * 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, and handler list

• Syntax: %FAILEDPLUGINS%
• Expands to: See Plugins#FAILEDPLUGINS
• Related: PLUGINDESCRIPTIONS, ACTIVATEDPLUGINS, PLUGINVERSION

FORMAT{"list" format="" header="" footer="" separator=""} -- format a list of objects

• Syntax: %FORMAT{"list"}%
• Supported parameters:

  Parameter:	Description:	Default:
  "one, two, three"	The list to be expanded into the format. Required. Currently only two types of list data are supported; topic names (type="topic") and plain strings (type="string").	""
  format="..."	Format string; see Supported formatting tokens for possible values.	""
  header="..."	Text to come before the formatted output	""
  footer="..."	Text to come after the formatted output	""
  separator="n"	Separator between formatted elements	"$n"
  type=""	Treat input list as either topic or string	"topic"

• 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="
     }%

• Related: SEARCH

Supported formatting tokens

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

• Related: SEARCH, ENCODE, FormattedSearch

FORMFIELD{"fieldname"} -- renders a field in the form attached to some topic

• Syntax: %FORMFIELD{"fieldname"}%
• Supported parameters:

  Parameter:	Description:	Default:
  "fieldname"	The name of a Data form field	required
  topic="..."	Topic where form data is located. May be of the form Web.TopicName	Current topic
  format="..."	Format string. $value expands to the field value, and $name expands to the field name, $title to the field title, $form to the name of the form the field is in. The standard format tokens are also expanded.	"$value"
  default="..."	Text shown if the field is defined in the topic, but the field value is empty. For example, a text field for which all the content has been deleted.	""
  alttext="..."	Text shown if the field is not defined in the topic (even if it is specified in the form definition). For example, this is used when a field exists in the form definition, but the referring topic hasn't been edited since it was added.	""
  rev="n"	Specifiy a revision of the topic. If not specified, defaults to the most recent rev (or the viewed rev if viewing an old rev of the same topic)

• Example:

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

• Related: SEARCH

GMTIME{"format"} -- formatted GM time

• Syntax: %GMTIME% OR %GMTIME{"format"}%
• %GMTIME% uses the default date format defined by the {DefaultDateFormat} setting in configure
  • expands to 13 Feb 2012 - 10:09
• Supported special format tokens:

  Token:	Unit:	Example
  $seconds	seconds	59
  $minutes	minutes	59
  $hours	hours	23
  $day	day of month	31
  $wday	day of the Week (Sun, Mon, Tue, Wed, Thu, Fri, Sat)	Thu
  $dow	day of the week (Sun = 0)	2
  $week	number of week in year (ISO 8601)	34
  $month	short name of month	Dec
  $mo	2 digit month	12
  $year	4 digit year	1999
  $ye	2 digit year	99
  $tz	either "GMT" (if set to gmtime), or "Local" (if set to servertime)	GMT
  $iso	ISO format timestamp	2012-02-13T10:09:31Z
  $rcs	RCS format timestamp	2012/02/13 10:09:31
  $http	E-mail & http format timestamp	Mon, 13 Feb 2012 10:09:31 GMT
  $epoch	Number of seconds since 00:00 on 1st January, 1970	1329127771

• Tokens can be shortened to 3 characters
• Example:

  %GMTIME{"$day $month, $year - $hour:$min:$sec"}%

  expands to

  13 Feb, 2012 - 10:09:31

  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.

• Related: GMTIME, REVINFO, SERVERTIME

GRAY -- start gray colored text

• GRAY is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
  Example:

  %GRAY% gray text %ENDCOLOR%

  Expands to: gray text

  %<color>% text must end with %ENDCOLOR%. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%, e.g. write

  %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%

GREEN -- start green colored text

• GREEN is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
  Example:

  %GREEN% green text %ENDCOLOR%

  Expands to: green text

  %<color>% text must end with %ENDCOLOR%. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%, e.g. write

  %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%

GROUPINFO{"name"} -- retrieve details about a group

• Syntax: %GROUPINFO%
  • Expands to: comma-separated list of all groups
• Syntax: %GROUPINFO{"groupname"}%
  • Expands to: comma-separated list of users in that group
• Parameters:

  format	Format of a single user or group in the list. $name expands to the group name, and (for users list only) $wikiname, $username and $wikiusername to the relevant strings. $allowschange returns 0 (false) or 1 (true) if that group can be modified by the current user. $allowschange(UserWikiName) returns 0 (false) or 1 (true) if that group can be modified by the specified user (does not work for groups yet.). The standard FormatTokens are also supported.	$name for groups list, $wikiusername for users list
  separator	separator between items in the list	,
  header	Header for the list	''
  footer	Footer for the list	''
  zeroresults	If set, and there are no Groups or Members that can be shown, the header and footer are suppressed, and this text is output	undefined
  show	filter the output list of Groups - can be set to all, allowschange, denychange, allowschange(UserWikiName), denychange(UserWikiName)	all
  expand	Set false if users should not be expanded from nested groups. Default behavior is to expand all nested groups into a flat list of users.	1
  limit	If set, limits the number of results to this	infinity
  limited	If limit is set, and the list is truncated, this text will be added at the end of the list	''

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.

• Related: USERINFO

GROUPS -- a formatted list of groups

• Expands to a formatted list of user groups in your Foswiki.
• Syntax: %GROUPS%
• The macro is intended to be used in Main.WikiGroups, to allow a group listing for various user mapping managers.
• Related: REMOTE_USER, USERINFO, USERNAME, WIKIUSERNAME, WIKIUSERSTOPIC

H -- help icon

• Current value: H =
• Related: I, ICON, M, N, P, Q, S, T, U, X, Y

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

• The %HISTORY{}% macro is handled by the HistoryPlugin
• Syntax: %HISTORY{ attributes }%

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

• Syntax: %HOMETOPIC%
• Expands to: WebHome, renders as WebHome
• Related: NOTIFYTOPIC, STATISTICSTOPIC, TOPIC

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.
• Syntax: %HTTP%
• Syntax: %HTTP{"Header-name"}%
• Examples:

  %HTTP%
  %HTTP{"Accept-language"}%	en-us,en;q=0.5
  %HTTP{"User-Agent"}%	CCBot/1.0 (+http://www.commoncrawl.org/bot.html)

  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

• Related: HTTPS, REMOTE_ADDR, REMOTE_PORT, REMOTE_USER

HTTP_HOST -- environment variable

• Syntax: %HTTP_HOST%
• Expands to: www.foswiki.org
• Related: ENV, REMOTE_ADDR, REMOTE_PORT, REMOTE_USER

HTTPS -- get HTTPS headers

• The same as %HTTP% but operates on the HTTPS environment variables present when the SSL protocol is in effect. Can be used to determine whether SSL is turned on.
• Syntax: %HTTPS%
• Syntax: %HTTPS{"Header-name"}%
• Related: HTTP, REMOTE_ADDR, REMOTE_PORT, REMOTE_USER

I -- idea icon

• Current value: I =
• Related: H, ICON, M, N, P, Q, S, T, U, X, Y

ICON{"name" alt="" default="name"} -- small documentation graphic or icon of common attachment types

• Generates a small graphic image from the set attached to System.DocumentGraphics. Images typically have a 16x16 pixel size. You can select a specific image by name, or you can give a full filename, in which case the type of the file will be used to select one of a collection of common file type icons.
• if you specify an icon which cannot be found, the one specified in the default parameter will be used (and if that fails, the 'else' icon will be used)
• Syntax: =%ICON{ "filename or icon name" [ default="filename or icon name" ] [ alt="alt text to be added to the HTML img tag" ] }%
• 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
• Graphic samples: arrowbright, bubble, choice-yes, hand
• File type samples: bmp, doc, gif, hlp, html, mp3, pdf, ppt, txt, xls, xml, zip
• Related: ICONURL, ICONURLPATH, DefaultPreferences, FileAttachments, System.DocumentGraphics

ICONURL{"name" default="name"} -- URL of small documentation graphic or icon

• Generates the full URL of a System.DocumentGraphics image, which Foswiki renders as an image. The related %ICON{"name"}% generates the full HTML img tag. Specify image name or full filename (see ICON for details on filenames.)
• Syntax: %ICONURL{"name"}%
• Examples:
  • %ICONURL{"arrowbright"}% returns http://www.foswiki.org/pub/System/DocumentGraphics/arrowbright.png
  • %ICONURL{"novel.pdf"}% returns http://www.foswiki.org/pub/System/DocumentGraphics/pdf.png
  • %ICONURL{"/queen/boheme.mp3"}% returns http://www.foswiki.org/pub/System/DocumentGraphics/mp3.png
• Related: ICONURLPATH, ICON, DefaultPreferences, FileAttachments, System.DocumentGraphics

ICONURLPATH{"name" default="name"} -- URL path of small documentation graphic or icon

• Generates the relative URL path of a System.DocumentGraphics image, typically used in an HTML img tag. Specify image name or full filename (see ICON for details on filenames.)
• Syntax: %ICONURLPATH{"name"}%
• Examples:
  • %ICONURLPATH{"locktopic"}% returns /pub/System/DocumentGraphics/locktopic.png
  • %ICONURLPATH{"eggysmell.xml"}% returns /pub/System/DocumentGraphics/xml.png
  • %ICONURLPATH{"/doc/xhtml.xsl"}% returns /pub/System/DocumentGraphics/xsl.png
• Related: ICONURL, ICON, DefaultPreferences, FileAttachments, System.DocumentGraphics

IF{"condition" ...} -- simple conditionals

• Evaluate a condition and show one text or another based on the result. See details in IfStatements
• Syntax:

  %IF{"CONDITION" then="THEN" else="ELSE"}%

  shows
  "THEN" if "CONDITION" evaluates to TRUE, otherwise "ELSE" will be shown
• Example:

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

  renders as

  FUNFACTOR is not defined

• Related: $IF() of SpreadSheetPlugin

INCLUDE{"topic"} -- include other topic.

• Syntax: %INCLUDE{"topic" ...}% (See also the URL form of %INCLUDE%)
• Supported parameters:

  Parameter:	Description:	Default:
  "SomeTopic"	The name of a topic located in the current web, i.e. %INCLUDE{"WebNotify"}%
  "Web.Topic"	A topic in another web, i.e. %INCLUDE{"System.SiteMap"}%
  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
  rev="2"	Include a previous topic revision; N/A for URLs	top revision
  warn="off"	Warn if topic include fails: Fail silently (if off); output default warning (if set to on); else, output specific text (use $topic for topic name)	%INCLUDEWARNING% preferences setting
  section="name"	Includes only the specified named section, as defined in the included topic by the STARTSECTION and ENDSECTION macros. Nothing is shown if the named section does not exists. section="" is equivalent to not specifying a section
  PARONE="val 1" PARTWO="val 2"	Any other parameter will be defined as a macro within the scope of the included topic. The example parameters on the left will result in %PARONE% and %PARTWO% being defined within the included topic.

• Examples: See IncludeTopicsAndWebPages
• Related: BASETOPIC, BASEWEB, INCLUDE("URL"), INCLUDE("doc:") ,INCLUDINGTOPIC, INCLUDINGWEB, STARTINCLUDE, STOPINCLUDE, STARTSECTION, ENDSECTION

INCLUDE{"url"} -- include a web page

• Syntax: %INCLUDE{"http://..." ...}% (See also the topic form of %INCLUDE%)
• Supported 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="on"	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="on"	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".	disabled
  disableremoveheaders="on"	Bypass stripping headers from included HTML (everything until first </head> tag)	disabled
  disableremovescript="on"	Bypass stripping all <script> tags from included HTML	disabled
  disableremovebody="on"	Bypass stripping the </body> tag and everything around over and below it	disabled
  disablecompresstags="on"	Bypass replacing newlines in HTML tags with spaces. This compression step rewrites unmatched <'s into &lt; entities unless bypassed	disabled
  disablerewriteurls="on"	Bypass rewriting relative URLs into absolute ones	disabled
  warn="off"	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
• Related: INCLUDE("topic")

INCLUDE{"doc:"} -- include Foswiki embedded module documentation

• Syntax: %INCLUDE{"doc:Foswiki::Func" ...}%
• Supported parameters:

  Parameter:	Description:	Default:
  "doc:..."	A full qualified Foswiki module, i.e. %INCLUDE{"doc:Foswiki::Func"}%. The module must be found on the Foswiki lib path
  level="1"	Override the root heading level to the specified number
  pattern="..."	Include a subset of the module. Specify a RegularExpression that contains the text you want to keep in parenthesis, e.g. pattern="(from here.*?to here)". IncludeTopicsAndWebPages has more.	none

• Examples: See System/PerlDoc?module=Foswiki::Func
• Related: INCLUDE("topic") INCLUDE("URL")

INCLUDINGTOPIC -- name of topic that includes current topic

• The name of the topic that includes the current topic - same as %TOPIC% in case there is no include
• If a topic is used in a chain of INCLUDEs, INCLUDINGTOPIC is set to the topic directly INCLUDing this one, NOT the topic that has been requested by the user (which is set in BASETOPIC)

  While this Macro may appear to work, unless you require the subtle difference between INCLUDINGTOPIC and BASETOPIC, you probably should use BASETOPIC

• Syntax: %INCLUDINGTOPIC%
• Related: BASETOPIC, INCLUDINGWEB, INCLUDE, TOPIC

INCLUDINGWEB -- web that includes current topic

• The web name of the topic that includes the current topic - same as %WEB% if there is no INCLUDE.
• If a topic is used in a chain of INCLUDEs, INCLUDINGWEB is set to the topic directly INCLUDing this one, NOT the web that has been requested by the user (which is set in BASEWEB)

  While this Macro may appear to work, unless you require the subtle difference between INCLUDINGWEB and BASEWEB, you probably should use BASEWEB

• Syntax: %INCLUDINGWEB%
• Related: BASEWEB, INCLUDINGTOPIC, INCLUDE, WEB

JQICON{"name" ...} -- render an image

• This renders an icon image as found on an icon search path. The icon search path is configured in {JQueryPlugin}{IconSearchPath} and defaults to FamFamFamSilkIcons, FamFamFamSilkCompanion1Icons, FamFamFamFlagIcons, FamFamFamMiniIcons, FamFamFamMintIcons'. The named icon will be picked found first on this path of topics where icons are attached to. The JQICON leverages the general icon loading mechanism as implemented by the JQueryPlugin and used by BUTTON as well.
• Parameters:

  Parameter:	Description:	Default:
  "name"	name of the icon to display
  class	additional css class for the img tag
  alt		alt attribute
  title	title attribute
  format	format string used to render the icon; known variables to be used in the format string are: $iconPath: url path $iconClass: css class as specified by the class parameter $iconAlt: alt attribute-value; if the alt parameter to JQICON is set, this expands to alt='...' $iconTitle: title attribute-value; if the title parameter to JQICON is set, this expands to title='...'	<img src='$iconPath' class='$iconClass' $iconAlt$iconTitle/>

• Example:

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

  Produces:
• Related: VarJQICONPATH, VarICON, JQueryPlugin, FamFamFamSilkIcons

JQICONPATH{"name"} -- render the urlpath to an image

• This is a shortcut for

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

• Example: /pub/System/FamFamFamSilkIcons/tick.png
• Related: VarJQICON, VarICONURL, JQueryPlugin

JQPLUGINS{"plugins" ... } -- display a summary of available plugins

• Parameters:

  Parameter:	Description:	Default:
  "plugins"	this is a regular expression that the plugin identifier must match to be displayed
  format	format string to render information for each matching plugin; known variables to be used in the format string are: active: state of the plugin: displays (active) when this plugin is loaded on the current page author: author of the plugin documentation: plugin documentation topic defaults to %SYSTEMWEB%.JQuery$name homepage: link to the hompeage of this third party plugin index: the current index in the list of all plugins being displayed name: name of the plugin as can be used in JQREQUIRE summary: short description what this plugin does; most plugins provide this piece of information in the summary section of the documentation topic tags: list of TML macros this plugin implements version: version of the plugin as provided by the author of this plugin	1 <a href="$homepage">$name</a> $active $version $author
  header	header string prepended to the output; empty when no plugin matches
  footer	footer string appended to the output; empty when no plugin matches
  separator	separator put between each plugin rendered in a row	$n
  tagformat	format string to render a link to any tag documentation a plugin implements	[[%SYSTEMWEB%.Var$tag][$tag]]

• Example:

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

  Produces:
• JQuery Plugins:
  • Slimbox v2.04 was developed by Christophe Beyls
  • Treeview v1.4 was developed by Joern Zaefferer
• Related: JQueryPlugin

JQREQUIRE{"plugin, plugin, ... "} -- enable a plugin on the current page

• This macro will load a list of plugins to be added to the current page. Use JQPLUGINS to display the list of available and active plugins. While loading a plugin, additional plugins it may depend on are loaded as well. Information about these dependencies is stored within the plugins themselves and can't be changed. Dependencies also make sure the javascript code is added to the html page in the right order. It uses ADDTOZONE to aggregate javascript and css at the right place on the html page.
• Parameters:

  Parameter:	Description:	Default:
  "plugin[, plugin, plugin]"	list of plugins to be loaded
  warn	(on/off) allows you to switch off warnings when a plugin was not found	on

• Related: JQueryPlugin, VarJQPLUGINS, VarADDTOZONE

JQTHEME{"name" ...} -- switch jQuery UI theme

• Foswiki's default UI theme is configured in $Foswiki::cfg{JQueryPlugin}{JQueryTheme} and defaults to base. Use configure to change this site wide. Use JQTHEME if you decide to use a different theme on the current page.
• Note: some Foswiki skins may come with their own jQuery UI matching the overall user experience of the web design.
• Parameters:

  Parameter:	Description:	Default:
  "name"	name of theme: JQueryPlugin knows the following themes base, lightness, redmod, smoothness; additional themes maybe created using the themeroller and installed to /pub/System/JQueryPlugin/$name	base

• Related: JQueryUI

LANG -- the lang attribute of generated HTML pages

• In templates the lang attribute is defined like this:

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

• The value is read from configure setting {Site}{Locale}
• Do not confuse LANG with LANGUAGE
• Syntax: %LANG%
• Expands to: en_US

LANGUAGE -- current user's language

• Returns the language code for the language used as the current user. This is the language actually used by Foswiki (e.g. in user interface).
• The language is detected from the user's browser, unless some site/web/user/session-defined setting overrides it:
  • If the LANGUAGE preference is set, it's used as user's language instead of any language detected from the browser.
  • Avoid defining LANGUAGE at a non per-user way, so each user can choose his/her preferred language.
• Related: LANGUAGES

LANGUAGES -- list available languages

• List the languages available (as PO files). These are the languages in which the user interface is available.
• Syntax: %LANGUAGES{...}%
• Supported parameters:

  Parameter:	Description:	Default:
  format	format for each item. See below for format tokens available in the format string.	"   * $langname"
  separator	separator between items.	"\n" (newline)
  marker="selected"	Text for $marker if the item matches selection	"selected"
  selection="%LANGUAGE%"	Current language to be selected in list	(none)

• format tokens:

  Token	Meaning
  $langname	language's name, as informed by the translators
  $langtag	language's tag. Ex: en, pt-br, etc.

• Example: <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

LIME -- start lime colored text

• LIME is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
  Example:

  %LIME% lime text %ENDCOLOR%

  Expands to: lime text

  %<color>% text must end with %ENDCOLOR%. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%, e.g. write

  %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%

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.
• Syntax: %LOCALSITEPREFS%
• Expands to: Main.SitePreferences, renders as Main.SitePreferences

LOGIN -- present a full login link

• Syntax: %LOGIN%
• Expand to: Log In
• Related: UserAuthentication, SESSIONID, SESSIONVAR, LOGOUT, SESSION_VARIABLE

LOGOUT -- present a full logout link

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

• Syntax: %LOGOUT%
• Expand to:
• Related: UserAuthentication, SESSIONID, SESSIONVAR, LOGIN, SESSION_VARIABLE

M -- moved to... icon

• Current value: M =
• Related: H, I, ICON, N, P, Q, S, T, U, X, Y

MAINWEB -- synonym for USERSWEB

Deprecated. Please use %USERSWEB% instead.

MAKETEXT -- creates text using Foswiki's I18N infrastructure

• Syntax: %MAKETEXT{"string" args="..."}%
• Supported parameters:

  Parameter	Description	Default
  "text" or string="text"	The text to be displayed (the translatable string).	none
  args="param1, param2"	a comma-separated list of arguments to be interpolated in the string, replacing [_N] placeholders in it.	none

• Examples:

    %MAKETEXT{string="Notes:"}%
    expands to:
      Notes:
  
    %MAKETEXT{
      "If you have any questions, please contact [_1]."
      args="%WIKIWEBMASTER%"
    }%
    expands to:
      If you have any questions, please contact webmaster@foswiki.org.
  
    %MAKETEXT{
      "Did you want to [[[_1]][reset [_2]'s password]]?"
      args="%SYSTEMWEB%.ResetPassword,%WIKIUSERNAME%"
    }%
    expands to:
      Did you want to [[System.ResetPassword][reset Main.WikiGuest's password]]?

• Notes:
  • 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.

MAROON -- start maroon colored text

• MAROON is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
  Example:

  %MAROON% maroon text %ENDCOLOR%

  Expands to: maroon text

  %<color>% text must end with %ENDCOLOR%. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%, e.g. write

  %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%

META -- displays meta-data

• "form" - generates the table showing the form fields. See Form Definition.
• "attachments" - generate a table of attachments
  • all="on" to show hidden attachments.
  • title="..." to show a title - only if attachments are displayed.
  • template="..." to use a custom template for the rendering of attachments; default attachtables is used.
• "moved" - if a topic was moved or renamed, generates a message with details and a revert link
  • prefix="...": Prefix that goes before the moved message, but only if the message is generated, default "".
  • suffix="...": Prefix that goes after the moved message, but only if the message is generated, default "".
• "parent" - display details of ancestor topics
  • dontrecurse="on": By default recurses up tree, this has some cost. Equivalent to depth=1
  • depth="...": Return only the specified ancestor.
  • nowebhome="on": Suppress WebHome.
  • format="...": Format string used to display each parent topic where $web expands to the web name, and $topic expands to the topic name; default: "[[$web.$topic][$topic]]"
  • separator="...": Separator between parents; default " > "
  • prefix="...": Prefix that goes before parents, but only if there are parents, default "".
  • suffix="...": Suffix, only appears if there are parents; default "".
• "formfield" - display the value of a single form field
  • name="...": name of the field.
  • newline="...": by default, each newline character will be rewritten to <br /> to allow metadata that contains newlines to be used in tables, etc. $n indicates a newline character.
  • bar="...": by default, each vertical bar is rewritten to an HTML entity so as to not be mistaken for a table separator.

Use of "formfield" is deprecated in favour of the much more powerful QUERY macro.

METASEARCH -- special search of meta data

METASEARCH is deprecated in favour of the new and much more powerful query type search. See SEARCH and QuerySearch.

• Syntax: %METASEARCH{...}%
• Supported parameters:

  Parameter:	Description:	Default:
  type="topicmoved"	What sort of search is required? "topicmoved" if search for a topic that may have been moved "parent" if searching for topics that have a specific parent i.e. its children "field" if searching for topics that have a particular form field value (use the name and value parameters to specify which field to search).	Required
  web="%WEB%"	Wiki web to search: A web, a list of webs separated by whitespace, or all webs.	Current web
  topic="%TOPIC%"	The topic the search relates to, for topicmoved and parent searches	All topics in a web
  name	form field to search, for field type searches. May be a regular expression (see SEARCH).
  value	form field value, for field type searches. May be a regular expression (see SEARCH).
  title="Title"	Text that is prefixed to any search results	empty
  format="..."	Custom format results. Supports same format strings as SEARCH. See FormattedSearch for usage & examples	Results in table
  default="none"	Default text shown if no search hit	Empty

• Examples:

    %METASEARCH{
      type="topicmoved"
      web="%WEB%"
      topic="%TOPIC%"
      title="This topic used to exist and was moved to: "
    }%

  You may want to use this in WebTopicViewTemplate and WebTopicNonWikiTemplate:

    %METASEARCH{
      type="parent"
      web="%WEB%"
      topic="%TOPIC%"
      title="Children: "
    }%
  
    %METASEARCH{
      type="field"
      name="Country"
      value="China"
    }%

• Related: SEARCH, META

N -- "new" icon

• Current value: N =
• Related: H, I, ICON, M, P, Q, S, T, U, X, Y

NAVY -- start navy colored text

• NAVY is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
  Example:

  %NAVY% navy text %ENDCOLOR%

  Expands to: navy text

  %<color>% text must end with %ENDCOLOR%. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%, e.g. write

  %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%

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

• Syntax: %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.
• Syntax: %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).

• Related: STARTSECTION, TemplateTopics

NOTIFYTOPIC -- name of the notify topic

• Syntax: %NOTIFYTOPIC%
• Expands to: WebNotify, renders as WebNotify
• Related: HOMETOPIC, STATISTICSTOPIC, TOPIC

OLIVE -- start olive colored text

• OLIVE is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
  Example:

  %OLIVE% olive text %ENDCOLOR%

  Expands to: olive text

  %<color>% text must end with %ENDCOLOR%. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%, e.g. write

  %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%

ORANGE -- start orange colored text

• ORANGE is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
  Example:

  %ORANGE% orange text %ENDCOLOR%

  Expands to: orange text

  %<color>% text must end with %ENDCOLOR%. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%, e.g. write

  %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%

P -- pencil icon

• Current value: P =
• Related: H, I, ICON, M, N, Q, S, T, U, X, Y

PINK -- start pink colored text

• PINK is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
  Example:

  %PINK% pink text %ENDCOLOR%

  Expands to: pink text

  %<color>% text must end with %ENDCOLOR%. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%, e.g. write

  %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%

PLUGINDESCRIPTIONS -- list of plugin descriptions

• Syntax: %PLUGINDESCRIPTIONS%
• Expands to:
  • System.TWikiCompatibilityPlugin (1.1.2, $Rev: 13315 (2011-12-06) $): Add TWiki personality to Foswiki
  • System.SpreadSheetPlugin (1.1.4, $Rev: 13315 (2011-12-06) $): Add spreadsheet calculations like "$SUM($ABOVE())" to Foswiki tables and other topic text
  • System.AutoViewTemplatePlugin (10 Apr 2011, $Rev: 11364 (2011-04-10) $): Automatically sets VIEW_TEMPLATE and EDIT_TEMPLATE
  • System.CommentPlugin (10 Apr 2011, $Rev: 11361 (2011-04-10) $): Quickly post comments to a page without an edit/save cycle
  • System.CompareRevisionsAddonPlugin (1.1.6, $Rev: 13317 (2011-12-06) $):
  • System.EditTablePlugin (4.41, $Rev: 13315 (2011-12-06) $): Edit tables using edit fields, date pickers and drop down boxes
  • System.ExternalLinkPlugin (1.21, $Rev: 5906 (2009-12-31) $): Adds a visual indicator to outgoing links
  • System.FilterPlugin (2.06, $Rev: 12386 (2011-08-25) $): Substitute and extract information from content by using regular expressions
  • System.FindElsewherePlugin (2.2, $Rev: 13097 (2011-11-16) $): Automatically link to another web(s) if a topic isn't found in the current web.
  • System.HistoryPlugin (1.10, $Rev: 13288 (2011-12-03) $): Shows a complete history of a topic
  • System.IfDefinedPlugin (v2.00, $Rev: 4422 (2009-07-03) $): Render content conditionally
  • System.ImagePlugin (2.40, $Rev: 11303 (2011-04-05) $):
  • System.InterwikiPlugin (1.1.2, $Rev: 12957 (2011-10-31) $): Link ExternalSite:Page text to external sites based on aliases defined in a rules topic
  • System.JQGridPlugin (2.02, $Rev: 12796 (2011-10-19) $): jQuery grid widget for Foswiki
  • System.JQueryPlugin (4.32, $Rev: 13479 (2011-12-20) $): jQuery JavaScript library for Foswiki
  • System.MailerContribPlugin (9 Jul 2010, $Rev: 13315 (2011-12-06) $): Supports e-mail notification of changes
  • System.MultiTopicSavePlugin (1.7, $Rev: 9013 (2010-09-12) $): Save form data to multiple topics in one single submission
  • System.PiwikPlugin ($Date: 2009-08-18 17:13:53 +0200 (Tue, 18 Aug 2009) $, $Rev: 4684 (2009-08-18) $): Empty Plugin used as a template for new Plugins
  • System.PreferencesPlugin (1.1.2, $Rev: 13315 (2011-12-06) $): Allows editing of preferences using fields predefined in a form
  • System.RatingPlugin ($Date: 2009-08-18 17:13:53 +0200 (Tue, 18 Aug 2009) $, $Rev: 4684 (2009-08-18) $): Expose RatingContrib as a tag
  • System.RedirectPlugin (1.1, $Rev: 7923 (2010-06-26) $): Create a redirect to another topic or website.
  • System.RenderListPlugin (2.2.5, $Rev: 13315 (2011-12-06) $): Render bullet lists in a variety of formats
  • System.SlideShowPlugin (2.1.4, $Rev: 12410 (2011-08-28) $): Create web based presentations based on topics with headings
  • System.SmiliesPlugin (05 Dec 2011, $Rev: 13315 (2011-12-06) $): Render smilies like as icons
  • System.TablePlugin (1.138, $Rev: 13401 (2011-12-13) $): Control attributes of tables and sorting of table columns
  • System.TinyMCEPlugin (1.1.12, $Rev: 13315 (2011-12-06) $): Integration of the Tiny MCE WYSIWYG Editor
  • System.TwistyPlugin (1.6.15, $Rev: 13315 (2011-12-06) $): Twisty section Javascript library to open/close content dynamically
  • System.VarCachePlugin (29 Jan 2009, $Rev: 2215 (29 Jan 2009) $): Cache Foswiki macros in selected topics for faster page rendering
  • System.VotePlugin (1.33, $Rev: 4084 (2009-06-10) $): Simple way to count votes
  • System.WikiAppInstallerPlugin (1.0.0, $Rev: 13199 (2011-11-23) $): Explore, install, and package wiki applications
  • System.WysiwygPlugin (1.1.3, $Rev: 13315 (2011-12-06) $): Translator framework for WYSIWYG editors
• Related: ACTIVATEDPLUGINS, FAILEDPLUGINS, PLUGINVERSION

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

• Syntax: %PLUGINVERSION{"name"}% to get the version of a specific plugin
• Example: %PLUGINVERSION{"InterwikiPlugin"}% expands to $Rev: 12957 (2011-10-31) $
• Syntax: %PLUGINVERSION% to get the version of the API
• Expands to: 2.1
• Related: WIKIVERSION, ACTIVATEDPLUGINS, FAILEDPLUGINS, PLUGINDESCRIPTIONS

POPUPWINDOW{"topic" ...} -- opens a topic or url in a new window

• Parameters:

  Parameter:	Description:	Default:
  "topic", topic="topic", topic="web.topic"	Topic to open
  url	URL to open (if topic is not used)
  label	Link label	the topic or the url
  template	View template to call when viewing a topic; not used for URLs	"viewplain"
  width	Width of window	"600"
  height	Height of window	"480"
  toolbar	Show toolbars?	"0"
  scrollbars	Show scrollbars?	"1"
  status	Show status?	"1"
  location	Show location bar?	"0"
  resizable	Is the window resizable?	"1"
  left	Left position	"0"
  top	Top position	"0"
  center	Center the window?	"0"
  menubar	Show menubar?	"0"
  createnew	Create a new window for each popup?	"1"

• 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://