Resource | Required Server Environment * |
---|---|
Perl | 5.6.1 or higher (5.8.4 or higher is recommended) |
RCS | 5.7 or higher (including GNU diff ) Optional, Foswiki includes a pure perl implementation of RCS that can be used instead (although it's slower) |
GNU diff |
GNU diff 2.7 or higher is required when not using the all-Perl RcsLite. Install on PATH if not included with RCS (check version with diff -v ) Must be the version used by RCS, to avoid problems with binary attachments - RCS may have hard-coded path to diff |
GNU patch |
For upgrades only: GNU patch is required when patching the code using patches in diff format submitted by the community. |
GNU fgrep , egrep |
Modify command line parameters in configure if you use non-GNU grep programs |
Cron/scheduler | • Unix: cron • Windows: cron equivalents |
Web server | Apache is well supported; see Foswiki:Support.InstallingOnSpecificPlatforms for alternative options. |
lib/DEPENDENCIES
.
Most of them will probably already be available in your installation. You can check version numbers with the configure
script, or if you're still trying to get to that point, check from the command line like this:
perl -e 'use FileHandle; print $FileHandle::VERSION."\n"'
System.InstallationGuide
(the InstallationGuide topic in the System web).
For information on upgrades, please also refer to Foswiki:System.UpgradeGuide. A static HTML version of this document, UpgradeGuide.html
, is included in the root of your Foswiki distribution.
UpgradeGuide.html
, is included in the root of your Foswiki distribution.
Verify that your server meets the Foswiki system requirements, including having the minimum required Perl version and all required Perl modules installed. If you need to install any Perl libraries from CPAN for use by Foswiki, see Foswiki:Support.HowToInstallCpanModules for more information.
If you need help, feel free to ask a question in the Foswiki:Support web or on Foswiki:Community.InternetRelayChat (irc.freenode.net, channel #foswiki).
/path/to/foswiki
. foswiki
directory tree.
Note: for more information on the appropriate permissions to ensure security for your Foswiki data, see Foswiki:Support.SecuringYourSite.
The default file and directory access permissions as set by the distribution define a reasonable security level that will work for many types of installations, including shared hosting. Nonetheless, you should verify that the web server user has read access to all files and directories beneath the foswiki
directory, and execute access for all directories. Also verify that the data
and pub
directories and all the subdirectories and files beneath them allow write access for the web server user. chmod -R 770 foswiki
. Providing execute access to all files is potentially dangerous. This is a common mistake made by Foswiki installers. See Foswiki:Support.SettingFileAccessRightsLinuxUnix for a sample set of Unix commands to set the file and directory permissions.
foswiki
directory tree to the web server user, using the command chown -R user:group /path/to/foswiki
. The web server username varies in different installations; here are some sample commands for various Linux distributions: chown -R apache:apache /path/to/foswiki
chown -R www-data:www-data /path/to/foswiki
chown -R wwwrun:www /path/to/foswiki
/usr/bin/perl
. If it's somewhere else, change the path to Perl in the first line of each script (you may have to give yourself write permission first) in the bin
and tools
directories. You can use the tools/rewriteshbang.pl
script to do this; for example:cd /path/to/foswiki/bin /path/to/perl ../tools/rewriteshbang.pl # At the prompt, enter the full path to the perl executable, including # the full filename of the executable. You will be prompted twice for # this information in order to confirm it. cd /path/to/foswiki/tools /path/to/perl rewriteshbang.plSome web servers require a special extension on perl script files (e.g.
.cgi
or .pl
). This is not normally required with the Apache web server, though some hosted web servers are configured to require it. If the documentation for your web server indicates that a special extension is necessary, rename all the executable scripts in bin
; that is, rename bin/view
to bin/view.pl
, and so on. When configuring Foswiki (see the section "Configure Foswiki"), set the ScriptSuffix
option to the special extension.
Create the file LocalLib.cfg located at bin/LocalLib.cfg
bin
directory, copy the template file LocalLib.cfg.txt
to LocalLib.cfg
. Make sure the ownership and access rights of the copy are the same as LocalLib.cfg.txt.
bin/LocalLib.cfg
so that $foswikiLibPath
is set to the absolute file path of your lib
directory. For example: /path/to/foswiki/lib
.
$CPANBASE
to point to your personal CPAN install. Don't forget that the web server user has to be able to read those files as well.
foswiki.conf
). Performance is much better with a config file, and one file gives the best overview and ensures that you get a safe installation . However to use a config file you need root or sudo access to stop and start Apache. The Foswiki apache config file is included from the main Apache config file http.conf. Most distributions have a directory from which any file that ends with .conf
gets included when you restart Apache (Example RedHat/Fedora/Centos: /etc/httpd/conf.d
). If you use a virtual host setup in Apache you should include the foswiki.conf
file from inside the desired virtual host config in your Apache configuration.
.htaccess
files on each page access. Normally this is the only way to control Apache in a shared host environment where you have no root or sudo privileges.
foswiki_httpd_conf.txt
can be found in the root of the foswiki installation.
bin
and pub
. The Foswiki:Support.ApacheConfigGenerator tool will generate the appropriate settings; the foswiki_httpd_conf.txt
file also has examples of configuring Apache appropriately.
ScriptAlias
directive for the bin
subdirectory, or an Alias
directive with SetHandler cgi-script
and Options ExecCGI
directives for the bin
subdirectory, so that the bin
scripts will be executed by Apache.
bin
directory, there are sample .htaccess
files for various subdirectories in your installation. Each file has help text explaining how to modify it for your configuration. For more information, see Foswiki:Support.SupplementalDocuments. location and name of sample .htaccess file | copy sample file to the following location |
---|---|
foswiki/root-htaccess.txt | foswiki/.htaccess |
foswiki/bin/.htaccess.txt | foswiki/bin/.htaccess |
foswiki/pub-htaccess.txt | foswiki/pub/.htaccess |
foswiki/subdir-htaccess.txt | .htaccess in all other subdirectories below foswiki |
bin
and pub
. The sample .htaccess
files show how to configure Apache appropriately.
foswiki/bin/.htaccess
files contains the line SetHandler cgi-script
so that all scripts in the bin
directory will be executed by Apache.
pub
directory. For example, most Linux distributions have a default Apache installation with PHP and server side include (SSI) enabled. This would allow PHP scripts uploaded as attachments to be executed, which is a security risk, so it should be disabled in the Apache configuration with php_admin_flag engine off
.
Different script execution mechanisms are disabled in different ways; see your web server configuration and documentation for more details.
Protect the configure script: You should never leave the configure
script open to the public. Limit access to the bin/configure
script to either localhost, an IP address or a specific user using basic Apache authentication. The Foswiki:Support.ApacheConfigGenerator lets you setup who has access to the configure
script. Also see the foswiki-httpd-conf.txt
or bin/.htaccess.txt
file for an example of the setting required to protect the configure
script.
To limit access to a particular user, set up a .htpasswd
file that contains the user name and password that Apache will use to authenticate the user: foswiki/data
directory.
htpasswd -c .htpasswd <username>
, where <username> is the name of the user you will use to access the configure
script. Choose the username with care: the username cannot be an existing login name for your Foswiki installation, nor can it be used later on to register in Foswiki. Enter a password when prompted.
configure
web page will be protected using the user and password held in the data/.htpasswd
file. The Apache config file or .htaccess file will have a Require user <username>
directive to restrict access to the configure
script. Ensure the user specified in the directive matches the <username> you used when creating the .htpasswd file.
Note: In addition to any web server security protection that you have set up, when saving any configuration settings for the first time on the configure
web page, you will be prompted to set a configuration password. This password must be entered on all subsequent configuration changes, and is also used to log in via the internal admin link (see the section "Define the administrator user(s)"). Even after a configure
password has been set, access to the configure
page should still be restricted by the web server, in order to avoid revealing internal information to potential attackers.
For more information, refer to Foswiki:Support.ProtectingYourConfiguration.
configure
script from your browser: enter http://yourdomain/foswiki/bin/configure
into your browser address bar. configure
web page for the first time, you can only edit the section General Path Settings
. Make any required changes, and save the settings, whether or not you needed to make any changes. You will be prompted to set a password for the configure
page: this password must be entered for all subsequent configuration changes, and is also used to log in via the internal admin link (see the section "Define the administrator user(s)"). Note the configuration password is separate from any web server security you have set up for the configure
web page (see "Protect the configure script").
{PermittedRedirectHostUrls}
{WebMasterEmail}
and {SMTP}{MAILHOST}
settings must be defined so Foswiki can send registration emails. Many ISPs have introduced authentication when sending emails to fight spam so you may also have to set {SMTP}{Username}
and {SMTP}{Password}
. If you do not want to enable sending registration emails or want to enable it later you can uncheck {EnableEmail}
. If your server is behind a firewall with a proxy, and you wish to install extensions via configure
, you may have to set {PROXY}{HOST}
and {PROXY}{PORT}
.
configure
page, you can configure Foswiki manually.
mod_auth_ldap
or mod_auth_mysql
. However, as your browser is caching your login, you must restart the browser to log out.
System.InstallationGuide
into the "Jump" text box. By doing this instead of using the INSTALL.html
file from the distribution, you will be able to use the embedded hyperlinks to jump directly to the referenced pages.
Main.WikiUsers
topic.
To setup Template Login, perform the following steps:
Security Settings
pane of the configure
page: Foswiki::LoginManager::TemplateLogin
for {LoginManager}
.
Foswiki::Users::HtPasswdUser
for {PasswordManager}
.
Foswiki::Users::TopicUserMapping
for {UserMappingManager}
.
System.UserRegistration
topic in your Foswiki installation. Note if you are viewing this page via the INSTALL.html
file, then you can access the user registration page by entering System.UserRegistration
into the "Jump" text box at the top right of any Foswiki page in your installation.foswiki/data/.htpassswd
file, with the username and encrypted password. If the user and password information was not added, you probably got a path wrong, or the directory permissions on foswiki/data
or foswiki/data/.htpasswd
may not be set to allow the web server user to modify the file.
Edit
link at the top or bottom of a topic. If you have been authenticated, then you will see the edit page; otherwise, you will see an error message.
Security Settings
pane of the configure
page: Foswiki::LoginManager::ApacheLogin
for {LoginManager}
.
Foswiki::Users::HtPasswdUser
for {PasswordManager}
.
Foswiki::Users::TopicUserMapping
for {UserMappingManager}
.
foswiki/bin/.htaccess
file to set the following Apache directives on the bin
scripts:<FilesMatch "(attach|edit|manage|rename|save|upload|mail|logon|rest|.*auth).*"> require valid-user </FilesMatch>You can also refer to the sample
foswiki_httpd_conf.txt
and bin/.htaccess.txt
files to see how the appropriate Apache directives are specified.
System.UserRegistration
topic in your Foswiki installation. Note if you are viewing this page via the INSTALL.html
file, then you can access the user registration page by entering System.UserRegistration
into the "Jump" text box at the top right of any Foswiki page in your installation.foswiki/data/.htpassswd
file, with the username and encrypted password. If the user and password information was not added, you probably got a path wrong, or the directory permissions on foswiki/data
or foswiki/data/.htpasswd
may not be set to allow the web server user to modify the file.
Edit
link at the top or bottom of a topic. If you have been authenticated, then you will see the edit page; otherwise, you will see an error message.
AdminGroup
, defined in the Main.AdminGroup
topic in your Foswiki installation.
To make it easier to follow the instructions in this section, you can view this installation guide using your Foswiki site by entering System.InstallationGuide
into the "Jump" text box. By doing this instead of using the INSTALL.html
file from the distribution, you will be able to use the embedded hyperlinks to jump directly to the referenced pages.
To add an initial administrator to the AdminGroup
, perform the following steps:
Main.AdminGroup
topic and select the "internal admin login" link. Login using the password you set on the configure
page.
Main.AdminGroup
topic. Follow the instructions on the page carefully and add your WikiName to the group.
Main.AdminGroup
page, select the "Logout link" and logout from being the internal admin. Select the "Edit" link for the Main.AdminGroup
page. If you successfully added yourself as an admin user, you should see the edit page.
AdminGroup
is no longer empty, then any member of the group can add subsequent members — you do not have to use the internal admin login.
To more easily debug access control issues, you may want to have a regular Foswiki user account for daily use, and a special one that belongs to the AdminGroup
that you use only for administering your Foswiki site. See Foswiki:System.AccessControl for more information on access controls and user groups.
http://yourdomain.com/foswiki/bin/view
and start using your Foswiki site.
In order to keep your user, group, and site configuration information separate from the actual content of your site, it is recommended that you create a new web in which your site's pages will reside. See Foswiki:System.ManagingWebs for more information on Wiki webs and how to create one.
System.Skins
refers to the Skins
topic in your System web. To go directly to a topic, enter the full topic name, such as System.Skins
, into the "Jump" text box at the top right of any Foswiki page.
To make it easier to follow the instructions in this section, you can view this installation guide using your Foswiki site by entering System.InstallationGuide
into the "Jump" text box. By doing this instead of using the INSTALL.html
file from the distribution, you will be able to use the embedded hyperlinks to jump directly to the referenced pages.
All of the Foswiki documentation can also be found online in the Foswiki documentation section (the "System" web) of the Foswiki web site.
Note the configure
page mentioned in this section is accessed by visiting http://yourdomain/foswiki/bin/configure
your web browser.
Main.SitePreferences
. If a given preference is not set in Main.SitePreferences
, then a default value is picked up from System.DefaultPreferences
, if present, or, for extensions, from the extension topics.
To simplify your upgrades, do not modify System.DefaultPreferences
. Instead, copy any settings you want to change from System.DefaultPreferences
to Main.SitePreferences
.
To see the available preferences that can be set, look through System.DefaultPreferences
.
If, for some reason, you wish to pick up default preferences from a different topic, you can set the location in the Miscellaneous settings
pane of the configure
page, in the {SitePrefsTopicName}
setting (visible when Expert mode is enabled). It is recommended that you leave this setting to its default value, DefaultPreferences
.
configure
page.
tools/mailnotify
script, as described in the System.MailerContrib topic.
tools/tick_foswiki.pl
script, and set a negative value on the configure
page for {Sessions}{ExpireAfter}
. For more details, read System.CommandAndCGIScripts#tick_foswiki_pl.
Localisation
section of the configure
page. For more information, see Foswiki:Support.InternationalizationSupplement.
Main.NewUserTemplate?
topic; if it is not present, then System.NewUserTemplate
(and its associated System.UserForm
) is used as a default. If you want to customize the user topic for your users, copy System.NewUserTemplate
to Main.NewUserTemplate?
, and System.UserForm
to Main.UserForm
, and make your changes to Main.NewUserTemplate?
and Main.UserForm
. (See Foswiki:System.ManagingTopics#CopyTopic for instructions on copying a topic.)
You can edit these topics to suit your needs, such as the following: ALLOWTOPICCHANGE
preference setting to Main.NewUserTemplate?
so only the user can edit their own user topic. In particular, on a public Foswiki site, restricting edit access will avoid vandalism and spam.
Main.UserForm
.
Main.UserRegistration?
to match (copy over the contents from System.UserRegistration to Main.UserRegistration
when creating it).
System.WebTopBarExample
to System.WebTopBar?
, and make your desired changes to System.WebTopBar
.
To customize the bottom bar, copy System.WebBottomBarExample
to System.WebBottomBar?
, and make your desired changes to System.WebBottomBar
.
The side bar can be customized on a per web basis. To customize the side bar, copy the WebLeftBarExample
topic in the given web to WebLeftBar
, and make your desired changes to WebLeftBar
. If you would like to move the side bar to the right of the page, see System.PatternSkin for more details.
WEBCOPYRIGHT
preference. Its default is the following: Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
If your Foswiki site is used in an environment without public access you should replace this with your normal copyright notice. You should also consider adding a security classification (e.g., For Internal Use Only) so people do not have to add this manually to every new topic.
If your Foswiki site is publicly accessible, you need to decide which copyright and license you wish to apply to all contributions. For open source applications, licenses such as the GNU Free Documentation License, FreeBSD Documentation License, and one of the various Creative Commons licenses are possible licenses to consider. Remember that once people have started contributing, you cannot retroactively change the license (unless it has a provision for this).
To change the copyright statement, perform the following steps:
WEBCOPYRIGHT
preference setting from System.DefaultPreferences
to Main.SitePreferences
. Change the value to your desired text. This value will be your new default across all webs.
WEBCOPYRIGHT
preference in the WebPreferences
topic for the given web. For example, you could add a confidential classification to a web that has restricted access.
WEBCOPYRIGHT
preference setting in System.WebPreferences
covers the documentation that comes with Foswiki, and should not be changed.
configure
page, you can select the Find More Extensions button to download and install additional plugins from the foswiki.org website. If you are behind a firewall or your server has no access to the Internet, you can also install plugins manually. Installation instructions for each plugin are located in its corresponding topic on http://foswiki.org/. Additional documentation on Foswiki plugins can be found at Foswiki:Support.PluginsSupplement.
Plugins are activated in the Plugins section of the configure
page. In addition, some plugins are also configured in this section.
TWikiCompatibilityPlugin
. This plugin enables most TWiki extensions to work with Foswiki, without modifications. It also maps requests for legacy TWiki web topics to their Foswiki equivalents, as defined in Foswiki:Development.TopicNameMappingTable. The TWIKIWEB
and MAINWEB
TWiki variables are also mapped to the new Foswiki macros SYSTEMWEB
and USERSWEB
.
If you are not upgrading an existing TWiki installation and do not plan to install plugins from the TWiki web site, it is recommended that you disable the TWikiCompatibilityPlugin in the Plugins Section on the configure
page.
If a plugin exists both in a TWiki version and a Foswiki version, it is strongly recommended that you use the Foswiki version, as this is coded to work optimally with Foswiki. As part of the Foswiki project, the Foswiki community is evaluating all of the extensions that are available for TWiki, and porting them over to the Foswiki name space. Many of them are being enhanced through the removal of bugs and security vulnerabilities, resulting in better, more functional extensions for Foswiki.
configure
script and make sure you have resolved all errors and are satisfied that you understand any warnings.
Failing that, consult the topics at Foswiki:Support.SupplementalDocuments and Foswiki:Support.AskedQuestions.
If you need help, ask a question in the Foswiki:Support web or on Foswiki:Community.InternetRelayChat (irc.freenode.net, channel #foswiki).
Resource | Required Server Environment |
---|---|
Perl | 5.8.4 or higher is recommended. Foswiki will run in perl 5.6.1 but only with Wysiwyg editor disabled. Wysiwyg requires Unicode support which is provided by perl 5.8.1 onwards. |
RCS | 5.7 or higher (including GNU diff ) Optional. Foswiki includes a pure perl implementation of RCS (RcsLite) that can be used instead, at the cost of performance |
GNU diff | GNU diff 2.7 or higher is required when not using the all-Perl RcsLite. Install within the PATH if not included with RCS (check version with diff -v ) Must be the version used by RCS, to avoid problems with binary attachments - RCS may have hard-coded path to diff |
Other external programs | fgrep, egrep |
Cron/scheduler | • Unix: cron • Windows: cron equivalents |
Web server | Apache is well supported; for information on other servers, see Foswiki:Support.InstallingOnSpecificPlatforms. |
Module | Preferred version |
---|---|
Algorithm::Diff (included with Foswiki) | |
CGI | Versions 2.89 and 3.37 must be avoided. Most version from 3.15 and onwards should work. |
CGI::Carp | >=1.26 |
CGI::Session | >=4.30 (included with Foswiki) Versions 4.20 and before have Foswikitask:Item1306 |
Config | >=0 |
Cwd | >=3.05 |
Data::Dumper | >=2.121 |
Error (included) | |
File::Copy | >=2.06 |
File::Find | >=1.05 |
File::Spec | >=3.05 |
FileHandle | >=2.01 |
IO::File | >=1.10 |
Text::Diff (included with Foswiki) | |
Time::Local | >=1.11 |
perl -le 'use ModuleName; print "ModuleName"->VERSION'
Module | Preferred version | Description |
---|---|---|
Archive::Tar | May be required by the Extensions Installer in configure if command line tar or unzip is not available | |
CGI::Cookie | >=1.24 | Used for session support |
Digest::base | ||
Digest::SHA1 | ||
Jcode | Used for I18N support with perl 5.6 | |
Locale::Maketext::Lexicon | >=0 | Used for I18N support |
Net::SMTP | >=2.29 | Used for sending mail |
Unicode::Map | Used for I18N support with perl 5.6 | |
Unicode::Map8 | Used for I18N support with perl 5.6 | |
Unicode::MapUTF8 | Used for I18N support with perl 5.6 | |
Unicode::String | Used for I18N support with perl 5.6 | |
URI | Used for configure |
configure
script, or if you're still trying to get to that point, check from the command line (replace "ModuleName" with the name of the module):
perl -e 'use ModuleName; print $ModuleName::VERSION."\n"'
pub
directory.)
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 |
configure
page) configure
page. However, if you are unable to get the configure
page to display (for example, if a dependency is missing), or for some reason you do not wish to use the configure
page, then you can configure Foswiki manually
Perform the following steps to manually configure Foswiki: lib/Foswiki.spec
to lib/LocalSite.cfg
$Foswiki::cfg{DefaultUrlHost} $Foswiki::cfg{ScriptUrlPath} $Foswiki::cfg{PubUrlPath} $Foswiki::cfg{PubDir} $Foswiki::cfg{TemplateDir} $Foswiki::cfg{DataDir} $Foswiki::cfg{LocalesDir} $Foswiki::cfg{OS}
$Foswiki::cfg{LoginManager} $Foswiki::cfg{WebMasterEmail} $Foswiki::cfg{SMTP}{MAILHOST} $Foswiki::cfg{SMTP}{SENDERHOST}
TWikiCompatibilityPlugin
), thereby enabling a smooth transition from TWiki to Foswiki.
Main
web in the new installation, including all user topics.
<oldwiki>
refers to the directory in which the old installation is located
<newwiki>
refers to the directory in which the new installation is located; it is assumed to be immediately below the root directory of your web server
<old_users_web>
refers to the web in which the user topics are located in the old installation. The default value is the Main web. The web is specified in the Store settings
pane of the configure
page, in the {UsersWebName} setting (visible when Expert mode is enabled).
<old_system_web>
refers to the web used for documentation and default preferences in the old installation. In Foswiki, the default value is the System web; in TWiki, the default value is the TWiki web. The web is specified in the Store settings
pane of the configure
page, in the {SystemWebName} setting (visible when Expert mode is enabled).
configure
page mentioned in this document is accessible via your web browser at http://yourdomain/<newwiki>/bin/configure .
configure
page. <oldwiki>/lib/LocalSite.cfg
file to <newwiki>/lib/LocalSite.cfg
in order to preserve your existing configuration settings. Alternatively, you can reconfigure the new installation from scratch (you can use your old LocalSite.cfg
file as a reference).
LocalSite.cfg
file (though you can use it as a reference). Run configure
and set the configuration values in the new installation to match those of the old installation.
configure
page, including any new settings added in the new version. Save the configuration after you have completed your changes.
<newwiki>/lib/LocalSite.cfg
file and run configure
.
System.UpgradeGuide
into the "Jump" text box on the top right of any topic. By doing this instead of using the UpgradeGuide.html file from the distribution, you will be able to use the embedded hyperlinks to jump directly to the referenced pages.
configure
page to install and configure extensions from the Foswiki:Extensions repository. You can also install extensions manually; see the instructions on the extension's web page from where you obtained the extension (for Foswiki extensions, on foswiki.org).
TWikiCompatibilityPlugin
is installed to provide backwards compatible support for TWiki plugins. However if the TWiki plugin calls private APIs or invokes helper scripts, it may still not work correctly. Check for an upgraded Foswiki version of the extension in the Foswiki:Extensions repository and install it instead.
Main.SitePreferences
topic in your new Foswiki site, prefixing each setting with the name of the plugin in uppercase followed by an underscore. For example, to copy over the DEFAULT_TYPE
setting from the CommentPlugin
topic in the old site to the new site, copy the value to a COMMENTPLUGIN_DEFAULT_TYPE
setting in the Main.SitePreferences
topic in the new site.
Commonly-customized plugin settings include the following: CommentPlugin
- DEFAULT_TYPE
EditTablePlugin
- CHANGEROWS, QUIETSAVE, EDITBUTTON
InterwikiPlugin
- RULESTOPIC
InterWikis
- If you added your own rules, make sure you copy over the rules to the new installation.
SlideShowPlugin
- If you changed the embedded 'Default Slide Template', then copy your customed template to the topic in the new installation. You should prefer creating your own slide show template in a separate topic, so you will not have to take special steps over upgrades to preserve your modifications to the default slide template.
SmiliesPlugin
- If you added your own smileys, make sure you copy over your customizations to the topic in the new installatin.
TablePlugin
- TABLEATTRIBUTES
configure
.
find data -name '*,v' -exec rcs -u -M '{}' \;
find pub -name '*,v' -exec rcs -u -M '{}' \;
WebChanges
topics depend on the file timestamp. If you touch the .txt files make sure to preserve the timestamp, or change them in the same chronological order as the old file timestamps.
Main
web <oldwiki>/data/<old_users_web>/
to <newwiki>/data/Main/
, and copy all files from <oldwiki>/pub/<old_users_web>/
to <newwiki>/pub/Main/
. Do not overwrite any topics already present in the <newwiki>/data/Main/
directory. <old_users_web>.NewUserTemplate
in the old installation, this step will copy over your template for user topics to the new installation.
Security setup
pane of the configure
page, in the {SuperAdminGroup} setting (visible when Expert mode is enabled). You can do either of the following: configure
page, or if you did customize {LocalSitePreferences} but kept your site preferences within the <old_users_web> web, then this step will also copy over your site preferences to the new installation.
<old_users_web>.WikiUsers
topic in the old installation to the Main.WikiUsers
topic in the new installation. If the new installation does not yet have an initial Main.WikiUsers
topic, then copy <oldwiki>/data/<old_users_web>/WikiUsers.txt
to <newwiki>/data/Main/WikiUsers.txt
.
Main.WikiUsers
topic: Main.WikiUsers
, using the corresponding entries in Foswiki:System.UsersTemplate as an example.
data/.htpasswd
for authentication, copy this file from the old installation to the new one.
<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.
<old_users_web>.TWikiUsers
topic in the old installation to the Main.WikiUsers
topic in the new installation. If the new installation does not yet have an initial Main.WikiUsers
topic, then copy <oldwiki>/data/<old_users_web>/TWikiUsers.txt
to <newwiki>/data/Main/WikiUsers.txt
, and manually add the required default users (see the next steps).
Main.WikiUsers
topic: Main.WikiUsers
, using the corresponding entries in Foswiki:System.UsersTemplate as an example.
data/.htpasswd
for authentication, copy this file from the old installation to the new one.
tools/upgrade_emails.pl
script to move the user emails out of the user topics and into the password file.
<old_system_web>.TWikiRegistration
, then modify System.UserRegistration
in the new installation to contain your customizations.
<oldwiki>/data/Sandbox/
to <newwiki>/data/Sandbox
and from <oldwiki>/pub/Sandbox/
to <newwiki>/pub/Sandbox
. Some pages you may wish to preserve are the WebHome
topic and the WebLeftBar
topic (if you had created it in the old wiki installation). The Sandbox web often contains work-in-progress topics that users will want to keep.
Make sure the data and pub directories, as well as the files within them, are readable and writeable by the web server user.
Execute your test plans for authentication and authorization. Test that users that you have transferred from the old installation can login with any problems, and that access controls work appropriately: check that users are able to view and edit pages for which they have access, and are denied permission to view or edit pages for which they do not have access. Also check that pages restricted to the admin group are not accessible by non-admin users, and that administrators continue to have access.
Miscellaneous settings
pane of the configure
page, in the {LocalSitePreferences} setting (visible when Expert mode is enabled) — the default location is Main.SitePreferences. Copy any customized preferences from the site preferences topic in your old installation to the site preferences topic in the new installation. (Note you may have already copied over your customized preferences when you transfered the contents of the <old_users_web> web.)
If, in your old installation, you customized the default preferences in <old_system_web>.DefaultPreferences
, then transfer your customizations from this topic to the site preferences topic instead (i.e. the topic specified in your {LocalSitePreferences} setting), so that your customizations will not get overwritten on the next upgrade.
If you are upgrading from TWiki, note that the default location of the default preferences in TWiki is <old_system_web>.TWikiPreferences
, and the default location of the site preferences is Main.TWikiPreferences
. Transfer any customized preferences from these topics to the site preferences topic in your new installation.
<oldwiki>/<old_system_web>/
directory as a reference.
http://yourdomain/wiki/
. You can use one of the following approaches to make the new installation accessible using the same URL prefix: <newwiki>/
directory to wiki/
(renaming the directory of your old installation if necessary).
wiki/
that points to <newwiki>/
(renaming the directory of your old installation if necessary).
/wiki/
are served from your <newwiki>/
directory.
System.DefaultPreferences
for a description of the FAVICON preference. To set it for your site, add the FAVICON preference to your site preferences topic, Main.SitePreferences
(or the topic you configured in your {LocalSitePreferences} setting in the Miscellaneous settings
pane on the configure
page). To set it for a web, add the FAVICON preference to the WebPreferences
topic for that web.
System.CommentPluginTemplate
for examples of how comment template definitions should look like in TWiki 4.1.x.
Example: a CommentPlugin template that adds a row to a table. With versions of TWiki prior to 4.1, the following syntax can be used:
%TMPL:DEF{OUTPUT:tabletest}%%POS:BEFORE% |%URLPARAM{"comment"}%| -- %WIKIUSERNAME% - %DATE% | %TMPL:END%Starting in TWiki 4.1 and continuing with Foswiki 1.0, the newline before the start of the table row must be removed:
%TMPL:DEF{OUTPUT:tabletest}%%POS:BEFORE%|%URLPARAM{"comment"}%| -- %WIKIUSERNAME% - %DATE% | %TMPL:END%
{PassthroughDir}
and {Sessions}{Dir}
were set by default to /tmp
. These config settings have been eliminated: Foswiki creates a tmp directory and other temporary directories under the directory defined by the configure setting {WorkingDir}
.
NewUserTemplate
and UserForm
in the Main web, if they exist. If the topic does not exist in the Main web, then the default version from System is used. Thus on upgrades, any customizations you made to NewUserTemplate
or UserForm
in the Main web will be preserved.
In previous TWiki versions, only System.NewUserTemplate
and System.UserForm
are used; you cannot override them by creating your own version in the Main web.
Main.WikiUsers
topic contains all the registered users. It is not included in the Foswiki distribution, so that your list of users will not be overwritten on upgrades. When the first user is registered in Foswiki, the Main.WikiUsers
topic is created on demand.
working
directory {WorkingDir}
in the General path settings
pane on the configure
page defines the location of a working directory for various subdirectories for use by Foswiki. The default value for this setting is the working
subdirectory within the installation root directory for the Foswiki installation.
The subdirectories within the working directory include the following:
registration_approvals
— previously located in the data/ directory
tmp
— avoids security issues with using the /tmp directory
work_areas
— previously located in the pub/ directory.
working/tmp/
subdirectory.
configure
page. The internal admin username can be configured in the {AdminUserLogin} setting in the Security setup
pane on the configure
page.
In order to add an initial user to the default {SuperAdminGroup}, Main.AdminGroup, you must login as the internal admin user using the link on the Main.AdminGroup page.
<form name="new" action="%SCRIPTURLPATH{save}%/Sandbox/" method="post"> ... </form>The template webs _default and _empty are frequent targets for spammers because these webs are normally not monitored very carefully by the community around a Foswiki installation. These webs are now write protected so on an administrator can edit topics in these webs. When an administrator creates a new web it is important to remember to remove the access restriction from the WebPreferences in the new web.
.htpasswd
files on the server. These files can be unique to Foswiki, or can be shared with other applications (such as an Apache webserver). A variety of password encodings are supported for flexibility when re-using existing files. See the descriptive comments in the Security Settings section of the configure interface for more details.
You can easily plug in alternate password management modules to support interfaces to other third-party authentication databases.
The password manager is selected using the {PasswordManager} setting in configure
.
configure
.
configure
.
none
) Foswiki::LoginManager::TemplateLogin
) Foswiki::LoginManager::TemplateLogin
login manager (on the Security Settings pane).
{TemplateLogin}{PreventBrowserRememberingPassword}
that you can set to prevent Browsers from remembering username and passwords if you are concerned about public terminal usage.
.htpasswd
files, check that a new line with the username and encrypted password is added to the .htpasswd
file. If not, you probably got a path wrong, or the permissions may not allow the webserver user to write to that file.
pub
area, unless they are only accessed through the viewfile
script. If your pub
directory is set up in the webserver to allow open access you may want to add .htaccess
files in there to restrict access.
You can create a custom version of the UserRegistration form by copying the topic, and then deleting or adding input tags in your copy. The name=""
parameter of the input tags must start with: "Twk0..."
(if this is an optional entry), or "Twk1..."
(if this is a required entry). This ensures that the fields are carried over into the user home page correctly. Do not modify the version of UserRegistration shipped with Foswiki, as your changes will be overwritten next time you upgrade.
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 home page by creating the Main.NewUserTemplate? topic, which will then override the default.
Foswiki::LoginManager::ApacheLogin
) REMOTE_USER
environment variable, which is set when you enable authentication in the webserver.
The advantage of this scheme is that if you have an existing website authentication scheme using Apache modules such as mod_auth_ldap
or mod_auth_mysql
you can just plug in directly to them.
The disadvantage is that because the user identity is cached in the browser, you can log in, but you can't log out again unless you restart the browser.
Foswiki maps the REMOTE_USER
that was used to log in to the webserver to a WikiName using the table in Main.WikiUsers. This table is updated whenever a user registers, so users can choose not to register (in which case their webserver login name is used for their signature) or register (in which case that login name is mapped to their WikiName).
The same private .htpasswd
file used in Foswiki Template Login can be used to authenticate Apache users, using the Apache Basic Authentication support.
Warning: Do not use the Apache htpasswd
program with .htpasswd
files generated by Foswiki! htpasswd
wipes out email addresses that Foswiki plants in the info fields of this file.
mod_auth
Foswiki::LoginManager::ApacheLogin
login manager.
.htpasswd
entries.
.htaccess
file in the bin
directory.bin/.htaccess.txt
that you can copy and change. The comments in the file explain what need to be done..htaccess
does not have the desired effect, you may need to "AllowOverride All" for the directory in httpd.conf
(if you have root access; otherwise, e-mail web server support) pub
area, unless they are only accessed through the viewfile
script. If your pub
directory is set up to allow open access you may want to add .htaccess
files in there as well to restrict access
name=""
parameter of the input tags must start with: "Twk0..."
(if this is an optional entry), or "Twk1..."
(if this is a required entry). This ensures that the fields are carried over into the user home page correctly. Do not modify the version of UserRegistration shipped with Foswiki, as your changes will be overwritten next time you upgrade. .htpasswd
file. If not, you may have got a path wrong, or the permissions may not allow the webserver user to write to that file.
bin/logon
script enables this. If you are using Apache Login, the bin/logon
script must be setup in the bin/.htaccess
file to be a script which requires a valid user
. Once authenticated, it will redirect the user to the view URL for the page from which the logon
script was linked.
%SESSION_VARIABLE{ "varName" }% %SESSION_VARIABLE{ "varName" set="varValue" }% %SESSION_VARIABLE{ "varName" clear="" }%Note that you cannot override access controls preferences this way.
REMOTE_USER
environment variable, and used internally. Login Usernames are maintained by your system administrator.
JohnSmith
, is recorded when you register using UserRegistration; doing so also generates a personal home page in the Main web.
NOTE: To correctly enter a WikiName - your own or someone else's - be sure to include the Main web name in front of the Wiki username, followed by a period, and no spaces, for exampleMain.WikiUsername
or%USERSWEB%.WikiUsername
. This pointsWikiUsername
to the Main web, where user home pages are located, no matter which web it's entered in. Without the web prefix, the name appears as a NewTopic everywhere but in the Main web.
Foswiki/ChangePassword
)
Foswiki/ResetPassword
)
Foswiki/ChangeEmailAddress
)
.htaccess
Web | Sitemap | VIEW | CHANGE | RENAME | |||
---|---|---|---|---|---|---|---|
Listed | DENY | ALLOW | DENY | ALLOW | DENY | ALLOW | |
Main | on | ||||||
System | on | Main.AdminGroup | Main.AdminGroup | ||||
Home | on | Main.HomeGroup | Main.HomeGroup | ||||
Sandbox | on |
Main
web. To create a new group, visit Main.WikiGroups and enter the name of the new group ending in Group
into the "new group" form field. This will create a new group topic with two important settings: Set GROUP = < list of users and/or groups >
Set ALLOWTOPICCHANGE = < list of users and/or groups >
Set GROUP = Main.SomeUser, Main.OtherUser, Main.SomeGroup
Set ALLOWTOPICCHANGE = Main.KasabianGroup
AdminGroup
. The system administrator may have chosen a different name for this group if your local Foswiki uses an alternate group mapping manager but for simplicity we will use the default name AdminGroup in the rest of this topic.
You can create new administrators simply by adding them to the Main.AdminGroup topic. For example, Set GROUP = Main.ElizabethWindsor, Main.TonyBlair
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 >
ALLOWWEBVIEW
set, this will also apply to the subweb. Also note that you will need to ensure that the parent web's FINALPREFERENCES
does not include the access control settings listed above. Otherwise you will not be able override the parent web's access control settings in sub-webs.
Creation and renaming of sub-webs is controlled by the WEBCHANGE setting on the parent web (or ROOTCHANGE for root webs). Renaming is additionally restricted by the setting of WEBRENAME in the web itself.
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 >
Set ALLOWTOPICVIEW =
Set DENYTOPICVIEW =
mod_rewrite
module, and configure your webserver to redirect accesses to attachments to the Foswiki viewfile
script. For example,
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]That way all the controls that apply to the topic also apply to attachments to the topic. Other types of webserver have similar support. Images embedded in topics will load much slower since each image will be delivered by the
viewfile
script.
Set DENYROOTCHANGE = < comma-delimited list of users and groups >
Set ALLOWROOTCHANGE = < comma-delimited list of users and groups >
ROOTCHANGE
access to rename an existing top-level web. You just need WEBCHANGE
in the web itself.
all webs
search option from accessing obfuscated webs. Do so by enabling the NOSEARCHALL
setting in WebPreferences: Set NOSEARCHALL = on
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>If needed, you can further restrict access to selected webs with ALLOWWEBVIEW and other access control settings. With this configuration, someone with access to the site needs to register new users.
WebPreferences
in all webs. Set DENYWEBVIEW = WikiGuest
Set ALLOWWEBVIEW = < list of users and groups >
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.
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).
Set DENYWEBVIEW = < list of users and groups >
Set ALLOWWEBVIEW = < list of users and groups >
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.
Edit topic preference settings
under More topic actions
menu. Preferences set in this manner are not visible in the topic text, but take effect nevertheless. Access control settings added as topic preference settings are stored in the topic meta data and they override settings defined in the topic text.
Alternatively, place them in HTML comment markers, but this exposes the access setting during ordinary editing.
Back to top<!--
* Set DENYTOPICCHANGE = Main.SomeGroup
-->
Formatting Command: | You write: | You get: | |||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Paragraphs: Blank lines will create new paragraphs. |
1st paragraph 2nd paragraph | 1st paragraph 2nd paragraph | |||||||||||||||||||||||||
Headings: Three or more dashes at the beginning of a line, followed by plus signs and the heading text. One plus creates a top level heading, two pluses a second level heading, etc. The maximum heading depth is 6. You can create a table of contents with the %TOC% macro. If you want to exclude a heading from the TOC, put !! after the ---+ .
Empty headings are allowed, but won't appear in the table of contents.
|
---++ Sushi ---+++ Maguro ---+++!! Not in TOC |
SushiMaguroNot in TOC |
|||||||||||||||||||||||||
Bold Text: Words get shown in bold by enclosing them in * asterisks.
|
*Bold* | Bold | |||||||||||||||||||||||||
Italic Text: Words get shown in italic by enclosing them in _ underscores.
|
_Italic_ | Italic | |||||||||||||||||||||||||
Bold Italic: Words get shown in bold italic by enclosing them in __ double-underscores.
|
__Bold italic__ | Bold italic | |||||||||||||||||||||||||
Fixed Font: Words get shown in fixed font by enclosing them in = equal signs.
|
=Fixed font= |
Fixed font
|
|||||||||||||||||||||||||
Bold Fixed Font: Words get shown in bold fixed font by enclosing them in double equal signs.
|
==Bold fixed== |
Bold fixed
|
|||||||||||||||||||||||||
You can follow the closing bold, italic, or other (* _ __ = == ) indicator
with normal punctuation, such as commas and full stops.
Make sure there is no space between the text and the indicators.
|
_This works_, _this does not _ |
This works, _this does not _ |
|||||||||||||||||||||||||
Verbatim (Literal) Text: Surround code excerpts and other formatted text with <verbatim> and </verbatim> tags.verbatim tags disable HTML code. Use <pre> and </pre> tags instead if you want the HTML code within the tags to be interpreted.Preferences settings (* Set NAME = value) are set within verbatim tags. |
<verbatim> class CatAnimal { void purr() { <code here> } } </verbatim> |
class CatAnimal { void purr() { <code here> } } |
|||||||||||||||||||||||||
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 |
|
|||||||||||||||||||||||||
Numbered List: Multiple of three spaces, a type character, a dot, and another space. Several types are available besides a number:
|
1. Sushi 1. Dim Sum 1. Fondue A. Sushi A. Dim Sum A. Fondue i. Sushi i. Dim Sum i. Fondue |
|
|||||||||||||||||||||||||
Definition List: Three spaces, a dollar sign, the term, a colon, a space, followed by the definition. |
$ Sushi: Japan $ Dim Sum: S.F. |
|
|||||||||||||||||||||||||
Table: Each row of the table is a line containing of one or more cells. Each cell starts and ends with a vertical bar '|'. Any spaces at the beginning of a line are ignored.
|^| 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 | |
|
|||||||||||||||||||||||||
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% and %USERSWEB% instead of System and Main.
|
WebStatistics Sandbox.WebNotify Sandbox.WebHome Sandbox.Subweb.TopicName | WebStatistics Sandbox.WebNotify Sandbox.WebHome TopicName | |||||||||||||||||||||||||
Anchors: You can define a reference inside a topic (called an anchor name) and link to that. To define an anchor write #AnchorName at the beginning of a line. The anchor name must be a WikiWord of no more than 32 characters. To link to an anchor name use the [[MyTopic#MyAnchor]] syntax. You can omit the topic name if you want to link within the same topic.
|
[[WikiWord#NotThere]] [[#MyAnchor][Jump]] #MyAnchor To here | WikiWord#NotThere Jump To here | |||||||||||||||||||||||||
Forced Links: You can create a forced internal link by enclosing words in double square brackets. Text within the brackets may contain optional spaces; the topic name is formed by capitalizing the initial letter and by removing the spaces; for example, [[wiki syntax]] links to topic WikiSyntax. You can also refer to a different web and use anchors.
To "escape" double square brackets that would otherwise make a link, prefix the leading left square bracket with an exclamation point. |
[[wiki syntax]] [[Sandbox.My unspaced topic]] escaped: ![[wiki syntax]] | wiki syntax Main.Wiki groups escaped: [[wiki syntax]] | |||||||||||||||||||||||||
Specific Links: You can create a link where you specify the link text and the URL separately using nested square brackets [[reference][text]] . Internal link references (e.g. WikiSyntax) and URLs (e.g. http://foswiki.org/) are both supported.
The rules described under Forced Links apply for internal link references.
Anchor names can be added as well, to create a link to a specific place in a topic. |
[[WikiSyntax][wiki syntax]] [[http://gnu.org][GNU]] | wiki syntax GNU | |||||||||||||||||||||||||
Prevent a Link: Prevent a WikiWord from being linked by prepending it with an exclamation point. |
!SunOS | SunOS | |||||||||||||||||||||||||
Disable Links: You can disable automatic linking of WikiWords by surrounding text with <noautolink> and </noautolink> tags.It is possible to turn off all auto-linking with a NOAUTOLINK preferences setting. |
<noautolink> RedHat & SuSE </noautolink> | RedHat & SuSE | |||||||||||||||||||||||||
Mailto Links: E-mail addresses are linked automatically. To create e-mail links that have more descriptive link text, specify subject lines or message bodies, or omit the e-mail address, you can write [[mailto:user@domain][descriptive text]] .
|
a@b.com [[mailto:a@b.com]\ [Mail]] [[mailto:?subject=\ Hi][Hi]] | a@b.com Mail Hi | |||||||||||||||||||||||||
Literal content: Foswiki generates HTML code from TML shorthand. Experts surround anything that must be output literally in the HTML code, without the application of shorthand rules, with <literal>..</literal> tags. any HTML
within literal tags must be well formed i.e. all tags must be properly closed before
the end of the literal block. Macros are expanded within literal blocks.
|
<literal> | Not | A | Table | </literal> |
| Not | A | Table | | |||||||||||||||||||||||||
Protected content: Experts protect text from mangling by WYSIWYG editors using <sticky>..</sticky> tags. Sticky tags don't have any effect on normal
topic display; they are only relevant when content has to be
protected from a WYSIWYG editor (usually because it isn't well-formed HTML, or because it
is HTML that WYSIWYG would normally filter out or modify). Protected
content appears as plain text in the WYSIWYG editor.
|
<sticky> <div> This div is required </div> </sticky> |
This div is required
|
<strike>deleted text</strike>
to get <literal>..</literal>
tags around blocks of HTML to avoid accidental interpretation of shorthand within the HTML.
<body>
and </body>
tags.
<p />
paragraph tags on empty lines, which causes problems if done between HTML tags that do not allow paragraph tags, like for example between table tags.
<...>
- of a HTML tag are on the same line, or the tag will be broken.
LinkProtocolPattern
, which by default is set to (file|ftp|gopher|https|http|irc|mailto|news|nntp|telnet)
, are linked automatically. You might change this setting to add more protocols (such as smb). Thus, all lines containing: file://...
ftp://...
gopher://...
https://...
http://...
irc://...
mailto:...@...
news://...
nntp://...
telnet://...
are linked automatically.
name@domain.com
are linked automatically.
[[Square bracket rules]]
let you easily create non-WikiWord links. [[http://yahoo.com Yahoo home page]]
as an easier way of doing external links with descriptive text for the link, such as Yahoo home page.
%TOPIC%
is expanded to MacrosQuickStart, the title of this topic.
Some macros can take arguments in curly braces - for example, %INCLUDE{"OtherTopic" ARG="arg"}%
.
Many macro definitions are built-in, and others (preference settings) are predefined for your convenience. You can also define your own
preference settings at the entire site, individual web, or individual topic level. For more information, see Macros
Macros are fully expanded before any of the text formatting rules are applied.
Documentation Graphics: There are many graphics available to use in your topics. Use %ICON{"help"}%
, %ICON{"tip"}%
, and %ICON{"warning"}%
to get: , , and , respectively. DocumentGraphics lists them all.
To "escape" a macro, prefix it with an exclamation mark. Write: !%SOMEMACRO%
to get: %SOMEMACRO%.
%PLUGINDESCRIPTIONS%
:
<filename>
is not displayed. How can I show it as it is? '<'
and '>'
characters have a special meaning in HTML, they define HTML tags. You need to escape them, so write '<'
instead of '<'
, and '>'
instead of '>'
. 'prog <filename>'
to get 'prog <filename>'
.
'&'
character sometimes not displayed? '&'
character has a special meaning in HTML, it starts a so called character entity, i.e. '©'
is the ©
copyright character. You need to escape '&'
to see it as it is, so write '&'
instead of '&'
. 'This & that'
to get 'This & that'
.
%MACRONAME%
or %MACRONAME{ parameter="value" }%
- that expand into content whenever a topic is rendered for viewing. There are two types of macros: %CALC{}%
macro)
%T%
to get (a preference settings)
%TOPIC%
to get Macros
(a predefined macro?)
%CALC{ "$UPPER(Text)" }%
to get TEXT
(a macro? defined by a Plugin)
!%TOPIC%
to get %TOPIC%
%ALLVARIABLES%
to get a full listing of all macros defined for a particular topic
%MYVAR%
, %MyVar%
, %My2ndVar%
, and %My_Var%
are all valid macro names. Macros are case sensitive. %MyVAR%
and %MYVAR%
are not the same macro.
By convention all settings, predefined macros and macros used by plugins are always UPPER-CASE.
Preview
will show the wrong thing, and you must Save
the topic to see it correctly.
The syntax for setting macros is the same anywhere: [multiple of 3 spaces] * [space] Set [space] MACRONAME [space] = [space] value
Examples:Spaces between the = sign and the value will be ignored. You can split a value over several lines by indenting following lines with spaces - as long as you don't try to use * as the first character on the following line.
Set MACRONAME = value
Set MACRONAME = value
Example:Whatever you include in your Macro will be expanded on display, exactly as if it had been entered directly.* Set MACRONAME = value starts here and continues here
Example: Create a custom logo macroYou can also set preference settings in a topic by clicking the link
- To place a logo anywhere in a web by typing
%MYLOGO%
, define the preference settings on 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
Edit topic preference settings
under More topic actions
. Preferences set in this manner are not visible in the topic text, but take effect nevertheless.
Local
in place of Set
in the macro definition. For example, if the user sets the following in their home topic:
* Set EDITBOXHEIGHT = 10 * Local EDITBOXHEIGHT = 20Then when they are editing any other topic, they will get a 10 high edit box. However when they are editing their home topic, they will get a 20 high edit box.
Local
can be used wherever a preference needs to take a different value depending on where the current operation is being performed.
Use this powerful feature with great care! %ALLVARIABLES%
can be used to get a listing of the values of all macros in their evaluation order, so you can see macro scope if you get confused.
%SEARCH%
, are powerful and general tools.
%BASETOPIC%
, %INCLUDE%
, and the mighty %SEARCH%
.
%ACTIVATEDPLUGINS%
%ADDTOHEAD{...}%
in a topic or template. This variable accepts the following parameters: _DEFAULT
optional, id of the head block. Used to generate a comment in the output HTML.
text
optional, text to use for the head block. Mutually exclusive with topic
.
topic
optional, full Foswiki path name of a topic that contains the full text to use for the head block. Mutually exclusive with text
. Example: topic="System.MyTopic"
.
requires
optional, comma-separated list of id's of other head blocks this one depends on.
%ADDTOHEAD%
expands in-place to the empty string, unless there is an error in which case the variable expands to an error string.
Use %RENDERHEAD%
to generate the sorted head tags.
%ALLVARIABLES%
AQUA
is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
%AQUA% aqua text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%ATTACHURL%
http://www.wetherby.me/wiki/pub/System/VarATTACHURL
%ATTACHURL%/image.gif
%ATTACHURLPATH%
/wiki/pub/System/VarATTACHURLPATH
%AUTHREALM%
%TOPIC%
if there is no INCLUDE
%BASETOPIC%
%WEB%
in case there is no include.
%BASEWEB%
BLACK
is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
%BLACK% black text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
BLUE
is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
%BLUE% blue text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
BROWN
is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
%BROWN% brown text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%CALC{"formula"}%
macro is handled by the SpreadSheetPlugin. There are around 90 formulae, such as $ABS()
, $EXACT()
, $EXISTS()
, $GET()/$SET()
, $IF()
, $LOG()
, $LOWER()
, $PERCENTILE()
, $TIME()
, $VALUE()
.
%CALC{"formula"}%
%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
%COMMENT%
without parameters shows a simple text box.
Name | Description | Default |
---|---|---|
type | This is the name of the template to use for this comment. Comment templates are defined in a Foswiki template - see Customisation, below. If this attribute is not defined, the type is whatever is defined by COMMENTPLUGIN_DEFAULT_TYPE, either in this topic or in your WebPreferences. | below |
default | Default text to put into the textarea of the prompt. | |
target | Name of the topic to add the comment to | the current topic |
location | Regular expression specifying the comment location in the target topic. Read carefully the CommentPlugin documentation! | |
mode | For compatibility with older versions only, synonymous with type | |
nonotify | Set to "on" to disable change notification for target topics | off |
noform | Set to "on" to disable the automatic form that encloses your comment block - remember to insert <form> tags yourself! See CommentPluginExamples#noform for an example. | off |
nopost | Set to "on" to disable insertion of the posted text into the topic. | off |
remove | Set to "on" to remove the comment prompt after the first time it is clicked. | off |
button | Button label text | Add comment |
%DATE%
09 Oct 2024
%GMTIME%
%DISPLAYTIME%
OR %DISPLAYTIME{"format"}%
%DISPLAYTIME%
The time is shown as hh:mm (24 hour clock) 09 Oct 2024 - 23:19
%DISPLAYTIME{"$hou:$min"}%
expands to 23:19
text
, then hide the form. If EDITACTION is defined as form
hide the normal text area and only edit the form.
;action=text
or ;action=form
to the URL for the edit script. If you have defined an EDITACTION preference setting you can still edit the topic content or the form by removing the ;action=form
or ;action=text
from the edit URL in the browser and reload.
%EDITTABLE{}%
macro is handled by the EditTablePlugin
%EDITTABLE{ attributes }%
Attribute | Comment | Default |
---|---|---|
header | Specify the header format of a new table like "|*Food*|*Drink*|" . Useful to start a table with only a button | (no header) |
format | The format of one column when editing the table. A cell can be a text input field, or any of these edit field types: • Text input field (1 line): | text, <size>, <initial value> | • Textarea input field: | textarea, <rows>x<columns>, <initial value> | • Drop down box: | select, <size>, <option 1>, <option 2>, etc* | * only one item can be selected • Radio buttons: | radio, <size*>, <option 1>, <option 2>, etc | * size indicates the number of buttons per line in edit mode • Checkboxes: | checkbox, <size*>, <option 1>, <option 2>, etc | * size indicates the number of checkboxes per line in edit mode • Fixed label: | label, 0, <label text> | • Row number: | row, <offset> | • Date: | date, <size>, <initial value>, <DHTML date format> | (see Date Field Type) | "text, 16" for all cells |
changerows | Rows can be added and removed if "on" Rows can be added but not removed if "add" Rows cannot be added or removed if "off" | CHANGEROWS plugin setting |
quietsave | Quiet Save button is shown if "on" , hidden if "off" | QUIETSAVE plugin setting |
include | Other topic defining the EDITTABLE parameters. The first %EDITTABLE% in the topic is used. This is useful if you have many topics with the same table format and you want to update the format in one place. Use topic or web.topic notation. | (none) |
helptopic | Topic name containing help text shown below the table when editing a table. The %STARTINCLUDE% and %STOPINCLUDE% macros can be used in the topic to specify what is shown. | (no help text) |
headerislabel | Table header cells are read-only (labels) if "on" ; header cells can be edited if "off" or "0" | "on" |
editbutton | Set edit button text, e.g. "Edit this table" ; set button image with alt text, e.g. "Edit table, %PUBURL%/%SYSTEMWEB%/DocumentGraphics/edittopic.gif" ; hide edit button at the end of the table with "hide" (Note: Button is automatically hidden if an edit button is present in a cell) | EDITBUTTON plugin setting |
buttonrow | Set to top to put the edit buttons above the table. | bottom |
javascriptinterface | Use javascript to directly move and delete row without page refresh. Enable with "on" , disable with "off" . | JAVASCRIPTINTERFACE plugin setting |
%EDITTABLE{ format="| text, 20 | select, 1, one, two, three |" changerows="on" }%
| *Name* | *Type* |
| Foo | two |
"\n"
) and linefeed ("\r"
)
"<"
, ">"
, "&"
, single quote ('
) and double quote ("
)
"%"
, "["
, "]"
, "@"
, "_"
, "*"
, "="
and "|"
%ENCODE{"string"}%
Parameter: | Description: | Default: |
---|---|---|
"string" | String to encode | required (can be empty) |
type="entity" type="safe" type="html" type="quotes" type="url" | Control how special characters are encoded entity : Encode special characters into HTML entities, like a double quote into " . Does not encode \n or \r . safe : Encode characters '"<>% into HTML entities. html : As type="entity" except it also encodes \n and \r quotes : Escape double quotes with backslashes (\" ), does not change other characters url : Encode special characters for URL parameter use, like a double quote into %22 (this is the default) | type="url" |
%ENCODE{"spaced name"}%
expands to spaced%20name
<input type="text" name="address" value="%ENCODE{ "any text" type="entity" }%" />
%SEARCH{ "%ENCODE{ "string with "quotes"" type="quotes" }%" noheader="on" }%
type="entity"
. This can however prevent an application from fully working. You can then use type="safe"
which encodes only the characters '"<>%
into HTML entities (same as encode="safe"). When ENCODE is passing a string inside another macro always use double quotes ("") type="quote". For maximum security against cross-site scripting you are adviced to install the Foswiki:Extensions.SafeWikiPlugin.
ENDCOLOR
is a shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
%RED% red text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%ENDSECTION{"name"}%
%ENDSECTION{type="include"}%
Parameter: | Description: |
---|---|
"name" | Name of the section. |
type="..." | Type of the section being terminated; supported types "section" , "include" , "expandvariables" , "templateonly" . |
STARTSECTION
is named, the corresponding ENDSECTION
must also be named with the same name. If the STARTSECTION
specifies a type, then the corresponding ENDSECTION
must also specify the same type. If the section is unnamed, ENDSECTION
will match with the nearest unnamed %STARTSECTION%
of the same type above it.
{AccessibleENV}
in the Security Settings/Miscellaneous section of configure
can be displayed. Any other variable will just be shown as an empty string, irrespective of its real value.
%ENV{MOD_PERL}%
displays as: not set
not set
.
%FAILEDPLUGINS%
%FORMFIELD{"fieldname"}%
Parameter: | Description: | Default: |
---|---|---|
"fieldname" | The name of a Data form field | required |
topic="..." | Topic where form data is located. May be of the form Web.TopicName | Current topic |
format="..." | Format string. $value expands to the field value, and $name expands to the field name, $title to the field title, $form to the name of the form the field is in. The standard format tokens are also expanded. | "$value" |
default="..." | Text shown if the field is defined in the topic, but the field value is empty. For example, a text field for which all the content has been deleted. | "" |
alttext="..." | Text shown if the field is not defined in the topic (even if it is specified in the form definition). For example, this is used when a field exists in the form definition, but the referring topic hasn't been edited since it was added. | "" |
%FORMFIELD{"ProjectName" topic="Projects.SushiProject" default="(no project name given)" alttext="ProjectName field not found in form"}%
%GMTIME%
OR %GMTIME{"format"}%
%GMTIME%
uses the default date format defined by the {DefaultDateFormat} setting in configure Token: | Unit: | Example |
---|---|---|
$seconds | seconds | 59 |
$minutes | minutes | 59 |
$hours | hours | 23 |
$day | day of month | 31 |
$wday | day of the Week (Sun, Mon, Tue, Wed, Thu, Fri, Sat) | Thu |
$dow | day of the week (Sun = 0) | 2 |
$week | number of week in year (ISO 8601) | 34 |
$month | short name of month | Dec |
$mo | 2 digit month | 12 |
$year | 4 digit year | 1999 |
$ye | 2 digit year | 99 |
$tz | either "GMT" (if set to gmtime), or "Local" (if set to servertime) | GMT |
$iso | ISO format timestamp | 2024-10-09T23:19:24Z |
$rcs | RCS format timestamp | 2024/10/09 23:19:24 |
$http | E-mail & http format timestamp | Wed, 09 Oct 2024 23:19:24 GMT |
$epoch | Number of seconds since 00:00 on 1st January, 1970 | 1728515964 |
%GMTIME{"$day $month, $year - $hour:$min:$sec"}%
expands to 09 Oct, 2024 - 23:19:24
GRAY
is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
%GRAY% gray text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
GREEN
is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
%GREEN% green text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%GROUPS%
%HOMETOPIC%
WebHome
, renders as WebHome
%HTTP%
%HTTP{"Header-name"}%
%HTTP% | |
%HTTP{"Accept-language"}% | en-US,en;q=0.5 |
%HTTP{"User-Agent"}% | CCBot/2.0 (https://commoncrawl.org/faq/) |
%HTTP_HOST%
www.wetherby.me
%HTTP%
but operates on the HTTPS environment variables present when the SSL protocol is in effect. Can be used to determine whether SSL is turned on.
%HTTPS%
%HTTPS{"Header-name"}%
%ICON{"name"}%
%ICON{"flag-gray"}%
returns
%ICON{"pdf"}%
returns
%ICON{"smile.pdf"}%
returns
%ICON{"/dont/you/dare/smile.pdf"}%
returns
%ICON{"http://trunk.foswiki.org/pub/System/DocumentGraphics/xsl.gif"}%
returns
arrowbright
, bubble
, choice-yes
, hand
bmp
, doc
, gif
, hlp
, html
, mp3
, pdf
, ppt
, txt
, xls
, xml
, zip
%ICON{"name"}%
generates the full HTML img tag. Specify image name or full filename (see ICON for details on filenames.)
%ICONURL{"name"}%
%ICONURL{"arrowbright"}%
returns http://www.wetherby.me/wiki/pub/System/DocumentGraphics/arrowbright.gif
%ICONURL{"novel.pdf"}%
returns http://www.wetherby.me/wiki/pub/System/DocumentGraphics/pdf.gif
%ICONURL{"/queen/boheme.mp3"}%
returns http://www.wetherby.me/wiki/pub/System/DocumentGraphics/mp3.gif
%ICONURLPATH{"name"}%
%ICONURLPATH{"locktopic"}%
returns /wiki/pub/System/DocumentGraphics/locktopic.gif
%ICONURLPATH{"eggysmell.xml"}%
returns /wiki/pub/System/DocumentGraphics/xml.gif
%ICONURLPATH{"/doc/xhtml.xsl"}%
returns /wiki/pub/System/DocumentGraphics/xsl.gif
%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"}%
renders as FUNFACTOR is not defined
%INCLUDE{"page" ...}%
Parameter: | Description: | Default: |
---|---|---|
"SomeTopic" | The name of a topic located in the current web, i.e. %INCLUDE{"WebNotify"}% | |
"Web.Topic" | A topic in another web, i.e. %INCLUDE{"System.SiteMap"}% | |
"http://..." | A full qualified URL, i.e. %INCLUDE{"http://foswiki.org:80/index.html"}% . Supported content types are text/html and text/plain . if the URL resolves to an attachment file on the server this will automatically translate to a server-side include. | |
"doc:Foswiki::..." level="3" | Generates the embedded documentation in the given perl module. The optional =level parameter lets you define the base level for headings in the included text. | |
pattern="..." | Include a subset of a topic or a web page. Specify a RegularExpression that scans from start ('^' ) to end and contains the text you want to keep in parenthesis, e.g., pattern="^.*?(from here.*?to here).*" . IncludeTopicsAndWebPages has more. | none |
rev="2" | Include a previous topic revision; N/A for URLs | top revision |
raw="on" | When a page is included, normally Foswiki will process it, doing the following: 1) Alter relative links to point back to originating host, 2) Remove some basic HTML tags (html, head, body, script) and finally 3) Remove newlines from HTML tags spanning multiple lines. If you prefer to include exactly what is in the source of the originating page set this to on . raw="on" is short for disableremoveheaders="on" , disableremovescript="on" , disableremovebody="on" , disablecompresstags="on" and disablerewriteurls="on" . | disabled |
literal="on" | While using the raw option will indeed include the raw content, the included content will still be processed and rendered like regular topic content. To disable parsing of the included content, set the literal option to "on" . | disabled |
disableremoveheaders="on" | Bypass stripping headers from included HTML (everything until first </head> tag) | disabled |
disableremovescript="on" | Bypass stripping all <script> tags from included HTML | disabled |
disableremovebody="on" | Bypass stripping the </body> tag and everything around over and below it | disabled |
disablecompresstags="on" | Bypass replacing newlines in HTML tags with spaces. This compression step rewrites unmatched <'s into < entities unless bypassed | disabled |
disablerewriteurls="on" | Bypass rewriting relative URLs into absolute ones | disabled |
warn="off" | Warn if topic include fails: Fail silently (if off ); output default warning (if set to on ); else, output specific text (use $topic for topic name) | %INCLUDEWARNING% preferences setting |
section="name" | Includes only the specified named section, as defined in the included topic by the STARTSECTION and ENDSECTION macros. Nothing is shown if the named section does not exists. section="" is equivalent to not specifying a section | |
PARONE="val 1" | Any other parameter will be defined as a macro within the scope of the included topic. The example parameters on the left will result in %PARONE% and %PARTWO% being defined within the included topic. |
disableremovescript
parameter)
%TOPIC%
in case there is no include
%INCLUDINGTOPIC%
%WEB%
if there is no INCLUDE.
%INCLUDINGWEB%
LANGUAGE
preference is set, it's used as user's language instead of any language detected from the browser.
LANGUAGE
at a non per-user way, so each user can choose his/her preferred language.
PO
files). These are the languages in which the user interface is available.
%LANGUAGES{...}%
Parameter: | Description: | Default: |
---|---|---|
format | format for each item. See below for format tokens available in the format string. | " * $langname" |
separator | separator between items. | "\n" (newline) |
marker="selected" | Text for $marker if the item matches selection | "selected" |
selection="%LANGUAGE%" | Current language to be selected in list | (none) |
format
tokens: Token | Meaning |
---|---|
$langname | language's name, as informed by the translators |
$langtag | language's tag. Ex: en , pt-br , etc. |
<select>%LANGUAGES{format="<option $marker value='$langtag'>$langname</option>" selection="%LANGUAGE%"}%</select>
creates an option list of the available languages with the current language selected
LIME
is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
%LIME% lime text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%LOCALSITEPREFS%
Main.SitePreferences
, renders as Main.SitePreferences
%LOGIN%
%LOGOUT%
%MAKETEXT{"string" args="..."}%
Parameter | Description | Default |
---|---|---|
"text" or string="text" | The text to be displayed. | none |
args="param1, param2" | a comma-separated list of arguments to be interpolated in the string, replacing the [_N] placeholders in it. | none |
%MAKETEXT{string="Notes:"}%
%MAKETEXT{"If you have any questions, please contact [_1]." args="%WIKIWEBMASTER%"}%
%MAKETEXT{"Did you want to [[[_1]][reset [_2]'s password]]?" args="%SYSTEMWEB%.ResetPassword,%WIKIUSERNAME%"}%
string
to the current user's language only if it has such string in its translation table for that language.
&
) followed by one letter (one of a...z, A...Z) (say, X
) in the translatable string will be translated to <span class='foswikiAccessKey'>X</span>
. This is used to implement access keys. If you want to write an actual amperstand that stays just before a letter, write two consecutive amperstands (&&
): they will be transformed in just one.
_
) are reserved. You cannot use translatable phrases starting with an underscore.
%MACROS%
inside the translatable strings (since they will get expanded before the %MAKETEXT{...}%
itself is handled).
MAROON
is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
%MAROON% maroon text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
formfield
item is the most likely to be useful to casual users.
%META{ "item" ...}%
Item | Options | Description |
---|---|---|
"formfield" | name="..." : name of the field. The field value can be shortened as described in System.FormattedSearch for $formfield newline="..." : by default, each newline character will be rewritten to <br /> to allow metadata that contains newlines to be used in tables, etc. $n indicates a newline character. bar="..." : by default, each vertical bar is rewritten to an HTML entity so as to not be mistaken for a table separator. | Show a single form field |
"form" | none | Generates the table showing the form fields. See Form Definition |
"attachments" | all="on" to show hidden attachments. title="..." to show a title - only if attachments are displayed. template="..." to use a custom template for the rendering of attachments; default attachtables is used. | Generates the list of attachments |
"moved" | none | Details of any topic moves |
"parent" | dontrecurse="on" : By default recurses up tree, this has some cost. Equivalent to depth=1 depth="..." : Return only the specified ancestor. nowebhome="on" : Suppress WebHome. prefix="..." : Prefix that goes before parents, but only if there are parents, default "" . format="..." : Format string used to display each parent topic where $web expands to the web name, and $topic expands to the topic name; default: "[[$web.$topic][$topic]]" suffix="..." : Suffix, only appears if there are parents; default "" . separator="..." : Separator between parents; default " > " . | Generates the parent link |
%METASEARCH{...}%
Parameter: | Description: | Default: |
---|---|---|
type="topicmoved" | What sort of search is required? "topicmoved" if search for a topic that may have been moved "parent" if searching for topics that have a specific parent i.e. its children "field" if searching for topics that have a particular form field value (use the name and value parameters to specify which field to search) | Required |
web="%WEB%" | Wiki web to search: A web, a list of webs separated by whitespace, or all webs. | Current web |
topic="%TOPIC%" | The topic the search relates to, for topicmoved and parent searches | All topics in a web |
name | form field to search, for field type searches. May be a regular expression (see SEARCH). | |
value | form field value, for field type searches. May be a regular expression (see SEARCH). | |
title="Title" | Text that is prefixed to any search results | empty |
format="..." | Custom format results. Supports same format strings as SEARCH. See FormattedSearch for usage & examples | Results in table |
default="none" | Default text shown if no search hit | Empty |
%METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%" title="This topic used to exist and was moved to: "}%
%METASEARCH{type="parent" web="%WEB%" topic="%TOPIC%" title="Children: "}%
%METASEARCH{type="field" name="Country" value="China"}%
NAVY
is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
%NAVY% navy text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%NOP%
%NOP{...}%
deprecated %STARTSECTION{type="templateonly"}%
.. %ENDSECTION{type="templateonly"}%
instead (see TemplateTopics for more details).
%NOTIFYTOPIC%
WebNotify
, renders as WebNotify
OLIVE
is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
%OLIVE% olive text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
ORANGE
is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
%ORANGE% orange text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
PINK
is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
%PINK% pink text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%PLUGINDESCRIPTIONS%
%PLUGINVERSION{"name"}%
to get the version of a specific plugin
%PLUGINVERSION{"InterwikiPlugin"}%
expands to $Rev: 5022 (2009-09-20) $
%PLUGINVERSION%
to get the version of the API
2.0
%PUBURL%
http://www.wetherby.me/wiki/pub
%PUBURL%/%WEB%/OtherTopic/image.gif
%PUBURLPATH%
/wiki/pub
PURPLE
is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
%PURPLE% purple text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%QUERYPARAMS{...}%
Parameter: | Description: | Default: |
---|---|---|
format="..." | Format string for each entry | $name=$value |
separator="..." | Separator string | separator="$n" (newline) |
encoding="entity" encoding="safe" encoding="html" encoding="quotes" encoding="url" | Control how special characters are encoded. If this parameter is not given, "safe" encoding is performed which HTML entity encodes the characters '"<>% . entity : Encode special characters into HTML entities, like a double quote into " . Does not encode \n or \r . safe : Encode characters '"<>% into HTML entities. (this is the default) html : As type="entity" except it also encodes \n and \r quotes : Escape double quotes with backslashes (\" ), does not change other characters url : Encode special characters for URL parameter use, like a double quote into %22 | type="safe" |
Sequence: | Expands To: |
---|---|
$name |
Name of the parameter |
$value |
String value of the parameter. Multi-valued parameters will have a "row" for each value. |
$n or $n() |
New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar |
$nop or $nop() |
Is a "no operation". This token gets removed; useful for nested search |
$quot |
Double quote (" ) (\" also works) |
$percnt |
Percent sign (% ) |
$dollar |
Dollar sign ($ ) |
$lt |
Less than sign (< ) |
$gt |
Greater than sign (> ) |
$amp |
Ampersand (& ) |
%QUERYPARAMS{format="<input type='hidden' name='$name' value='$value' encoding="entity" />"}%
'"<>%
into HTML entities (same as encoding="safe") which is relatively safe. The safest is to use encoding="entity". When passing QUERYPARAMS inside another macro always use double quotes ("") combined with using QUERYPARAMS with encoding="quote". For maximum security against cross-site scripting you are adviced to install the Foswiki:Extensions.SafeWikiPlugin.
%QUERYPARAMS%
.
%QUERYSTRING%
RED
is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
%RED% red text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%REMOTE_ADDR%
3.238.82.77
%REMOTE_PORT%
%REMOTE_USER%
%RENDERLIST%
macro is handled by the RenderListPlugin
%RENDERLIST%
%RENDERLIST{ "org" focus="Sales.WestCoastTeam" }%
%RENDERLIST{ "org" }%
* [[Eng.WebHome][Engineering]]
* [[Eng.TechPubs][Tech Pubs]]
* [[Sales.WestCoastTeam][Sales]]
* [[Sales.EastCoastTeam][East Coast]]
* [[Sales.WestCoastTeam][West Coast]]
%REVINFO%
OR %REVINFO{"format"}%
%REVINFO%
is equivalent to %REVINFO{format="r1.$rev - $date - $wikiusername"}%
r1 - 09 Jan 2009 - 12:00:00 - Main.ProjectContributor
Parameter: | Description: | Default: |
---|---|---|
"format" | Format of revision information, see supported formatting tokens below | "r1.$rev - $date - $wikiusername" |
web="..." | Name of web | Current web |
topic="..." | Topic name | Current topic |
rev="1.5" | Specific revision number | Latest revision |
Token: | Unit: | Example |
---|---|---|
$web | Name of web | Current web |
$topic | Topic name | Current topic |
$rev | Revision number. Prefix r1. to get the usual r1.5 format | 5 |
$username | Login username of revision | jsmith |
$wikiname | WikiName of revision | JohnSmith |
$wikiusername | WikiName with Main web prefix | Main.JohnSmith |
$date | Revision date. Actual date format defined as {DefaultDateFormat} in configure | 21 Sep 2006 |
$time | Revision time | 23:24:25 |
$iso | Revision date in ISO date format | 2006-09-22T06:24:25Z |
$min , $sec , etc. | Same date format qualifiers as GMTIME{"format"} |
%REVINFO{"$date - $wikiusername" rev="1.1"}%
returns revision info of first revision
viewauth.cgi
)
%SCRIPTNAME%
view
.pl
or .cgi
%SCRIPTSUFFIX%
%SCRIPTURL%
OR %SCRIPTURL{"script"}%
%SCRIPTURL%
returns the base URL of scripts - expands to http://www.wetherby.me/wiki/bin
http://www.wetherby.me/wiki/bin/script
%SCRIPTURL{"viewauth"}%/%WEB%/%TOPIC%
which expands to http://www.wetherby.me/wiki/bin/viewauth/System/Macros
%SCRIPTURLPATH{"script"}%
instead, as it works with URL rewriting much better
edit
script should always be used in conjunction with ?t=%GMTIME{"$epoch"}%
to ensure pages about to be edited are not cached in the browser
%SCRIPTURL{"script"}%
, but doesn't include the protocol and host part of the URL
%SCRIPTURL%
OR %SCRIPTURLPATH{"script"}%
/wiki/bin/script
edit
script should always be used in conjunction with ?t=%GMTIME{"$epoch"}%
to ensure pages about to be edited are not cached in the browser
%SEARCH{"text" ...}%
Parameter: | Description: | Default: |
---|---|---|
"text" | Search term. Is a keyword search, literal search, regular expression search, or query, depending on the type parameter. SearchHelp has more | required |
search="text" | (Alternative to above) | N/A |
web="Name" web="Main, Know" web="all" | Comma-separated list of webs to search. You can specifically exclude webs from an all search using a minus sign - for example, web="all,-Secretweb" . The special word all means all webs that do not have the NOSEARCHALL preference set to on in their WebPreferences. Note that AccessControls are respected when searching webs; it is much better to use them than NOSEARCHALL . | Current web |
topic="WebPreferences" topic="*Bug" | Limit search to topics: A topic, a topic with asterisk wildcards, or a list of topics separated by comma. Note this is a list of topic names and must not include web names. | All topics in a web |
excludetopic="Web*" excludetopic="WebHome, WebChanges" | Exclude topics from search: A topic, a topic with asterisk wildcards, or a list of topics separated by comma. Note this is a list of topic names and must not include web names. | None |
scope="topic" scope="text" scope="all" | Search topic name (title); the text (body) of topic; or all (title and body) | "text" |
type="keyword" type="word" type="literal" type="regex" type="query" | Control how the search is performed when scope="text" or scope="all" keyword : use Google-like controls as in soap "web service" -shampoo ; searches word parts: using the example, topics with "soapsuds" will be found as well, but topics with "shampoos" will be excluded word : identical to keyword but searches whole words: topics with "soapsuds" will not be found, and topics with "shampoos" will not be excluded literal : search for the exact string, like web service regex : use a RegularExpression search like soap;web service;!shampoo ; to search on whole words use \bsoap\b query : query search of form fields and other meta-data, like (Firstname='Emma' OR Firstname='John') AND Lastname='Peel' | %SEARCHVAR- DEFAULTTYPE% preferences setting (literal) |
order="topic" order="created" order="modified" order="editby" order= | Sort the results of search by the topic names, topic creation time, last modified time, last editor's WikiName, or named field of DataForms. The sorting is done web by web; if you want to sort across webs, create a formatted table and sort it with TablePlugin's initsort. Note that dates are sorted most recent date last (i.e at the bottom of the table). | Sort by topic name |
limit="all" limit="16" | Limit the number of topics from which results will be returned. This is done after sorting if order is specified. Note that this does not limit the number of hits from the same topic when you have multiple="on". | All results |
date="..." | limits the results to those pages with latest edit time in the given time interval. | All results |
reverse="on" | Reverse the direction of the search | Ascending search |
casesensitive="on" | Case sensitive search | Ignore case |
bookview="on" | BookView search, e.g. show complete topic text. Very resource demanding. Use only with small result sets | Show entire topic content. |
nonoise="on" | Shorthand for nosummary="on" nosearch="on" nototal="on" zeroresults="off" noheader="on" noempty="on" | Off |
nosummary="on" | Show topic title only | Show topic summary |
nosearch="on" | Suppress search string | Show search string |
noheader="on" | Suppress default search header Topics: Changed: By: , unless a header is explicitly specified | Show default search header, unless search is inline and a format is specified (Cairo compatibility) |
nototal="on" | Do not show number of topics found | Show number |
zeroresults="off" | Suppress all output if there are no hits | zeroresults="on" , displays: "Number of topics: 0" |
noempty="on" | Suppress results for webs that have no hits. | Show webs with no hits |
header="..." format="..." footer="..." | Custom format results: see FormattedSearch for usage & examples | Results in table |
expandvariables="on" | Expand embedded macros before applying a FormattedSearch on a search hit. Useful to show the expanded text, e.g. to show the result of a SpreadSheetPlugin %CALC{}% instead of the formula | Raw text |
multiple="on" | Multiple hits per topic. Each hit can be formatted. The last token is used in case of a regular expression ";" and search | Only one hit per topic |
nofinalnewline="on" | If on , the search variable does not end in a line by itself. Any text continuing immediately after the SEARCH macro on the same line will be rendered as part of the table generated by the search, if appropriate. | off |
recurse="on" | Recurse into subwebs, if subwebs are enabled. | off |
separator=", " | Line separator between search hits | "$n" (Newline) |
newline="%BR%" | Line separator within a search hit. Useful if you want to put multi-line content into a table cell, for example if the format="" parameter contains a $pattern() that captures more than one line, or contains a $formfield() that returns a multi-line textfield. | "$n" (Newline) |
%SEARCH{"wiki" web="Main" scope="topic"}%
%SEARCH{"FAQ" scope="topic" nosearch="on" nototal="on" header="| *Topic: * | *Summary: * |" format="| $topic | $summary |"}%
(displays results in a table with header - details)
%TABLE{}%
macro just before the %SEARCH{}%
to alter the output of a search. Example: %TABLE{ tablewidth="90%" }%
%GMTIME%
%SERVERTIME%
OR %SERVERTIME{"format"}%
%SERVERTIME%
uses the Date format defined as {DefaultDateFormat} in configure
%SERVERTIME{"$hou:$min"}%
expands to 00:19
%SESSIONID%
%SESSIONVAR%
%SESSION_VARIABLE{"name"}%
%SESSION_VARIABLE{"name" set="value"}%
%SESSION_VARIABLE{"name" clear=""}%
AUTHUSER
session variable, and is read-only
SILVER
is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
%SILVER% silver text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%SLIDESHOWEND%
macro is handled by the SlideShowPlugin
%SLIDESHOWEND%
%SLIDESHOWSTART%
macro is handled by the SlideShowPlugin
%SLIDESHOWSTART%
%SLIDESHOWSTART{ template="MyOwnSlideTemplate" }%
%SLIDESHOWSTART%
---++ Sample Slide 1
* Bullet 1
* Bullet 2
---++ Sample Slide 2
* Bullet 1
* Bullet 2
%SLIDESHOWEND%
%SPACEDTOPIC%
Var%20*SPACEDTOPIC
%ENCODE{%SPACEOUT{"%TOPIC%" separator=" *"}%}%
%SPACEOUT{ "%TOPIC%" }%
Macros
Parameter: | Description: | Default: |
---|---|---|
separator | The separator to put between words e.g. %SPACEOUT{"DogsCatsBudgies" separator=", "}% -> Dogs, Cats, Budgies | ' ' |
[[WebHome][%SPACEOUT{"WebHome"}%]]
expands to Web Home
%STOPINCLUDE%
macro. A normal view of the topic shows everything exept the %STARTINCLUDE%
macro itself.
%STARTSECTION{type="include"}%
instead
%STARTINCLUDE%
%STARTSECTION{}%
and %ENDSECTION{}%
.
type="section"
- the default, used for a generic section, such as a named section used by INCLUDE.
type="include"
- like %STARTINCLUDE%
... %STOPINCLUDE%
except that you can have as many include blocks as you want (%STARTINCLUDE%
is restricted to only one).
type="expandvariables"
- all macros inside an "expandvariables" type section gets expanded when a new topic based on the template topic is created. See TemplateTopics for more information.
type="templateonly"
- start position of text to be removed when a template topic is used. This is used to embed text that you do not want expanded when a new topic based on the template topic is created. See TemplateTopics for more information.
%STARTSECTION{"name"}% ................... %ENDSECTION{"name"}%
%STARTSECTION{type="include"}% ........... %ENDSECTION{type="include"}%
%STARTSECTION{type="expandvariables"}% ... %ENDSECTION{type="expandvariables"}%
%STARTSECTION{type="templateonly"}% ...... %ENDSECTION{type="templateonly"}%
Parameter: | Description: | Default |
---|---|---|
"name" | Name of the section. Must be unique inside a topic. | Generated name |
type="..." | Type of the section; type "section" , "expandvariables" , "include" or "templateonly" | "section" |
_SECTION0
for the first unnamed section in the topic, _SECTION1
for the second, etc..
%STATISTICSTOPIC%
WebStatistics
, renders as WebStatistics
%STOPINCLUDE%
macro itself.
%STOPINCLUDE%
%SYSTEMWEB%
System
%TABLE{}%
macro is handled by the TablePlugin
%TABLE{ attributes }%
Argument | Comment | Default value | Example |
---|---|---|---|
sort | Set table sorting by clicking headers "on" or "off" . | unspecified | sort="on" |
initsort | Column to sort initially ("1" to number of columns). | unspecified | initsort="2" |
initdirection | Initial sorting direction for initsort , set to "up" (descending) or "down" (ascending). | unspecified | initdirection="up" |
disableallsort | Disable all sorting, both initsort and header sort. This is mainly used by plugins such as the EditTablePlugin to disable sorting in a table while editing the table. | unspecified | disableallsort="on" |
headerbg | Header cell background colour. | "#6b7f93" | headerbg="#999999" |
headerbgsorted | Header cell background colour of a sorted column. | the value of headerbg | headerbgsorted="#32596c" |
headercolor | Header cell text colour. | "#ffffff" | headercolor="#0000cc" |
databg | Data cell background colour, a comma separated list. Specify "none" for no colour, that is to use the colour/background of the page the table is on. | "#edf4f9,#ffffff" | databg="#f2f2f2,#ffffff" |
databgsorted | Data cell background colour of a sorted column; see databg . | the values of databg | databgsorted="#d4e8e4,#e5f5ea" |
datacolor | Data cell text colour, a comma separated list. | unspecified | datacolor="#0000CC, #000000" |
tableborder | Table border width (pixels). | "1" | tableborder="2" |
tableframe | Table frame, set to "void" (no sides), "above" (the top side only), "below" (the bottom side only), "hsides" (the top and bottom sides only), "lhs" (the left-hand side only), "rhs" (the right-hand side only), "vsides" (the right and left sides only), "box" (all four sides), "border" (all four sides). | unspecified | tableframe="hsides" |
tablerules | Table rules, set to "none" (no rules), "groups" (rules will appear between row groups and column groups only), "rows" (rules will appear between rows only), "cols" (rules will appear between columns only), "all" (rules will appear between all rows and columns). | unspecified | tablerules="rows" |
cellpadding | Cell padding (pixels). | "0" | cellpadding="0" |
cellspacing | Cell spacing (pixels). | "0" | cellspacing="3" |
cellborder | Cell border width (pixels). | unspecified | cellborder="0" |
valign | Vertical alignment of cells and headers, set to "top" , "middle" , "bottom" or "baseline" . | unspecified | valign="top" |
headervalign | Vertical alignment of header cells; overrides valign . | unspecified | headervalign="top" |
datavalign | Vertical alignment of data cells; overrides valign . | unspecified | datavalign="top" |
headeralign | Header cell alignment, one value for all columns, or a comma separated list for different alignment of individual columns. Set to "left" , "center" , "right" or "justify" . Overrides individual cell settings. | unspecified | headeralign="left,right" |
dataalign | Data cell alignment, one value for all columns, or a comma separated list for different alignment of individual columns. Set to "left" , "center" , "right" or "justify" . Overrides individual cell settings. | unspecified | dataalign="center" |
tablewidth | Table width: Percentage of window width, or absolute pixel value. | unspecified | tablewidth="100%" |
columnwidths | Column widths: Comma delimited list of column widths, percentage or absolute pixel value. | unspecified | columnwidths="80%,20%" |
headerrows | Number of header rows to exclude from sort. (will be rendered in a HTML thead section) | "1" | headerrows="1" |
footerrows | Number of footer rows to exclude from sort. (will be rendered in a HTML tfoot section) | "0" | footerrows="1" |
id | Unique table identifier string, used for targeting a table with CSS. | tableN (where N is the table order number on the page) | id="userTable" |
summary | Table summary used by screenreaders: A summary of what the table presents. It should provide an orientation for someone who listens to the table. | unspecified | summary="List of subscribed users" |
caption | Table caption: A title that will be displayed just above the table. | unspecified | caption="Users" |
%TABLE{ tableborder="0" cellpadding="4" cellspacing="3" cellborder="0" }%
| *A1* | *B1* |
| A2 | B2 |
TEAL
is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
%TEAL% teal text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
"---++ text"
) and HTML ("<h2>text</h2>"
) are taken into account. Any heading text after "!!"
is excluded from the TOC; for example, write "---+!! text"
if you do not want to list a header in the TOC
%TOC%
OR %TOC{"SomeTopic" ...}%
Parameter: | Description: | Default: |
---|---|---|
"TopicName" | topic name | Current topic |
web="Name" | Name of web | Current web |
depth="2" | Limit depth of headings shown in TOC | 6 |
title="Some text" | Title to appear at top of TOC | none |
%TOC{depth="2"}%
%TOC{"CompleteDocumentation" web="System" title="Contents:"}%
foswikiTOC
just before the table of contents. This enables adding a link from within a topic back to the table of contents to ease navigation. Example [[#foswikiTOC][Back to TOC]]
creates Back to TOC.
%TOPIC%
expands to the name of the topic. If you are looking at the text of an included topic, it is the name of the included topic.
%TOPIC%
Macros
, renders as Macros
$topic
token gets expanded to the topic name, $marker
to marker
parameter where topic matches selection
, and $web
to the name of the web, or any of the standard FormatTokens.
%TOPICLIST{"format" ...}%
Parameter: | Description: | Default: |
---|---|---|
"format" | Format of one line, may include $web (name of web), $topic (name of the topic), $marker (which expands to marker for the item matching selection only) | "$topic" |
format="format" | (Alternative to above) | "$topic" |
separator=", " | line separator | "$n" (new line) |
marker="selected" | Text for $marker if the item matches selection | "selected" |
selection="TopicA, TopicB" | Current value to be selected in list | (none) |
web="Name" | Name of web | Current web |
%TOPICLIST{" * $web.$topic"}%
creates a bullet list of all topics
%TOPICLIST{separator=", "}%
creates a comma separated list of all topics
%TOPICLIST{" <option>$topic</option>"}%
creates an option list (for drop down menus)
<select>%TOPICLIST{" <option $marker value='$topic'>$topic</option>" separator=" " selection="%TOPIC%"}%</select>
creates an option list of web topics with the current topic selected
%SYSTEMWEB%
instead.
%URLPARAM{"name"}%
Parameter: | Description: | Default: |
---|---|---|
"name" | The name of a URL parameter | required |
default="..." | Default value in case parameter is empty or missing | empty string |
newline="<br />" | Convert newlines in textarea to other delimiters | no conversion |
encode="off" encode="entity" encode="safe" encode="url" encode="quote" | Control how special characters are encoded off : No encoding. Avoid using this when possible. See the security warning below. entity : Encode special characters into HTML entities. See ENCODE for more details. safe : Encode characters '"<>% into HTML entities. url : Encode special characters for URL parameter use, like a double quote into %22 quote : Escape double quotes with backslashes (\" ), does not change other characters; required when feeding URL parameters into other macros. | "safe" |
multiple="on" multiple="[[$item]]" | If set, gets all selected elements of a <select multiple="multiple"> tag. A format can be specified, with $item indicating the element, e.g. multiple="Option: $item" | first element |
separator=", " | Separator between multiple selections. Only relevant if multiple is specified | "\n" (new line) |
%URLPARAM{"skin"}%
returns print
for a .../view/System/Macros?skin=print
URL
%SEARCH{ "%URLPARAM{ "search" encode="quote" }%" noheader="on" }%
rev
, skin
, template
, topic
, web
; they have a special meaning in Foswiki. Common parameters and view script specific parameters are documented at CommandAndCGIScripts.
%URLPARAM{
in the value of a URL parameter, it will be modified to %<nop>URLPARAM{
. This is to prevent an infinite loop during expansion.
'"<>%
into HTML entities (same as encode="safe") which is relatively safe. The safest is to use encode="entity". When passing URLPARAM inside another macro always use double quotes ("") combined with using URLPARAM with encode="quote". For maximum security against cross-site scripting you are adviced to install the Foswiki:Extensions.SafeWikiPlugin.
%USERINFO%
guest, Main.WikiGuest,
(comma-separated list of the username, wikiusername, and emails)
$emails
, $username
, $wikiname
, $wikiusername
, $groups
and $admin
($admin returns 'true' or 'false'): %USERINFO{ format="$username is really $wikiname" }%
guest is really WikiGuest
%USERINFO{ "WikiGuest" format="$username is really $wikiname" }%
guest is really WikiGuest
{AntiSpam}{HideUserDetails}
configuration option is not enabled, or if you are an admin. (User details are hidden in this site)
jsmith
, WIKINAME like JohnSmith
and WIKIUSERNAME like Main.JohnSmith
. Un-authenticated users are all Main.WikiGuest.
%USERNAME%
guest
%USERSWEB%
Main
%VAR{"NAME" web="Web"}%
%WEBBGCOLOR%
of the Main web write %VAR{"WEBBGCOLOR" web="Main"}%
, which expands to #FFEFA6
%WEB%
expands to the name of the web where the topic is located. If you are looking at the text of an included topic, it is the web where the included topic is located.
%WEB%
System
NOSEARCHALL = on
preference setting. The "format"
defines the format of one web item. The $name
gets expanded to the name of the web, $qname
gets expanded to double quoted name, $marker
to marker
where web matches selection
.
%WEBLIST{"format" ...}%
Parameter: | Description: | Default: |
---|---|---|
"format" | Format of one line, may include $name (the name of the web), $qname (the name of the web in double quotes), $indentedname (the name of the web with parent web names replaced by indents, for use in indented lists), and $marker (which expands to marker for the item matching selection only) | "$name" |
format="format" | (Alternative to above) | "$name" |
separator=", " | Line separator | "$n" (new line) |
web="" | if you specify $web in format, it will be replaced with this | "" |
webs="public" | Comma separated list of webs, public expands to all non-hidden.NOTE: Administrators will see all webs, not just the public ones | "public" |
marker="selected" | Text for $marker if the item matches selection | "selected" |
selection="%WEB%" | Current value to be selected in list | selection="%WEB%" |
subwebs="Sandbox" | show webs that are a sub-web of this one (recursivly) | "" |
%WEBLIST{" * [[$name.WebHome]]"}%
- creates a bullet list of all webs.
<form><select name="web"> %WEBLIST{"<option $marker value=$qname>$name</option>" webs="Trash, public" selection="%WEB%" separator=" "}% </select></form>
- creates a dropdown of all public webs + Trash web, with the current web highlighted.
TWikiCompatibilityPlugin
is installed and activated in configure. This is done to ensure that the TWiki compatibility components such as the TWiki web are only visible and active when needed.
%WEBPREFSTOPIC%
WebPreferences
, renders as WebPreferences
WHITE
is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
%WHITE% white text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%WIKIHOMEURL%
/wiki/bin/view
%SCRIPTURLPATH{"view"}%
%WIKILOGOURL%
defined in WebPreferences instead.
%USERNAME%
if not defined in the Main.WikiUsers topic
%WIKINAME%
WikiGuest
%WIKIPREFSTOPIC%
DefaultPreferences
, renders as DefaultPreferences
%WIKITOOLNAME%
Foswiki
%WIKIUSERNAME%
Main.WikiGuest
, renders as Main.WikiGuest
%WIKIUSERSTOPIC%
WikiUsers
, with Main prefix renders as Main.WikiUsers
%WIKIVERSION%
Foswiki-1.0.9, Sun, 17 Jan 2010, build 6075
YELLOW
is one of the shortcut macros predefined in DefaultPreferences. See the section shortcut macros in that topic for a complete list of colors.
%YELLOW% yellow text %ENDCOLOR%
%<color>%
text must end with %ENDCOLOR%
. If you want to switch from one color to another one you first need to end the active color with %ENDCOLOR%
, e.g. write %RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%
.
%BR%
- line break
%BULLET%
- bullet sign
%BB%
- line break and bullet combined
%BB2%
- indented line break and bullet
%RED% text %ENDCOLOR%
- colored text (also %YELLOW%
, %ORANGE%
, %PINK%
, %PURPLE%
, %TEAL%
, %NAVY%
, %BLUE%
, %AQUA%
, %LIME%
, %GREEN%
, %OLIVE%
, %MAROON%
, %BROWN%
, %BLACK%
, %GRAY%
, %SILVER%
, %WHITE%
)
%H%
- Help icon
%I%
- Idea icon
%M%
- Moved to icon
%N%
- New icon
%P%
- Refactor icon
%Q%
- Question icon
%S%
- Pick icon
%T%
- Tip icon
%U%
- Updated icon
%X%
- Alert icon
%Y%
- Done icon
%SEARCH{...}%
is a table consisting of topic names and topic summaries. Use the format="..."
parameter to customize the search result. The format parameter typically defines a bullet or a table row containing macros, such as %SEARCH{ "food" format="| $topic | $summary |" }%
. See %SEARCH{...}%
for other search parameters, such as separator=""
.
header="..."
parameter header="| *Topic:* | *Summary:* |"
Format tokens that can be used in the header string:
Name: | Expands To: |
---|---|
$web |
Name of the web |
$n or $n() |
New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar |
$nop or $nop() |
Is a "no operation". This token gets removed; useful for nested search |
$quot |
Double quote (" ) (\" also works) |
$percnt |
Percent sign (% ) |
$dollar |
Dollar sign ($ ) |
$lt |
Less than sign (< ) |
$gt |
Greater than sign (> ) |
$amp |
Ampersand (& ) |
footer="..."
parameter footer="| *Topic* | *Summary* |"
Format tokens that can be used in the footer string:
Name: | Expands To: |
---|---|
$web |
Name of the web |
$ntopics |
Number of topics found in current web |
$nhits |
Number of hits if multiple="on" . Cumulative across all topics in current web. Identical to $ntopics unless multiple="on" |
$n or $n() |
New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar |
$nop or $nop() |
Is a "no operation". This token gets removed; useful for nested search |
$quot |
Double quote (" ) (\" also works) |
$percnt |
Percent sign (% ) |
$dollar |
Dollar sign ($ ) |
$lt |
Less than sign (< ) |
$gt |
Greater than sign (> ) |
$amp |
Ampersand (& ) |
format="..."
parameter format="| $topic | $summary |"
Format tokens that can be used in the format string:
Name: | Expands To: |
---|---|
$web |
Name of the web |
$topic |
Topic name |
$topic(20) |
Topic name, "- " hyphenated each 20 characters |
$topic(30, -<br />) |
Topic name, hyphenated each 30 characters with separator "-<br />" |
$topic(40, ...) |
Topic name, shortended to 40 characters with "..." indication |
$parent |
Name of parent topic; empty if not set |
$parent(20) |
Name of parent topic, same hyphenation/shortening like $topic() |
$text |
Formatted topic text. In case of a multiple="on" search, it is the line found for each search hit. |
$locked |
LOCKED flag (if any) |
$date |
Time stamp of last topic update, e.g. 09 Oct 2024 - 23:19 |
$isodate |
Time stamp of last topic update, e.g. 2024-10-09T23:19Z |
$rev |
Number of last topic revision, e.g. 4 |
$username |
Login name of last topic update, e.g. jsmith |
$wikiname |
Wiki user name of last topic update, e.g. JohnSmith |
$wikiusername |
Wiki user name of last topic update, like Main.JohnSmith |
$createdate |
Time stamp of topic revision 1 |
$createusername |
Login name of topic revision 1, e.g. jsmith |
$createwikiname |
Wiki user name of topic revision 1, e.g. JohnSmith |
$createwikiusername |
Wiki user name of topic revision 1, e.g. Main.JohnSmith |
$summary |
Topic summary, just the plain text, all formatting and line breaks removed; up to 162 characters |
$summary(50) |
Topic summary, up to 50 characters shown |
$summary(showvarnames) |
Topic summary, with %SOMEMACRO{...}% macros shown as SOMEMACRO{...} |
$summary(noheader) |
Topic summary, with leading ---+ headers removedNote: The tokens can be combined, for example $summary(100, showvarnames, noheader) |
$changes |
Summary of changes between latest rev and previous rev |
$changes(n) |
Summary of changes between latest rev and rev n |
$formname |
The name of the form attached to the topic; empty if none |
$formfield(name) |
The field value of a form field; for example, $formfield(TopicClassification) would get expanded to PublicFAQ . This applies only to topics that have a DataForm |
$formfield(name, 10) |
Form field value, "- " hyphenated each 10 characters |
$formfield(name, 20, -<br />) |
Form field value, hyphenated each 20 characters with separator "-<br />" |
$formfield(name, 30, ...) |
Form field value, shortended to 30 characters with "..." indication |
$pattern(reg-exp) |
A regular expression pattern to extract some text from a topic (does not search meta data; use $formfield instead). In case of a multiple="on" search, the pattern is applied to the line found in each search hit.• Specify a RegularExpression that covers the whole text (topic or line), which typically starts with .* , and must end in .* • Put text you want to keep in parenthesis, like $pattern(.*?(from here.*?to here).*) • Example: $pattern(.*?\*.*?Email\:\s*([^\n\r]+).*) extracts the e-mail address from a bullet of format * Email: ... • This example has non-greedy .*? patterns to scan for the first occurance of the Email bullet; use greedy .* patterns to scan for the last occurance • Limitation: Do not use .*) inside the pattern, e.g. $pattern(.*foo(.*)bar.*) does not work, but $pattern(.*foo(.*?)bar.*) does • Note: Make sure that the integrity of a web page is not compromised; for example, if you include an HTML table make sure to include everything including the table end tag |
$count(reg-exp) |
Count of number of times a regular expression pattern appears in the text of a topic (does not search meta data). Follows guidelines for use and limitations outlined above under $pattern(reg-exp) . Example: $count(.*?(---[+][+][+][+]) .*) counts the number of <H4> headers in a page. |
$ntopics |
Number of topics found in current web. This is the current topic count, not the total number of topics |
$nhits |
Number of hits if multiple="on" . Cumulative across all topics in current web. Identical to $ntopics unless multiple="on" |
$n or $n() |
New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar |
$nop or $nop() |
Is a "no operation". This token gets removed; useful for nested search |
$quot |
Double quote (" ) (\" also works) |
$percnt |
Percent sign (% ) |
$dollar |
Dollar sign ($ ) |
$lt |
Less than sign (< ) |
$gt |
Greater than sign (> ) |
$amp |
Ampersand (& ) |
%SEARCH{ "VarREMOTE" scope="topic" nosearch="on" nototal="on" header="| *Topic* | *Summary* |" format="| [[$topic]] | $summary |" footer="| *Topics found* | *$ntopics* |" }%
To get this:
Topic | Summary |
---|---|
VarREMOTEADDR | #VarREMOTEADDR REMOTE ADDR environment variable Syntax: % nop REMOTE ADDR% Expands to: Related: ENV, HTTP HOST, REMOTE PORT, REMOTE USER |
VarREMOTEPORT | #VarREMOTEPORT REMOTE PORT environment variable Syntax: % nop REMOTE PORT% Expands to: Related: ENV, HTTP HOST, REMOTE ADDR, REMOTE USER |
VarREMOTEUSER | #VarREMOTEUSER REMOTE USER environment variable Syntax: % nop REMOTE USER% Expands to: Related: ENV, HTTP HOST, REMOTE ADDR, REMOTE PORT, USERNAME ... |
Topics found | 3 |
TopicClassification
field, an OperatingSystem
field and an OsVersion
field we could write:
| *Topic:* | *OperatingSystem:* | *OsVersion:* |
%SEARCH{ "[T]opicClassification.*?value=\"[P]ublicFAQ\"" scope="text" type="regex" nosearch="on" nototal="on" format="| [[$topic]] | $formfield(OperatingSystem) | $formfield(OsVersion) |" }%
To get this:
Topic: | OperatingSystem: | OsVersion: |
---|---|---|
IncorrectDllVersionW32PTH10DLL | OsWin | 95/98 |
WinDoze95Crash | OsWin | 95 |
%SEARCH{ "\*Back to:\* FrequentlyAskedQuestions" scope="text" type="regex" nosearch="on" nototal="on" header="FAQs:" format=" * $pattern(.*?FAQ\:[\n\r]*([^\n\r]+).*) [[$topic][Answer...]]" footer="Found $ntopics FAQ topics" }%
To get this:
FAQs: %SEARCH{ "culture" format=" * $topic is referenced by: (list all references)" nosearch="on" nototal="on" }%
%SEARCH{ "(topic found in first search)" format="$topic" nosearch="on" nototal="on" separator=", " }%
$percnt
to escape the leading percent of the second search
\"
to escape the double quotes
$dollar
to escape the $
of $topic
$nop
to escape the }%
sequence
%SEARCH{ "culture" format=" * $topic is referenced by:$n * $percntSEARCH{ \"$topic\" format=\"$dollartopic\" nosearch=\"on\" nototal=\"on\" separator=\", \" }$nop%" nosearch="on" nototal="on" }%
To get this:
$dollarpercntSEARCH{
for level three, $dollardollarpercntSEARCH{
for level four, etc.
%SEARCH{ "\.*" scope="topic" type="regex" nosearch="on" nototal="on" order="modified" reverse="on" format="| [[$topic]] | $wikiusername | $date |" limit="7" }%
To get this:
WebTopicCreator | Main.ProjectContributor | 13 Sep 2009 - 01:30 |
WikiWikiClones | Main.ProjectContributor | 12 Sep 2009 - 02:11 |
WikiNotation | Main.ProjectContributor | 12 Sep 2009 - 02:10 |
WebTopicList | Main.ProjectContributor | 12 Sep 2009 - 02:10 |
WikiWord | Main.ProjectContributor | 12 Sep 2009 - 02:01 |
WebTemplateTopics | Main.ProjectContributor | 12 Sep 2009 - 01:56 |
WebsTable | Main.ProjectContributor | 12 Sep 2009 - 01:51 |
%CALC{$SET(weekold, $TIMEADD($TIME(), -7, day))}%
%SEARCH{ "." scope="topic" type="regex" nosearch="on" nototal="on" order="modified" reverse="on" format="$percntCALC{$IF($TIME($date) < $GET(weekold), <nop>, | [[$topic]] | $wikiusername | $date | $rev |)}$percnt" limit="100" }%
weekold
variable to the serialized date of exactly one week ago
$percnt
makes sure that the CALC gets executed once for each search hit
weekold
date
<nop>
is returned, which gets removed at the end of the rendering process
%URLPARAM{"..."}%
macro. Example:
Write this:
<form action="%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%"> Find Topics: <input type="text" name="q" size="32" value="%URLPARAM{"q" encode="entity"}%" /> <input type="submit" class="foswikiSubmit" value="Search" /> </form> Result: %SEARCH{ search="%URLPARAM{"q" encode="quote"}%" type="keyword" format=" * $web.$topic: %BR% $summary" nosearch="on" }%To get this: Result:
[Attach]
link at the bottom of the page. The Attach
screen lets you browse for a file, add a comment, and upload it. The uploaded file will show up in the file attachment table. *.php
files are renamed to *.php.txt
so that no one can place code that would be read in a .php file.
%ATTACHFILESIZELIMIT%
preference settings, currently set at 10000 kB. [Attach]
link. This is a convenient way to quickly "attach" files to a topic without uploading them one by one; although at the cost of losing audit trail and version control.
[Manage]
on the Attachment to be moved.
[Move]
. The attachment and its version history are moved. The original location is stored as topic meta data.
Trash
, topic TrashAttachment
.
[Attach]
a file, for example: Sample.txt
[Edit]
the topic you attached the file to and enter: %ATTACHURL%/Sample.txt
[Preview]
: the %ATTACHURL%/Sample.txt
text appears as: /wiki/pub/System/FileAttachment/Sample.txt, a link to the text file.
%PUBURLPATH%/%WEB%/OtherTopic/Sample.txt
(if it's within the same web)
%PUBURLPATH%/Otherweb/OtherTopic/Sample.txt
(if it's in a different web)
[Attach]
file: Sample.txt
[Edit]
topic and write text: %INCLUDE{"%ATTACHURL%/Sample.txt"}%
[Attach]
an image file, for example: Smile.gif
[Edit]
topic and write text: %ATTACHURL%/Smile.gif
[Preview]
: text appears as , an image.
h
means the attachment is hidden and not listed when viewing a topic in normal mode.
The file attachment table is normally displayed at the bottom of the page, or optionally, hidden and accessed when you click [Attach]
.
I | Attachment | Action | Size | Date | Who | Comment |
---|---|---|---|---|---|---|
txt | Sample.txt | manage | 0.1 K | 22 Jul 2000 - 19:37 | ProjectContributor | Just a sample |
gif | Smile.gif | manage | 0.1 K | 22 Jul 2000 - 19:38 | ProjectContributor | Smiley face |
[Manage]
link takes you to a new page that looks a bit like this (depending on what skin is selected).
Here, you have different options: [Update file]
. The filename of the original attachment will preserved; the filename of the local file you chose will not be used.
[Change comment and properties only]
. Note that the comment listed against the specific version will not change, however the comment displayed when viewing the topic does change.
Do not show attachment in table
checkbox, then click [Change comment and properties only]
.
YourForm
, ExpenseReportForm
, InfoCategoryForm
, RecordReviewForm
, whatever you need.
Name
, Type
, Size
, Values
, Tooltip message
, and Attributes
(see sample below).
Example:See structure of a form for full details of what types are available and what all the columns mean. You can also retrieve possible values for
| *Name* | *Type* | *Size* | *Values* | *Tooltip message* | *Attributes* |
| TopicClassification | select | 1 | NoDisclosure, PublicSupported, PublicFAQ | blah blah... | |
| OperatingSystem | checkbox | 3 | OsHPUX, OsLinux, OsSolaris, OsWin | blah blah... | |
| OsVersion | text | 16 | | blah blah... | |
Name Type Size Values Tooltip message Attributes TopicClassification select 1 NoDisclosure, PublicSupported, PublicFAQ blah blah... OperatingSystem checkbox 3 OsHPUX, OsLinux, OsSolaris, OsWin blah blah... OsVersion text 16 blah blah...
select
, checkbox
or radio
types from other topics:
Example:Field values can also be set using the result of expanding other macros. For example,
- In the WebForm topic, define the form:
Name Type Size Values Tooltip message Attributes TopicClassification select 1 blah blah... OperatingSystem checkbox 3 blah blah... OsVersion text 16 blah blah...
Leave theValues
field blank.
- Then in the TopicClassification topic, define the possible values:
| *Name* |
| NoDisclosure |
| Public Supported |
| Public FAQ |
Name NoDisclosure Public Supported Public FAQ
%SEARCH{"Office$" scope="topic" web="%USERSWEB%" nonoise="on" type="regex" format="$web.$topic" separator=", " }%
When used in the value field of the form definition, this will find all topic names in the Main web which end in "Office" and use them as the legal field values.
WEBFORMS
setting in WebPreferences is optional and defines a list of possible form definitions.
Example:
- Set WEBFORMS = BugForm, FeatureForm, Books.BookLoanForm
WEBFORMS
enabled, an extra button is added to the edit view. If the topic doesn't have a Form, an Add Form button appears at the end of the topic. If a Form is present, a Change button appears in the top row of the Form. The buttons open a screen that enables selection of a form specified in WEBFORMS
, or the No form option.
SEARCH
to define WEBFORMS
.
WebTopicEditTemplate
topic in a web, or a new topic that serves as an application specific template topic. Initial Form values can be set there.
formtemplate
parameter in the (edit or save) URL. Initial values can then be provided in the URLs or as form values: name
, ex: ?BugPriority=1
namevalue=1
, ex: ?ColorRed=1
. <form name="newtopic" action="%SCRIPTURLPATH{"edit"}%/%WEB%/"> <input type="hidden" name="formtemplate" value="MyForm" /> New topic name <input type="text" name="topic" size="40" /> <input type="submit" class="foswikiSubmit" value="Create" /> </form>
save
script instead of the edit
script in the form action. When you specify the save
script you must to use the "post" method. Example: <form name="newtopic" action="%SCRIPTURLPATH{"save"}%/%WEB%/" method="post"> ..... </form>
edit
and save
scripts understand many more parameters, see CommandAndCGIScripts#edit and CommandAndCGIScripts#save for details.
Name
, Type
, Size
, Values
, Tooltip message
, and Attributes
.
The Name
, Type
and Size
columns are required. Other columns are optional. The form must have a header row (e.g. | *Name* | *Type* | *Size* |
).
Name
is the name of the form field.
The Type
, Size
and Value
fields describe the legal values for this field, and how to display them. Type
checkbox
specifies one or more checkboxes. The Size
field specifies how many checkboxes will be displayed on each line. The Value
field should be a comma-separated list of item labels. Type
checkbox+buttons
will add Set and Clear buttons to the basic checkbox
type.
Type
radio
is like checkbox
except that radio buttons are mutually exclusive; only one can be selected.
Type
label
specifies read-only label text. The Value
field should contain the text of the label.
Type
select
specifies a select box. The Value
field should contain a comma-separated list of options for the box. The Size
field can specify a fixed size for the box (e.g. 1
, or a range e.g. 3..10
. If you specify a range, then the box will never be smaller than 3 items, never larger than 10, and will be 5 high if there are only 5 options. select
type: select+multi
turns multiselect on for the select, to allow Shift+Click and Ctrl+Click to select (or deselect) multiple items.
select+values
allows the definition of values that are different to the displayed text. For example: | Field 9 | select+values | 5 | One, Two=2, Three=III, Four | Various values formats |shows but the values or options
Two
and Three
are 2
and III
respectively.select+multi+values
Type
text
specifies a one-line text field. Size
specifies the text box width in number of characters. Value
is the initial (default) content when a new topic is created with this form definition.
Type
textarea
specifies a multi-line text box. The Size
field should specify columns x rows, e.g. 80x6
; default size is 40x5. As for text
, the Value
field specifies the initial text
Type
date
specifies a single-line text box and a button next to it; clicking on the button will bring up a calendar from which the user can select a date. The date can also be typed into the text box. Size
specifies the text box width in characters. As for text
, the Value
field specifies the initial text
Tooltip message
is a message that will be displayed when the cursor is hovered over the field in edit
view.
Attributes
specifies special attributes for the field. Multiple attributes can be entered, separated by spaces. H
indicates that this field should not be shown in view mode. However, the field is available for editing and storing information.
M
indicates that this field is mandatory. The topic cannot be saved unless a value is provided for this field. If the field is found empty during topic save, an error is raised and the user is redirected to an oops
page. Mandatory fields are indicated by an asterisks next to the field name.
| *Name* | *Type* | *Size* | | Name | text | 80 | | Date | date | 30 |Field Name Notes:
Aeroplane Manufacturers
is equivalent to AeroplaneManufacturers
.
label
field has no name, it will not be shown when the form is viewed, only when it is edited.
select
, checkbox
or radio
field, and want to get the values from another topic, you can use [[...]]
links. This notation can also be used when referencing another topic to obtain field values, but a name other than the topic name is required as the name of the field.
label
, text
, and textarea
fields the value may also contain commas. checkbox
fields cannot be initialized through the form definition.
|
character in the initial values field, you have to precede it with a backslash, thus: \|
.
<nop>
to prevent macros from being expanded.
| *Name* | *Type* | *Size* | | AeroplaneManufacturers | select | |the Foswiki will look for the topic AeroplaneManufacturers to get the possible values for the
select
.
The AeroplaneManufacturers topic must contain a table, where each row of the table describes a possible value. The table only requires one column, Name
. Other columns may be present, but are ignored.
For example:
| *Name* | | Routan | | Focke-Wulf | | De Havilland |Notes:
Values
column must be empty in the referring form definition.
checkbox
+multi
anywhere in the name
SubmitExpenseReport
topic where you can create new expense reports, a SubmitVacationRequest
topic, and so on. These can specify the required template topic with its associated form. Template topics has more.
text
fields when a topic is saved. If you need linefeeds in a field, make sure it is a textarea
.
Topic Name: | What it is: |
---|---|
WebCreateNewTopicTemplate | Page shown when you click on a Create New Topic link. It provides a form requesting the necessary information to create a new, nonexistent topic. |
TopicDoesNotExistViewTemplate | Alert page shown when you try to view a nonexistent topic and usually used as a prompt to help you create this new topic. For this reason, the form of the WebCreateNewTopicTemplate is included and therefore shown, too. |
WebTopicEditTemplate | Default text used in a new topic. |
<MyCustomNamed>Template | Whenever you create a topic ending in the word "Template", it is automatically added to the list of available template topics in the "Use Template" drop down field on the WebCreateNewTopic page. |
edit
script, the system locates a template topic according to the following search order: templatetopic
CGI parameter Macro: | Description: |
---|---|
%DATE% |
Signature format date. See VarDATE |
%GMTIME% |
Date/time. See VarGMTIME |
%GMTIME{...}% |
Formatted date/time. See VarGMTIME |
%NOP% |
A no-operation macro that gets removed. Useful to prevent a SEARCH from hitting an edit template topic; also useful to escape a variable, such as %URLPA%NOP%RAM{...}% escaping URLPARAM |
%STARTSECTION{type="templateonly"}% |
Text that gets removed when a new topic based on the template topic is created. See notes below. |
%SERVERTIME% |
Date/time. See VarSERVERTIME |
%SERVERTIME{...}% |
Formatted date/time. See VarSERVERTIME |
%USERNAME% |
Login name of user who is instantiating the new topic, e.g. guest |
%URLPARAM{"name"}% |
Value of a named URL parameter |
%WIKINAME% |
WikiName of user who is creating the new topic, e.g. WikiGuest |
%WIKIUSERNAME% |
User name of user who is creating the new topic, e.g. Main.WikiGuest |
%STARTSECTION{type="templateonly"}%
...
%ENDSECTION{type="templateonly"}%
markers are used to embed text that you do not want expanded when a new topic based on the template topic is created. For example, you might want to write in the template topic:
%STARTSECTION{type="templateonly"}% This template topic can only be changed by: * Set ALLOWTOPICCHANGE = Main.AdminGroup %ENDSECTION{type="templateonly"}%This will restrict who can edit the template topic, but will get removed when a new topic based on that template topic is created.
%NOP%
can be used to prevent expansion of macros that would otherwise be expanded during topic creation e.g. escape %SERVERTIME%
with %SER%NOP%VERTIME%
.
All other macros are unchanged, e.g. are carried over "as is" into the new topic.
formtemplate
parameter to the edit
script to specify the name of a form to attach.
See CommandAndCGIScripts for information about this, and all the other parameters to edit
.
AUTOINC<n>
to the topic name in the edit and save scripts, and it will be replaced with an auto-incremented number on topic save. <n>
is a number starting from 0, and may include leading zeros. Leading zeros are used to zero-pad numbers so that auto-incremented topic names can sort properly. Deleted topics are not re-used to ensure uniqueness of topic names. That is, the auto-incremented number is always higher than the existing ones, even if there are gaps in the number sequence.
Examples: BugAUTOINC0
- creates topic names Bug0
, Bug1
, Bug2
, ... (does not sort properly)
ItemAUTOINC0000
- creates topic names Item0000
, Item0001
, Item0002
, ... (sorts properly up to 9999)
DocIDAUTOINC10001
- start with DocID10001
, DocID10002
, ... (sorts properly up to 99999; auto-links)
[[%SCRIPTURLPATH{edit}%/%WEB%/BugIDAUTOINC00001?templatetopic=BugTemplate;topicparent=%TOPIC%;t=%SERVERTIME{"$day$hour$min$sec"}%][Create new item]]
templatetopic
specifies ExampleTopicTemplate as the template topic to use. Here is the HTML source of the form:
<form name="new" action="%SCRIPTURLPATH{edit}%/Sandbox/" method="post"> * New example topic: <input type="text" name="topic" value="ExampleTopicAUTOINC0001" size="30" /> <input type="hidden" name="templatetopic" value="ExampleTopicTemplate" /> <input type="hidden" name="topicparent" value="%TOPIC%" /> <input type="hidden" name="onlywikiname" value="on" /> <input type="hidden" name="onlynewtopic" value="on" /> <input type="submit" class="foswikiSubmit" value="Create" /> </form>Note: You can create a topic in one step, without going through the edit screen. To do that, specify the
save
script instead of the edit
script in the form action. When you specify the save script you must use the "post" method. Example:
<form name="new" action="%SCRIPTURLPATH{save}%/Sandbox/" method="post"> ... </form>See CommandAndCGIScripts#edit for details of the parameters that the
edit
script understands.
You can use the %WIKIUSERNAME%
and %DATE%
macros in your template topics to include the signature of the person creating a new topic. The macros are expanded into fixed text when a new topic is created. The standard signature is: -- %WIKIUSERNAME% - %DATE%
.tmpl
, though can also come from topic text in some limited circumstances. They are usually HTML with embedded template macros. The macros are expanded when we want to generate output, such as a user interface screen.
%TMPL:<key>%
and %TMPL:<key>{"attr"}%
.
%TMPL:INCLUDE{"file"}%
: Includes a template file. The file is found as described below.
%TMPL:DEF{"block"}%
: Define a block. All text between this and the next %TMPL:END%
directive is removed and saved for later use with %TMPL:P%
.
%TMPL:END%
: Ends a block definition.
%TMPL:P{"var"}%
: Includes a previously defined block.
%{...}%
: is a comment.
foswiki.tmpl
master skin template, like foswiki.print.tmpl
, that redefines the header and footer.
%TMPL:P
.
%TMPL:DEF{"x"}% x%P%z%TMPL:END%
then %TMPL:P{"x" P="y"}%
will expand to xyz
.
Note that parameters can simply be ignored; for example, %TMPL:P{"x"}%
will expand to x%P%z.
Any alphanumeric characters can be used in parameter names.
You are highly recommended to use parameter names that cannot be confused with macros.
Note that three parameter names, context
, then
and else
are reserved.
They are used to support a limited form of "if" condition that you can use to select which of two TMPL:DEFs to use, based on a context identifier:
%TMPL:DEF{"link_inactive"}%<input type="button" disabled value="Link>%TMPL:END% %TMPL:DEF{"link_active"}%<input type="button" onclick="link()" value="Link" />%TMPL:END% %TMPL:P{context="inactive" then="inactive_link" else="active_link"}% for %CONTEXT%When the "inactive" context is set, then this will expand the "link_inactive" TMPL:DEF; otherwise it will expand the "link_active" TMPL:DEF. See IfStatements for details of supported context identifiers.
templates
directory.
As an example, templates/view.tmpl
is the default skin template file for the bin/view
script.
You can save templates in other directories as long as they are listed in the {TemplatePath}
configuration setting.
The {TemplatePath}
is defined in the Miscellaneous section of the configure page.
You can also save skin templates in user topics (IF there is no possible template match in the templates
directory).
The {TemplatePath}
configuration setting defines which topics will be accepted as templates.
Skin templates that are included with an explicit '.tmpl'
extension are looked for only in the templates/
directory.
For instance %TMPL:INCLUDE{"example.tmpl"}%
will only return templates/example.tmpl
, regardless of {TemplatePath}
and SKIN settings.
The out-of-the-box setting of {TemplatePath}
supports the following search order to determine which template file or topic to use for a particular script or %TMPL:INCLUDE{"script"}%
statement.
The skin path is set as described in Skins.
view
, edit
View
dragon
, pattern
. All skins are checked at each stage, in the order they appear in the skin path.
Dragon
example
template file will be searched for in the following places, when the current web is Thisweb
and the skin path is print,pattern
:
templates/Thisweb/example.print.tmpl
deprecated; don't rely on it
templates/Thisweb/example.pattern.tmpl
deprecated; don't rely on it
templates/example.print.tmpl
templates/example.pattern.tmpl
templates/Thisweb/example.tmpl
deprecated; don't rely on it
templates/example.tmpl
Thisweb.PrintSkinExampleTemplate
Thisweb.PatternSkinExampleTemplate
Thisweb.ExampleTemplate
System.PrintSkinExampleTemplate
System.PatternSkinExampleTemplate
System.ExampleTemplate
view
and edit
scripts, for example when a topic-specific template is required. Two preference settings can be used to override the skin templates used: VIEW_TEMPLATE
sets the template to be used for viewing a topic.
EDIT_TEMPLATE
sets the template for editing a topic.
view
and edit
respectively. The template search order is as specified above.
%TMPL:INCLUDE{"foswiki"}%
, the templating system will include the next SKIN in the skin path.
For example, to create a customisation of pattern skin, where you only want to over-ride the breadcrumbs for the view script, you can create only a view.yourlocal.tmpl:
%TMPL:INCLUDE{"view"}% %TMPL:DEF{"breadcrumb"}% We don't want any crumbs %TMPL:END%and then set SKIN=yourlocal,pattern The default
{TemplatePath}
will not give you the desired result if you put these statements in the topic Thisweb.YourlocalSkinViewTemplate
. The default {TemplatePath}
will resolve the request to the template/view.pattern.tmpl
, before it gets to the Thisweb.YourlocalSkinViewTemplate
resolution. You can make it work by prefixing the {TemplatePath}
with: $web.YourlocalSkin$nameTemplate
.
foswiki.tmpl
is the default master template. It defines the following sections.
Template directive: | Defines: |
---|---|
%TMPL:DEF{"sep"}% |
"|" separator |
%TMPL:DEF{"htmldoctype"}% |
Start of all HTML pages |
%TMPL:DEF{"standardheader"}% |
Standard header (ex: view, index, search) |
%TMPL:DEF{"simpleheader"}% |
Simple header with reduced links (ex: edit, attach, oops) |
%TMPL:DEF{"standardfooter"}% |
Footer, excluding revision and copyright parts |
templates
directory and are named according to the skin: <scriptname>.<skin>.tmpl
. Skin files may also be defined in Foswiki topics - see SkinTemplates for details.
To start creating a new skin, copy the default skin templates (like view.tmpl
), or copy an existing skin to use as a base for your own skin. You should only need to copy the files you intend to customise, as Foswiki can be configured to fall back to another skin if a template is not defined in your skin. A custom skin can be as small as one file! Name your files as described above (for example view.myskin.tmpl
).
If you use PatternSkin as your starting point, and you want to modify the layout, colors or even the templates to suit your own needs, have a look first at the topics PatternSkinCustomization and PatternSkinCssCookbook. These topics also provide practical instructions how to create custom skin template files.
Note: Don't call your skin text
or rss
as these two skin names have reserved meanings, see below at hard-coded meanings.
The following template files are used for Foswiki screens, and are referenced in the Foswiki core code. If a skin doesn't define its own version of a template file, then Foswiki will fall back to the next skin in the skin path, or finally, to the default version of the template file.
(Certain template files are expected to provide certain TMPL:DEFs - these are listed in sub-bullets) addform
- used to select a new form for a topic
attachagain
- used when refreshing an existing attachment
attachnew
- used when attaching a new file to a topic
attachtables
- defines the format of attachments at the bottom of the standard topic view ATTACH:files:footer
, ATTACH:files:header
, ATTACH:files:row
, ATTACH:versions:footer
, ATTACH:versions:header
, ATTACH:versions:row
changeform
- used to change the form in a topic
changes
- used by the changes
script
edit
- used for the edit screen
form
formtables
- used to defined the format of forms FORM:display:footer
, FORM:display:header
, FORM:display:row
login
- used for loggin in when using the TemplateLoginManager LOG_IN
, LOG_IN_BANNER
, LOG_OUT
, LOGGED_IN_BANNER
, NEW_USER_NOTE
, UNRECOGNISED_USER
moveattachment
- used when moving an attachment
oopsaccessdenied
- used to format Access Denied messages no_such_topic
, no_such_web
, only_group
, topic_access
oopsattention
- used to format Attention messages already_exists
, bad_email
, bad_ver_code
, bad_wikiname
, base_web_missing
, confirm
, created_web
, delete_err
, invalid_web_color
, invalid_web_name
, in_a_group
, mandatory_field
, merge_notice
, missing_action
, missing_fields
, move_err
, missing_action
, no_form_def
, no_users_to_reset
, not_a_user
, oversized_upload
, password_changed
, password_mismatch
, problem_adding
, remove_user_done
, rename_err
, rename_not_wikiword
, rename_topic_exists
, rename_web_err
, rename_web_exists
, rename_web_prerequisites
, reset_bad
, reset_ok
, save_error
, send_mail_error
, thanks
, topic_exists
, unrecognized_action
, upload_name_changed
, web_creation_error
, web_exists
, web_missing
, wrong_password
, zero_size_upload
oopschangelanguage
- used to prompt for a new language when internationalisation is enabled
oopsgeneric
- a basic dialog for user information; provides "ok" button only
oopslanguagechanged
- used to confirm a new language when internationalisation is enabled
oopsleaseconflict
- used to format lease Conflict messages lease_active
, lease_old
preview
- used for previewing edited topics before saving
rdiff
- used for viewing topic differences
registernotify
- used by the user registration system
registernotifyadmin
- used by the user registration system
rename
- used when renaming a topic
renameconfirm
- used when renaming a topic
renamedelete
- used when renaming a topic
renameweb
- used when renaming a web
renamewebconfirm
- used when renaming a web
renamewebdelete
- used when renaming a web
searchbookview
- used to format inline search results in book view
searchformat
- used to format inline search results
search
- used by the search
CGI script
settings
view
- used by the view
CGI script
viewprint
- used to create the printable view
foswiki.tmpl
is a master template conventionally used by other templates, but not used directly by code.
Note: Make sure templates do not end with a newline. Any newline will expand to an empty <p />
in the generated html. It will produce invalid html, and may break the page layout.
%TMPL:INCLUDE{"foswiki"}%
, the templating system will include the next SKIN in the skin path.
For example, to create a customisation of pattern skin, where you only want to remove the edit & WYSIWYG buttons from view page, you create only a view.yourlocal.tmpl
:
%TMPL:INCLUDE{"view"}% %TMPL:DEF{"edit_topic_link"}%%TMPL:END% %TMPL:DEF{"edit_wysiwyg_link"}%%TMPL:END%and then set
SKIN=yourlocal,pattern
Macro: | Expanded to: |
---|---|
%WEBLOGONAME% |
Filename of web logo |
%WEBLOGOIMG% |
Image URL of web logo |
%WEBLOGOURL% |
Link of web logo |
%WEBLOGOALT% |
Alt text of web logo |
%WIKILOGOURL% |
Link of page logo |
%WIKILOGOIMG% |
Image URL of page logo |
%WIKILOGOALT% |
Alt text of page logo |
%WEBBGCOLOR% |
Web-specific background color, defined in the WebPreferences |
%WIKITOOLNAME% |
The name of your Foswiki site |
%SCRIPTURL% |
The script URL of Foswiki |
%SCRIPTURLPATH% |
The script URL path |
%SCRIPTSUFFIX% |
The script suffix, ex: .pl , .cgi |
%WEB% |
The name of the current web. |
%TOPIC% |
The name of the current topic. |
%WEBTOPICLIST% |
Common links of current web, defined in the WebPreferences. It includes a Go box |
%TEXT% |
The topic text, e.g. the content that can be edited |
%META{"form"}% |
DataForm, if any |
%META{"attachments"}% |
FileAttachment table |
%META{"parent"}% |
The topic parent |
%EDITTOPIC% |
Edit link |
%REVTITLE% |
The revision title, if any, ex: (r1.6) |
%REVINFO% |
Revision info, ex: r1.6 - 24 Dec 2002 - 08:12 GMT - Main.WikiGuest |
%WEBCOPYRIGHT% |
Copyright notice, defined in the WebPreferences |
%BROADCASTMESSAGE% |
Broadcast message at the beginning of your view template, can be used to alert users of scheduled downtimes; can be set in Main.SitePreferences |
css.pattern.tmpl
.
<style type='text/css' media='all'>@import url('%PUBURLPATH%/%SYSTEMWEB%/MySkin/mystyle.css');</style>
http://www.google.com/
to jump to an external web site. The feature is handy if you build a skin that has a select box of frequently used links, like Intranet home, employee database, sales database and such. A little JavaScript gets into action on the onchange
method of the select tag to fill the selected URL into the "Go" box field, then submits the form.
Here is an example form that has a select box and the "Go" box for illustration purposes. You need to have JavaScript enabled for this to work:
Note: Redirect to a URL only works if it is enabled in configure
(Miscellaneous, {AllowRedirectUrl}
).
FLASHNOTE
. For example:
attachtables.tmpl
template using the %TMPL:DEF
directive syntax described in SkinTemplates. These macros are:
Macro | Description |
---|---|
ATTACH:files:header |
Standard title bar |
ATTACH:files:row |
Standard row |
ATTACH:files:footer |
Footer for all screens |
ATTACH:files:header:A |
Title bar for upload screens, with attributes column |
ATTACH:files:row:A |
Row for upload screen |
ATTACH:files:footer:A |
Footer for all screens |
Macro | Description |
---|---|
ATTACH:versions:header |
Header for versions table on upload screen |
ATTACH:versions:row |
Row format for versions table on upload screen |
ATTACH:versions:footer |
Footer for versions table on upload screen |
ATTACH:row
macros are expanded for each file in the attachment table, using the following special tags:
Tag | Description |
---|---|
%A_URL% |
viewfile URL that will recover the file |
%A_REV% |
Revision of this file |
%A_ICON% |
A file icon suitable for representing the attachment content |
%A_FILE% |
The name of the file. To get the 'pub' url of the file, use %PUBURL%/%WEB%/%TOPIC%/%A_FILE% |
%A_SIZE% |
The size of the file |
%A_DATE% |
The date the file was uploaded |
%A_USER% |
The user who uploaded it |
%A_COMMENT% |
The comment they put in when uploading it |
%A_ATTRS% |
The attributes of the file as seen on the upload screen e.g "h" for a hidden file |
<a href="http://foswiki.org/"><img src="%PUBURL%/%SYSTEMWEB%/ProjectLogos/foswiki-poweredby.gif" alt="This site is powered by Foswiki" width="80" height="15" title="This site is powered by Forwiki" border="0" /></a>
The standard Foswiki skins show the logo in the %WEBCOPYRIGHT%
.
view.
skin.tmpl
, where skin is the name of the skin e.g. pattern
. If no template is found, then the fallback is to use view.tmpl
. Each skin on the path is searched for in turn. For example, if you have set the skin path to local,pattern
then view.local.tmpl
will be searched for first, then view.pattern.tmpl
and finally view.tmpl
.
The basic skin is defined by a SKIN
setting:
Set SKIN = catskin, bearskin
?skin=catskin,bearskin
:
Setting SKIN
(or the ?skin
parameter in the URL) replaces the existing skin path setting, for the current page only. You can also extend the existing skin path as well, using covers.
Set COVER = ruskin
ruskin, catskin, bearskin
). There is also an equivalent cover
URL parameter. The difference between setting SKIN
vs. COVER
is that if the chosen template is not found (e.g., for included templates), SKIN
will fall back onto the next skin in line, or the default skin, if only one skin was present, while COVER
will always fall back onto the current skin.
An example would be invoking the printable mode, which is achieved by applying ?cover=print
. The view.print.tmpl
simply invokes the viewprint
template for the current skin which then can appropriately include all other used templates for the current skin. Where the printable mode be applied by using SKIN
, all skins would have the same printable appearance.
The full skin path is built up as follows: SKIN
setting (or ?skin
if it is set), then COVER
setting is added, then ?cover
.
text
skin is reserved for Foswiki internal use.
Skin names starting with rss
also have a special meaning; if one or more of the skins in the skin path starts with 'rss' then 8-bit characters will be encoded as XML entities in the output, and the content-type
header will be forced to text/xml
.
META:
tags
META:
tags.
META:
data includes program-generated info like FileAttachment, topic movement data and user-defined information from DataForms.
%META:<type>{key1="value1" key2="value2" ...}%
name
, this appears first for easier searching (note the order of the data themselves is defined).
Example of Format%META:TOPICINFO{version="1.6" date="976762663" author="LastEditorWikiName" format="1.0"}% text of the topic %META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="TopicMoverWikiName" date="976762680"}% %META:TOPICPARENT{name="NavigationByTopicContext"}% %META:FILEATTACHMENT{name="Sample.txt" version="1.3" ... }% %META:FILEATTACHMENT{name="Smile.gif" version="1.1" ... }% %META:FORM{name="WebFormTemplate"}% %META:FIELD{name="OperatingSystem" value="OsWin"}% %META:FIELD{name="TopicClassification" value="PublicFAQ"}%
Key | Comment |
---|---|
version | Same as SVN version |
date | integer, unix time, seconds since start 1970 |
author | last to change topic, is the REMOTE_USER |
format | Format of this topic, will be used for automatic format conversion |
%META:TOPICMOVED{from="Codev.OldName" to="Codev.NewName" by="talintj" date="976762680"}%
Key | Comment |
---|---|
from | Full name, i.e., web.topic |
to | Full name, i.e., web.topic |
by | Who did it, is the REMOTE_USER, not WikiName |
date | integer, unix time, seconds since start 1970 |
Key | Comment |
---|---|
name | The topic from which this was created, typically when clicking on a ? questionmark link, or by filling out a form. Normally just TopicName , but it can be a full Web.TopicName format if the parent is in a different Web. |
Key | Comment |
---|---|
name | Name of file, no path. Must be unique within topic |
version | Same as SVN revision |
path | Full path file was loaded from |
size | In bytes |
date | integer, unix time, seconds since start 1970 |
user | the REMOTE_USER, not WikiName |
comment | As supplied when file uploaded |
attr | h if hidden, optional |
Key | Comment |
---|---|
movedfrom | full topic name - web.topic |
movedby | the REMOTE_USER, not WikiName |
movedto | full topic name - web.topic |
moveddate | integer, unix time, seconds since start 1970 |
Key | Comment |
---|---|
name | A topic name - the topic represents one of the DataForms. Can optionally include the web name (i.e., web.topic), but doesn't normally |
Key | Name |
---|---|
name | Ties to entry in DataForms template, is title with all bar alphanumerics and . removed |
title | Full text from DataForms template |
value | Value user has supplied via form |
diff
function output appears in a logical order
META:TOPICINFO
META:TOPICPARENT
(optional)
META:TOPICMOVED
(optional)
META:FILEATTACHMENT
(0 or more entries)
META:FORM
(optional)
META:FIELD
(0 or more entries; FORM required)
[View raw text]
link can be clicked to show the text of a topic (i.e., as seen when editing). This is done by adding raw=on
to URL. raw=debug
shows the meta data as well as the topic data, ex: debug view for this topic
view
, preview
and edit
scripts.
You can render form fields in topic text by using the FORMFIELD macro. Example:%FORMFIELD{"TopicClassification"}%
Macro usage: | Comment: |
---|---|
%META{"form"}% |
Show form data, see DataForms. |
%META{"formfield"}% |
Show form field value. Parameter: name="field_name" . Example:%META{ "formfield" name="TopicClassification" }% |
%META{"attachments"}% |
Show attachments, except for hidden ones. Options: all="on" : Show all attachments, including hidden ones. |
%META{"moved"}% |
Details of any topic moves. |
%META{"parent"}% |
Show topic parent. Options: dontrecurse="on" : By default recurses up tree, at some cost. nowebhome="on" : Suppress WebHome. prefix="..." : Prefix for parents, only if there are parents, default "" . suffix="..." : Suffix, only appears if there are parents, default "" . separator="..." : Separator between parents, default is " > " . |
Behaviour
Javascript event library to create javascript based interactions that degrade well when javascript is not available - version 5016 (2009-09-20) Plugin | Errors |
---|---|
System.TWikiCompatibilityPlugin | none |
System.SpreadSheetPlugin | none |
System.CommentPlugin | none |
System.EditTablePlugin | none |
System.InterwikiPlugin | none |
System.PreferencesPlugin | none |
System.SlideShowPlugin | none |
System.SmiliesPlugin | none |
System.TablePlugin | none |
System.TinyMCEPlugin | none |
System.TwistyPlugin | none |
System.WysiwygPlugin | none |
Handler | Plugins |
---|---|
afterEditHandler | WysiwygPlugin |
beforeCommonTagsHandler | EditTablePlugin PreferencesPlugin WysiwygPlugin |
beforeEditHandler | TinyMCEPlugin WysiwygPlugin |
beforeMergeHandler | WysiwygPlugin |
beforeSaveHandler | CommentPlugin WysiwygPlugin |
commonTagsHandler | SpreadSheetPlugin CommentPlugin EditTablePlugin SlideShowPlugin SmiliesPlugin |
earlyInitPlugin | TWikiCompatibilityPlugin |
initPlugin | TWikiCompatibilityPlugin SpreadSheetPlugin CommentPlugin EditTablePlugin InterwikiPlugin PreferencesPlugin SlideShowPlugin SmiliesPlugin TablePlugin TinyMCEPlugin TwistyPlugin WysiwygPlugin |
modifyHeaderHandler | WysiwygPlugin |
postRenderingHandler | EditTablePlugin PreferencesPlugin WysiwygPlugin |
preRenderingHandler | InterwikiPlugin SmiliesPlugin TablePlugin |
startRenderingHandler | WysiwygPlugin This handler is deprecated - please check for updated versions of the plugins that use it! |
%FAILEDPLUGINS%
macro can be used to debug failures. You may also want to check your webserver error log and the various Foswiki log files.
DISABLEDPLUGINS
to be a comma-separated list of names of plugins to disable. Define it in Main.SitePreferences to disable those plugins everywhere, in the WebPreferences topic to disable them in an individual web, or in a topic to disable them in that topic. For example,
* Set DISABLEDPLUGINS = SpreadSheetPlugin, EditTablePlugin
%ACTIVATEDPLUGINS%
- shows the activated plugins
%PLUGINVERSION%
- shows the plugins API version
%FAILEDPLUGINS%
- shows what plugins failed, and why
{PluginsOrder}
in the plugins section of configure.
configure
settings.
configure
settings are accessible though the configure interface.
Plugin preference settings are defined in the plugin topic and can be overloaded. The SHORTDESCRIPTION setting is always present, it is needed for the automation in the extensions repository. Example preference settings defined in the TablePlugin topic:
Set SHORTDESCRIPTION = Control attributes of tables and sorting of table columns
%<pluginname>_<var>%
, such as %TABLEPLUGIN_SHORTDESCRIPTION%
. They can also be redefined with the %<pluginname>_<var>%
setting at a lower level in the Main.SitePreferences or at the web level. For an easier upgrade it is recommended to customize plugin preference settings in Main.SitePreferences only.
%FAILEDPLUGINS%
macro can be used to debug failures. You may also want to check your webserver error log and the various Foswiki log files.
DISABLEDPLUGINS
to be a comma-separated list of names of plugins to disable. Define it in Main.SitePreferences to disable those plugins everywhere, in the WebPreferences topic to disable them in an individual web, or in a topic to disable them in that topic. For example,
* Set DISABLEDPLUGINS = SpreadSheetPlugin, EditTablePlugin
lib/Foswiki/Plugins/EmptyPlugin.pm
).
Foswiki::Func
- bridge to core functions. This is the package you will use most.
Foswiki::Meta
- topic meta-data
Foswiki::OopsException
- special exception for invoking the 'oops' script
Foswiki::AccessControlException
- access control exception
Foswiki::Attrs
- parser and storage object for macro parameters
Foswiki::Time
- time parsing and formatting
Foswiki::Sandbox
- safe server-side program execution, used for calling external programs.
Foswiki::Iterator
specification Foswiki::ListIterator
- utility class for iterator objects that iterate over list contents
Foswiki::LineIterator
- utility class for iterator objects that iterate over lines in a block of text
Foswiki::AggregateIterator
- utility class for iterator objects that aggregate other iterators into a single iteration
$Foswiki::Plugins::VERSION
- plugin handler API version number
$Foswiki::Plugins::SESSION
- reference to Foswiki
singleton object
$Foswiki::cfg
- reference to configuration hash
$Foswiki::regex
- see Standard Regular Expressions, below
Foswiki
singleton object having been created before the APIs can be used.
This will only be a problem if you are writing an extension that doesn't
use the standard initialisation sequence.
$Foswiki::regex
hash. these regular expressions are precompiled in an
I18N-compatible manner. The
following are guaranteed to be present. Others may exist, but their use
is unsupported and they may be removed in future Foswiki versions.
In the table below, the expression marked type 'String' are intended for
use within character classes (i.e. for use within square brackets inside
a regular expression), for example:
my $isCapitalizedWord = ( $s =~ /[$Foswiki::regex{upperAlpha}][$Foswiki::regex{mixedAlpha}]+/ );Those expressions marked type 'RE' are precompiled regular expressions that can be used outside square brackets. For example:
my $isWebName = ( $s =~ m/$Foswiki::regex{webNameRegex}/ );
Name | Matches | Type |
---|---|---|
upperAlpha | Upper case characters | String |
upperAlphaNum | Upper case characters and digits | String |
lowerAlpha | Lower case characters | String |
lowerAlphaNum | Lower case characters and digits | String |
numeric | Digits | String |
mixedAlpha | Alphabetic characters | String |
mixedAlphaNum | Alphanumeric characters | String |
wikiWordRegex | WikiWords | RE |
webNameRegex | User web names | RE |
topicNameRegex | Topic names | RE |
anchorRegex | #AnchorNames | RE |
abbrevRegex | Abbreviations/Acronyms e.g. GOV, IRS | RE |
emailAddrRegex | email@address.com | RE |
tagNameRegex | Standard macro names e.g. %THIS_BIT% (THIS_BIT only) | RE |
lib/Foswiki/Plugins/MyFirstPlugin.pm
MyFirstPlugin.txt
lib/Foswiki/Plugins/EmptyPlugin.pm
to <name>Plugin.pm
. The EmptyPlugin does nothing, but it contains all the information you need to create you own custom plugin.
OUTLINE: Doc Topic Contents
Check the plugins web on Foswiki.org for the latest plugin doc topic template. Here's a quick overview of what's covered: Syntax Rules: <Describe any special text formatting that will be rendered.>" Example: <Include an example of the plugin in action. Possibly include a static HTML version of the example to compare if the installation was a success!>" Plugin Settings: <Description and settings for custom plugin settings, and those required by Foswiki.>"Plugin Installation Instructions: <Step-by-step set-up guide, user help, whatever it takes to install and run, goes here.>" Plugin Info: <Version, credits, history, requirements - entered in a form, displayed as a table. Both are automatically generated when you create or edit a page in the Foswiki:Extensions web.>
- Plugins Preferences <If user settings are needed, link to preference settings and explain the role of the plugin name prefix
Plugin
, ex: MyFirstPlugin.pm
, and a documentation page with the same name(MyFirstPlugin.txt
).
lib/Foswiki/Plugins/MyFirstPlugin.pm
data/Foswiki/MyFirstPlugin.txt
pub/Foswiki/MyFirstPlugin/uparrow.gif
[a required graphic]
MyFirstPlugin.zip
) and add the entire directory structure from Step 1. The archive should look like this: lib/Foswiki/Plugins/MyFirstPlugin.pm
data/Foswiki/MyFirstPlugin.txt
pub/Foswiki/MyFirstPlugin/uparrow.gif
MyFirstPlugin.zip
eval
block like this:eval { require IPC::Run }
return "<font color=\"red\">SamplePlugin: Can't load required modules ($@)</font>" if $@;
lib/Foswiki/Plugins/BathPlugin/
.
$NO_PREFS_IN_TOPIC
if you possibly can, as that will stop Foswiki from reading the plugin topic for every page. Use Config.spec instead.
%Foswiki::cfg
hash for configuration options. Don't ask installers to edit topics in the System web. configure
describes the steps
eval
, and if you must use it make sure you sanitise parameters
Foswiki::Func::checkAccessPermission
to check the access rights of the current user.
Foswiki::Func::getWorkArea()
function, which gives you a persistent directory where you can store data files. By default they will not be web accessible. The directory is guaranteed to exist, and to be writable by the webserver user. For convenience, Foswiki::Func::storeFile()
and Foswiki::Func::readFile()
are provided to persistently store and retrieve simple data in this area.
Foswiki::Func::saveAttachment()
function to store the data.
Recommendation for file name: _GaugePlugin_img123.gif
Foswiki::Func::saveAttachment()
function to store the data in this topic.
configure
configure
rather than trying to use preference settings. These extensions use Config.spec
files to publish their configuration requirements.
Config.spec
files are read during configuration. Once a Config.spec
has defined a configuration item, it is available for edit through the standard configure
interface. Config.spec
files are stored in the 'plugin directory' e.g. lib/Foswiki/Plugins/BathPlugin/Config.spec
.
Config.spec
file Config.spec
file for a plugin starts with the plugin announcing what it is:
# ---+ BathPlugin # This plugin senses the level of water in your bath, and ensures the plug # is not removed while the water is still warm.This is followed by one or more configuration items. Each configuration item has a type, a description and a default. For example:
# **SELECT Plastic,Rubber,Metal** # Select the plug type $Foswiki::cfg{BathPlugin}{PlugType} = 'Plastic'; # **NUMBER** # Enter the chain length in cm $Foswiki::cfg{BathPlugin}{ChainLength} = '30'; # **BOOLEAN EXPERT** # Turn this option off to disable the water temperature alarm $Foswiki::cfg{BathPlugin}{TempSensorEnabled} = '1';The type (e.g.
**SELECT**
) tells configure
to how to prompt for the value. It also tells configure how to do some basic checking on the value you actually enter. All the comments between the type and the configuration item are taken as part of the description. The configuration item itself defines the default value for the configuration item. The above spec defines the configuration items $Foswiki::cfg{BathPlugin}{PlugType}
, $Foswiki::cfg{BathPlugin}{ChainLength}
, and $Foswiki::cfg{BathPlugin}{TempSensorEnabled}
for use in your plugin. For example,
if( $Foswiki::cfg{BathPlugin}{TempSensorEnabled} && $curTemperature > 50 ) { die "The bathwater is too hot for comfort"; }The
Config.spec
file is read by configure, and configure
then writes LocalSite.cfg
with the values chosen by the local site admin.
A range of types are available for use in Config.spec
files:
BOOLEAN |
A true/false value, represented as a checkbox |
COMMAND length |
A shell command |
LANGUAGE |
A language (selected from {LocalesDir} |
NUMBER |
A number |
OCTAL |
An octal number |
PASSWORD length |
A password (input is hidden) |
PATH length |
A file path |
PERL |
A simplified perl data structure, consisting of arrays, hashes and scalar values |
REGEX length |
A perl regular expression |
SELECT choices |
Pick one of a range of choices |
SELECTCLASS package-specifier |
Select a perl package (class) e.g. SELECTCLASS Foswiki::Plugins::BathPlugin::*Plug lets the user select between all packages with names ending in Plug , Foswiki::Plugins::BathPlugin::RubberPlug , Foswiki::Plugins::BathPlugin::BrassPlug etc. |
STRING length |
A string |
URL length |
A url |
URLPATH length |
A relative URL path |
EXPERT |
means this an expert option |
M |
means the setting is mandatory (may not be empty) |
H |
means the option is not visible in configure |
lib/Foswiki.spec
for many more examples.
Config.spec
files are also used for other (non-plugin) extensions. in this case they are stored under the Contrib
directory instead of the Plugins
directory.
if( $Foswiki::Plugins::VERSION >= 1.1 ) { @webs = Foswiki::Func::getListOfWebs( 'user,public' ); } else { @webs = Foswiki::Func::getPublicWebList( ); }
Foswiki::Plugins
version in which the handler was first deprecated. For example, if we need to define the endRenderingHandler
for compatibility with Foswiki::Plugins
versions before 1.1, we would add this to the plugin:
package Foswiki::Plugins::SinkPlugin; use vars qw( %FoswikiCompatibility ); $FoswikiCompatibility{endRenderingHandler} = 1.1;If the currently-running Foswiki version is 1.1 or later, then the handler will not be called and the warning will not be issued. Foswiki with versions of
Foswiki::Plugins
before 1.1 will still call the handler as required.
bin
and tools
directories. This topic describes the interfaces to some of those scripts. All scripts in the bin
directory can be called from the CGI (Common Gateway Interface) environment or from the command line. The scripts in the tools
directory can only be called from the command line.
bin
directory.
guest
).
bin
directory on the perl path to run the scripts from the command line. To avoid issues with file permissions, run the scripts as the web server user such as nobody
or www
.
Parameters are passed on the command line using '-name' - for example,
$ cd /usr/local/foswiki/bin $ save -topic MyWeb.MyTopic -user admin -action save -text "New text of the topic"All parameters require a value, even if that is the empty string.
Parameter | Description | Default |
---|---|---|
topic |
If this is set to a URL, Foswiki will immediately redirect to that URL. Otherwise it overrides the URL and is taken as the topic name (you can pass Web.TopicName) | |
user |
Command-line only; set the name of the user performing the action. Note: this usage is inherently insecure, as it bypasses webserver login constraints. For this reason only authorised users should be allowed to execute scripts from the command line. | |
skin |
Overrides the default skin path (see Skins) | |
cover |
Specifies temporary skin path to prepend to the skin path for this script only (see Skins) | |
t |
While the t parameter is not actively used by any scripts, it is used throughout the links like edit to ensure that the browser doesn't cache the reply. |
generally set to current time |
logout |
requests the LoginManager to log the current user out. (happens at the begining of the request so will terminate any other operation requested) |
attach
upload
. This script is part of the transactions sequence executed when a file is uploaded from the browser. it just generates the "new attachment" page for a topic.
Parameter | Description | Default |
---|---|---|
filename |
Name of existing attachment (if provided, this is a "manage attachment" action) | none (in which case this is a "new attachment" action) |
changes
changes
script can receive one parameter:
Parameter | Description | Default |
---|---|---|
minor |
If 0, show only major changes. If 1, show all the changes (both minor and major) | 0 |
%SEARCH%
, while this script reads the changes
file in each web, making it much faster.
NOTE: The result from changes
script and the topic WebChanges can be different, if the changes
file is deleted from a web. In particular, in new installations the changes
script will return no results while the WebChanges topic will.
configure
configure
is the browser script used for inspection of, and changes to, the site configuration. None of the parameters to this script are useable for any purpose except configure
. See configure.
edit
edit
script understands the following parameters, typically supplied by HTML input fields:
Parameter | Description | Default |
---|---|---|
action |
Optional. Use the editaction template instead of the standard edit. If action=text, then hide the form. If action=form hide the normal text area and only edit the form. You can change the Edit/Edit Raw buttons to always append the action parameter in skins like Pattern and Classic by setting the topic or preference setting EDITACTION to the value text or form . To edit the topic once the EDITACTION is defined as form simply remove the action=form from the browser URL of the edit script and reload the edit window |
|
onlynewtopic |
If set, error if topic already exists | |
onlywikiname |
If set, error if topic name is not a WikiWord | |
templatetopic |
The name of the template topic, copied to get the initial content (new topic only) | |
text |
Initial text for the topic | |
topicparent |
The parent topic | |
formtemplate |
Name of the form to instantiate in the topic. Overrides the form set in the templatetopic if defined. (will remove the form is set to 'none') |
|
contenttype |
Optional parameter that defines the application type to write into the CGI header. Defaults to text/html . May be used to invoke alternative client applications |
|
anyname |
Any parameter can passed to the new topic; if the template topic contains %URLPARAM{"anyname"}% , it will be replaced by its value |
|
breaklock |
If set, any lease conflicts will be ignored, and the edit will proceed even if someone is already editing the topic. | |
redirectto |
If the user continues from edit to save, and if the save (or cancels the edit) process is successful, save will redirect to this topic or URL. The parameter value can be a TopicName , a Web.TopicName , or a URL.Note: Redirect to a URL only works if it is enabled in configure (Miscellaneous {AllowRedirectUrl} ). |
Status
the parameter name is Status
. X
characters in the topic name will be converted on save to a number such that the resulting topic name is unique in the target web.
EDIT_SKIN
, which is used as the value of the cover
parameter in edit
URLs. This allows you to override the default edit skin on a web, topic or user basis.
login
Parameter | Description | Default |
---|---|---|
origurl |
URL that was being accessed when an access violation occurred. the login process will redirect to this URL if it is successful | none |
username |
username of user logging in | none |
password |
password of user logging in | none |
logon
manage
manage
script can only be called via HTTP POST method. Make sure you specify method="post"
if you call the manage
script via a form action. It is not possible to call manage
from an <A href
link.
Parameter | Description | Default |
---|---|---|
action |
One of create , createweb , changePassowrd , resetPassword , bulkRegister , deleteUserAccount , editSettings , saveSettings , restoreRevision |
none |
action=create
edit
, of a new topic, used by screens that support several actions using manage
.
Parameter | Description | Default |
---|---|---|
topic |
Name of topic to create (can be web.topic) | none |
edit
.
action=createweb
Parameter | Description | Default |
---|---|---|
newweb |
Name of the new web | '' |
baseweb |
Name of the web to copy to create the new web | '' |
webbgcolor |
value for WEBBGCOLOR | '' |
sitemapwhat |
Value for SITEMAPWHAT | '' |
sitemapuseto |
Value for SITEMAPUSETO | '' |
nosearchall |
Value for NOSEARCHALL | '' |
newtopic |
Value of %TOPIC% within the web creation message. Optionally used in some skins to signify a non-default home topic. |
action=editSettings
action=saveSettings
Parameter | Description | Default |
---|---|---|
text |
Text of the topic | '' |
originalrev |
Revision that the edit started on | Most recent revision |
redirectto |
If the savesettings process is successful, save will redirect to this topic or URL. The parameter value can be a TopicName , a Web.TopicName , or a URL.Note: Redirect to a URL only works if it is enabled in configure (Miscellaneous {AllowRedirectUrl} ). |
action=bulkRegister
Parameter | Description | Default |
---|---|---|
OverwriteHomeTopics |
Whether to overwrite existing home topics or not | false |
EmailUsersWithDetails |
Whether to mail registered users or not | false |
LogTopic |
Topic to save the log in | Same as topic name, with 'Result' appended. |
action=changePassword
Parameter | Description | Default |
---|---|---|
username |
god alone knows | none |
oldpassword |
current password | none |
password |
new password | none |
passwordA |
new password confirmation | none |
email |
new email address | none |
password, =passwordA
and email
are optional. If neither or password
and passwordA
is set, then the user password is left unchanged. If email
is unset, their email is left unchanged.
action=resetPassword
Parameter | Description | Default |
---|---|---|
LoginName |
list of usernames to reset | none - error if not set |
Introduction |
message to be sent alongside the reset, most often used to announce to the user that they have been given an account. | '' |
action=deleteUserAccount
Parameter | Description | Default |
---|---|---|
password |
Users' password | none |
action=restoreRevision
edit
, used by screens that support several actions using manage. Parameters are as for =edit
.
oops
oops
templates are used with the oops
script to generate system messages. This is done to make internationalisation or other local customisations simple.
The oops
script supports the following parameters:
Parameter | Description | Default |
---|---|---|
template |
Name of the template file to display | |
def |
Optional, can be set to the name of a single definition within template . This definition will be instantiated in the template wherever %INSTANTIATE% is seen. This lets you use a single template file for many messages. For an example, see oopsmanagebad.tmpl . |
|
paramN |
Where N is an integer from 1 upwards. These values will be substituted into template for %PARAM1% etc. |
preview
save
script.
rdiff
Parameter | Description | Default |
---|---|---|
rev1 | the higher revision | |
rev2 | the lower revision | |
render | the rendering style {sequential, sidebyside, raw, debug} | DIFFRENDERSTYLE, sequential |
type | {history, diff, last} history diff, version to version, last version to previous | diff |
context | number of lines of context |
register
Parameter | Description | Default |
---|---|---|
action |
register or verify or resetPassword or approve |
register
script can only be called via the HTTP POST method except when the action is verify
. Make sure you specify method="post"
if you call the register
script via a form action. It is not possible to call register
from an <A href
link. The verify
action is an exception as it is used to verify registration by clicking a href link from an email.
rename
Parameter | Description | Default |
---|---|---|
action |
renameweb or anything else |
|
skin |
skin(s) to use | |
confirm |
if defined, requires a second level of confirmation | |
referring_topics |
(internal use only) list of topics that refer to the web or topic being renamed | |
redirectto |
If the rename process is successful, rename will redirect to this topic or URL. The parameter value can be a TopicName , a Web.TopicName , or a URL.Note: Redirect to a URL only works if it is enabled in configure (Miscellaneous {AllowRedirectUrl} ). |
action="renameweb"
Parameter | Description | Default |
---|---|---|
newparentweb |
new parent web name | existing parent |
newsubweb |
new web name |
action=anything else
Parameter | Description | Default |
---|---|---|
newweb |
new web name | |
newtopic |
new topic name | |
attachment |
Attachment to move | none |
template |
template for error when an attachment doesn't exist, deleteattachment for when deleting an attachment |
|
currentwebonly |
if defined, searches current web only for links to this topic | |
nonwikiword |
if defined, a non-wikiword is acceptable for the new topic name |
rename
script can only be called via the HTTP POST method. Make sure you specify method="post"
if you call the rename
script via a form action. It is not possible to call rename
from an <A href
link.
rest
Foswiki::Func::registerRESTHandler
method. The rest
script will print the result directly to the browser unless the endPoint
parameter is specified, in which case it will output a redirect to the given topic.
The rest
script supports the following parameters:
username |
If TemplateLogin , or a similar login manager not embedded in the web server, is used, then you need to pass a username and password to the server. The username and password parameters are used for this purpose. |
password |
See username |
topic |
If defined as the full name (including web) of a topic, then when the script starts up plugins will be passed this as the "current" topic. If not defined, then Main.WebHome will be passed to plugins. |
endPoint |
Where to redirect the response once the request is served, in the form "Web.Topic" |
rest
script should always require authentication in any site that has logins. Otherwise there is a risk of opening up major security holes. So make sure you add it to the list of authenticated scripts if you are using ApacheLogin
.
rest
script assumes that it will be called with URL in the form:
http://my.host/bin/rest/<subject>/<verb>
where <subject>
must be the WikiWord name of one of the installed Plugins, and the <verb>
is the alias for the function registered using the Foswiki::Func::registerRESTHandler
method. The <subject>
and <verb>
are then used to lookup and call the registered function.
<subject>
and <verb>
are checked for illegal characters exactly in the same way as the web and topic names.
As an example, the EmptyPlugin has registered a function to be used with the rest
script under the subject EmptyPlugin and the verb example. Click below to see the rest
script in action (run as guest).
Call the Plugin
Note that for Plugins to register REST handlers, they must be enabled in configure
.
$session
, for example with the url:
http://my.host/bin/rest/MyPlugin/update?web=fooThe url parameters can be processed using:
my $query = $session->{request}; my $web = $query->{param}->{web}[0];
save
save
script performs a range of save-related functions, as selected by the action
parameter.
Parameter | Description | Default |
---|---|---|
action_save=1 |
default; save, return to view, dontnotify is off |
|
action_quietsave=1 |
save, and return to view, dontnotify is on |
|
action_checkpoint |
save and redirect to the edit script, dontnotify is on |
|
action_cancel |
exit without save, return to view | |
action_preview |
preview edited text | |
action_addform |
Redirect to the "change form" page. | |
action_replaceform... |
Redirect to the "change form" page. | |
action_delRev |
Administrators only delete the most recent revision of the topic - all other parameters are ignored. You have to be an administrator to use this, and not all store implementations will support it. | |
action_repRev |
Administrators only replace the text of the most recent revision of the topic with the text in the text parameter. text must included embedded meta-data tags. All other parameters are ignored. You have to be an administrator to use this, and not all store implementations will support it. |
|
onlynewtopic |
If set, error if topic already exists | |
onlywikiname |
If set, error if topic name is not a WikiWord | |
dontnotify |
if defined, suppress change notification | |
templatetopic |
Name of a topic to use as a template for the text and form (new topic only) | |
text |
New text of the topic | |
forcenewrevision |
if set, forces a revision even if Foswiki thinks one isn't needed | |
topicparent |
If 'none' remove any current topic parent. If the name of a topic, set the topic parent to this. | |
formtemplate |
if defined, use the named template for the form (will remove the form is set to 'none') | |
editaction |
When action is checkpoint , add form or replace form... , this is used as the action parameter to the edit script that is redirected to after the save is complete. |
|
originalrev |
Revision on which the edit started. | |
edit |
The script to use to edit the topic when action is checkpoint |
edit |
editparams |
The parameter string to use to edit the topic | |
redirectto |
The save process will redirect to this topic or URL if it is successful. (Typically this would be the URL that was being viewed when edit was invoked). The parameter value can be a TopicName , a Web.TopicName , or a URL.Note: Redirect to a URL only works if it is enabled in configure (Miscellaneous {AllowRedirectUrl} ). |
view topic being edited |
oops
page.
The parameters are interpreted in according to the following rules.
X
characters in the topic name will be converted to a number such that the resulting topic name is unique in the target web.
save
, checkpoint
, quietsave
, or preview
: text
parameter, if it is defined, templatetopic
, if it is defined, (new topic only)
formtemplate
, if defined templatetopic
, if defined, (new topic only)
templatetopic
, if defined, (new topic only)
text
and originalrev
is > 0 and is not the same as the revision number of the most recent revision. If merging is enabled both the topic and the meta-data are merged.
Form field values are passed in parameters named 'field' - for example, if I have a field Status
the parameter name is Status
.
Note: The save
script can only be called via HTTP POST method. Make sure you specify method="post"
if you call the save
script via a form action. Example:
<form name="new" action="%SCRIPTURLPATH{save}%/Sandbox/" method="post"> ... </form>It is not possible to call
save
from an <A href
link.
search
%SEARCH%
functionality driven by the following CGI parameters:
Parameter: | Description: | Default: |
---|---|---|
"text" |
Search term. Is a keyword search, literal search or regular expression search, depending on the type parameter. SearchHelp has more |
required |
search="text" |
(Alternative to above) | N/A |
web="Name" web="Main, Know" web="all" |
Comma-separated list of webs to search. See Macros#VarSEARCH for more details. | Current web |
topic="WebPreferences" topic="*Bug" |
Limit search to topics: A topic, a topic with asterisk wildcards, or a list of topics separated by comma. | All topics in a web |
excludetopic="Web*" excludetopic="WebHome, WebChanges" |
Exclude topics from search: A topic, a topic with asterisk wildcards, or a list of topics separated by comma. | None |
type="keyword" type="literal" type="regex" |
Do a keyword search like soap "web service" -shampoo ; a literal search like web service ; or RegularExpression search like soap;web service;!shampoo |
%SEARCHVAR- DEFAULTTYPE% preferences setting (literal) |
scope="topic" scope="text" scope="all" |
Search topic name (title); the text (body) of topic; or all (both) | "text" |
order="topic" order="created" order="modified" order="editby" order= |
Sort the results of search by the topic names, topic creation time, last modified time, last editor, or named field of DataForms. The sorting is done web by web; in case you want to sort across webs, create a formatted table and sort it with TablePlugin's initsort | Sort by topic name |
limit="all" limit="16" |
Limit the number of results returned. This is done after sorting if order is specified |
All results |
date="..." |
limits the results to those pages with latest edit time in the given time interval. | All results |
reverse="on" |
Reverse the direction of the search | Ascending search |
casesensitive="on" |
Case sensitive search | Ignore case |
bookview="on" |
BookView search, e.g. show complete topic text. Very resource demanding. Use only with small result sets | Show entire topic content of found topics |
nonoise="on" |
Shorthand for nosummary="on" nosearch="on" nototal="on" zeroresults="off" noheader="on" noempty="on" |
Off |
nosummary="on" |
Show topic title only | Show topic summary |
nosearch="on" |
Suppress search string | Show search string |
noheader="on" |
Suppress search header Topics: Changed: By: |
Show search header |
nototal="on" |
Do not show number of topics found | Show number |
zeroresults="off" |
Suppress all output if there are no hits | zeroresults="on" , displays: "Number of topics: 0" |
noempty="on" |
Suppress results for webs that have no hits. | Show webs with no hits |
header="..." format="..." |
Custom format results: see FormattedSearch for usage & examples | Results in table |
expandvariables="on" |
Expand embedded macros before applying a FormattedSearch on a search hit. Useful to show the expanded text, e.g. to show the result of a SpreadSheetPlugin %CALC{}% instead of the formula |
Raw text |
multiple="on" |
Multiple hits per topic. Each hit can be formatted. The last token is used in case of a regular expression ";" and search | Only one hit per topic |
nofinalnewline="on" |
If on , the result of the macro does not end in a line by itself. Any text continuing immediately after the search macro on the same line will be rendered as part of the table generated by the search, if appropriate. |
off |
separator=", " |
Line separator between hits | Newline "$n" |
statistics
Parameter | Description | Default |
---|---|---|
webs |
comma-separated list of webs to run stats on | all accessible webs |
logdate |
YYYYMM to generate statistics for | current month |
upload
multipart/form-data
format.
Parameter | Description | Default |
---|---|---|
hidefile |
if defined, will not show file in attachment table | |
filepath |
local (client) path name of the file being uploaded. This is used to look up the data for the file in the HTTP query. | |
filename |
deprecated, do not use | |
filecomment |
Comment to associate with file in attachment table | |
createlink |
if defined, will create a link to file at end of topic | |
changeproperties |
if defined, this is a property change operation only - no file will be uploaded. | null |
redirectto |
URL to redirect to after upload. {AllowRedirectUrl} must be enabled in configure . The parameter value can be a TopicName , a Web.TopicName , or a URL. Redirect to a URL only works if it is enabled in configure , and is ignored if noredirect is specified.Note: Redirect to a URL only works if it is enabled in configure (Miscellaneous {AllowRedirectUrl} ). |
|
noredirect |
Normally it will redirect to 'view' when the upload is complete, but also designed to be useable for REST-style calling using the 'noredirect' parameter. If this parameter is set it will return an appropriate HTTP status code and print a message to STDOUT, starting with 'OK' on success and 'ERROR' on failure. |
curl
to upload files from the command line using this script.
upload
script can only be called via HTTP POST method. Make sure you specify method="post"
if you call the upload
script via a form action. It is not possible to call upload
from an <A href
link.
view
Parameter | Description | Default |
---|---|---|
raw=on |
Shows the text of the topic in a scrollable textarea | |
raw=debug |
As raw=on , but also shows the metadata (forms etc) associated with the topic. |
|
raw=text |
Shows only the source of the topic, as plain text (Content-type: text/plain). Only shows the body text, not the form or other meta-data. | |
raw=all |
Shows only the source of the topic, as plain text (Content-type: text/plain), with embedded meta-data. This may be useful if you want to extract the source of a topic to a local file on disc. | |
section |
Allows to view only a part of the topic delimited by a named section (see System.VarSTARTSECTION). If the given section is not present, no topic content is displayed. | |
contenttype |
Allows you to specify a different Content-Type: (e.g. contenttype=text/plain ) |
|
rev |
Revision to view (e.g. rev=45 ) |
|
template |
Allows you to specify a different skin template, overriding the 'view' template the view script would normally use. The default template is view . For example, you could specify /wiki/bin/view/System/CommandAndCGIScripts?template=edit. This is mainly useful when you have specialised templates for a Wiki Application. |
|
topic |
redirects (at the beging of the cgi script running) to show the spcified Web.Topic, or, redirects to a URL, if allowed by {AllowRedirectUrl} and {PermittedRedirectHostUrls} |
text
skin. This skin cannot be redefined.
viewfile
pub
) directory using a URL. However if it contains sensitive information, you will want to protect attachments using AccessControls. In this case, you can use the viewfile
script to give access to attachments while still checking access controls.
Parameter | Description | Default |
---|---|---|
filename |
name of attachment | |
rev |
Revision to view |
filename
parameter, you can append the attachment name
to the end of the URL path (after the topic) e.g. http://www.wetherby.me/wiki/bin/viewfile/Webname/TopicName/Attachment.gif
tools
directory.
geturl.pl
wget
and curl
commands. geturl.pl <host> <path> [<port> [<header>]]
geturl.pl some.domain /some/dir/file.html 80
http://some.domain:80/some/dir/file.html
rewriteshebang.pl
#!/usr/bin/perl
shebang lines specific to your local Perl installation. It will rewrite the first line of all your cgi scripts so they use a different shebang line. Use it if your perl is in a non-standard location, or you want to use a different interpreter (such as 'speedy').
tick_foswiki.pl
0 0 * * 0 cd /usr/local/foswiki/bin && perl ../tools/tick_foswiki.pl
Note: The script has to be run by a user who can write files created by the webserver user.
*
subscriber [ :
topics ]
Where subscriber can be a WikiName, an E-mail address, or a
group name. If subscriber contains any characters that are not legal in
an email address, then it must be enclosed in 'single' or "double" quotes.
topics is an optional space-separated list of topics: *
in a topic name, where it is treated as a wildcard character. A *
will match zero or more other characters - so, for example, Fred*
will match all topic names starting with Fred
, *Fred
will match all topic names ending with Fred
, and *
will match all topic names.
* daisy.cutter@flowers.comSubscribe Daisy to all changes to topics that start with
Web
.
* daisy.cutter@flowers.com : Web*Subscribe Daisy to changes to topics starting with
Petal
, and their immediate children, WeedKillers and children to a depth of 3, and all topics that match start with Pretty
and end with Flowers
e.g. PrettyPinkFlowers
* DaisyCutter: Petal* (1) WeedKillers (3) Pretty*FlowersSubscribe StarTrekFan to changes to all topics that start with
Star
except those that end in Wars
, sInTheirEyes
or shipTroopers
.
* StarTrekFan: Star* - *Wars - *sInTheirEyes - *shipTroopersSubscribe Daisy to the full content of NewsLetter whenever it has changed
* daisy@flowers.com: NewsLetter?Subscribe buttercup to NewsLetter and its immediate children, even if it hasn't changed.
* buttercup@flowers.com: NewsLetter! (1)Subscribe GardenGroup (which includes Petunia) to all changed topics under AllnewsLetters to a depth of 3. Then unsubscribe Petunia from the ManureNewsLetter, which she would normally get as a member of GardenGroup:
* GardenGroup: AllNewsLetters? (3) * petunia@flowers.com: - ManureNewsLetterSubscribe
IT:admins
(a non-Foswiki group defined by an alternate user mapping) to all changes to Web* topics.
* 'IT:admins' : Web*A user may be listed many times in the WebNotify topic. Where a user has several lines in WebNotify that all match the same topic, they will only be notified about changes that topic once (though they will still receive individual mails for news topics). If a group is listed for notification, the group will be recursively expanded to the e-mail addresses of all members. __ Warning: Because an email address is not linked to a user name, there is no way for Foswiki to check access controls for subscribers identified by email addresses. A subscriber identified by an email address alone will only be sent change notifications if the topic they are subscribed to is readable by guest users. You can limit what email addresses can be used in %NOTIFYTOPIC%, or even block use of emails altogther, using the
{MailerContrib}{EmailFilterIn} setting in =configure
.
Tip: List names in alphabetical order to make it easier to find the names.
Note for System Administrators: Notification is supported by an add-on to the Foswiki kernel called the MailerContrib. See the MailerContrib topic for details of how to set up this service.
Note: If you prefer a news feed, point your reader to WebRss (for RSS 1.0 feeds) or WebAtom (for ATOM 1.0 feeds). Learn more at WebRssBase and WebAtomBase, respectively.
SEARCH
. The number of topics listed by the limit
parameter.:
%SEARCH{ ".*" web="System" type="regex" nosearch="on" order="modified"
reverse="on" limit="50" }%
%SEARCH{}%
.
SEARCH
:
%SEARCH{ "\.*" scope="topic" type="regex" nosearch="on" }%
%STATISTICSTOPIC%
bin/statistics
script from a cron job, once a day is recommended. This will update the WebStatistics topics in all webs.
nobody
on many systems. Example crontab entry: 0 0 * * * (cd /path/to/bin; ./statistics >/dev/null 2>&1)
nobody
: Run the utility tools/geturl.pl
in your cron job and specify the URL of the bin/statistics
script as a parameter. Example: 0 0 * * * (cd /path/to/tools; ./geturl.pl mydomain.com /urlpath/to/bin/statistics >/dev/null 2>&1)
geturl.pl
will do a CGI request as the WikiGuest user, so if you use this workaround, the WebStatistics topics you are updating will have to be writable by WikiGuest.
./statistics -logdate 200605 -webs Userweb,Sandbox
bin/statistics
script can also be executed as a CGI script, just enter the URL in your browser. Examples: /wiki/bin/statistics
/wiki/bin/statistics/Main
/wiki/bin/statistics/Main?logdate=202410
/wiki/bin/statistics?logdate=202410;webs=ProjectX,ProjectY,ProjectZ
log<year><month>.txt
logs/log202410.txt
| <time> | <wikiusername> | <action> | <web>.<topic> | <extra info> | <IP address> |
| 10 Oct 2024 - 00:19 | Main.WikiGuest | view | System.WebRss | | 66.124.232.02 |
Script | Action name | Extra info |
---|---|---|
attach | attach | when viewing attach screen of previous uploaded attachment: filename |
changes | changes | |
edit | edit | when editing non-existing topic: (not exist) |
rdiff | rdiff | higher and lower revision numbers: 4 3 |
register | regstart | WikiUserName, e-Mail address, LoginName: user attempts to register |
register | register | E-mail address: user successfully registers |
register | bulkregister | WikiUserName of new, e-mail address, admin ID |
manage | rename | when moving topic: moved to Newweb.NewTopic |
manage | move | when moving attachment: Attachment filename moved to Newweb.NewTopic |
manage | renameweb | when renaming a web: oldweb moved to newweb |
save | save | when replacing existing revision: repRev 3 when user checks the minor changes box: dontNotify when user changes attributes to an exising attachment: filename.ext |
save | cmd | special admin parameter used when saving |
search | search | search string |
upload | upload | filename |
view | view | when viewing non-existing topic: (not exist) when viewing previous topic revision: r3 |
Net::SMTP
module if it is installed on your system. Set this with the SMTPMAILHOST
preference setting.
The notify e-mail uses the default changes.tmpl
template, or a skin if activated by a preference setting.
mailnotify also relies on two hidden files in each data/Web
directory: .changes
and .mailnotify.
Make sure both are writable by your web server process. .changes
contains a list of changes; go ahead and make this empty. .mailnotify
contains a timestamp of the last time notification was done.
You can use an external mail program, such as sendmail
, if the Net::SMTP
module is not installed. Set the program path in {MailProgram}
in configure.
! * Net::SMTP can be easily disabled (if there is an installation error) by setting the SMTPMAILHOST
preference setting to an empty value.
SMTPSENDERHOST
preference setting to define the mail sender host (some SMTP installations require this).
cron
table so that mailnotify
is called in an interval of your choice. Please consult man crontab
of how to modify the table that schedules program execution at certain intervals. Example:
% crontab -e 0 1 * * * (cd /path/to/bin; ./mailnotify -q)The above line will run mailnotify nightly at 01:00. The
-q
switch suppresses all normal output.
For ISP installations: Many ISPs don't allow hosted accounts direct cron access, as it's often used for things that can heavily load the server. Workaround scripts are available.
On Windows: You can use a scheduled task if you have administrative privileges.
Trash
web.
[More actions]
link (normally located in an action toolbar at the top or bottom of page) on the topic to be changed. Then, in the new screen, click [Rename, move or delete this topic]
. You can now rename and/or move/delete in one operation: Trash
to delete a topic.
[Rename]
: the topic will be renamed and links to the topic updated as requested. [Rename]
.
rename/move/delete
action - an instruction line and an undo link will appear at the bottom of the modified topic. This allows you to revert from the last modification only.
[More actions]
link (normally located in an action toolbar at the top or bottom of page) on the topic to be changed.
Web.TopicName
).
[Copy topic]
button. You will be directed to an edit page for the newly-created topic. You can save the new copy immediately, or make some changes and then save it.
Trash
web - they are NOT physically erased from the server. All webs share the same Trash
- in case of a name conflict with a topic already existing in the Trash
web, the user is alerted and asked to choose a new name.
The Trash
web should be be cleared periodically, by archiving (saving) the text and RCS files if required (recommended), then deleting them from the Trash
directory.
Trash
directory is all that is required for maintenance, it is possible to grant Trash
admin privileges to multiple users, while strictly limiting server access.
%<nop>METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%" title="This topic used to exist and was moved to: "}%
<pre>
and <verbatim>
are honoured - no changes are made to text within these areas.
topic
. Next, all webs (including the current one) are listed that match web.topic
. All webs will be searched during rename, even if NOSEARCHALL
is defined on a web, though access permissions will of course be honoured.
Changed references are kept as short as possible, ex: topic
is used in preference to web.topic
.
VIEW
, CHANGE
and RENAME
access to that topic. To alter referring topics, you need CHANGE
access. See AccessControl for information on setting up access permissions.
search
can show matches that will not be updated due to case differences. Other mismatches with actual rendered output are also possible as the approaches are so different.
The following shows some limitations of square bracket processing.
[[Old Topic]] => [[NewTopic][Old Topic]] [[old topic]] => [[NewTopic][old topic]] [[old t opic]] => not changed [[OldTopic]] => [[NewTopic]]
data
directory, with text files as topics. System
for documentation, Main
to store user pages and site-wide preferences, Trash
for the topic recycle bin. Sandbox/TestWeb/SubWeb.SubWebTopic
topic: System.DefaultPreferences
default settings
Main.SitePreferences
site-wide settings inherits from and overrides settings in System.DefaultPreferences
Sandbox.WebPreferences
inherits from and overrides settings in Main.SitePreferences
Sandbox/TestWeb.WebPreferences
inherits from and overrides settings in Sandbox.WebPreferences
Sandbox/TestWeb/SubWeb.WebPreferences
inherits from and overrides settings in Sandbox/TestWeb.WebPreferences
Sandbox/TestWeb/SubWeb.SubWebTopic
inherits from and overrides settings in Sandbox/TestWeb/SubWeb.WebPreferences
Main.SomeUserName
- points to it and would need updating (unless the macro style %USERSWEB%.SomeUserName
, is used throughout). This potentially large change can be performed automatically if you rename the web from the Tools section of WebPreferences, as described above.
If you want to rename the System or Main webs, remember they are referred to in the Foswiki configuration. You will need to change the {SystemWebName}
, {UsersWebName}
and/or {LocalSitePreferences}
settings in the configuration using the configure interface.
Renaming the webs in the distribution is not recommended because it makes upgrades much more complicated.
JaneSmith
to JaneMiller
. %M% Jane Smith is now known as JaneMiller
* JaneSmith - jsmith - 13 Sep 2006
* JaneMiller - jmiller - 13 Sep 2006
.htpasswd
file, edit the .htpasswd
file to delete the line starting fred:
htpasswd
program with .htpasswd
files generated by Foswiki! htpasswd
wipes out email addresses that Foswiki plants in the info fields of this file.
FredQuimby - fred
line from the Main.WikiUsers topic
FredQuimby
from all groups and from all the ALLOWWEB/ALLOWTOPIC...
declarations, if any.templates/registerconfirm.tmpl
templates/registernotify.tmpl
templates/registernotifyadmin.tmpl
templates
dir, this cannot use Template topics.
These template files have a specific format that matches the raw format of emails sent via SMTP,
so be careful and test your changes. It is easiest to start by copying the default templates:
cd templates cp registernotify.tmpl registernotify.myskin.tmpl cp registerconfirm.tmpl registerconfirm.myskin.tmpl cp registernotifyadmin.tmpl registernotifyadmin.myskin.tmplthen add
myskin
to the beginning of the SKIN
setting in Main.SitePreferences.
From this point on, your myskin templates will be used for the registration emails.
To make it possible for WikiUsers to modify the email contents, you could use a parameterized %INCLUDE%
statement in your customized version. eg:
From: %WIKIWEBMASTERNAME% <%WIKIWEBMASTER%> To: %FIRSTLASTNAME% <%EMAILADDRESS%> Subject: %MAKETEXT{"[_1] - Registration for [_2] ([_3])" args="%WIKITOOLNAME%, %WIKINAME%, %EMAILADDRESS%"}% MIME-Version: 1.0 Content-Type: text/plain; charset=%CHARSET% Content-Transfer-Encoding: 8bit %INCLUDE{ "%USERSWEB%.RegisterNotifyEmail" WIKINAME="%WIKINAME%" FIRSTLASTNAME="%FIRSTLASTNAME%" EMAILADDRESS="%EMAILADDRESS%" }%
Welcome to %WIKITOOLNAME%. %MAKETEXT{"Your personal [_1] topic is located at [_2]. You can customize it as you like:" args="%WIKITOOLNAME%, %SCRIPTURL{"view"}%/%USERSWEB%/%WIKINAME%"}% * %MAKETEXT{"Some people turn it into a personal portal with favorite links, what they work on, what help they'd like, etc."}% * %MAKETEXT{"Some add schedule information and vacation notice."}% Regards %WIKIWEBMASTERNAME% Your Wiki Admin %MAKETEXT{"Note:"}% 2 %MAKETEXT{"You can change your password at via [_1]" args="%SCRIPTURL{"view"}%/%SYSTEMWEB%/ChangePassword"}% 3 %MAKETEXT{"If you haven't set a password yet or you want to reset it, go to: [_1]" args="%SCRIPTURL{"view"}%/%SYSTEMWEB%/ResetPassword"}% %MAKETEXT{"Submitted content:"}% %FORMDATA%
viewfile
script can be used as a webserver ErrorDocument enabling both more secure attachments and user focused error dialogs.
'"<>%
which eliminates most XSS possibilities encountered with URLPARAM. This protects all topics using the URLPARAM macro without requiring any changes to them.
TWiki term | Foswiki term |
---|---|
TWiki variable | Macro |
preference(s) variable | preference setting, or macro when referring to expansion of same |
TWiki form | Data form |
TWiki Plugin | Plugin |
TWiki Template | Skin Template |
Topic Template | Template Topic |
TWiki Markup Language (TML) | Topic Markup Language (TML) |
TWiki Application | Wiki Application |
working
which per default is located in the TWiki root which contains registration_approvals, tmp, and work_areas
query
search mode supports SQL-style queries over form fields and other meta-data
templatetopic
parameter to point to custom comment template topic
Eng.ajax
into the Jump box... Here we go, the third link is the AjaxCookbook I was looking for."
redirectto
parameter to redirect to a topic or a URL; for security, redirect to URL needs to be enabled with a {AllowRedirectUrl}
configure flag.
redirectto
parameter to redirect to a URL or link to TWiki topic after submitting comment.
topic
URL parameter also respects the {AllowRedirectUrl}
configure flag so redirects to URLs can be disabled which could be abused for phishing attacks.
section
URL parameter to view just a named section within a topic. Useful for simple AJAX type applications.
$nop
, $quot
, $percnt
, $dollar
.
$LISTRAND()
, $LISTSHUFFLE()
, $LISTTRUNCATE()
.
cellborder
.
Installation & configuration | Contributor |
---|---|
Much simpler install and configuration | Crawford Currie, LynnwoodBrown, ArthurClemens |
mod_perl safe code for better performance |
Crawford Currie |
Security | |
Security sandbox blocking exploits for remote command execution on the server | Florian Weimer, Crawford Currie, Sven Dowideit |
Reworked access permission model | Crawford Currie |
Internationalization & localization | |
User Interface Internationalisation | AntonioTerceiro |
Chinese translation | CheDong |
Danish translation | SteffenPoulsen |
Dutch translation | ArthurClemens |
French translation | BenVoui |
German translation | AndreUlrich |
Italian translation | MassimoMancini |
Polish translation | ZbigniewKulesza |
Portuguese translation | AntonioTerceiro, CarlinhosCecconi |
Spanish translation | WillNorris, MiguelABayona |
Swedish translation | Erik �man |
New features for users | |
Edit conflict resolution with automatic merge | Crawford Currie |
Fine grained change notification on page level and parent/child relationship | Crawford Currie |
WYSIWYG editor | Crawford Currie, ColasNahaboo, DamienMandrioli, RomainRaugi |
Integrated session support | GregAbbas, Crawford Currie |
Webserver-independent login/logout | Crawford Currie |
Registration process with e-mail confirmation | MartinCleaver |
Tip of the Day box in TWiki Home | PaulineCheung, Peter Thoeny, AntonAylward |
ATOM feeds | Peter Thoeny |
"Force New Revision" check box for topic save | WillNorris |
New features for Wiki administrators and wiki application developers | |
Improved preferences handling | ThomasWeigert, Crawford Currie |
Named include sections | RafaelAlvarez |
Create topic names with consecutive numbers | Sven Dowideit |
Parameterized includes | Crawford Currie |
Dynamic form option definitions of DataForms with FormattedSearch | MartinCleaver |
SEARCH enhancements with new parameters excludeweb , newline , noempty , nofinalnewline , nonoise , recurse , zeroresults |
Crawford Currie, ArthurClemens, Peter Thoeny, ThomasWeigert |
FormattedSearch enhancements with $changes , $count , $formfield(name, 30, ...) , $summary(expandvar) , $summary(noheaders) , $summary(showvarnames) |
ColasNahaboo, Crawford Currie, Peter Thoeny, Sven Dowideit |
New TWikiVariables ACTIVATEDPLUGINS?, ALLVARIABLES?, AUTHREALM?, EMAILS?, FAILEDPLUGINS?, HTTP?, HTTPS?, ICONURL?, ICONURLPATH?, IF?, LANGUAGES?, LOCALSITEPREFS?, LOGIN?, LOGOUT?, MAKETEXT?, META?, PLUGINDESCRIPTIONS?, QUERYSTRING?, STARTSECTION?/ENDSECTION?, SESSION_VARIABLE?, SESSIONID?, SESSIONVAR?, SPACEOUT?, USERLANGUAGE?, WIKIHOMEURL? | ArthurClemens, AntonioTerceiro, Crawford Currie, GregAbbas, Peter Thoeny, Sven Dowideit, WillNorris and many more |
TWiki form with hidden type and other form enhancements | LynnwoodBrown, ThomasWeigert |
Support topic-specific templates for TWiki applications | ThomasWeigert |
Direct save feature for one-click template-based topic creation | LynnwoodBrown, Crawford Currie, ThomasWeigert |
Automatic Attachments showing all files in the attachment directory | MartinCleaver |
Rename, move or delete webs | PeterNixon |
Hierarchical subwebs (beta) | PeterNixon |
New features for Plugin developers | |
REST (representational state transfer) interface for Plugins | RafaelAlvarez, TWiki:Main.MartinCleaver, Sven Dowideit |
New and improved Plugins APIs | Crawford Currie, ThomasWeigert |
Improvements in the TWiki engine room | |
Major OO redesign and refactoring of codebase | Crawford Currie |
Automatic build system | Crawford Currie |
Extensive test suite, unit tests and testcases | Crawford Currie |
TWiki:Codev.DevelopBranch , DEVELOP branch Bugs system | Sven Dowideit |
Documentation, logo artwork, skins: | |
Documentation | Crawford Currie, LynnwoodBrown, Peter Thoeny, Sven Dowideit and others |
Design of TWikiLogos with big "T" in a speech bubble | ArthurClemens, Peter Thoeny |
Improved templates and PatternSkin | ArthurClemens |
Details of New Features and Enhancements of 01-Sep-2004 Release | Developer, Sponsor |
---|---|
Install: Ship with an automatic upgrade script to facilitate TWiki upgrades. Details | TWiki:Main.MartinGregory Foswiki:Main.SvenDowideit |
Install: New testenv function to change the locks in the TWiki database to the web server user id (automates installation step). Details | TWiki:Main.MattWilkie Foswiki:Main.SvenDowideit |
Install: The shipped .htaccess.txt now needs to be edited before it is valid, to help reduce chances of error. Details | Foswiki:Main.CrawfordCurrie Foswiki:Main.SvenDowideit |
Install: Configurable password file handling for different types of encryption. Details | TWiki:Main.PavelGoran Foswiki:Main.SvenDowideit |
Install: Remove office locations from registration. Details | TWiki:Main.PeterThoeny |
Install: Changes to support shorter URLs with Apache Rewrite rules. Details | TWiki:Main.AntonioBellezza TWiki:Main.WalterMundt |
Install: Remove the Know web from the distribution. Details | TWiki:Main.PeterThoeny |
Internationalization: Support use of UTF-8 URLs for I18N characters in TWiki page and attachment names. Details | TWiki:Main.RichardDonkin |
Authentication: Authenticate users when creating new topic in view restricted web. Details | TWiki:Main.JonathanGraehl Foswiki:Main.SvenDowideit |
Preferences: TWiki Preferences need to be secured properly. Details | TWiki:Main.PeterThoeny |
Preferences: Use TWiki Forms to set user preferences. Details | TWiki:Main.JohnTalintyre |
Skins: New pre-installed skins PatternSkin and DragonSkin. Details | Foswiki:Main.ArthurClemens TWiki:Main.PeterThoeny |
Skins: New skin browser to choose from installed skins. Details | TWiki:Main.PeterThoeny |
Skins: Documented set of CSS classes that are used in standard skins. Details | Foswiki:Main.ArthurClemens Foswiki:Main.SvenDowideit |
Skins: Added CSS class names to Diff output. Details | Foswiki:Main.SvenDowideit |
Skins: Templates can now be read from user topics, as well as from files in the templates diretcory. Details | Foswiki:Main.CrawfordCurrie TWiki:Main.WalterMundt |
Skins: Ensure that the default template gets overridden by a template passed in. Details | TWiki:Main.MartinCleaver TWiki:Main.WalterMundt |
Skin: Convey an important broadcast message to all users, e.g. scheduled server downtime. Details | TWiki:Main.PeterThoeny |
Skin: Balanced pastel colors for TWiki webs. Details | Foswiki:Main.ArthurClemens |
Rendering: Use exclamation point prefix to escape TWiki markup rendering. Details | Foswiki:Main.ArthurClemens |
Rendering: Ordered lists with uppercase & lowercase letters, uppercase & lowercase Roman numerals. Details | TWiki:Main.DanBoitnott TWiki:Main.PeterThoeny |
Rendering: Allow custom styles for the "?" of uncreated topics. Details | Foswiki:Main.SvenDowideit |
Rendering: Render IRC and NNTP as a URL. Details | TWiki:Main.PeterThoeny |
Rendering: Make acronym linking more strict by requiring a trailing boundary, e.g. excluding TLAfoobar. Details | Foswiki:Main.CrawfordCurrie Foswiki:Main.SvenDowideit |
Rendering: TWiki Form with Label type. Details | TWiki:Main.PeterThoeny |
Rendering: Web names can now be WikiWords. Details | TWiki:Main.PeterThoeny |
Rendering: New syntax for definition list with dollar sign and colon. Details | TWiki:Main.AdamTheo TWiki:Main.PeterThoeny |
Rendering: Table with multi-span rows, functionality provided by Table Plugin. Details | TWiki:Main.WalterMundt |
Variables: New title parameter for TOC variable. Details | TWiki:Main.PeterThoeny Foswiki:Main.ArthurClemens |
Variables: New REVINFO variable in templates supports flexible display of revision information. Details | TWiki:Main.PeterThoeny Foswiki:Main.SvenDowideit |
Variables: Set times to be displayed as gmtime or servertime. Details | TWiki:Main.SueBlake Foswiki:Main.SvenDowideit |
Variables: Properly encode parameters for form fields with ENCODE variable. Details | TWiki:Main.PeterThoeny |
Variables: Expand USERNAME and WIKINAME in Template Topics. Details | TWiki:Main.PeterThoeny |
Variables: Expand same variables in new user template as in template topics. Details | TWiki:Main.PeterThoeny |
Variables: Optionally warn when included topic does not exist; with the option to create the included topic. Details | TWiki:Main.PeterThoeny |
Variables: In topic text show file-types of attached files as icons. Details | TWiki:Main.PeterThoeny |
Variables: New variable FORMFIELD returns the value of a field in the form attached to a topic.. Details | TWiki:Main.DavidSachitano Foswiki:Main.SvenDowideit |
Variables: Meta data rendering for form fields with META{"formfield"}. Details | TWiki:Main.PeterThoeny |
Variables: New PLUGINVERSION variable. Details | TWiki:Main.PeterThoeny |
Variables: URLPARAM now has a default="..." argument, for when no value has been given. Details |