Reference Manual (v2.1.8)

Step 4: Configure the web server

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

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

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

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

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

Step 5: Bootstrap your configuration

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

Step 6: Configure email

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

Step 7: Check Authentication and Register Yourself

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

Step 8: Establish an Administrator user

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

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

Step 9. Save your configuration!

Congratulations! Your Foswiki Installation is Ready to Use!

Troubleshooting

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

    cd /path/to/foswiki
    perl tools/dependencies 

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

Supplemental Information For Installation

System Requirements

Server Requirements

cd /path/to/foswiki
perl tools/dependencies

Specific distribution details

Ubuntu and other Debian derived distributions

RedHat, SuSE, CentOS and other RPM based distributions

Gentoo (ebuild) based distributions

FreeBSD (pkg) based distributions

Installation with CPAN

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

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

Client Requirements

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

Uploading the Foswiki distribution to your web server host

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

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

About Administrators

Instead of adding users to the AdminGroup, grant those candidate administrators ALLOWTOPICCHANGE rights on the AdminGroup. They can then use a button on the AdminGroup page to join or leave the group at will.

Options to Protect the Configure Script

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

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

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

Establishing an internal admin login (optional)

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

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

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

     htpasswd -bn  admin {password}

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

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

User Authentication Options

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

Template Login authentication

Enabling Template Login

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

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

Apache Login authentication

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

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

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

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

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

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

Testing your authentication configuration:

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

Configuring Foswiki manually (without using the configure page)

$ perl -CAS tools/configure -save

$ tools/configure -save

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

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

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

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

{ScriptUrlPath} (/foswiki/bin):

...

tools/configure -save -noprompt
tools/configure -save -set {DefaultUrlHost}='http://mysite.com'
tools/configure -save -set {ScriptUrlPath}='/bin'
tools/configure -save -set {ScriptUrlPaths}{view}=''
tools/configure -save -set {PubUrlPath}='/pub'
perl -CA tools/configure -save -set {Password}='ÄdmînPäss' 

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

tools/configure -check -verbose

tools/configure -check {DataDir} -method validate_permissions

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

TWiki Compatibility

Foswiki Upgrade Guide

This upgrade procedure is used to upgrade a to a new major version of Foswiki (1.x to 2.x) or from TWiki. Generally, upgrades of a minor Foswiki version (2.0 to 2.1), or Foswiki patch releases (2.1.3 to 2.1.4) can be done by using the -upgrade- version of the Foswiki package, and follow the Release Notes for the new release.

Overview

Upgrade requirements

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

Upgrading to a new patch or minor release

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

Upgrade procedure: upgrading to a new major version

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

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

Before the upgrade

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

Prepare for all upgrade steps

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

• The EditTablePlugin has been deprecated and is not enabled by default on Foswiki 2.0. It is replaced by the EditRowPlugin. Only one of EditTablePlugin or EditRowPlugin should be enabled.
• Review the deprecated jQuery javascript plugins. The JQueryPlugin has several changes in available jQuery JavaScript plugins. Determine if any of these will impact your JavaScript enabled topics.

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

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

• RcsStoreContrib is compatible with topics created in prior versions of Foswiki.
• PlainFileStoreContrib requires that topic histories be converted to a new history format. This can be done at the same time you convert the character set. perl -I lib tools/bulk_copy.pl --help for more information on conversion.
  • Note: If your old data is on TWiki, then bulk_copy.pl is not compatible. You must migrate to Foswiki before converting the Store.

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

Installation

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

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

Install extensions

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

Copy parts of the working directory

Migrate .htpasswd file

Alternative 1: Convert the data using tools/bulk_copy.pl

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

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

Note that bulk_copy.pl has limitations! It uses the Foswiki Store API to copy topic and attachments. If the store doesn't recognize a topic or attachment, it won't be copied.

• Files in pub that are "hidden" from the store are not copied.
  • Any filename beginning with an underscore. For ex _myfile. Frequently used by extensions as cache type files. Could also have been directly uploaded.
  • Any filename beginning with a dot. For ex. .htaccess files.
  • Any filename beginning with an asterisk. (This appears to be historical, with no common use).
• Files in pub that are not associated with a topic attachment META are not copied. (ex. files manually copied into the pub directories).
  • Auto attachments are not copied if the {RCS}{AutoAttachPubFiles} feature is not enabled.
  • Auto attached files in the RCS store will be converted to regular attachments in the PlainFile store. The PlainFile store does not support auto attachments..
• Files in subdirectories of topic attachments are not copied. (ex. image caches, javascript & css subdirectories, etc.) This is common in the System web.
• All topic revisions must have the same encoding. If {Site}{CharSet} was changed after history exists, the history will not convert correctly and the copy may fail.
• bulk_copy.pl can be very slow converting topics with extensive histories. Each revision of a topic is separately converted. Any errors in the history can cause the conversion to fail.

bulk_copy.pl executes the code and APIs of the older Foswiki release. Older versions of Foswiki may fail on the latest versions of Perl due to language changes. If you encounter this issue, you could try an upgrade of the 1.1.x system to Foswiki 1.1.10, or use the CharsetConverterContrib to complete the migration.

bulk_copy.pl is not compatible with Foswiki 1.0.x versions. If you are copying data from Foswiki 1.0.x, there are two options:

1. Use CharsetConverterContrib to convert the data "in-place" on Foswiki 2.x -or-
2. Convert to Foswiki 1.1.10 first, and then convert to Foswiki 2.x.

The first option is faster and less complex.

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

Alternative 2: Convert data using CharsetConverterContrib

Main changes for older Foswiki installations

• Copy any topics shipped in the default Main web into your new Main, and check for any local customization of these default topics.
• 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.
  • Be sure to preserve the alphabetical order of the WikiUsers topic, and do not insert any blank lines.
• 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.

Convert empty DENY ACLs to ALLOW * wildcards

Get help text for convertTopicSettings

perl tools/convertTopicSettings.pl -help

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

perl tools/convertTopicSettings.pl

Replace all empty DENY rules with ALLOW * wildcards

perl tools/convertTopicSettings.pl -fixdeny -update

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

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

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

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

DataForms Applications

• Releases prior to Foswiki 2.0 stripped characters other than A-Z, a-z, 0-9 and _. So a field named Fühler would be stored as Fhler.
• The same DataForms definition on Foswiki 2.0 would be stored as Fühler.

  %META:FIELD{name="Fhler" title="Fühler" value="123"}%

  %META:FIELD{name="Fühler" title="Fühler" value="123"}%

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

Check your configuration and installation

cd <path-to-foswiki-installation>
sudo -u www-data tools/configure -check
sudo -u www-data perl tools/configure -check {DataDir} -method validate_permissions
sudo -u www-data perl tools/configure -check {PubDir} -method validate_permissions
 ...  also can be run on: 
    {LocalesDir} {ScriptDir}  {TemplateDir} {ToolsDir} {WorkingDir}

Validate your Wiki applications and other key functionality

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

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

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

User Authentication

Overview

• You are guest, WikiGuest,

Password Management

The default Password Manager, HtPasswdUser

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

Changing Passwords (and Email Addresses)

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

• The ChangeEmailAddress form ( Foswiki/ChangeEmailAddress )

User Mapping

The default User Mapping Manager, TopicUserMapping

User Registration

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

Configuration

• Enable user registration: {Register}{EnableNewUserRegistration}
• Use login names separate from the WikiName: {Register}{AllowLoginName}
• Verify the user's email address: {Register}{NeedVerification}
• Expiration of unverified pending registrations: {Register}{ExpireAfter}
• Approve registrations by a 3rd party: {Register}{NeedApproval}
• Block duplicate registrations by same email address: {Register}{UniqueEmail}
• Filter registering email addresses by domain: {Register}{EmailFilter}

How registration works:

• Main.UserRegistration or if that page does not exist,
• System.DefaultUserRegistration

• %NEWUSERTEMPLATE% - Specifies the template topic used to create the new user's topic. If not set, %USERSWEB.NewUserTemplate or if that does not exist, NewUserTemplate is used.
• %REGPARTS% - Specifies a list of topics used to resolve the INCLUDEs used to build the registration form. Defaults to the current topic, and then UserRegistrationParts.
• %FIELDS% - List optional fields to add to the registration form. They correspond to sections in the topics listed in %REGPARTS%
• %REGISTRATIONGROUPTYPE% and %REGISTRATIONGROUPS%, which controls automatic group membership upon registration.

Custom registration page

• The name="" parameter of the <input> tags must start with: "Fwk0..." (if this is an optional entry), or "Fwk1..." (if this is a required entry).
• The field name (without the Fwk* prefix) should be added to the Main.UserForm (or whaver form you use for user registration) so that they are stored in the user topics.

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 enrolment 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 RegistrationAgent. Group topics must include an ALLOWTOPICCHANGE = RegistrationAgent to be eligible for enrolment.

Registration by logged-in users

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

Login Management

No Login

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

Enabling Template Login

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

1. Using configure, Security And Authentication tab
   1. Navigate to the Login tab on the Security and Authentication panel. Select the Foswiki::LoginManager::TemplateLogin login manager.
   2. Navigate to the Passwords tab. Select the appropriate PasswordManager for your system - the default is Foswiki::Users::HtPasswdUser.
      There is an EXPERT configure setting {TemplateLogin}{PreventBrowserRememberingPassword} that you can set to prevent Browsers from remembering username and passwords if you are concerned about public terminal usage.
      There is an EXPERT configure setting {TemplateLogin}{AllowLoginUsingEmailAddress} that you can set to allow users to login using their password system registered e-mail addresses.
2. Verify that registration works by registering yourself with the System.UserRegistration topic. If there are problems, try these troubleshooting tips:
   1. Note: If e-mail is enabled in configure, Foswiki will not allow any new registrations unless e-mail is functional. In order to avoid issues, return to the Mail and Proxies, Email Test tab in configure and verify that Foswiki can successfully send e-mail.
   2. If your PasswordManager is HtPasswdUser (the default), check the .htpasswd file is being updated correctly with a new entry. If not, check {Htpasswd}{FileName} is correct (under Security and Authentication on the Password tab in configure), and that the webserver user has write permission.
3. Create a new topic (in Sandbox web for example) to confirm that authentication works.
4. Add users to the AdminGroup. Edit the 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 UserForm for copy instructions.

Controlling access to individual scripts

Enabling Webserver Login

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

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

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

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

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

      You can also refer to the sample foswiki_httpd_conf.txt and bin-htaccess-advanced.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: If e-mail is enabled in configure, Foswiki will not allow any new registrations unless e-mail is functional. In order to avoid issues, return to the Mail and Proxies, Email Test tab in configure and verify that Foswiki can successfully send e-mail.
   2. If your PasswordManager is HtPasswdUser (the default), check the .htpasswd file is being updated correctly with a new entry. If not, check {Htpasswd}{FileName} is correct (under Security and Authentication on the Password tab in configure), and that the webserver user has write permission.
3. Create a new topic (in Sandbox web for example) to confirm that authentication works.
4. Add users to the AdminGroup. Edit the 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

Controlling access to individual scripts

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

Sessions and Roaming or Mobile Users

Optional Sessions for Guest users

Important Considerations

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 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 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!

• Set ALLOWTOPICVIEW = Main.SecretGroup
  • This group will be usable in the ACL of any topic, but is only visible to members of the group.
  • Caution As with the the prior example, this is set in the "Topic Settings" and not inline in the topic text!

Foswiki has strict formatting rules. Settings must be entered as a bullet point.

• With the TML editor, or in the Settings editor, make sure you have three spaces, an asterisk, and an extra space in front of any access control rule.
• When using the WYSIWYG editor, create a bullet using the bullet button on the toolbar.

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

Hint: Instead of adding users to the AdminGroup, consider adding them to the ALLOWTOPICCHANGE setting for the AdminGroup. Those users will then be able to add and remove themselves from the AdminGroup when they need admin rights, rather than running as admin all the time.

Restricting Access

• The {AuthScripts} setting in configure -> Security and Authentication -> Login;
• The {FeatureAccess} settings in configure -> Security and Authentication -> Access Control; and
• setting the values of certain preferences.

• Restricting VIEW blocks viewing and searching of content. When you restrict 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.

• Restricting HISTORY blocks access to older revisions of topics by the rev= URL parameter.
• Restricting RAW blocks access to the raw= topic text.

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 >
• If {FeatureAccess}{AllowRaw} is set to acl in configure, then the following rules are also active:
  • Set ALLOWWEBRAW = < comma-delimited list of users and groups >
  • Set DENYWEBRAW = < comma-delimited list of users and groups >
• If {FeatureAccess}{AllowHistory} is set to acl in configure, then the following rules are also active:
  • Set ALLOWWEBHISTORY = < comma-delimited list of users and groups >
  • Set DENYWEBHISTORY = < 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 >
• If {FeatureAccess}{AllowRaw} is set to acl in configure, then the following rules are also active:
  • Set ALLOWTOPICRAW = < comma-delimited list of users and groups >
  • Set DENYTOPICRAW = < comma-delimited list of users and groups >
• If {FeatureAccess}{AllowHistory} is set to acl in configure, then the following rules are also active:
  • Set ALLOWTOPICHISTORY = < comma-delimited list of users and groups >
  • Set DENYTOPICHISTORY = < 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. If the topic was restricted because it contained sensitive information, and that information was removed, it still exists in the topic history. Once you remove the access restrictions, the topic history will be viewable.

Access rules in Foswki version 1.x

If your site started out life using an earlier version of Foswiki, you might have seen that from Foswiki 2.0 onwards, the empty DENY has been removed. This rule has been replaced by * wildcards in the ALLOW and DENY rules.

The previous documentation said:

• Set ALLOWTOPICVIEW =
  This means the same as not setting it at all.
• Set DENYTOPICVIEW =
  This means the same as not setting it at all.

As of Foswiki 2.0, the empty DENY setting is now meaningless, unless explicitly overridden by your installation.

	Before Foswiki 2.0	Foswiki 2.0 and newer
Allow ALL users	Set DENY to an empty string	Set ALLOW to *
Allow All logged-in users	Set DENY to WikiGuest Leave ALLOW un-set	<no change from before>
Deny all access	Set ALLOW to NobodyGroup	Set ALLOW to NobodyGroup -or- Set DENY to *
Allow selected users	Set ALLOW to desired users/groups	Set ALLOW to desired users/groups
Deny selected users	Set DENY to desired users/groups	Set DENY to desired users/groups

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.

Wildcard matching

• Set ALLOWTOPICVIEW = *
  This allows everyone.
• Set DENYTOPICVIEW = WikiGuest
  This overrides the ALLOW, and denies the guest user.

Note that it is not possible to override a DENY with an ALLOW at the same level ALLOW on a topic can override DENY at the web level, but not at the TOPIC level

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 has been removed. 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. The Foswiki:Support.ApacheConfigGenerator has some more extensive examples of protecting user attachments, but allowing direct access to trivial graphics attached to System topics.

Controlling who can manage top-level webs

• You can define these settings in the 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, or set to the * wildcard
   • people in the list will be DENIED.
3. If ALLOWTOPIC is set to a list of WikiNames, or set to the * wildcard
   1. people in the list are PERMITTED
   2. everyone else is DENIED (nobody is denied if ALLOW is set to *)
4. If DENYWEB is set to a list of WikiNames, or set to the * wildcard
   
   • people in the list are DENIED access (everyone if DENY is set to *)
5. If ALLOWWEB is set to a list of WikiNames, or set to the * wildcard
   • people in the list will be PERMITTED
   • everyone else will be DENIED (nobody is denied if ALLOW is set to *)
6. 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) to the list of {AuthScripts} in configure, Security And Authentication tab, Login sub-tab, For a default Foswiki installation:

• Default (open) site:

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

• Restricted (closed) site:

{AuthScripts} = 'attach,changes,compare,compareauth,configure,edit,jsonrpc,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.

Authenticate and restrict most webs, Allow access to selected topics

1. Restrict view access by the guest user, and then selectively unlock topics required for normal operation
   
   • Set <nop>DENYWEBVIEW = WikiGuest Set this in each WebPreferences topic:
   • Set <nop>ALLOWTOPICVIEW = * Set this in each topic that needs to be unlocked for unauthenticated users.
   • Note: ALLOWTOPICVIEW is evaluated before DENYWEBVIEW. Access is permitted if the authenticated person (or wildcard) is in the ALLOWTOPICVIEW list. The list of topics that need to be unlocked in the System web for login, password reset, registration, and guest access when the System has been locked down is rather extensive.

Control access to topic History and Raw text.

• authenticated - This is the default. Anyone who is logged in has access
• acl - The feature can be controlled per web or topic using ALLOW or DENY ACLs.
• all - Open access like on Foswiki 1.x

• Set DENYWEBRAW = WikiGuest
• Set DENYWEBHISTORY = WikiGuest

Show control settings

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

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

Hide control settings

<!-- 

 * Set DENYTOPICCHANGE = Main.SomeGroup 

-->

Controlling access to the System web.

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

Macros

%MACRONAME%
%MACRONAME{ parameter="value" }%
%MACRONAME{
  param1="value "
        +"& more "
  param2="whatever"
  param1+="and even more"
}%

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

Using Macros

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

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

Order of expansion

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

Standard form

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

Step-by-Step Example

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

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

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

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

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

These topics are for frequently
asked questions including answers.

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

These topics are for frequently
asked questions including answers.

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

Delayed form

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

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

Step-by-Step Example

Step 1

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

Step 2

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

Step 3

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

Step 4

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

Step 5

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

Macro Names

Preference Settings

• preference settings are used by Plugins to control their features,
• preference settings are used for Access Control.

   * Set WEBBGCOLOR = #FFFFC0

1. DefaultPreferences (Foswiki upgrades overwrite this topic)
2. In (some) plugin documentation topics. (Deprecated)
3. SitePreferences
4. In user topics, if the user has one (yours is Main.WikiGuest)
5. WebPreferences in each web.
6. Sub-webs inherit the WebPreferences of their parent
7. In the topic when it is loaded from the Store
8. In SET macros for run-time preferences

Writing preference settings

   * Set MYSETTING = My setting value

   * Set MACRONAME = value starts here
     and continues here

   * #Set DENYWEBCHANGE = %USERSWEB%.UnknownUser

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

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

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

Hiding preference settings

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

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

Order of preference settings

• Preferences and their effect will be visible in the preview.
• %SET{} will override both META and bullet style settings unless the preference is FINALIZED.
• The %SET{} is positional in the topic. Multiple %SET{} macros for the same preference will change the value as the topic is rendered.

Preference settings and topic revision history

Preference settings and INCLUDE

• Bullet and META style preference settings are never set when topic content is obtained by %INCLUDE{.
• %SET{ style settings can be overidden when an INCLUDE is expanded, but only when referenced locally in the included topic.

Parameters

Macros defined using preference settings can take parameters. These are symbols passed in the call to the macro to define local macros that will be expanded in the output. For example, Both Macros and PreferenceSettings have a Set statement that defines the %CONDITIONS% macro as shown here:

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

The %TOPIC% shows where the CONDITIONS macro is expanded, and the ... shows where the Set statement was actually defined.

You can call this macro passing in values for WHAT and STATE. For example:

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

   * Local NOWYSIWYG = 1

%SHOWPREFERENCE{"CONDITIONS"}%

• Set CONDITIONS = ""

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

Readable Macros

• parameter="value" +"more" +"and more"
• param1+="value1" param2+="value2" param1+="more1" param2+="more2"

type="query" nonoise="on" web="Batch" header="|*Batch Code*|*Batch Value*|*Currencies*|*Sizes*|*Count*|*To Queue*|*Killed*|*Ignored*|*Errors*|*Notes*|*History*|*Flow*|" format="| [[$topic][$formfield(BatchCode) $formfield(BatchDate) $formfield(BatchNumber) $formfield(BatchLocation)]]"}$percnt | $formfield(BatchValue) | $formfield(BatchCurrencies) | $formfield(BatchSizes) | $formfield(BatchCount) | $formfield(BatchToQueue) | $formfield(BatchKilled) | $formfield(BatchIgnored) | <div style='background-color:#$percntCALC{$SET(dat,$formfield(BatchDate))$SET(pdat,$formfield(BatchProcessDate))$SET(age,$EVAL($percnt$formfield(BatchCode)_days$percnt))$IF($EXACT($percntWORKFLOWSTATE{\"$topic\"}$percnt,CHECKED),FAF0D4,$IF($GET(age)>=0,ff3300,$IF($GET(age)>=-2,ff9933,66cc33)))}$percnt'>$formfield(BatchErrors)&nbsp;</div> | $formfield(BatchOperators) | $formfield(BatchActivities) | <form name=\"Edit\" action=\"%SCRIPTURLPATH{edit}%/%WEB%/\"> <input type=\"hidden\" name=\"action\" value=\"form\"/> <input type=\"hidden\" name=\"topic\" value=\"$topic\"/> <input type=\"hidden\" name=\"redirectto\" value=\"%TOPIC%?%QUERYSTRING{encode="url"}%\"/> <input type=\"image\" src=\"%ICONURL{pencil}%\" alt=\"Edit Form\" /> </form> $formfield(BatchNotes) | $percntWORKFLOWHISTORY{\"$topic\"}$percnt | $percntWORKFLOWTRANSITION{\"$topic\" redirectto=\"%TOPIC%?%QUERYSTRING{encode="url"}%\"}$percnt |"

  type="query"
  nonoise="on"
  web="Batch"
  header="|*Batch Code*|*Batch Value*|*Currencies*|*Sizes*|*Count*|*To Queue*|*Killed*|*Ignored*|*Errors*|*Notes*|*History*|*Flow*|"
  format="| [[$topic][$formfield(BatchCode) $formfield(BatchDate) $formfield(BatchNumber) $formfield(BatchLocation)]] | $formfield(BatchValue) | $formfield(BatchCurrencies) | $formfield(BatchSizes) | $formfield(BatchCount) | $formfield(BatchToQueue) | $formfield(BatchKilled) | $formfield(BatchIgnored) | <div style='background-color:#$percntCALC{$SET(dat,$formfield(BatchDate))$SET(pdat,$formfield(BatchProcessDate))$SET(age,$EVAL($percnt$formfield(BatchCode)_days$percnt))$IF($EXACT($percntWORKFLOWSTATE{\"$topic\"}$percnt,CHECKED),FAF0D4,$IF($GET(age)>=0,ff3300,$IF($GET(age)>=-2,ff9933,66cc33)))}$percnt'>$formfield(BatchErrors)&nbsp;</div> | $formfield(BatchOperators) | $formfield(BatchActivities) | <form name=\"Edit\" action=\"%SCRIPTURLPATH{edit}%/%WEB%/\"> <input type=\"hidden\" name=\"action\" value=\"form\"/> <input type=\"hidden\" name=\"topic\" value=\"$topic\"/> <input type=\"hidden\" name=\"redirectto\" value=\"%TOPIC%?%QUERYSTRING{encode="url"}%\"/> <input type=\"image\" src=\"%ICONURL{pencil}%\" alt=\"Edit Form\" /> </form> $formfield(BatchNotes) | $percntWORKFLOWHISTORY{\"$topic\"}$percnt | $percntWORKFLOWTRANSITION{\"$topic\" redirectto=\"%TOPIC%?%QUERYSTRING{encode="url"}%\"}$percnt |"

  type="query"
  nonoise="on"
  web="Batch"
  header=""
        +"|*Batch Code*"
        +"|*Batch Value*"
        +"|*Currencies*"
        +"|*Sizes*"
        +"|*Count*"
        +"|*To Queue*"
        +"|*Killed*"
        +"|*Ignored*"
        +"|*Errors*"
        +"|*Notes*"
        +"|*History*"
        +"|*Flow*"
        +"|"
  format=""
        +"| [[$topic][$formfield(BatchCode) $formfield(BatchDate) $formfield(BatchNumber) $formfield(BatchLocation)]]"
        +"| $formfield(BatchValue) "
        +"| $formfield(BatchCurrencies) "
        +"| $formfield(BatchSizes) "
        +"| $formfield(BatchCount) "
        +"| $formfield(BatchToQueue) "
        +"| $formfield(BatchKilled) "
        +"| $formfield(BatchIgnored) "
        +"| <div style='background-color:#"
        +"$percntCALC{"
        +"$SET(dat,$formfield(BatchDate))"
        +"$SET(pdat,$formfield(BatchProcessDate))"
        +"$SET(age,$EVAL($percnt$formfield(BatchCode)_days$percnt))"
        +"$IF($EXACT($percntWORKFLOWSTATE{\"$topic\"}$percnt,CHECKED),FAF0D4,"
        +"$IF($GET(age)>=0,ff3300,$IF($GET(age)>=-2,ff9933,66cc33)))}"
        +"$percnt'>$formfield(BatchErrors)&nbsp;</div> "
        +"| $formfield(BatchOperators) "
        +"| $formfield(BatchActivities) "
        +"| <form name=\"Edit\" action=\"%SCRIPTURLPATH{edit}%/%WEB%/\">"
        +"<input type=\"hidden\" name=\"action\" value=\"form\"/>"
        +"<input type=\"hidden\" name=\"topic\" value=\"$topic\"/>"
        +"<input type=\"hidden\" name=\"redirectto\" value=\"%TOPIC%?%QUERYSTRING{encode="url"}%\"/>"
        +"<input type=\"image\" src=\"%ICONURL{pencil}%\" alt=\"Edit Form\" /> </form> $formfield(BatchNotes) "
        +"| $percntWORKFLOWHISTORY{\"$topic\"}$percnt "
        +"| $percntWORKFLOWTRANSITION{\"$topic\" redirectto=\"%TOPIC%?%QUERYSTRING{encode="url"}%\"}$percnt "
        +"|"

parameter="value" +" and more" — is quite valid on one line if its useful

parameter="1" +"2" gives you "12" not "3"

  type="query"
  nonoise="on"
  web="Batch"

  header+="|*Control record*"
  format+="| <span style=\"display:none;\">"
         +"$formfield(BatchNumber) $formfield(BatchLocation) "
         +"$percntCALC{$SUBSTRING($topic,13,3)}$percnt $formfield(BatchDate) "
         +"!$formfield(BatchCode)"
         +"</span>"
         +"<a id=\"$topic\"/>[[$topic]]"

  header+="|*Batch Value*"
  format+="|  $formfield(BatchValue) "

  header+="|*Batch Curr- encies*"
  format+="| $formfield(BatchCurrencies) "

  header+="|*Success*"
  format+="|  $formfield(BatchCount) "

  header+="|*To Queue*"
  format+="|  $formfield(BatchToQueue) "

  header+="|*Killed*"
  format+="|  $formfield(BatchKilled) "

  header+="|*Ignored*"
  format+="|  $formfield(BatchIgnored) "

  header+="|*Batch Size*"
  format+="|  $formfield(BatchSizes) "

  header+="|*Batch Errors*"
  format+="| <div style='background-color:#"
         +"$percntCALC{$SET(dat,$formfield(BatchDate))"
         +"$SET(pdat,$formfield(BatchProcessDate))"
         +"$SET(age,$EVAL($percnt$formfield(BatchCode)_days$percnt))"
         +"$IF($EXACT($percntWORKFLOWSTATE{\"$topic\"}$percnt,CHECKED),FAF0D4,"
         +"$IF($GET(age)>=0,ff3300,$IF($GET(age)>=-2,ff9933,66cc33)))}$percnt'>"
         +"$formfield(BatchErrors) </div> "

  header+="|*Batch Oper- ators*"
  format+="| $formfield(BatchOperators) "

  header+="|*Batch Acti- vities*"
  format+="| $formfield(BatchActivities) "

  header+="|*Batch Notes*"
  format+="| <form name=\"Edit\" action=\"%SCRIPTURLPATH{edit}%/%WEB%/\">"
         +"<input type=\"hidden\" name=\"action\" value=\"form\"/>"
         +"<input type=\"hidden\" name=\"topic\" value=\"$topic\"/>"
         +"<input type=\"hidden\" name=\"redirectto\" value=\"%TOPIC%?%QUERYSTRING%#$topic\"/>"
         +"<input type=\"image\" src=\"%ICONURL{pencil}%\" alt=\"Edit Form\" /> </form> $formfield(BatchNotes)"

  header+="|*Status History*"
  format+="| $percntWORKFLOWHISTORY{\"$topic\"}$percnt "

  header+="|*Change Status*"
  format+="| $percntWORKFLOWTRANSITION{\"$topic\" redirectto=\"%TOPIC%?%QUERYSTRING%#$topic\"}$percnt "

  header+="|"
  format+="|"

%SEARCH{"form.name ~ 'FAQForm'"
  type="query"
  web="System"
  nonoise="on"

  header+="|*Title*"
  format+="|$formfield(TopicTitle)"

  header+="|*Topic*"
  format+="|$web.$topic"

  header+="|*Summary*"
  format+="|$formfield(TopicSummary)"

  header+="|*Related Topics*"
  format+="|$formfield(RelatedTopics)"

  header+="|"
  format+="|"
}%

ACTIVATEDPLUGINS -- list of currently activated plugins

Examples

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

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

Parameters

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

What is a "Zone"?

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

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

Adding content to a zone

Enforcing a linear order of content within a zone

Working with {MergeHeadAndScriptZones} disabled (default)

Working with {MergeHeadAndScriptZones} enabled

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

Examples

Adding to a zone with missing dependencies

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

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

Adding Javascript to a page

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

Adding CSS to a page

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

ATTACHURL -- full URL for attachments in the current topic

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

AUTHREALM -- authentication realm

Examples

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

BASETOPIC -- base topic where an INCLUDE started

BASEWEB -- base web where an INCLUDE started

BUTTON -- renders a nice button

Parameters

Examples

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

• Expands as:
  Submit Cancel

CALC -- add spreadsheet calculations to tables and outside tables

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

Examples

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

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

Examples

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

Related

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

Parameters

• The following standard attributes are recognized

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

Examples

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

COVER -- current skin cover

Examples

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

DATE -- signature format date

Examples

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

DISPLAYTIME -- display formatted time

Parameters

Examples

• %DISPLAYTIME% expands to 31 Oct 2024 - 23:01
• %DISPLAYTIME{"$hou:$min"}% expands to 23:01

ENCODE -- encode characters in a string

Parameters

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

Predefined encodings

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

Examples

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

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

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

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

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

ENDINCLUDE -- end position of topic text if included

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

Parameters

Examples

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

ENDTAB -- ending marker for a tab of a tabpane

ENDTABPANE -- ending tag for tabpane widget

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

ENDTWISTYTOGGLE -- Twisty closure

Examples

ENV -- inspect the value of an environment variable

Examples

• %ENV{MOD_PERL}% displays as: mod_perl/2.0.12

EXAMPLETAG -- example macro tag

Parameters

Examples

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

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

Parameters

Examples

   * Set MYPREFERENCE = value

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

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

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

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

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

FAILEDPLUGINS -- debugging for plugins that failed to load

Examples

• %FAILEDPLUGINS%

FORMAT -- format a list of objects

Parameters

Examples

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

Supported formatting tokens

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

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

Parameters

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

Examples

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

GMTIME -- formatted Greenwich Mean Time (UTC)

Parameters

Supported special format tokens:

Examples

• %GMTIME% expands to 31 Oct 2024 - 23:01
• %GMTIME{"$day $month, $year - $hour:$min:$sec"}% expands to 31 Oct, 2024 - 23:01:16
  When used in a template topic, this macro will be expanded when the template is used to create a new topic. See TemplateTopics#TemplateTopicsVars for details.

GROUPINFO -- retrieve details about a group

Parameters

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

Examples

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

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

Parameters

Additional macros

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

HOMETOPIC -- home topic in each web

Examples

• %HOMETOPIC% expands to WebHome, renders as WebHome

HTTP -- get HTTP headers

• Called with the name of an HTTP request header field, returns its value. Capitalization and the use of hyphens versus underscores are not significant.
• Request headers are sent by the browser to the server. It is not possible to access the Response headers returned to the browser.
• Only returns headers permitted by site configuration. Returns '' if the header is not allowed.
• When called without a parameter, nothing is returned. See VarHTTPS for other options.

The HTTP and HTTPS macros are deprecated as of Foswiki release 2.1. and will be removed in a future release.

Parameters

Name	Description
"name"	Name of the header to get

Examples

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

HTTP_HOST -- environment variable

Examples

• %HTTP_HOST% expands to wiki.digitalmethods.net

HTTPS -- get HTTPS headers

• Called with the name of an HTTP request header field, returns its value. Capitalization and the use of hyphens versus underscores are not significant.
• Request headers are sent by the browser to the server. It is not possible to access the Response headers returned to the browser.
• Only returns headers permitted by site configuration.
• When called without a parameter, nothing is returned. See VarHTTPS for other options.

The HTTP and HTTPS macros are deprecated as of Foswiki release 2.1. and will be removed in a future release.

Parameters

Examples

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

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

Parameters

Examples

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

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

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

ICONURL -- URL of small documentation graphic or icon

Parameters

Examples

• %ICONURL% returns https://www.digitalmethods.net/bin/../pub/System/DocumentGraphics/else.png
• %ICONURL{"arrowbright"}% returns https://www.digitalmethods.net/bin/../pub/System/DocumentGraphics/arrowbright.png
• %ICONURL{"novel.pdf"}% returns https://www.digitalmethods.net/bin/../pub/System/DocumentGraphics/pdf.png
• %ICONURL{"notanicon" default="ram"}% returns https://www.digitalmethods.net/bin/../pub/System/DocumentGraphics/ram.png
• %ICONURL{"/queen/boheme.mp3"}% returns https://www.digitalmethods.net/bin/../pub/System/DocumentGraphics/mp3.png

ICONURLPATH -- URL path of small documentation graphic or icon

Parameters

Examples

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

IF -- simple conditionals

Examples

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

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

FUNFACTOR is not defined

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

(Including a topic) Parameters

• Examples: See IncludeTopicsAndWebPages

(Including a web page) Parameters

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

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

Foswiki by default is configured to deny URL format includes.

• Examples: See IncludeTopicsAndWebPages

(Including Foswiki embedded module documentation) Parameters

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

INCLUDINGTOPIC -- name of topic that includes current topic

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

INCLUDINGWEB -- web that includes current topic

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

JQICON -- render an image

Parameters

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

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

JQICONPATH -- render the url path to an image icon

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

Examples

JQPLUGINS -- display a summary of available plugins

Parameters

Examples

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

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

JQREQUIRE -- enable a plugin on the current page

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

Parameters

Examples

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

JQTHEME -- switch jQuery UI theme

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

Parameters

LANG -- the language specified by the server locale

• In templates the lang attribute is defined like this:

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

• Do not confuse LANG with LANGUAGE

Examples

• %LANG% expands to en

LANGUAGE -- language code for the current user

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

Examples

• %LANGUAGE% expands to en

LANGUAGES -- list available languages

Parameters

Examples

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

LOCALSITEPREFS -- web.topicname of site preferences topic

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

Examples

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

LOGIN -- present a full login link

Examples

• %LOGIN% expands to Log In

LOGOUT -- present a full logout link

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

Examples

• %LOGOUT% expands to

MAKETEXT -- creates text using Foswiki's I18N infrastructure

Parameters

Examples

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

Notes

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

Plurals

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

Notes on plurals

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

META -- displays meta-data

Parameters

"form"

"attachments"

"moved"

"parent"

"formfield"

Related

NONCE -- generate a nonce (developers only)

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

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

NOTIFYTOPIC -- name of the notify topic

Examples

• %NOTIFYTOPIC% expands to WebNotify, renders as WebNotify

PERLDEPENDENCYREPORT -- report perl module dependencies

Parameters

PLUGINDESCRIPTIONS -- list of plugin descriptions

Examples

• %PLUGINDESCRIPTIONS% expands to
  • SpreadSheetPlugin (17 May 2023, 1.25): Add spreadsheet calculations like "$SUM($ABOVE())" to Foswiki tables and other topic text
  • SlideShowPlugin (09 Mar 2021, 2.40): Create web based presentations based on topics with headings
  • AutoViewTemplatePlugin (2016-04-08, 1.24): Automatically sets VIEW_TEMPLATE and EDIT_TEMPLATE
  • BlackListPlugin (08 Jan 2010, $Rev: 5969 (2010-01-07) $): Utility to keep malicious users away from a public Foswiki site
  • CommentPlugin (06 Aug 2023, 2.95): Quickly post comments to a page without an edit/save cycle
  • CompareRevisionsAddonPlugin (1.114, 1.114):
  • ConfigurePlugin (06 Aug 2023, 1.12): configure interface using json-rpc
  • EditRowPlugin (12 Jan 2024, 3.402): Inline edit for tables
  • FilterPlugin (21 Jan 2024, 7.10): Substitute and extract information from content by using regular expressions
  • HistoryPlugin (16 Nov 2020, 1.20): Shows a complete history of a topic
  • HomePagePlugin (1.23, 1.23): Allow User specified home pages - on login
  • IfDefinedPlugin (2.01, 2.01): Render content conditionally
  • InterwikiPlugin (06 Aug 2023, 1.27): Link ExternalSite:Page text to external sites based on aliases defined in a rules topic
  • JQueryPlugin (25 Apr 2023, 10.51): jQuery JavaScript library for Foswiki
  • MailerContribPlugin (2.84, 2.84): Supports e-mail notification of changes
  • NatEditPlugin (11 Jul 2023, 9.63): A Wikiwyg Editor
  • PreferencesPlugin (1.16, 1.16): Allows editing of preferences using fields predefined in a form
  • RenderListPlugin (06 Aug 2023, 2.29): Render bullet lists in a variety of formats
  • SmiliesPlugin (17 Sep 2015, 2.03): Render smilies like as icons
  • SubscribePlugin (06 Aug 2023, 3.7): This is a companion plugin to the MailerContrib. It allows you to trivially add a "Subscribe me" link to topics to get subscribed to changes.
  • TablePlugin (22 Jan 2018, 1.160): Control attributes of tables and sorting of table columns
  • TagMePlugin (10 Jan 2017, 2.2): Tag wiki content collectively to find content by keywords
  • TinyMCEPlugin (11 Feb 2019, 1.32): Integration of the Tiny MCE WYSIWYG Editor
  • TwistyPlugin (29 Jun 2023, 3.00): Twisty section Javascript library to open/close content dynamically
  • UpdatesPlugin (12 Nov 2019, 2.00): Checks Foswiki.org for updates
  • WysiwygPlugin (13 Jun 2018, 1.38): Translator framework for WYSIWYG editors