--- /dev/null
+%TMPL:INCLUDE\{"view"\}%
+
+%TMPL:DEF\{"active\_form"\}%[Edit personal data](http://www.dementia.org/twiki/edit/%WEB%/%TOPIC%?action=form&t=1277827630 Edit personal data)%TMPL:END% %TMPL:DEF\{"inactive\_form"\}% %TMPL:END%
+
+%TMPL:DEF\{"inactive\_edit"\}%<strike>Edit text</strike>%TMPL:END% %TMPL:DEF\{"create\_topic"\}%Cr<span>e</span>ate%TMPL:END% %TMPL:DEF\{"edit\_topic"\}%<span>E</span>dit text%TMPL:END% %TMPL:DEF\{"active\_edit"\}%[****](http://www.dementia.org/twiki/edit/%WEB%/%TOPIC%?action=text&t=1277827630 Edit this topic text)%TMPL:END%
+
+%TMPL:DEF\{"content"\}%
+
+%BR% %TEXT% <a name="TopicEnd"></a>
+
+%TMPL:END%
--- /dev/null
+# <a name="TWiki Administrator User"></a> TWiki Administrator User
+
+The %TOPIC% has been added to TWiki 4.2.0 to make it possible to login without needing to create a TWiki User, or to temporarily login as %TOPIC% using the password set in configure, and then log back out to the same User and Group as before.
+
+This means it is no longer necessary to add yourself to the [[TWikiAdminGroup]], and you will be able to quicky change to Admin User (and back to your user) only when you need to.
+
+### <a name="How to login as %TOPIC%"></a> How to login as %TOPIC%
+
+- Login as the internal TWiki administrator:
+ - %ADMINLOGIN%
+- Logout from Administrator:
+ - click the [[Logout link|Main/LOGOUTURL]]
+
+**_%X% NOTE:_** If you lock yourself out of TWikiAdminUser during setup activities or have forgotten the configure password, you can unset the configure password by editing the `lib/LocalSite.cfg` file and deleting the line that starts with `$TWiki::cfg{Password}` and then set it again by saving your settings in `configure`.
+
+### <a name="Prerequisites"></a> Prerequisites
+
+- `Security Setup : Sessions : {UserClientSession}` needs to be enabled in configure
+- a configure password (otherwise the Admin login is automatically disabled.)
+- If your TWiki is configured to use ApacheLoginManager, you will need to log in as a valid user first.
+
+**_Related topics:_** [[TWikiUsers]], [[TWikiAdminGroup]], [[TWikiGroups]], %SYSTEMWEB%.TWikiAccessControl
+
+----
**_Notes:_**
- This topic is updated by the statistics script. (You can also [force](http://www.dementia.org/twiki/statistics/%WEB%) an update)
-- [[TWikiDocumentation]] tells you how to enable the automatic updates of the statistics.
+- %SYSTEMWEB%.TWikiDocumentation tells you how to enable the automatic updates of the statistics.
- Suggestion: You could archive this topic once a year and delete the previous year's statistics from the table.
- For example, we might have a web called "Enemies", where we keep all we know about our enemies, and another called "Friends"
- There's usually a safe play web called something like "Sandbox" or "Scratch", where you can create pages just to try things out
-- And some admin areas, like "Main" and "TWiki"
+- And some admin areas, like "%USERSWEB%" and "%SYSTEMWEB%"
## <a name="Slide 10: The Page Footer"></a> Slide 10: The Page Footer
... and easier to read<br /><br />`_Actually_ it is *perfectly* and __absolutely__ flat`<br /><br /> appears as <br /><br />_Actually_ it is **perfectly** and **_absolutely_** flat
-- A full description of all the formatting can be found in the [[TextFormattingRules]] and [[TextFormattingFAQ]]
+- A full description of all the formatting can be found in the %SYSTEMWEB%.TextFormattingRules and %SYSTEMWEB%.TextFormattingFAQ
- The best thing to do is just to type until you get stuck
- then follow the link on the edit page to the help.
| Cat | Feline |
| Bear | Ursine |
- | Wolf | Vulpine |
+ | Wolf | Lupine |
- appears as <table border="1" cellpadding="0" cellspacing="0">
<tr>
</tr>
<tr>
<td><font color="black">Wolf</font></td>
- <td><font color="black">Vulpine</font></td>
+ <td><font color="black">Lupine</font></td>
</tr>
</table>
- %RED% .... %ENDCOLOR% will change the colour of the enclosed text. Lots of colours are available (%RED%%RED%%ENDCOLOR%, %GREEN%%GREEN%%ENDCOLOR%, %BLUE%%BLUE%%ENDCOLOR% etc)
- An ordinary URL pasted into text will appear as a link - <http://www.google.com>
- You can also prettify URLs using square brackets:
- `[[http://www.google.com/][Google]]` appears as [Google](http://www.google.com/)
-- Use %SEARCH. This is an interface to a sophisticated search engine that embeds the results of the search in your page. See [[TWikiVariables]] for full details.
+- Use %SEARCH. This is an interface to a sophisticated search engine that embeds the results of the search in your page. See %SYSTEMWEB%.TWikiVariables for full details.
## <a name="Slide 19: More formatting"></a> Slide 19: More formatting
-- There's **lots** more formatting available, see [[TextFormattingRules]] and [[TextFormattingFAQ]]
+- There's **lots** more formatting available, see %SYSTEMWEB%.TextFormattingRules and %SYSTEMWEB%.TextFormattingFAQ
- _If you are a real masochist, you can even enter raw HTML tags!_
- **Important** to _disable_ unwanted formatting, use `<nop>`
- `<nop>_word_` appears as \_word\_
- Press the required letter
- Release the keys and press the 'ENTER' key
-- If you use Netscape Navigator, Mozilla, or Firefox
+- If you use Netscape Navigator, Mozilla, or Firefox 1.0
- Press and hold the 'Alt' key
- Press the required letter
+- If you use Firefox 2.0
+ - Press and hold both the 'Shift' and the 'Alt' key
+ - Press the required letter
+
- If you are using a Mac
- Press and hold the 'Ctrl' key
- Press the required letter
-[Learn more](http://www.salford.gov.uk/online/howto/accesskeys.htm)
-
**_Related Topics:_** [[UserDocumentationCategory]]
# <a name="Administrator Skills Assumptions"></a> Administrator Skills Assumptions
-For each of these, the requirement is either pre-existing knowledge/skill, or the willingness to spend significant time (i.e. from hours to days) learning these.
+**_Note:_** If you aren't already fairly well-skilled in Linux/Unix/Windows, Apache, and so on, consider using TWiki:Codev.TWikiVMDebianStable - this can be installed on Windows or Linux, and makes it possible to get a working TWiki system within 5 minutes (after a fairly big download), ready to use from your browser. This is ideal for personal use or evaluations - if you decide to go for production use then these AdminSkillsAssumptions apply to some degree, but you are starting from a working system.
+
+If you need to install TWiki you'll need to either have or learn the following skills (even with TWikiVMDebianStable, you'll need these for upgrades). For each of these, the requirement is either pre-existing knowledge/skill, or the willingness to spend significant time (i.e. from hours to days) learning them:
- **Operating system administration:** Ability to use Unix/Linux command line tools (or equivalent Windows tools), including ability to move/copy/delete files, change permissions, view web server log files, set environment variables, use a text editor, etc.
- **Web server administration:** Ability to do basic setup, e.g. ability to edit config files or use GUI configuration tools to enable CGI scripts on a directory.
-- **Program compilation:** _Where RCS is not pre-installed_ (that is most Unix systems), the ability to download and compile the RCS program from source, including use of `configure`, `make`, etc. This is often **not** necessary on Linux or Windows.
+- **Program compilation:** _Where Revision Control System (RCS) is not pre-installed_ (that is most Unix systems), the ability to download and compile the RCS program from source, including use of `configure`, `make`, etc. This is often **not** necessary on Linux or Windows.
- **Troubleshooting**: Ability to perform tests, inspect error logs, talk to technical support (whether in an IT department or web hosting provider) and read documentation in order to help with diagnosing installation problems.
Installing TWiki is **not** recommended for people who only know HTML and web design, unless they are willing to learn the above, or team up with someone who can handle the installation.
There are many excellent resources for learning how to administer your OS and web server, including books, web sites, web forums, IM and e-mail lists. The TWiki:Support web must **not** be depended on as a resource for this purpose - in other words, it is not there to answer basic questions about operating system and web server administration. Asking and answering questions is time consuming for all concerned and is best used for specific _TWiki related_ issues, rather than helping you learn the OS and web server.
-r.
+To get started with Linux, visit [LinuxBasics.org](http://linuxbasics.org/). LinuxBasics.org offers Linux tutorials, a mailing-list and an IRC-channel to answer questions, and links to sites with information to install and use Linux. LinuxBasics.org now also offers a downloadable Linux 'virtual machine' (LBox) that runs on Windows - you can use this as a completely safe learning environment, and feel free to make mistakes without any chance of damaging your Windows setup.
-To get started with Linux, visit <http://linuxbasics.org/>. LinuxBasics.org offers Linux tutorials, a mailing-list and an IRC-channel to answer questions, and links to sites with information to install and use Linux. A nice tool for people migrating from Windows is <http://www.MidnightCommander.org/>. It is already installed on Linux systems: try <code>**mc -ac**</code> and <code>**ESC 1**</code> to get help.
+A nice tool for people migrating from Windows is <http://www.MidnightCommander.org/>. It is already installed on Linux systems: try <code>**mc -ac**</code> and <code>**ESC 1**</code> to get help.
**_Related Topics:_** [[AdminDocumentationCategory]]
- <img src="http://www.dementia.org/twiki//view/Main/WebHome/help.gif" width="16" height="16" alt="help" /> Documentation: [[TWiki Reference Manual|Main/TWikiReferenceManual]]
- <img src="http://www.dementia.org/twiki//view/Main/WebHome/wrench.gif" width="16" height="16" alt="wrench" /> [[Site Tools|Main/TWikiSiteTools]]: [Configure](http://www.dementia.org/twiki/configure), [[TWikiPreferences]], [[InterWikis]], [[Variables|Main/TWikiVariables]], [[Doc Graphics|Main/TWikiDocGraphics]]
-- <img src="http://www.dementia.org/twiki//view/Main/WebHome/persons.gif" width="16" height="16" alt="persons" /> Manage [[Users|Main/TWikiUsers]]: [[Register|Main/TWikiRegistration]], [[NewUserTemplate]], [[UserForm]], [[ResetPassword]], [[ChangePassword]]
+- <img src="http://www.dementia.org/twiki//view/Main/WebHome/persons.gif" width="16" height="16" alt="persons" /> Manage [[Users|USERSWEB/TWikiUsers]]: [[Register|Main/TWikiRegistration]], %SYSTEMWEB%.NewUserTemplate, %SYSTEMWEB%.UserForm, [[ResetPassword]], [[ChangePassword]]
- <img src="http://www.dementia.org/twiki//view/Main/WebHome/indexlist.gif" width="16" height="16" alt="indexlist" /> Manage Content: [[Topics|Main/ManagingTopics]], [[Webs|Main/ManagingWebs]], [[YouAreHere]]
- <img src="http://www.dementia.org/twiki//view/Main/WebHome/folder.gif" width="16" height="16" alt="folder" /> Webs: <table bgcolor="#000000" border="0" cellpadding="3" cellspacing="2" width="100%">
<tr bgcolor="#99CCCC">
<tr bgcolor="#ffffff">
<td valign="top"> Legend: </td>
<td valign="top"> </td>
- <td valign="top"><img alt="Home of web" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/home.gif" width="16" /> WebHome </td>
- <td valign="top"><img alt="Search web" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/searchtopic.gif" width="16" /> WebSearch </td>
- <td valign="top"><img alt="Recent changes in the web" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/recentchanges.gif" width="16" /> WebChanges </td>
- <td valign="top"><img alt="Get notified of changes to the web" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/notify.gif" width="16" /> WebNotify </td>
+ <td valign="top"><img alt="Home of web" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/home.gif" width="16" /> WebHome </td>
+ <td valign="top"><img alt="Search web" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/searchtopic.gif" width="16" /> WebSearch </td>
+ <td valign="top"><img alt="Recent changes in the web" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/recentchanges.gif" width="16" /> WebChanges </td>
+ <td valign="top"><img alt="Get notified of changes to the web" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/notify.gif" width="16" /> WebNotify </td>
</tr>
<tr bgcolor="#ffffff">
<td valign="top"> </td>
<td valign="top"> </td>
- <td valign="top"><img alt="Preferences of web" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/wrench.gif" width="16" /> WebPreferences </td>
- <td valign="top"><img alt="Statistics of web" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/statistics.gif" width="16" /> WebStatistics </td>
- <td valign="top"><img alt="Bullet list of all topics" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/indexlist.gif" width="16" /> WebTopicList </td>
- <td valign="top"><img alt="Index of all topics" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/index.gif" width="16" /> WebIndex </td>
+ <td valign="top"><img alt="Preferences of web" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/wrench.gif" width="16" /> WebPreferences </td>
+ <td valign="top"><img alt="Statistics of web" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/statistics.gif" width="16" /> WebStatistics </td>
+ <td valign="top"><img alt="Bullet list of all topics" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/indexlist.gif" width="16" /> WebTopicList </td>
+ <td valign="top"><img alt="Index of all topics" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/index.gif" width="16" /> WebIndex </td>
</tr>
</table>
+<a name="EncodeURLsUTF8"></a>
+
+# <a name="Appendix B: Encode URLs With UTF"></a> Appendix B: Encode URLs With UTF8
+
+_Use internationalised characters within WikiWords and attachment names_
+
+This topic addresses implemented UTF-8 support for URLs only. The overall plan for UTF-8 support for TWiki is described in TWiki:Codev.ProposedUTF8SupportForI18N.
+
<div>
<ul>
<li><a href="#Appendix B: Encode URLs With UTF"> Appendix B: Encode URLs With UTF8 </a><ul>
</ul>
</div>
-<a name="EncodeURLsUTF8"></a>
-
-# <a name="Appendix B: Encode URLs With UTF"></a> Appendix B: Encode URLs With UTF8
-
-_Use internationalised characters within WikiWords and attachment names_
-
-This topic addresses implemented UTF-8 support for URLs only. The overall plan for UTF-8 support for TWiki is described in TWiki:Codev.ProposedUTF8SupportForI18N.
-
## <a name="Current Status"></a> Current Status
To simplify use of internationalised characters within [[WikiWords]] and attachment names, TWiki now supports UTF-8 URLs, converting on-the-fly to virtually any character set, including ISO-8859-\*, KOI8-R, EUC-JP, and so on.
This contrib packages the third-party `Behaviour` Javascript event library, available from <http://bennolan.com/behaviour/>.
-Behaviour is suited to create javascript based interaction that degrades well when javascript is not available.
-
-Javascript file: [behaviour.js](http://www.dementia.org/twiki//view/TWiki/%TOPIC%/behaviour.js) (8.1K). The [compressed javascript file](http://www.dementia.org/twiki//view/TWiki/%TOPIC%/behaviour.compressed.js) (2.9K) has been processed by [ShrinkSafe](http://alex.dojotoolkit.org/shrinksafe/).
+Behaviour uses CSS selectors to subscribe to javascript event handlers. This allows to create clean code, separated from HTML (and well suited to create javascript based interaction that degrades nicely when javascript is not available).
<div><span>On this page:</span><ul>
<li><a href="#Introduction"> Introduction</a></li>
- <li><a href="#Usage"> Usage</a></li>
- <li><a href="#Example"> Example</a></li>
+ <li><a href="#Usage"> Usage</a><ul>
+ <li><a href="#Example"> Example</a></li>
+ <li><a href="#Leaking danger"> Leaking danger</a></li>
+ </ul>
+ </li>
<li><a href="#Development"> Development</a></li>
<li><a href="#License"> License</a></li>
<li><a href="#Links"> Links</a></li>
+ <li><a href="#Installation Instructions"> Installation Instructions</a></li>
+ <li><a href="#Contrib Settings"> Contrib Settings</a></li>
<li><a href="#Contrib Info"> Contrib Info</a></li>
</ul>
</div>
Include the javascript file:
-> <script type="text/javascript" src="%PUBURL%/%TWIKIWEB%/BehaviourContrib/behaviour.compressed.js"></script>
+> <script type="text/javascript" src="%PUBURL%/%TWIKIWEB%/BehaviourContrib/behaviour.js"></script>
In your code you create a "rules" object, with sub-objects for each html element class name or id:
> Behaviour.register(myrules);
-## <a name="Example"></a> Example
+### <a name="Example"></a> Example
If we have a 'normal' link to TWiki Web hometopic: [[TWiki Web Home|TWiki/WebHome]], we can use javascript to make it open a popup window. When javascript is not available the link behaviour defaults to opening the page in the current window.
-> <span class="link%TWIKIWEB%%HOMETOPIC%">[[%TWIKIWEB%.%HOMETOPIC%][TWiki Web Home]]</span>
+> <div id="demoblock" style="padding:1em; width:100px; text-align:center;">
+> MOUSE OVER ME
+> </div>
>
> <script type="text/javascript">
> // <![CDATA[
> var myrules = {
-> '.link%TWIKIWEB%%HOMETOPIC% a' : function(el){
-> el.onclick = function() {
-> // open in a popup with no other attributes than template 'viewplain'
-> launchTheWindow(this.href,null,null,null,"viewplain");
+> '#demoblock' : function(el) {
+> var defaultColor = '#A3D6F8';
+> var highlightColor = '#4A7FB5';
+>
+> el.style.backgroundColor = defaultColor;
+>
+> el.onmouseover = function() {
+> this.style.backgroundColor = highlightColor;
+> return false;
+> }
+> el.onmouseout = function() {
+> this.style.backgroundColor = defaultColor;
+> return false;
+> }
+> },
+> '#demoblock span' : function(el) {
+>
+> var text = el.innerHTML;
+>
+> var fisherYates = function (inArray) {
+> var i = inArray.length;
+> if ( i == 0 ) return false;
+> while ( --i ) {
+> var j = Math.floor( Math.random() * ( i + 1 ) );
+> var tempi = inArray[i];
+> var tempj = inArray[j];
+> inArray[i] = tempj;
+> inArray[j] = tempi;
+> }
+> }
+>
+> var randomize = function(inText) {
+> var letters = inText.split('');
+> fisherYates(letters);
+> return letters.join('');
+> }
+> el.onmouseover = function() {
+> this.innerHTML = randomize(text);
+> return false;
+> }
+> el.onmouseout = function() {
+> this.innerHTML = text;
> return false;
> }
> }
> };
->
> Behaviour.register(myrules);
> // ]]>
> </script>
>
-> The class name `link%TWIKIWEB%%HOMETOPIC%` will get expanded to `linkTWikiWebHome`
-
-Creates:
-
-<span>[[TWiki Web Home|TWiki/WebHome]]</span>
-
-## <a name="Development"></a> Development
-
-- [Google Groups: Behaviour Javascript Library](http://groups.google.com/group/behaviour)
-- [Dean Edwards: Faster DOM Queries](http://dean.edwards.name/weblog/2006/03/faster/) - with a speed-up hack to Behaviour
-
-## <a name="License"></a> License
-
-Behaviour is freely distributable under the terms of an BSD license. For details, see the Behaviour website.
-
-## <a name="Links"></a> Links
-
-- [Behaviour website](http://bennolan.com/behaviour/)
-- [Behaviour Google Group](http://groups.google.com/group/behaviour)
-
-## <a name="Contrib Info"></a> Contrib Info
-
-<table border="1" cellpadding="0" cellspacing="0">
- <tr>
- <td> Author: </td>
- <td> TWiki:Main.ArthurClemens </td>
- </tr>
- <tr>
- <td> Copyright: </td>
- <td> version 1.1 - Copyright (c) Ben Nolan and Simon Willison </td>
- </tr>
- <tr>
- <td> License: </td>
- <td> BSD </td>
- </tr>
- <tr>
- <td> Dependencies: </td>
- <td> None </td>
- </tr>
- <tr>
- <td> 4 June 2006 </td>
- <td> 1.000 First Version. Included Behaviour version: 1.1 </td>
- </tr>
- <tr>
- <td align="right"> Home: </td>
- <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%</a></td>
- </tr>
- <tr>
- <td align="right"> Feedback: </td>
- <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev</a></td>
- </tr>
- <tr>
- <td align="right"> Appraisal: </td>
- <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal</a></td>
- </tr>
-</table>
-
-**_Related Topics:_** [[TWikiPreferences]]
+> Creates:
+>
+> <div id="demoblock" style="padding: 1em; width: 150px; text-align: center"><span>MOUSE OVER ME</span></div>
+>
+> ### <a name="Leaking danger"></a> Leaking danger
+>
+> Behaviour code leaks memory on Windows Explorer prior to version 7. To prevent leaking, set the element variable to
+>
+> `null`
+>
+> :
+>
+> > var myrules = {
+> > 'table.test td' : function(element) {
+> > element.onmouseover = function() {
+> > this.style.backgroundColor = highlightColor;
+> > return false;
+> > }
+> > element = null; // by setting this IE will not leak
+> > }
+> > };
+> > Behaviour.register(myrules);
+>
+> ## <a name="Development"></a> Development
+>
+> - [Google Groups: Behaviour Javascript Library](http://groups.google.com/group/behaviour)
+> - [Nabble - Behaviour Javascript Library forum & mailing list archive](http://www.nabble.com/Behaviour-Javascript-Library-f16264.html)
+> - [Behaviour2](http://groups.google.com/group/behaviour/browse_thread/thread/e9828f9fdb482ac1/8ca704730053e23f?#8ca704730053e23f) - update in the making, since 2006
+>
+> ## <a name="License"></a> License
+>
+> Behaviour is freely distributable under the terms of an BSD license. For details see the Behaviour website.
+>
+> ## <a name="Links"></a> Links
+>
+> - [Behaviour website](http://bennolan.com/behaviour/)
+> - [Behaviour Google Group](http://groups.google.com/group/behaviour)
+>
+> ## <a name="Installation Instructions"></a> Installation Instructions
+>
+> You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.
+>
+> Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.
+>
+> - If you have TWiki 4.2 or later, you can install from the `configure` interface (Go to Plugins->Find More Extensions)
+> - See the [installation supplement](http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement) on TWiki.org for more information.
+> - If you have any problems, then you can still install manually from the command-line:
+> 1. Download one of the `.zip` or `.tgz` archives
+> 2. Unpack the archive in the root directory of your TWiki installation.
+> 3. Run the installer script ( `perl <module>_installer` )
+> 4. Run `configure` and enable the module, if it is a plugin.
+> 5. Repeat for any missing dependencies.
+> - If you are **still** having problems, then instead of running the installer script:
+> 1. Make sure that the file permissions allow the webserver user to access all files.
+> 2. Check in any installed files that have existing `,v` files in your existing install (take care **not** to lock the files when you check in)
+> 3. Manually edit LocalSite.cfg to set any configuration variables.
+>
+> <div class="twikiAlert">%X% WARNING: SYSTEMWEB is not defined in this TWiki. Please add these definitions to your [[Main/TWikiPreferences]], if they are not already there:<br /><pre> * Set SYSTEMWEB = %TWIKIWEB%<br /> * Set USERSWEB = %MAINWEB%</pre></div>
+>
+> ## <a name="Contrib Settings"></a> Contrib Settings
+>
+> - Set SHORTDESCRIPTION = `Behaviour` Javascript event library to create javascript based interactions that degrade well when javascript is not available
+>
+> You can also set the global TWiki variable BEHAVIOURCONTRIB\_DEBUG to 1 to make the contrib use uncompressed javascript sources, in the event of problems.
+>
+> ## <a name="Contrib Info"></a> Contrib Info
+>
+> <table border="1" cellpadding="0" cellspacing="0">
+> <tr>
+> <td align="right"> Author: </td>
+> <td> TWiki:Main.ArthurClemens </td>
+> </tr>
+> <tr>
+> <td align="right"> Copyright: </td>
+> <td> Code: <code>behaviour.js</code> version 1.1 - Copyright (c) Ben Nolan and Simon Willison. TWiki distribution and updates/additions: TWiki:Main.ArthurClemens. </td>
+> </tr>
+> <tr>
+> <td align="right"> License: </td>
+> <td> BSD </td>
+> </tr>
+> <tr>
+> <td align="right"> Version: </td>
+> <td> 15675 (22 Jan 2008) </td>
+> </tr>
+> <tr>
+> <td align="right"> Dependencies: </td>
+> <td> None </td>
+> </tr>
+> <tr>
+> <td align="right"> Contrib Version: </td>
+> <td> 1.3.1 </td>
+> </tr>
+> <tr>
+> <td align="right"> Change History: </td>
+> <td> </td>
+> </tr>
+> <tr>
+> <td align="right"> 17 Oct 2007 </td>
+> <td> 1.3 Replaced "faster code" by other code from Dean Edwards, [[ packed by <a href="http://groups.google.com/group/behaviour/browse_thread/thread/85137977bedf5ed/3cf3ba8065d41a8c#3cf3ba8065d41a8c][Raymond" target="_top">http://groups.google.com/group/behaviour/browse_thread/thread/85137977bedf5ed/3cf3ba8065d41a8c#3cf3ba8065d41a8c][Raymond</a> Irving]]. </td>
+> </tr>
+> <tr>
+> <td align="right"> 02 Jul 2007 </td>
+> <td> 1.2 Integrated other faster code by Dean Edwards: <a href="http://dean.edwards.name/weblog/2006/06/again/" target="_top">faster onload (again)</a>. </td>
+> </tr>
+> <tr>
+> <td align="right"> 08 Mar 2007 </td>
+> <td> 1.1 Integrated code by Dean Edwards (see [[Main/WebHome#CodeUpdate]]). </td>
+> </tr>
+> <tr>
+> <td align="right"> 04 Jun 2006 </td>
+> <td> 1.0 First Version. Included Behaviour version: 1.1. </td>
+> </tr>
+> <tr>
+> <td align="right"> Home: </td>
+> <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%</a></td>
+> </tr>
+> <tr>
+> <td align="right"> Feedback: </td>
+> <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev</a></td>
+> </tr>
+> <tr>
+> <td align="right"> Appraisal: </td>
+> <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal</a></td>
+> </tr>
+> </table>
+>
+> **_Related Topics:_** [[TWikiPreferences]]
# <a name="Bulk Registration"></a> Bulk Registration
-The [[TWikiAdminGroup]] can use %TOPIC% to register (i.e. create logins and [[UserTopics]]) for a group of people quickly. Create a table in the REGISTERTOPIC named below, setting each row to represent each user and each column to correspond to the metadata. Then press the button on this page to perform registration for those users. Unlike normal registration the administrator is assumed to have correct e-mail addresses for the users, so no verification is required. Note that the new users are not notified that they have an account. This is so you can prepare and verify the accounts before announcing them. To announce them use the [[BulkResetPassword]] feature: this will assign a new random password and notify users.
+Administrators can use this topic to register (i.e. create logins and [[UserTopics]]) for a group of people quickly. Create a table in the REGISTERTOPIC named below, setting each row to represent each user and each column to correspond to the metadata. Then press the button on this page to perform registration for those users. Unlike normal registration the administrator is assumed to have correct e-mail addresses for the users, so no verification is required. Note that the new users are not notified that they have an account. This is so you can prepare and verify the accounts before announcing them. To announce them use the [[BulkResetPassword]] feature: this will assign a new random password and notify users.
## <a name="Bulk Registration usage"></a> Bulk Registration usage
### <a name="Mandatory fields"></a> Mandatory fields
-- [[WikiName]]
-- Email
+- WikiName
- FirstName
- LastName
## <a name="Settings"></a> Settings
-- - Set REGISTERTOPIC = [[UnprocessedRegistrations]]
+- Define where to pick up the table of users to register
+ - Set REGISTERTOPIC = [[UnprocessedRegistrations]]
+- Use this to define where to log the bulk registration process. It needs to be a topic name in this web.
- Set LOGTOPIC = %REGISTERTOPIC%Log
-
-- - Set OVERWRITEHOMETOPICS = 0
+- Set this to 1 to make the bulk registration overwrite any existing user topics. By default, existing user topics are left alone.
+ - Set OVERWRITEHOMETOPICS = 0
### <a name="Example format"></a> Example format
Notes:
1. The first row of the table dictates the heading format and that the fieldnames must be plain, i.e. **must not contain bolded** entries.
-2. You are responsible for ensuring that the fieldnames appear in the [[Main.UserForm|Main/UserForm]]
-3. Only members of the [[TWikiAdminGroup]] can run this.
+2. You are responsible for ensuring that the fieldnames appear in the [[TWiki.UserForm|TWiki/UserForm]]
+3. Only administrators can run this.
+
+**Sorry, the password system is currently read only, please contact 0**<br />
-<form action="http://www.dementia.org/twiki/manage/%REGISTERTOPIC%" method="post" name="bulkRegister"><input name="action" type="hidden" value="bulkRegister" /> <input type="submit" value="Bulk Register these people" /> <input name="LogTopic" type="hidden" value="%LOGTOPIC%" /> <input name="OverwriteHomeTopics" type="hidden" value="%OVERWRITEHOMETOPICS%" /></form>
+<form action="http://www.dementia.org/twiki/manage/%REGISTERTOPIC%" method="post" name="bulkRegister"><input name="action" type="hidden" value="bulkRegister" /> <input %notmodifyable%="%NOTMODIFYABLE%" type="submit" value="Bulk Register these people" /> <input name="LogTopic" type="hidden" value="%LOGTOPIC%" /> <input name="OverwriteHomeTopics" type="hidden" value="%OVERWRITEHOMETOPICS%" /></form>
## <a name="%REGISTERTOPIC%"></a> %REGISTERTOPIC%
# <a name="Bulk Reset Passwords"></a> Bulk Reset Passwords
-**The [[TWikiAdminGroup]] can use this topic to reset any number of user passwords.**
+**Administrators can use this topic to reset any number of user passwords.**
Users whose passwords are reset with this will be sent an e-mail at the address recorded **in their home topic**. The administrator will **not** be told the new passwords.
**Follow these two steps:**
-<form action="http://www.dementia.org/twiki/resetpasswd/%WEB%/%TOPIC%" method="post">
+<form action="http://www.dementia.org/twiki/manage/%WEB%/%TOPIC%" method="post">
<div>
<div>
- <h3><a name="Select users"></a> Select users </h3>
- <p>
- </p>
- <p>
- </p>
- <h1><a name="TWiki Installation Error"></a> TWiki Installation Error </h1>Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags) <p><strong><em>Note</em></strong> if you don't see all the users you expect in this table, make sure their home topic has an attached [[Main/UserForm]]. This is used to identify users. </p>
+ <h3><a name="Select users"></a> Select users </h3><strong>Sorry, the password system is currently read only, please contact 0</strong><h1><a name="TWiki Installation Error"></a> TWiki Installation Error </h1>Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags) <p><strong><em>Note</em></strong> if you don't see all the users you expect in this table, make sure their home topic has an attached [[TWiki/UserForm]]. This is used to identify users. </p>
</div>
<div>
<h3><a name="Write message"></a> Write message </h3>
Welcome! The site is ready for your use. Please use the login name and password listed below and contact me if you have any questions.
</textarea>
</div>
- <div><input name="action" type="hidden" value="resetPassword" /> <input type="submit" value="Reset selected user passwords and send message" /></div>
+ <div><input name="action" type="hidden" value="resetPassword" /> <input %notmodifyable%="%NOTMODIFYABLE%" type="submit" value="Reset selected user passwords and send message" /></div>
</div>
</form>
--- /dev/null
+# <a name="Package <code>="></a> Package =
+
+**extends** `CGI::Session::ErrorHandler `
+
+<div>
+ <ul>
+ <li><a href="#Package =="> Package ==</a></li>
+ </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session - persistent session data in CGI applications
+
+=head1 SYNOPSIS
+
+# Object initialization: use CGI::Session; $session = new CGI::Session();
+
+$CGISESSID = $session->id();
+
+# send proper HTTP header with cookies: print $session->header();
+
+# storing data in the session $session->param('f\_name', 'Sherzod'); # or $session->param(-name=>'l\_name', -value=>'Ruzmetov');
+
+# flush the data from memory to the storage driver at least before your # program finishes since auto-flushing can be unreliable $session->flush();
+
+# retrieving data my $f\_name = $session->param('f\_name'); # or my $l\_name = $session->param(-name=>'l\_name');
+
+# clearing a certain session parameter $session->clear(["l\_name", "f\_name"]);
+
+# expire '\_is\_logged\_in' flag after 10 idle minutes: $session->expire('is\_logged\_in', '+10m')
+
+# expire the session itself after 1 idle hour $session->expire('+1h');
+
+# delete the session for good $session->delete();
+
+=head1 DESCRIPTION
+
+CGI-Session is a Perl5 library that provides an easy, reliable and modular session management system across HTTP requests. Persistency is a key feature for such applications as shopping carts, login/authentication routines, and application that need to carry data across HTTP requests. CGI::Session does that and many more.
+
+=head1 TRANSLATIONS
+
+This document is also available in Japanese.
+
+=over 4
+
+=item o
+
+Translation based on 4.14: <http://digit.que.ne.jp/work/index.cgi?Perldoc/ja>
+
+=item o
+
+Translation based on 3.11, including Cookbook and Tutorial: <http://perldoc.jp/docs/modules/CGI-Session-3.11/>
+
+=back
+
+=head1 TO LEARN MORE
+
+Current manual is optimized to be used as a quick reference. To learn more both about the philosophy and CGI::Session programming style, consider the following:
+
+=over 4
+
+=item \*
+
+L<CGI::Session::Tutorial|CGI::Session::Tutorial> - extended CGI::Session manual. Also includes library architecture and driver specifications.
+
+=item \*
+
+We also provide mailing lists for CGI::Session users. To subscribe to the list or browse the archives visit <https://lists.sourceforge.net/lists/listinfo/cgi-session-user>
+
+=item \*
+
+B - "HTTP State Management Mechanism" found at <ftp://ftp.isi.edu/in-notes/rfc2965.txt>
+
+=item \*
+
+L<CGI|CGI> - standard CGI library
+
+=item \*
+
+L<Apache::Session|Apache::Session> - another fine alternative to CGI::Session.
+
+=back
+
+=head1 METHODS
+
+Following is the overview of all the available methods accessible via CGI::Session object.
+
+=head2 new()
+
+=head2 new( $sid )
+
+=head2 new( $query )
+
+=head2 new( $dsn, $query||$sid )
+
+=head2 new( $dsn, $query||$sid, \\%dsn\_args )
+
+Constructor. Returns new session object, or undef on failure. Error message is accessible through L<errstr() - class method|CGI::Session::ErrorHandler/errstr>. If called on an already initialized session will re-initialize the session based on already configured object. This is only useful after a call to L<load()|/"load">.
+
+Can accept up to three arguments, $dsn - Data Source Name, $query||$sid - query object OR a string representing session id, and finally, \\%dsn\_args, arguments used by $dsn components.
+
+If called without any arguments, $dsn defaults to I<driver:file;serializer:default;id:md5>, $query||$sid defaults to C<< CGI->new() >>, and C<\\%dsn\_args> defaults to I.
+
+If called with a single argument, it will be treated either as C<$query> object, or C<$sid>, depending on its type. If argument is a string , C<new()> will treat it as session id and will attempt to retrieve the session from data store. If it fails, will create a new session id, which will be accessible through L<id() method|/"id">. If argument is an object, L<cookie()|CGI/cookie> and L<param()|CGI/param> methods will be called on that object to recover a potential C<$sid> and retrieve it from data store. If it fails, C<new()> will create a new session id, which will be accessible through L<id() method|/"id">. C<name()> will define the name of the query parameter and/or cookie name to be requested, defaults to I.
+
+If called with two arguments first will be treated as $dsn, and second will be treated as $query or $sid or undef, depending on its type. Some examples of this syntax are:
+
+$s = CGI::Session->new("driver:mysql", undef); $s = CGI::Session->new("driver:sqlite", $sid); $s = CGI::Session->new("driver:db\_file", $query); $s = CGI::Session->new("serializer:storable;id:incr", $sid); # etc...
+
+Following data source components are supported:
+
+=over 4
+
+=item \*
+
+B - CGI::Session driver. Available drivers are L<file|CGI::Session::Driver::file>, L<db\_file|CGI::Session::Driver::db\_file>, L<mysql|CGI::Session::Driver::mysql> and L<sqlite|CGI::Session::Driver::sqlite>. Third party drivers are welcome. For driver specs consider L<CGI::Session::Driver|CGI::Session::Driver>
+
+=item \*
+
+B - serializer to be used to encode the data structure before saving in the disk. Available serializers are L<storable|CGI::Session::Serialize::storable>, L<freezethaw|CGI::Session::Serialize::freezethaw> and L<default|CGI::Session::Serialize::default>. Default serializer will use L<Data::Dumper|Data::Dumper>.
+
+=item \*
+
+B - ID generator to use when new session is to be created. Available ID generator is L<md5|CGI::Session::ID::md5>
+
+=back
+
+For example, to get CGI::Session store its data using DB\_File and serialize data using [[FreezeThaw]]:
+
+$s = new CGI::Session("driver:DB\_File;serializer:FreezeThaw", undef);
+
+If called with three arguments, first two will be treated as in the previous example, and third argument will be C<\\%dsn\_args>, which will be passed to C<$dsn> components (namely, driver, serializer and id generators) for initialization purposes. Since all the $dsn components must initialize to some default value, this third argument should not be required for most drivers to operate properly.
+
+undef is acceptable as a valid placeholder to any of the above arguments, which will force default behavior.
+
+=head2 load()
+
+=head2 load($query||$sid)
+
+=head2 load($dsn, $query||$sid)
+
+=head2 load($dsn, $query, \\%dsn\_args);
+
+Accepts the same arguments as new(), and also returns a new session object, or undef on failure. The difference is, L<new()|/"new"> can create new session if it detects expired and non-existing sessions, but C<load()> does not.
+
+C<load()> is useful to detect expired or non-existing sessions without forcing the library to create new sessions. So now you can do something like this:
+
+$s = CGI::Session->load() or die CGI::Session->errstr(); if ( $s->is\_expired ) \{ print $s->header(), $cgi->start\_html(), $cgi->p("Your session timed out! Refresh the screen to start new session!") $cgi->end\_html(); exit(0); \}
+
+if ( $s->is\_empty ) \{ $s = $s->new() or die $s->errstr; \}
+
+Notice, all I sessions are empty, but not all I sessions are expired!
+
+=head2 id()
+
+Returns effective ID for a session. Since effective ID and claimed ID can differ, valid session id should always be retrieved using this method.
+
+=head2 param($name)
+
+=head2 param(-name=E$name)
+
+Used in either of the above syntax returns a session parameter set to $name or undef if it doesn't exist. If it's called on a deleted method param() will issue a warning but return value is not defined.
+
+=head2 param($name, $value)
+
+=head2 param(-name=E$name, -value=E$value)
+
+Used in either of the above syntax assigns a new value to $name parameter, which can later be retrieved with previously introduced param() syntax. C<$value> may be a scalar, arrayref or hashref.
+
+Attempts to set parameter names that start with I will trigger a warning and undef will be returned.
+
+=head2 param\_hashref()
+
+B. Use L<dataref()|/"dataref"> instead.
+
+=head2 dataref()
+
+Returns reference to session's data table:
+
+$params = $s->dataref(); $sid = $params->\{\_SESSION\_ID\}; $name= $params->\{name\}; # etc...
+
+Useful for having all session data in a hashref, but too risky to update.
+
+=head2 save\_param()
+
+=head2 save\_param($query)
+
+=head2 save\_param($query, \\@list)
+
+Saves query parameters to session object. In other words, it's the same as calling L<param($name, $value)|/"param"> for every single query parameter returned by C<< $query->param() >>. The first argument, if present, should be either CGI object or any object which can provide param() method. If it's undef, defaults to the return value of L<query()|/"query">, which returns C<< CGI->new >>. If second argument is present and is a reference to an array, only those query parameters found in the array will be stored in the session. undef is a valid placeholder for any argument to force default behavior.
+
+=head2 load\_param()
+
+=head2 load\_param($query)
+
+=head2 load\_param($query, \\@list)
+
+Loads session parameters into a query object. The first argument, if present, should be query object, or any other object which can provide param() method. If second argument is present and is a reference to an array, only parameters found in that array will be loaded to the query object.
+
+=head2 clear()
+
+=head2 clear('field')
+
+=head2 clear(\\@list)
+
+Clears parameters from the session object.
+
+With no parameters, all fields are cleared. If passed a single parameter or a reference to an array, only the named parameters are cleared.
+
+=head2 flush()
+
+Synchronizes data in memory with the copy serialized by the driver. Call flush() if you need to access the session from outside the current session object. You should at least call flush() before your program exits.
+
+As a last resort, CGI::Session will automatically call flush for you just before the program terminates or session object goes out of scope. This automatic behavior was the recommended behavior until the 4.x series. Automatic flushing has since proven to be unreliable, and in some cases is now required in places that worked with 3.x. For further details see:
+
+<http://rt.cpan.org/Ticket/Display.html?id=17541> <http://rt.cpan.org/Ticket/Display.html?id=17299>
+
+=head2 atime()
+
+Read-only method. Returns the last access time of the session in seconds from epoch. This time is used internally while auto-expiring sessions and/or session parameters.
+
+=head2 ctime()
+
+Read-only method. Returns the time when the session was first created in seconds from epoch.
+
+=head2 expire()
+
+=head2 expire($time)
+
+=head2 expire($param, $time)
+
+Sets expiration interval relative to L<atime()|/"atime">.
+
+If used with no arguments, returns the expiration interval if it was ever set. If no expiration was ever set, returns undef. For backwards compatibility, a method named C<etime()> does the same thing.
+
+Second form sets an expiration time. This value is checked when previously stored session is asked to be retrieved, and if its expiration interval has passed, it will be expunged from the disk immediately. Passing 0 cancels expiration.
+
+By using the third syntax you can set the expiration interval for a particular session parameter, say I<~logged-in>. This would cause the library call clear() on the parameter when its time is up. Note it only makes sense to set this value to something I than when the whole session expires. Passing 0 cancels expiration.
+
+All the time values should be given in the form of seconds. Following keywords are also supported for your convenience:
+
++-----------+---------------+
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <td align="center"> alias </td>
+ <td align="center"> meaning </td>
+ </tr>
+</table>
+
++-----------+---------------+
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <td align="center"> s </td>
+ <td align="center"> Second </td>
+ </tr>
+ <tr>
+ <td align="center"> m </td>
+ <td align="center"> Minute </td>
+ </tr>
+ <tr>
+ <td align="center"> h </td>
+ <td align="center"> Hour </td>
+ </tr>
+ <tr>
+ <td align="center"> d </td>
+ <td align="center"> Day </td>
+ </tr>
+ <tr>
+ <td align="center"> w </td>
+ <td align="center"> Week </td>
+ </tr>
+ <tr>
+ <td align="center"> M </td>
+ <td align="center"> Month </td>
+ </tr>
+ <tr>
+ <td align="center"> y </td>
+ <td align="center"> Year </td>
+ </tr>
+</table>
+
++-----------+---------------+
+
+Examples:
+
+$session->expire("2h"); # expires in two hours $session->expire(0); # cancel expiration $session->expire("~logged-in", "10m"); # expires '~logged-in' parameter after 10 idle minutes
+
+Note: all the expiration times are relative to session's last access time, not to its creation time. To expire a session immediately, call L<delete()|/"delete">. To expire a specific session parameter immediately, call L<clear([$name])|/"clear">.
+
+=head2 is\_new()
+
+Returns true only for a brand new session.
+
+=head2 is\_expired()
+
+Tests whether session initialized using L<load()|/"load"> is to be expired. This method works only on sessions initialized with load():
+
+$s = CGI::Session->load() or die CGI::Session->errstr; if ( $s->is\_expired ) \{ die "Your session expired. Please refresh"; \} if ( $s->is\_empty ) \{ $s = $s->new() or die $s->errstr; \}
+
+=head2 is\_empty()
+
+Returns true for sessions that are empty. It's preferred way of testing whether requested session was loaded successfully or not:
+
+$s = CGI::Session->load($sid); if ( $s->is\_empty ) \{ $s = $s->new(); \}
+
+Actually, the above code is nothing but waste. The same effect could've been achieved by saying:
+
+$s = CGI::Session->new( $sid );
+
+L<is\_empty()|/"is\_empty"> is useful only if you wanted to catch requests for expired sessions, and create new session afterwards. See L<is\_expired()|/"is\_expired"> for an example.
+
+=head2 delete()
+
+Deletes a session from the data store and empties session data from memory, completely, so subsequent read/write requests on the same object will fail. Technically speaking, it will only set object's status to I and will trigger L<flush()|/"flush">, and flush() will do the actual removal.
+
+=head2 find( \\&code )
+
+=head2 find( $dsn, \\&code )
+
+=head2 find( $dsn, \\&code, \\%dsn\_args )
+
+Experimental feature. Executes \\&code for every session object stored in disk, passing initialized CGI::Session object as the first argument of \\&code. Useful for housekeeping purposes, such as for removing expired sessions. Following line, for instance, will remove sessions already expired, but are still in disk:
+
+The following line, for instance, will remove sessions already expired, but which are still on disk:
+
+CGI::Session->find( sub \{\} );
+
+Notice, above \\&code didn't have to do anything, because load(), which is called to initialize sessions inside find(), will automatically remove expired sessions. Following example will remove all the objects that are 10+ days old:
+
+CGI::Session->find( \\&purge ); sub purge \{ my ($session) = @\_; next if $session->is\_empty; # <-- already expired?! if ( ($session->ctime + 3600\*240) <= time() ) \{ $session->delete() or warn "couldn't remove " . $session->id . ": " . $session->errstr; \} \}
+
+B: find will not change the modification or access times on the sessions it returns.
+
+Explanation of the 3 parameters to C<find()>:
+
+=over 4
+
+=item $dsn
+
+This is the DSN (Data Source Name) used by CGI::Session to control what type of sessions you previously created and what type of sessions you now wish method C<find()> to pass to your callback.
+
+The default value is defined above, in the docs for method C<new()>, and is 'driver:file;serializer:default;id:md5'.
+
+Do not confuse this DSN with the DSN arguments mentioned just below, under \\%dsn\_args.
+
+=item \\&code
+
+This is the callback provided by you (i.e. the caller of method C<find()>) which is called by CGI::Session once for each session found by method C<find()> which matches the given $dsn.
+
+There is no default value for this coderef.
+
+When your callback is actually called, the only parameter is a session. If you want to call a subroutine you already have with more parameters, you can achieve this by creating an anonymous subroutine that calls your subroutine with the parameters you want. For example:
+
+CGI::Session->find($dsn, sub \{ my\_subroutine( @\_, 'param 1', 'param 2' ) \} ); CGI::Session->find($dsn, sub \{ $coderef->( @\_, $extra\_arg ) \} );
+
+Or if you wish, you can define a sub generator as such:
+
+sub coderef\_with\_args \{ my ( $coderef, @params ) = @\_; return sub \{ $coderef->( @\_, @params ) \}; \}
+
+CGI::Session->find($dsn, coderef\_with\_args( $coderef, 'param 1', 'param 2' ) );
+
+=item \\%dsn\_args
+
+If your $dsn uses file-based storage, then this hashref might contain keys such as:
+
+\{ Directory => Value 1, [[NoFlock]] => Value 2, UMask => Value 3 \}
+
+If your $dsn uses db-based storage, then this hashref contains (up to) 3 keys, and looks like:
+
+\{ [[DataSource]] => Value 1, User => Value 2, Password => Value 3 \}
+
+These 3 form the DSN, username and password used by DBI to control access to your database server, and hence are only relevant when using db-based sessions.
+
+The default value of this hashref is undef.
+
+=back
+
+B<Note:> find() is meant to be convenient, not necessarily efficient. It's best suited in cron scripts.
+
+=head1 MISCELLANEOUS METHODS
+
+=head2 remote\_addr()
+
+Returns the remote address of the user who created the session for the first time. Returns undef if variable REMOTE\_ADDR wasn't present in the environment when the session was created.
+
+=head2 errstr()
+
+Class method. Returns last error message from the library.
+
+=head2 dump()
+
+Returns a dump of the session object. Useful for debugging purposes only.
+
+=head2 header()
+
+Replacement for L<CGI.pm|CGI>'s header() method. Without this method, you usually need to create a CGI::Cookie object and send it as part of the HTTP header:
+
+$cookie = CGI::Cookie->new(-name=>$session->name, -value=>$session->id); print $cgi->header(-cookie=>$cookie);
+
+You can minimize the above into:
+
+print $session->header();
+
+It will retrieve the name of the session cookie from C<$session->name()> which defaults to C<$CGI::Session::NAME>. If you want to use a different name for your session cookie, do something like following before creating session object:
+
+CGI::Session->name("MY\_SID"); $session = new CGI::Session(undef, $cgi, \\%attrs);
+
+Now, $session->header() uses "MY\_SID" as a name for the session cookie.
+
+=head2 query()
+
+Returns query object associated with current session object. Default query object class is L<CGI.pm|CGI>.
+
+=head2 DEPRECATED METHODS
+
+These methods exist solely for for compatibility with CGI::Session 3.x.
+
+=head3 close()
+
+Closes the session. Using flush() is recommended instead, since that's exactly what a call to close() does now.
+
+=head1 DISTRIBUTION
+
+CGI::Session consists of several components such as L<drivers|"DRIVERS">, L<serializers|"SERIALIZERS"> and L. This section lists what is available.
+
+=head2 DRIVERS
+
+Following drivers are included in the standard distribution:
+
+=over 4
+
+=item \*
+
+L<file|CGI::Session::Driver::file> - default driver for storing session data in plain files. Full name: B<CGI::Session::Driver::file>
+
+=item \*
+
+L<db\_file|CGI::Session::Driver::db\_file> - for storing session data in [[BerkelyDB]]. Requires: L. Full name: B<CGI::Session::Driver::db\_file>
+
+=item \*
+
+L<mysql|CGI::Session::Driver::mysql> - for storing session data in [[MySQL]] tables. Requires L<DBI|DBI> and L<DBD::mysql|DBD::mysql>. Full name: B<CGI::Session::Driver::mysql>
+
+=item \*
+
+L<sqlite|CGI::Session::Driver::sqlite> - for storing session data in SQLite. Requires L<DBI|DBI> and L<DBD::SQLite|DBD::SQLite>. Full name: B<CGI::Session::Driver::sqlite>
+
+=back
+
+=head2 SERIALIZERS
+
+=over 4
+
+=item \*
+
+L<default|CGI::Session::Serialize::default> - default data serializer. Uses standard L<Data::Dumper|Data::Dumper>. Full name: B<CGI::Session::Serialize::default>.
+
+=item \*
+
+L<storable|CGI::Session::Serialize::storable> - serializes data using L. Requires L. Full name: B<CGI::Session::Serialize::storable>.
+
+=item \*
+
+L<freezethaw|CGI::Session::Serialize::freezethaw> - serializes data using L. Requires L. Full name: B<CGI::Session::Serialize::freezethaw>
+
+=item \*
+
+L<yaml|CGI::Session::Serialize::yaml> - serializes data using YAML. Requires L or L<YAML::Syck>. Full name: B<CGI::Session::Serialize::yaml>
+
+=item \*
+
+L<json|CGI::Session::Serialize::json> - serializes data using JSON. Requires L<JSON::Syck>. Full name: B<CGI::Session::Serialize::json>
+
+=back
+
+=head2 ID GENERATORS
+
+Following ID generators are available:
+
+=over 4
+
+=item \*
+
+L<md5|CGI::Session::ID::md5> - generates 32 character long hexadecimal string. Requires L<Digest::MD5|Digest::MD5>. Full name: B<CGI::Session::ID::md5>.
+
+=item \*
+
+L<incr|CGI::Session::ID::incr> - generates incremental session ids.
+
+=item \*
+
+L<static|CGI::Session::ID::static> - generates static session ids. B<CGI::Session::ID::static>
+
+=back
+
+=head1 CREDITS
+
+CGI::Session evolved to what it is today with the help of following developers. The list doesn't follow any strict order, but somewhat chronological. Specifics can be found in F file
+
+=over 4
+
+=item Andy Lester
+
+=item Brian King Emrbbking@mac.comE
+
+=item Olivier Dragon Edragon@shadnet.shad.caE
+
+=item Adam Jacob Eadam@sysadminsith.orgE
+
+=item Igor Plisco Eigor@plisco.ruE
+
+=item Mark Stosberg
+
+=item Matt [[LeBlanc]] Emleblanc@cpan.orgE
+
+=item Shawn Sorichetti
+
+=back
+
+=head1 COPYRIGHT
+
+Copyright (C) 2001-2005 Sherzod Ruzmetov Esherzodr@cpan.orgE. All rights reserved. This library is free software. You can modify and or distribute it under the same terms as Perl itself.
+
+=head1 PUBLIC CODE REPOSITORY
+
+You can see what the developers have been up to since the last release by checking out the code repository. You can browse the Subversion repository from here:
+
+<http://svn.cromedome.net/>
+
+Or check it directly with C from here:
+
+svn://svn.cromedome.net/CGI-Session
+
+=head1 SUPPORT
+
+If you need help using CGI::Session consider the mailing list. You can ask the list by sending your questions to <cgi-session-user@lists.sourceforge.net> .
+
+You can subscribe to the mailing list at <https://lists.sourceforge.net/lists/listinfo/cgi-session-user> .
+
+Bug reports can be submitted at <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=CGI-Session>
+
+=head1 AUTHOR
+
+Sherzod Ruzmetov Esherzodr@cpan.orgE, <http://author.handalak.com/>
+
+Mark Stosberg became a co-maintainer during the development of 4.0. C<markstos@cpan.org>.
+
+=head1 SEE ALSO
+
+=over 4
+
+=item \*
+
+L<CGI::Session::Tutorial|CGI::Session::Tutorial> - extended CGI::Session manual
+
+=item \*
+
+B - "HTTP State Management Mechanism" found at <ftp://ftp.isi.edu/in-notes/rfc2965.txt>
+
+=item \*
+
+L<CGI|CGI> - standard CGI library
+
+=item \*
+
+L<Apache::Session|Apache::Session> - another fine alternative to CGI::Session
+
+=back
--- /dev/null
+# <a name="Package <code>="></a> Package =
+
+<div>
+ <ul>
+ <li><a href="#Package =="> Package ==</a></li>
+ </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Driver::DBI - Base class for native DBI-related CGI::Session drivers
+
+=head1 SYNOPSIS
+
+require CGI::Session::Driver::DBI; @ISA = qw( CGI::Session::Driver::DBI );
+
+=head1 DESCRIPTION
+
+In most cases you can create a new DBI-driven CGI::Session driver by simply creating an empty driver file that inherits from CGI::Session::Driver::DBI. That's exactly what L<sqlite|CGI::Session::Driver::sqlite> does. The only reason why this class doesn't suit for a valid driver is its name isn't in lowercase. I'm serious!
+
+=head2 NOTES
+
+CGI::Session::Driver::DBI defines init() method, which makes DBI handle available for drivers in I - object attribute regardless of what C<\\%dsn\_args> were used in creating session object. Should your driver require non-standard initialization you have to re-define init() method in your F<.pm> file, but make sure to set 'Handle' - object attribute to database handle (returned by DBI->connect(...)) if you wish to inherit any of the methods from CGI::Session::Driver::DBI.
+
+=head1 STORAGE
+
+Before you can use any DBI-based session drivers you need to make sure compatible database table is created for CGI::Session to work with. Following command will produce minimal requirements in most SQL databases:
+
+CREATE TABLE sessions ( id CHAR(32) NOT NULL PRIMARY KEY, a\_session TEXT NOT NULL );
+
+Your session table can define additional columns, but the above two are required. Name of the session table is expected to be I by default. You may use a different name if you wish. To do this you have to pass I as part of your C< \\%dsn\_args >:
+
+$s = new CGI::Session("driver:sqlite", undef, \{TableName=>'my\_sessions'\}); $s = new CGI::Session("driver:mysql", undef, \{ [[TableName]]=>'my\_sessions', [[DataSource]]=>'dbi:mysql:shopping\_cart'\});
+
+=head1 DRIVER ARGUMENTS
+
+Following driver arguments are supported:
+
+=over 4
+
+=item [[DataSource]]
+
+First argument to be passed to L<DBI|DBI>->L<connect()|DBI/connect()>. If the driver makes the database connection itself, it will also explicitly disconnect from the database when the driver object is DESTROYed.
+
+=item User
+
+User privileged to connect to the database defined in C.
+
+=item Password
+
+Password of the I privileged to connect to the database defined in C
+
+=item Handle
+
+An existing L database handle object. The handle can be created on demand by providing a code reference as a argument, such as C<<sub\{DBI->connect\}>>. This way, the database connection is only created if it actually needed. This can be useful when combined with a framework plugin like L<CGI::Application::Plugin::Session>, which creates a CGI::Session object on demand as well.
+
+C will override all the above arguments, if any present.
+
+=item [[TableName]]
+
+Name of the table session data will be stored in.
+
+=back
+
+=head1 LICENSING
+
+For support and licensing information see L<CGI::Session|CGI::Session>
--- /dev/null
+# <a name="Package <code>="></a> Package =
+
+<div>
+ <ul>
+ <li><a href="#Package =="> Package ==</a></li>
+ </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Driver::db\_file - CGI::Session driver for [[BerkeleyDB]] using DB\_File
+
+=head1 SYNOPSIS
+
+$s = new CGI::Session("driver:db\_file", $sid); $s = new CGI::Session("driver:db\_file", $sid, \{FileName=>'/tmp/cgisessions.db'\});
+
+=head1 DESCRIPTION
+
+B stores session data in [[BerkelyDB]] file using L<DB\_File|DB\_File> - Perl module. All sessions will be stored in a single file, specified in I driver argument as in the above example. If I isn't given, defaults to F</tmp/cgisess.db>, or its equivalent on a non-UNIX system.
+
+If the directory hierarchy leading to the file does not exist, will be created for you.
+
+This module takes a B option which will be used if DB\_File has to create the database file for you. By default the umask is 0660.
+
+=head1 LICENSING
+
+For support and licensing information see L<CGI::Session|CGI::Session>
--- /dev/null
+# <a name="Package <code>="></a> Package =
+
+**extends** `CGI::Session::ErrorHandler`
+
+<div>
+ <ul>
+ <li><a href="#Package =="> Package ==</a></li>
+ </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Driver - CGI::Session driver specifications
+
+=head1 WARNING
+
+Version 4.0 of CGI::Session's driver specification is B backward compatible with previous specification. If you already have a driver developed to work with the previous version you're highly encouraged to upgrade your driver code to make it compatible with the current version. Fortunately, current driver specs are a lot easier to adapt to.
+
+If you need any help converting your driver to meet current specs, send me an e-mail. For support information see L<CGI::Session|CGI::Session>
+
+=head1 SYNOPSIS
+
+require CGI::Session::Driver; @ISA = qw( CGI::Session::Driver );
+
+=head1 DESCRIPTION
+
+CGI::Session::Driver is a base class for all CGI::Session's native drivers. It also documents driver specifications for those willing to write drivers for different databases not currently supported by CGI::Session.
+
+=head1 WHAT IS A DRIVER
+
+Driver is a piece of code that helps CGI::Session library to talk to specific database engines, or storage mechanisms. To be more precise, driver is a F<.pm> file that inherits from CGI::Session::Driver and defines L<retrieve()|/"retrieve($self, $sid)">, L<store()|/"store($self, $sid, $datastr)"> and L<remove()|/"remove($self, $sid)"> methods.
+
+=head2 BLUEPRINT
+
+The best way of learning the specs is to look at a blueprint of a driver:
+
+package CGI::Session::Driver::your\_driver\_name; use strict; use base qw( CGI::Session::Driver CGI::Session::ErrorHandler );
+
+sub init \{ my ($self) = @\_; # optional \}
+
+sub DESTROY \{ my ($self) = @\_; # optional \}
+
+sub store \{ my ($self, $sid, $datastr) = @\_; # Store $datastr, which is an already serialized string of data. \}
+
+sub retrieve \{ my ($self, $sid) = @\_; # Return $datastr, which was previously stored using above store() method. # Return $datastr if $sid was found. Return 0 or "" if $sid doesn't exist \}
+
+sub remove \{ my ($self, $sid) = @\_; # Remove storage associated with $sid. Return any true value indicating success, # or undef on failure. \}
+
+sub traverse \{ my ($self, $coderef) = @\_; # execute $coderef for each session id passing session id as the first and the only # argument \}
+
+1;
+
+All the attributes passed as the second argument to CGI::Session's new() or load() methods will automatically be made driver's object attributes. For example, if session object was initialized as following:
+
+$s = CGI::Session->new("driver:your\_driver\_name", undef, \{Directory=>'/tmp/sessions'\});
+
+You can access value of 'Directory' from within your driver like so:
+
+sub store \{ my ($self, $sid, $datastr) = @\_; my $dir = $self->\{Directory\}; # <-- in this example will be '/tmp/sessions' \}
+
+Optionally, you can define C<init()> method within your driver to do driver specific global initialization. C<init()> method will be invoked only once during the lifecycle of your driver, which is the same as the lifecycle of a session object.
+
+For examples of C<init()> look into the source code of native CGI::Session drivers.
+
+=head1 METHODS
+
+This section lists and describes all driver methods. All the driver methods will receive driver object ($self) as the first argument. Methods that pertain to an individual session (such as C<retrieve()>, C<store()> and C<remove()>) will also receive session id ($sid) as the second argument.
+
+Following list describes every driver method, including its argument list and what step of session's life they will be invoked. Understanding this may help driver authors.
+
+=over 4
+
+=item retrieve($self, $sid)
+
+Called whenever a specific session is requested either via C<< CGI::Session->new() >> or C<< CGI::Session->load() >> syntax. Method should try to retrieve data associated with C< $sid > and return it. In case no data could be retrieved for C< $sid > 0 (zero) or "" should be returned. undef must be returned only to signal error. Error message should be set via set\_error(), which can be inherited from L<CGI::Session::ErrorHandler|CGI::Session::ErrorHandler>.
+
+Tip: set\_error() always returns undef. Use it for your advantage.
+
+=item store($self, $sid, $datastr)
+
+Called whenever modified session data is to be stored back to disk. This happens whenever CGI::Session->flush() is called on modified session. Since CGI::Session->DESTROY() calls flush(), store() gets requested each time session object is to be terminated.
+
+C< store() > is called both to store new sessions and to update already stored sessions. It's driver author's job to figure out which operation needs to be performed.
+
+$datastr, which is passed as the third argument to represents B session data that needs to be saved.
+
+store() can return any true value indicating success or undef on failure. Error message should be passed to set\_error()
+
+=item remove($self, $sid)
+
+Called whenever session data is to be deleted, which is when CGI::Session->delete() is called. Should return any true value indicating success, undef on failure. Error message should be logged in set\_error().
+
+=item traverse($self, \\&coderef)
+
+Called only from within CGI::Session->find(). Job of traverse() is to call \\&coderef for every single session stored in disk passing session's id as the first and only argument: C<< $coderef->( $sid ) >>
+
+=item init($self)
+
+Optional. Called whenever driver object is to be initialized, which happens only once during the lifecycle of CGI::Session object. Here you can do driver-wide initialization, such as to open connection to a database server.
+
+=item DESTROY($self)
+
+Optional. Perl automatically calls this method on objects just before they are to be terminated. This gives your driver chance to close any database connections or close any open file handles.
+
+=back
+
+=head2 NOTES
+
+=over 4
+
+=item \*
+
+All driver F<.pm> files must be lowercase!
+
+=item \*
+
+DBI-related drivers are better off using L<CGI::Session::Driver::DBI|CGI::Session::Driver::DBI> as base, but don't have to.
+
+=back
+
+=head1 LICENSING
+
+For support and licensing see L<CGI::Session|CGI::Session>.
--- /dev/null
+# <a name="Package <code>="></a> Package =
+
+<div>
+ <ul>
+ <li><a href="#Package =="> Package ==</a></li>
+ </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Driver::file - Default CGI::Session driver
+
+=head1 SYNOPSIS
+
+$s = new CGI::Session(); $s = new CGI::Session("driver:file", $sid); $s = new CGI::Session("driver:file", $sid, \{Directory=>'/tmp'\});
+
+=head1 DESCRIPTION
+
+When CGI::Session object is created without explicitly setting I, I will be assumed. I - driver will store session data in plain files, where each session will be stored in a separate file.
+
+Naming conventions of session files are defined by C<$CGI::Session::Driver::file::FileName> global variable. Default value of this variable is I<cgisess\_%s>, where %s will be replaced with respective session ID. Should you wish to set your own [[FileName]] template, do so before requesting for session object:
+
+$CGI::Session::Driver::file::FileName = "%s.dat"; $s = new CGI::Session();
+
+For backwards compatibility with 3.x, you can also use the variable name C<$CGI::Session::File::FileName>, which will override the one above.
+
+=head2 DRIVER ARGUMENTS
+
+If you wish to specify a session directory, use the B option, which denotes location of the directory where session ids are to be kept. If B is not set, defaults to whatever File::Spec->tmpdir() returns. So all the three lines in the SYNOPSIS section of this manual produce the same result on a UNIX machine.
+
+If specified B does not exist, all necessary directory hierarchy will be created.
+
+By default, sessions are created with a umask of 0660. If you wish to change the umask for a session, pass a B option with an octal representation of the umask you would like for said session.
+
+=head1 NOTES
+
+If your OS doesn't support flock, you should understand the risks of going without locking the session files. Since sessions tend to be used in environments where race conditions may occur due to concurrent access of files by different processes, locking tends to be seen as a good and very necessary thing. If you still want to use this driver but don't want flock, set C<$CGI::Session::Driver::file::NoFlock> to 1 or pass C<< [[NoFlock]] => 1 >> and this driver will operate without locks.
+
+=head1 LICENSING
+
+For support and licensing see L<CGI::Session|CGI::Session>
--- /dev/null
+# <a name="Package <code>="></a> Package =
+
+**extends** `CGI::Session::Driver::DBI `
+
+<div>
+ <ul>
+ <li><a href="#Package =="> Package ==</a></li>
+ </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Driver::mysql - CGI::Session driver for [[MySQL]] database
+
+=head1 SYNOPSIS
+
+$s = new CGI::Session( "driver:mysql", $sid); $s = new CGI::Session( "driver:mysql", $sid, \{ [[DataSource]] => 'dbi:mysql:test', User => 'sherzodr', Password => 'hello' \}); $s = new CGI::Session( "driver:mysql", $sid, \{ Handle => $dbh \} );
+
+=head1 DESCRIPTION
+
+B stores session records in a [[MySQL]] table. For details see L<CGI::Session::Driver::DBI|CGI::Session::Driver::DBI>, its parent class.
+
+It's especially important for the [[MySQL]] driver that the session ID column be defined as a primary key, or at least "unique", like this:
+
+CREATE TABLE sessions ( id CHAR(32) NOT NULL PRIMARY KEY, a\_session TEXT NOT NULL );
+
+=head2 DRIVER ARGUMENTS
+
+B driver supports all the arguments documented in L<CGI::Session::Driver::DBI|CGI::Session::Driver::DBI>. In addition, I argument can optionally leave leading "dbi:mysql:" string out:
+
+$s = new CGI::Session( "driver:mysql", $sid, \{DataSource=>'shopping\_cart'\}); # is the same as: $s = new CGI::Session( "driver:mysql", $sid, \{DataSource=>'dbi:mysql:shopping\_cart'\});
+
+=head2 BACKWARDS COMPATIBILITY
+
+For backwards compatibility, you can also set the table like this before calling C<new()>. However, it is not recommended because it can cause conflicts in a persistent environment.
+
+$CGI::Session::MySQL::TABLE\_NAME = 'my\_sessions';
+
+=head1 LICENSING
+
+For support and licensing see L<CGI::Session|CGI::Session>.
--- /dev/null
+# <a name="Package <code>="></a> Package =
+
+**extends** `CGI::Session::Driver::DBI `
+
+<div>
+ <ul>
+ <li><a href="#Package =="> Package ==</a></li>
+ </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Driver::postgresql - [[PostgreSQL]] driver for CGI::Session
+
+=head1 SYNOPSIS
+
+use CGI::Session; $session = new CGI::Session("driver:PostgreSQL", undef, \{Handle=>$dbh\});
+
+=head1 DESCRIPTION
+
+CGI::Session::PostgreSQL is a L<CGI::Session|CGI::Session> driver to store session data in a [[PostgreSQL]] table.
+
+=head1 STORAGE
+
+Before you can use any DBI-based session drivers you need to make sure compatible database table is created for CGI::Session to work with. Following command will produce minimal requirements in most SQL databases:
+
+CREATE TABLE sessions ( id CHAR(32) NOT NULL PRIMARY KEY, a\_session BYTEA NOT NULL );
+
+and within your code use:
+
+use CGI::Session; $session = new CGI::Session("driver:PostgreSQL", undef, \{Handle=>$dbh, [[ColumnType]]=>"binary"\});
+
+Please note the I argument. [[PostgreSQL]]'s text type has problems when trying to hold a null character. (Known as C<"\\0"> in Perl, not to be confused with SQL I). If you know there is no chance of ever having a null character in the serialized data, you can leave off the I attribute. Using a I column type and C<< [[ColumnType]] => 'binary' >> is recommended when using L<Storable|CGI::Session::Serialize::storable> as the serializer or if there's any possibility that a null value will appear in any of the serialized data.
+
+For more details see L<CGI::Session::Driver::DBI|CGI::Session::Driver::DBI>, parent class.
+
+Also see L, which exercises different method for dealing with binary data.
+
+=head1 COPYRIGHT
+
+Copyright (C) 2002 Cosimo Streppone. All rights reserved. This library is free software and can be modified and distributed under the same terms as Perl itself.
+
+=head1 AUTHORS
+
+Cosimo Streppone <cosimo@cpan.org>, heavily based on the CGI::Session::MySQL driver by Sherzod Ruzmetov, original author of CGI::Session.
+
+Matt [[LeBlanc]] contributed significant updates for the 4.0 release.
+
+=head1 LICENSING
+
+For additional support and licensing see L<CGI::Session|CGI::Session>
--- /dev/null
+# <a name="Package <code>="></a> Package =
+
+<div>
+ <ul>
+ <li><a href="#Package =="> Package ==</a></li>
+ </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Driver::sqlite - CGI::Session driver for SQLite
+
+=head1 SYNOPSIS
+
+$s = new CGI::Session("driver:sqlite", $sid, \{DataSource=>'/my/folder/sessions.sqlt'\}); $s = new CGI::Session("driver:sqlite", $sid, \{Handle=>$dbh\});
+
+=head1 DESCRIPTION
+
+B driver stores session data in SQLite files using L<DBD::SQLite|DBD::SQLite> DBI driver. More details see L<CGI::Session::Driver::DBI|CGI::Session::Driver::DBI>, its parent class.
+
+=head1 DRIVER ARGUMENTS
+
+Supported driver arguments are I and I. B only one of these arguments can be set while creating session object.
+
+I should be in the form of C<dbi:SQLite:dbname=/path/to/db.sqlt>. If C<dbi:SQLite:> is missing it will be prepended for you. If I is present it should be database handle (C<$dbh>) returned by L<DBI::connect()|DBI/connect()>.
+
+As of version 1.7 of this driver, the third argument is B optional. Using a default database in the temporary directory is a security risk since anyone on the machine can create and/or read your session data. If you understand these risks and still want the old behavior, you can set the C option to I<'/tmp/sessions.sqlt'>.
+
+=head1 BUGS AND LIMITATIONS
+
+None known.
+
+=head1 LICENSING
+
+For support and licensing see L<CGI::Session|CGI::Session>
--- /dev/null
+# <a name="Package <code>="></a> Package =
+
+<div>
+ <ul>
+ <li><a href="#Package =="> Package ==</a></li>
+ </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::ErrorHandler - error handling routines for CGI::Session
+
+=head1 SYNOPSIS
+
+require CGI::Session::ErrorHandler @ISA = qw( CGI::Session::ErrorHandler );
+
+sub some\_method \{ my $self = shift; unless ( $some\_condition ) \{ return $self->set\_error("some\_method(): \\$some\_condition isn't met"); \} \}
+
+=head1 DESCRIPTION
+
+CGI::Session::ErrorHandler provides set\_error() and errstr() methods for setting and accessing error messages from within CGI::Session's components. This method should be used by driver developers for providing CGI::Session-standard error handling routines for their code
+
+=head2 METHODS
+
+=over 4
+
+=item set\_error($message)
+
+Implicitly defines $pkg\_name::errstr and sets its value to $message. Return value is B undef.
--- /dev/null
+# <a name="Package <code>="></a> Package =
+
+**extends** `CGI::Session::ErrorHandler `
+
+<div>
+ <ul>
+ <li><a href="#Package =="> Package ==</a></li>
+ </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::ID::incr - CGI::Session ID driver
+
+=head1 SYNOPSIS
+
+use CGI::Session; $session = new CGI::Session("id:Incr", undef, \{ Directory => '/tmp', IDFile => '/tmp/cgisession.id', IDInit => 1000, IDIncr => 2 \});
+
+=head1 DESCRIPTION
+
+CGI::Session::ID::incr is to generate auto incrementing Session IDs. Compare it with L<CGI::Session::ID::md5|CGI::Session::ID::md5>, where session ids are truly random 32 character long strings. CGI::Session::ID::incr expects the following arguments passed to CGI::Session->new() as the third argument.
+
+=over 4
+
+=item IDFile
+
+Location where auto incremented IDs are stored. This attribute is required.
+
+=item IDInit
+
+Initial value of the ID if it's the first ID to be generated. For example, if you want the ID numbers to start with 1000 as opposed to 0, that's where you should set your value. Default is C<0>.
+
+=item IDIncr
+
+How many digits each number should increment by. For example, if you want the first generated id to start with 1000, and each subsequent id to increment by 10, set I to 10 and I to 1000. Default is C<1>.
+
+=back
+
+=head1 LICENSING
+
+For support and licensing information see L<CGI::Session|CGI::Session>
--- /dev/null
+# <a name="Package <code>="></a> Package =
+
+**extends** `CGI::Session::ErrorHandler `
+
+<div>
+ <ul>
+ <li><a href="#Package =="> Package ==</a></li>
+ </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::ID::md5 - default CGI::Session ID generator
+
+=head1 SYNOPSIS
+
+use CGI::Session; $s = new CGI::Session("id:md5", undef);
+
+=head1 DESCRIPTION
+
+CGI::Session::ID::MD5 is to generate MD5 encoded hexadecimal random ids. The library does not require any arguments.
+
+=head1 LICENSING
+
+For support and licensing see L<CGI::Session|CGI::Session>
--- /dev/null
+# <a name="Package <code>="></a> Package =
+
+<div>
+ <ul>
+ <li><a href="#Package =="> Package ==</a></li>
+ </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Serialize::default - Default CGI::Session serializer
+
+=head1 DESCRIPTION
+
+This library is used by CGI::Session driver to serialize session data before storing it in disk.
+
+All the methods are called as class methods.
+
+=head1 METHODS
+
+=over 4
+
+=item freeze($class, \\%hash)
+
+Receives two arguments. First is the class name, the second is the data to be serialized. Should return serialized string on success, undef on failure. Error message should be set using C<set\_error()|CGI::Session::ErrorHandler/"set\_error()">
+
+=item thaw($class, $string)
+
+Received two arguments. First is the class name, second is the I data string. Should return thawed data structure on success, undef on failure. Error message should be set using C<set\_error()|CGI::Session::ErrorHandler/"set\_error()">
+
+=back
+
+=head1 LICENSING
+
+For support and licensing see L<CGI::Session|CGI::Session>
--- /dev/null
+# <a name="Package <code>="></a> Package =
+
+<div>
+ <ul>
+ <li><a href="#Package =="> Package ==</a></li>
+ </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Serialize::freezethaw - serializer for CGI::Session
+
+=head1 DESCRIPTION
+
+This library can be used by CGI::Session to serialize session data. Uses L<FreezeThaw|FreezeThaw>.
+
+=head1 METHODS
+
+=over 4
+
+=item freeze($class, \\%hash)
+
+Receives two arguments. First is the class name, the second is the data to be serialized. Should return serialized string on success, undef on failure. Error message should be set using C<set\_error()|CGI::Session::ErrorHandler/"set\_error()">
+
+=item thaw($class, $string)
+
+Received two arguments. First is the class name, second is the I data string. Should return thawed data structure on success, undef on failure. Error message should be set using C<set\_error()|CGI::Session::ErrorHandler/"set\_error()">
+
+=back
+
+=head1 LICENSING
+
+For support and licensing see L<CGI::Session|CGI::Session>
--- /dev/null
+# <a name="Package <code>="></a> Package =
+
+<div>
+ <ul>
+ <li><a href="#Package =="> Package ==</a></li>
+ </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Serialize::json - serializer for CGI::Session
+
+=head1 DESCRIPTION
+
+This library can be used by CGI::Session to serialize session data. Requires L<JSON::Syck|JSON::Syck>. JSON is a type of L<YAML|CGI::Session::Serialize::yaml>, with one extension: serialized JSON strings are actually valid [[JavaScript]] code that a browser can execute. Any langauge that has a YAML parser (Perl, PHP, Python, Ruby, C, etc) can also read data that has been serialized with JSON.
+
+=head1 METHODS
+
+=over 4
+
+=item freeze($class, \\%hash)
+
+Receives two arguments. First is the class name, the second is the data to be serialized. Should return serialized string on success, undef on failure. Error message should be set using C<set\_error()|CGI::Session::ErrorHandler/"set\_error()">
+
+=item thaw($class, $string)
+
+Received two arguments. First is the class name, second is the I data string. Should return thawed data structure on success, undef on failure. Error message should be set using C<set\_error()|CGI::Session::ErrorHandler/"set\_error()">
+
+=back
+
+=head1 SEE ALSO
+
+L<CGI::Session>, L<JSON::Syck>.
--- /dev/null
+# <a name="Package <code>="></a> Package =
+
+<div>
+ <ul>
+ <li><a href="#Package =="> Package ==</a></li>
+ </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Serialize::storable - Serializer for CGI::Session
+
+=head1 DESCRIPTION
+
+This library can be used by CGI::Session to serialize session data. Uses L<Storable|Storable>.
+
+=head1 METHODS
+
+=over 4
+
+=item freeze($class, \\%hash)
+
+Receives two arguments. First is the class name, the second is the data to be serialized. Should return serialized string on success, undef on failure. Error message should be set using C<set\_error()|CGI::Session::ErrorHandler/"set\_error()">
--- /dev/null
+# <a name="Package <code>="></a> Package =
+
+<div>
+ <ul>
+ <li><a href="#Package =="> Package ==</a></li>
+ </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Serialize::yaml - serializer for CGI::Session
+
+=head1 DESCRIPTION
+
+This library can be used by CGI::Session to serialize session data. It uses L<YAML|YAML>, or the faster C implementation, L<YAML::Syck|YAML::Syck> if it is available. YAML serializers exist not just for Perl but also other dynamic languages, such as PHP, Python, and Ruby, so storing session data in this format makes it easy to share session data across different languages.
+
+YAML is made to be friendly for humans to parse as well as other computer languages. It creates a format that is easier to read than the default serializer.
+
+=head1 METHODS
+
+=over 4
+
+=item freeze($class, \\%hash)
+
+Receives two arguments. First is the class name, the second is the data to be serialized. Should return serialized string on success, undef on failure. Error message should be set using C<set\_error()|CGI::Session::ErrorHandler/"set\_error()">
+
+=item thaw($class, $string)
+
+Received two arguments. First is the class name, second is the I data string. Should return thawed data structure on success, undef on failure. Error message should be set using C<set\_error()|CGI::Session::ErrorHandler/"set\_error()">
+
+=back
+
+=head1 SEE ALSO
+
+L<CGI::Session>, L, L<YAML::Syck>.
--- /dev/null
+# <a name="Package <code>="></a> Package =
+
+<div>
+ <ul>
+ <li><a href="#Package =="> Package ==</a></li>
+ </ul>
+</div>
+
+=head1 NAME
+
+CGI::Session::Tutorial - Extended CGI::Session manual
+
+=head1 STATE MAINTENANCE OVERVIEW
+
+Since HTTP is a stateless protocol, each subsequent click to a web site is treated as new request by the Web server. The server does not relate a visit with a previous one, thus all the state information from the previous requests are lost. This makes creating such applications as shopping carts, web sites requiring users to authenticate, impossible. So people had to do something about this despair situation HTTP was putting us in.
+
+For our rescue come such technologies as I and Is that help us save the users' session for a certain period. Since I and Is alone cannot take us too far (B), several other libraries have been developed to extend their capabilities and promise a more reliable solution. L<CGI::Session|CGI::Session> is one of them.
+
+Before we discuss this library, let's look at some alternative solutions.
+
+=head2 COOKIE
+
+Cookie is a piece of text-information that a web server is entitled to place in the user's hard disk, assuming a user agent (such as Internet Explorer, Mozilla, etc) is compatible with the specification. After the cookie is placed, user agents are required to send these cookies back to the server as part of the HTTP request. This way the server application ( CGI, for example ) will have a way of relating previous requests by the same user agent, thus overcoming statelessness of HTTP.
+
+Although I seem to be promising solution for the statelessness of HTTP, they do carry certain limitations, such as limited number of cookies per domain and per user agent and limited size on each cookie. User Agents are required to store at least 300 cookies at a time, 20 cookies per domain and allow 4096 bytes of storage for each cookie. They also rise several Privacy and Security concerns, the lists of which can be found on the sections B<6-"Privacy"> and B<7-"Security Considerations"> of B.
+
+=head2 QUERY STRING
+
+Query string is a string appended to URL following a question mark (?) such as:
+
+<http://my.dot.com/login.cgi?user=sherzodr;password=top-secret>
+
+As you probably guessed, it can also help you pass state information from a click to another, but how secure is it do you think, considering these URLs tend to get cached by most of the user agents and also logged in the servers access log, to which everyone can have access.
+
+=head2 HIDDEN FIELDS
+
+Hidden field is another alternative to using query strings and they come in two flavors: hidden fields used in POST methods and the ones in GET. The ones used in GET methods will turn into a true query strings once submitted, so all the disadvantages of QUERY\_STRINGs apply. Although POST requests do not have limitations of its sister-GET, the pages that hold them get cached by Web browser, and are available within the source code of the page (obviously). They also become unwieldily to manage when one has oodles of state information to keep track of ( for instance, a shopping cart or an advanced search engine).
+
+Query strings and hidden fields are also lost easily by closing the browser, or by clicking the browser's "Back" button.
+
+=head2 SERVER SIDE SESSION MANAGEMENT
+
+This technique is built upon the aforementioned technologies plus a server-side storage device, which saves the state data on the server side. Each session has a unique id associated with the data in the server. This id is also associated with the user agent either in the form of a I, a I, hidden field or any combination of the above. This is necessary to make the connection with the client and his data.
+
+Advantages:
+
+=over 4
+
+=item \*
+
+We no longer need to depend on User Agent constraints in cookie size.
+
+=item \*
+
+Sensitive data no longer need to be traveling across the network at each request (which is the case with query strings, cookies and hidden fields). The only thing that travels is the unique id generated for the session (B<5767393932698093d0b75ef614376314>, for instance), which should make no sense to third parties.
+
+=item \*
+
+User will not have sensitive data stored in his/her computer in unsecured file (which is a cookie file).
+
+=item \*
+
+It's possible to handle very big and even complex data structures transparently (which I do not handle).
+
+=back
+
+That's what CGI::Session is all about - implementing server side session management. Now is a good time to get feet wet.
+
+=head1 PROGRAMMING STYLE
+
+Server side session management system might be seeming awfully convoluted if you have never dealt with it. Fortunately, with L<CGI::Session|CGI::Session> all the complexity is handled by the library transparently. This section of the manual can be treated as an introductory tutorial to both logic behind session management, and to CGI::Session programming style.
+
+All applications making use of server side session management rely on the following pattern of operation regardless of the way the system is implemented:
+
+=over 4
+
+=item 1
+
+Check if the user has session cookie dropped in his computer from previous request
+
+=item 2
+
+If the cookie does not exist, create a new session identifier, and drop it as cookie to the user's computer.
+
+=item 3
+
+If session cookie exists, read the session ID from the cookie and load any previously saved session data from the server side storage. If session had any expiration date set it's useful to re-drop the same cookie to the user's computer so its expiration time will be reset to be relative to user's last activity time.
+
+=item 4
+
+Store any necessary data in the session that you want to make available for the next HTTP request.
+
+=back
+
+CGI::Session will handle all of the above steps. All you have to do is to choose what to store in the session.
+
+=head2 GETTING STARTED
+
+To make L<CGI::Session|CGI::Session>'s functionality available in your program do either of the following somewhere on top of your program file:
+
+use CGI::Session; # or require CGI::Session;
+
+Whenever you're ready to create a new session in your application, do the following:
+
+$session = new CGI::Session() or die CGI::Session->errstr;
+
+Above line will first try to re-initialize an existing session by consulting cookies and necessary QUERY\_STRING parameters. If it fails will create a brand new session with a unique ID, which is normally called I, I for short, and can be accessed through L<id()|CGI::Session/id()> - object method.
+
+We didn't check for any session cookies above, did we? No, we didn't, but CGI::Session did. It looked for a cookie called C, and if it found it tried to load existing session from server side storage (B in our case). If cookie didn't exist it looked for a QUERY\_STRING parameter called C. If all the attempts to recover session ID failed, it created a new session.
+
+NOTE: For the above syntax to work as intended your application needs to have write access to your computer's I folder, which is usually F in UNIX. If it doesn't, or if you wish to store this application's session files in a different place, you may pass the third argument like so:
+
+$session = new CGI::Session(undef, undef, \{Directory=>'../tmp/sessions'\});
+
+Now it will store all the newly created sessions in (and will attempt to initialize requested sessions from) that folder. Don't worry if the directory hierarchy you want to use doesn't already exist. It will be created for you. For details on how session data are stored refer to L<CGI::Session::Driver::file|CGI::Session::Driver::file>, which is the default driver used in our above example.
+
+There is one small, but very important thing your application needs to perform after creating CGI::Session object as above. It needs to drop Session ID as an I into the user's computer. CGI::Session will use this cookie to identify the user at his/her next request and will be able to load his/her previously stored session data.
+
+To make sure CGI::Session will be able to read your cookie at next request you need to consult its C<name()> method for cookie's suggested name:
+
+$cookie = $query->cookie( -name => $session->name, -value => $session->id ); print $query->header( -cookie=>$cookie );
+
+C<name()> returns C by default. If you prefer a different cookie name, you can change it as easily too, but you have to do it before CGI::Session object is created:
+
+CGI::Session->name("SID"); $session = new CGI::Session();
+
+Baking the cookie wasn't too difficult, was it? But there is an even easier way to send a cookie using CGI::Session:
+
+print $session->header();
+
+The above will create the cookie using L<CGI::Cookie|CGI::Cookie> and will return proper http headers using L<CGI.pm|CGI>'s L<CGI|CGI/header()> method. Any arguments to L<CGI::Session|CGI::Session/header()> will be passed to L<CGI::header()|CGI/header()>.
+
+Of course, this method of initialization will only work if client is accepting cookies. If not you would have to pass session ID in each URL of your application as QUERY\_STRING. For CGI::Session to detect it the name of the parameter should be the same as returned by L<name()|CGI::Session/name()>:
+
+printf ("[click me](\"$ENV{SCRIPT_NAME}?%s=%s\")", $session->name, $session->id);
+
+If you already have session id to be initialized you may pass it as the only argument, or the second argument of multi-argument syntax:
+
+$session = new CGI::Session( $sid ); $session = new CGI::Session( "serializer:freezethaw", $sid ); $session = new CGI::Session( "driver:mysql", $sid, \{Handle=>$dbh\} );
+
+By default CGI::Session uses standard L<CGI|CGI> to parse queries and cookies. If you prefer to use a different, but compatible object you can pass that object in place of $sid:
+
+$cgi = new CGI::Simple(); $session = new CGI::Session ( $cgi ); $session = new CGI::Session( "driver:db\_file;serializer:storable", $cgi); # etc
+
+See L<CGI::Simple|CGI::Simple>
+
+=head2 STORING DATA
+
+L<CGI::Session|CGI::Session> offers L<param() method|CGI::Session/param()>, which behaves exactly as L<CGI.pm's param()|CGI/param()> with identical syntax. L<param()|CGI::Session/param()> is used for storing data in session as well as for accessing already stored data.
+
+Imagine your customer submitted a login form on your Web site. You, as a good host, wanted to remember the guest's name, so you can a) greet him accordingly when he visits your site again, or b) to be helpful by filling out I part of his login form, so the customer can jump right to the I field without having to type his username again.
+
+my $name = $cgi->param('username'); $session->param('username', $name);
+
+Notice, we're grabbing I value of the field using CGI.pm's (or another compatible library's) C<param()> method, and storing it in session using L<CGI::Session|CGI::Session>'s L<param()|CGI::Session/param()> method.
+
+If you have too many stuff to transfer into session, you may find yourself typing the above code over and over again. I've done it, and believe me, it gets very boring too soon, and is also error-prone. So we introduced the following handy method:
+
+$session->save\_param(['name']);
+
+If you wanted to store multiple form fields just include them all in the second list:
+
+$session->save\_param(['name', 'email']);
+
+If you want to store all the available I parameters you can omit the arguments:
+
+$session->save\_param();
+
+See L<save\_param()|CGI::Session/save\_param> for more details.
+
+When storing data in the session you're not limited to strings. You can store arrays, hashes and even most objects. You will need to pass them as references (except objects).
+
+For example, to get all the selected values of a scrolling list and store it in the session:
+
+my @fruits = $cgi->param('fruits'); $session->param('fruits', \\@fruits);
+
+For parameters with multiple values save\_param() will do the right thing too. So the above is the same as:
+
+$session->save\_param($cgi, ['fruits']);
+
+All the updates to the session data using above methods will not reflect in the data store until your application exits, or C<$session> goes out of scope. If, for some reason, you need to commit the changes to the data store before your application exits you need to call L<flush()|CGI::Session/flush()> method:
+
+$session->flush();
+
+I've written a lot of code, and never felt need for using C<flush()> method, since CGI::Session calls this method at the end of each request. There are, however, occasions I can think of one may need to call L<flush()|CGI::Session/flush()>.
+
+=head2 ACCESSING STORED DATA
+
+There's no point of storing data if you cannot access it. You can access stored session data by using the same L<param() method|CGI::Session/param()> you once used to store them. Remember the Username field from the previous section that we stored in the session? Let's read it back so we can partially fill the Login form for the user:
+
+$name = $session->param("name"); printf "
+
+<input name="\"name\"" type="\"text\"" value="\"%s\"" />
+
+", $name;
+
+To retrieve previously stored @fruits do not forget to de reference it:
+
+@fruits = @\{ $session->param('fruits') \};
+
+Very frequently, you may find yourself having to create pre-filled and pre-selected forms, like radio buttons, checkboxes and drop down menus according to the user's preferences or previous action. With text and textareas it's not a big deal - you can simply retrieve a single parameter from the session and hard code the value into the text field. But how would you do it when you have a group of radio buttons, checkboxes and scrolling lists? For this purpose, CGI::Session provides L<load\_param()|CGI::Session/load\_param()> method, which loads given session parameters to a CGI object (assuming they have been previously saved with L<save\_param()|CGI::Session/save\_param()> or alternative):
+
+$session->load\_param($cgi, ["fruits"]);
+
+Now when you say:
+
+print $cgi->checkbox\_group(fruits=>['apple', 'banana', 'apricot']);
+
+See L<load\_param()|CGI::Session/load\_param()> for details.
+
+Generated checkboxes will be pre-filled using previously saved information. To see example of a real session-powered application consider <http://handalak.com/cgi-bin/subscriptions.cgi>
+
+If you're making use of L<HTML::Template|HTML::Template> to separate the code from the skin, you can as well associate L<CGI::Session|CGI::Session> object with HTML::Template and access all the parameters from within HTML files. We love this trick!
+
+$template = new HTML::Template(filename=>"some.tmpl", associate=>$session); print $template->output();
+
+Assuming the session object stored "first\_name" and "email" parameters while being associated with HTML::Template, you can access those values from within your "some.tmpl" file now:
+
+Hello [ ](mailto:<TMPL_VAR email>)!
+
+See L<HTML::Template's online manual|HTML::Template> for details.
+
+=head2 CLEARING SESSION DATA
+
+You store session data, you access session data and at some point you will want to clear certain session data, if not all. For this purpose L<CGI::Session|CGI::Session> provides L<clear()|CGI::Session/clear()> method which optionally takes one argument as an arrayref indicating which session parameters should be deleted from the session object:
+
+$session->clear(["~logged-in", "email"]);
+
+Above line deletes "~logged-in" and "email" session parameters from the session. And next time you say:
+
+$email = $session->param("email");
+
+it returns undef. If you omit the argument to L<clear()|CGI::Session/clear()>, be warned that all the session parameters you ever stored in the session object will get deleted. Note that it does not delete the session itself. Session stays open and accessible. It's just the parameters you stored in it gets deleted
+
+See L<clear()|CGI::Session/clear()> for details.
+
+=head2 DELETING A SESSION
+
+If there's a start there's an end. If session could be created, it should be possible to delete it from the disk for good:
+
+$session->delete();
+
+The above call to L<delete()|CGI::Session/delete()> deletes the session from the disk for good. Do not confuse it with L<clear()|CGI::Session/clear()>, which only clears certain session parameters but keeps the session open.
+
+See L<delete()|CGI::Session/delete()> for details.
+
+=head2 EXPIRATION
+
+L<CGI::Session|CGI::Session> provides limited means to expire sessions. Expiring a session is the same as deleting it via delete(), but deletion takes place automatically. To expire a session, you need to tell the library how long the session would be valid after the last access time. When that time is met, CGI::Session refuses to retrieve the session. It deletes the session and returns a brand new one. To assign expiration ticker for a session, use L<expire()|CGI::Session/expire()>:
+
+$session->expire(3600); # expire after 3600 seconds $session->expire('+1h'); # expire after 1 hour $session->expire('+15m'); # expire after 15 minutes $session->expire('+1M'); # expire after a month and so on.
+
+When session is set to expire at some time in the future, but session was not requested at or after that time has passed it will remain in the disk. When expired session is requested CGI::Session will remove the data from disk, and will initialize a brand new session.
+
+See L<expire()|CGI::Session/expire()> for details.
+
+Before CGI::Session 4.x there was no way of intercepting requests to expired sessions. CGI::Session 4.x introduced new kind of constructor, L<load()|CGI::Session/load()>, which is identical in use to L<new()|CGI::Session/new()>, but is not allowed to create sessions. It can only load them. If session is found to be expired, or session does not exist it will return an empty CGI::Session object. And if session is expired, in addition to being empty, its status will also be set to expired. You can check against these conditions using L<empty()|CGI::Session/empty()> and L<is\_expired()|CGI::Session/is\_expired()> methods. If session was loaded successfully object returned by C<load()> is as good a session as the one returned by C<new()>:
+
+$session = CGI::Session->load() or die CGI::Session->errstr; if ( $session->is\_expired ) \{ die "Your session expired. Please refresh your browser to re-start your session"; \} if ( $session->is\_empty ) \{ $session = $session->new(); \}
+
+Above example is worth an attention. Remember, all expired sessions are empty sessions, but not all empty sessions are expired sessions. Following this rule we have to check with C<is\_expired()> before checking with C<is\_empty()>. There is another thing about the above example. Notice how its creating new session when un existing session was requested? By calling C<new()> as an object method! Handy thing about that is, when you call C<new()> on a session object new object will be created using the same configuration as the previous object.
+
+For example:
+
+$session = CGI::Session->load("driver:mysql;serializer:storable", undef, \{Handle=>$dbh\}); if ( $session->is\_expired ) \{ die "Your session is expired. Please refresh your browser to re-start your session"; \} if ( $session->is\_empty ) \{ $session = $session->new(); \}
+
+Initial C<$session> object was configured with B as the driver, B as the serializer and B<$dbh> as the database handle. Calling C< new() > on this object will return an object of the same configuration. So C< $session > object returned from C< new() > in the above example will use B as the driver, B as the serializer and B<$dbh> as the database handle.
+
+See L<is\_expired()|CGI::Session/is\_expired()>, L<is\_empty()|CGI::Session/is\_empty()>, L<load()|CGI::Session/load()> for details.
+
+Sometimes it makes perfect sense to expire a certain session parameter, instead of the whole session. I usually do this in my login enabled sites, where after the user logs in successfully, I set his/her "\_logged\_in" session parameter to true, and assign an expiration ticker on that flag to something like 30 minutes. It means, after 30 idle minutes CGI::Session will L<clear|CGI::Session/clear()> "\_logged\_in" flag, indicating the user should log in over again. I agree, the same effect can be achieved by simply expiring() the session itself, but by doing this we would loose other session parameters, such as user's shopping cart, session-preferences and the like.
+
+This feature can also be used to simulate layered authentication, such as, you can keep the user's access to his/her personal profile information for as long as 60 minutes after a successful login, but expire his/her access to his credit card information after 5 idle minutes. To achieve this effect, we will use L<expire()|CGI::Session/expire()> method again:
+
+$session->expire(\_profile\_access, '1h'); $session->expire(\_cc\_access, '5m');
+
+With the above syntax, the person will still have access to his personal information even after 5 idle hours. But when he tries to access or update his/her credit card information, he may be displayed a "login again, please" screen.
+
+See L<expire()|CGI::Session/expire()> for details.
+
+This concludes our discussion of CGI::Session programming style. The rest of the manual covers some L<"SECURITY"> issues. Driver specs from the previous manual were moved to L<CGI::Session::Driver|CGI::Session::Driver>.
+
+=head1 SECURITY
+
+"How secure is using CGI::Session?", "Can others hack down people's sessions using another browser if they can get the session id of the user?", "Are the session ids easy to guess?" are the questions I find myself answering over and over again.
+
+=head2 STORAGE
+
+Security of the library does in many aspects depend on the implementation. After making use of this library, you no longer have to send all the information to the user's cookie except for the session id. But, you still have to store the data in the server side. So another set of questions arise, can an evil person get access to session data in your server, even if he does, can he make sense out of the data in the session file, and even if he can, can he reuse the information against a person who created that session. As you see, the answer depends on yourself who is implementing it.
+
+=over 4
+
+=item \*
+
+First rule of thumb, do not store users' passwords or other sensitive data in the session, please. If you have to, use one-way encryption, such as md5, or SHA-1-1. For my own experience I can assure you that in properly implemented session-powered Web applications there is never a need for it.
+
+=item \*
+
+Default configuration of the driver makes use of L<Data::Dumper|Data::Dumper> class to serialize data to make it possible to save it in the disk. Data::Dumper's result is a human readable data structure, which, if opened, can be interpreted easily. If you configure your session object to use either L<Storable|CGI::Session::Serialize::storable> or L<FreezeThaw|CGI::Session::Serialize::freezethaw> as a serializer, this would make it more difficult for bad guys to make sense out of session data. But don't use this as the only precaution. Since evil fingers can type a quick program using L<Storable|Storable> or L<FreezeThaw|FreezeThaw> to decipher session files very easily.
+
+=item \*
+
+Do not allow anyone to update contents of session files. If you're using L serialized data string needs to be eval()ed to bring the original data structure back to life. Of course, we use L<Safe|Safe> to do it safely, but your cautiousness does no harm either.
+
+=item \*
+
+Do not keep sessions open for very long. This will increase the possibility that some bad guy may have someone's valid session id at a given time (acquired somehow). To do this use L<expire()|CGI::Session/expire()> method to set expiration ticker. The more sensitive the information on your Web site is, the sooner the session should be set to expire.
+
+=back
+
+=head2 SESSION IDs
+
+Session ids are not easily guessed (unless you're using L)! Default configuration of CGI::Session uses L<Digest::MD5|CGI::Session::ID::md5> to generate random, 32 character long identifier. Although this string cannot be guessed as easily by others, if they find it out somehow, can they use this identifier against the other person?
+
+Consider the scenario, where you just give someone either via email or an instant messaging a link to a Web site where you're currently logged in. The URL you give to that person contains a session id as part of a query string. If the site was initializing the session solely using query string parameter, after clicking on that link that person now appears to that site as you, and might have access to all of your private data instantly.
+
+Even if you're solely using cookies as the session id transporters, it's not that difficult to plant a cookie in the cookie file with the same id and trick the web browser to send that particular session id to the server. So key for security is to check if the person who's asking us to retrieve a session data is indeed the person who initially created the session data.
+
+One way to help with this is by also checking that the IP address that the session is being used from is always same. However, this turns out not to be practical in common cases because some large ISPs (such as AOL) use proxies which cause each and every request from the same user to come from different IP address.
+
+If you have an application where you are sure your users' IPs are constant during a session, you can consider enabling an option to make this check:
+
+use CGI::Session ( '-ip\_match' );
+
+For backwards compatibility, you can also achieve this by setting $CGI::Session::IP\_MATCH to a true value. This makes sure that before initializing a previously stored session, it checks if the ip address stored in the session matches the ip address of the user asking for that session. In which case the library returns the session, otherwise it dies with a proper error message.
+
+=head1 LICENSING
+
+For support and licensing see L<CGI::Session|CGI::Session>
If your old e-mail addresses are all invalid (you can't receive mail there any more) and you have forgotten your password, please contact 0 for help.
-<form action="http://www.dementia.org/twiki/passwd/%WEB%/%TOPIC%" method="post" name="passwd">
+<form action="http://www.dementia.org/twiki/manage/%WEB%/%TOPIC%" method="post" name="manage">
<div>
- <div><strong>After submitting this form your e-mail will be changed, and you will be returned to this form.</strong></div>
+ <div><strong>Sorry, the password system is currently read only, please contact 0</strong></div>
<div> Registered e-mail addresses for currently logged in user (<code>admin</code>): </div>
<div>
- <table border="0" cellpadding="0" cellspacing="0" style="border-width: 0px">
+ <table border="0" cellpadding="0" cellspacing="0" rules="none" style="border-width: 0px">
<tr>
- <td style="border-width: 0px"> </td>
- <td style="border-width: 0px"> Fields marked <code><font color="red">**</font></code> are required </td>
+ <td bgcolor="transparent" style=""> </td>
+ <td bgcolor="transparent" style=""> Fields marked <code><font color="red">**</font></code> are required </td>
</tr>
<tr>
- <td align="right" style="border-width: 0px"> Your [[TWiki/LoginName]]: </td>
- <td style="border-width: 0px"><input name="username" size="40" type="text" value="admin" /> <code><font color="red">**</font></code></td>
+ <td align="right" bgcolor="transparent" style=""> Your [[TWiki/LoginName]]: </td>
+ <td bgcolor="transparent" style=""><input %notmodifyable%="%NOTMODIFYABLE%" name="username" size="40" type="text" value="admin" /> <code><font color="red">**</font></code></td>
</tr>
<tr>
- <td align="right" style="border-width: 0px"> Password: </td>
- <td style="border-width: 0px"><input name="oldpassword" size="40" type="password" value="" /> <code><font color="red">**</font></code></td>
+ <td align="right" bgcolor="transparent" style=""> Password: </td>
+ <td bgcolor="transparent" style=""><input %notmodifyable%="%NOTMODIFYABLE%" name="oldpassword" size="40" type="password" value="" /> <code><font color="red">**</font></code></td>
</tr>
<tr>
- <td align="right" style="border-width: 0px"> New e-mails (space-separated list): </td>
- <td style="border-width: 0px"><input name="email" size="40" type="text" /> <code><font color="red">**</font></code></td>
+ <td align="right" bgcolor="transparent" style=""> New e-mails (space-separated list): </td>
+ <td bgcolor="transparent" style=""><input %notmodifyable%="%NOTMODIFYABLE%" name="email" size="40" type="text" /> <code><font color="red">**</font></code></td>
</tr>
</table>
</div>
- <div><input name="TopicName" type="hidden" value="%TOPIC%" /> <input name="action" type="hidden" value="changePassword" /> <input type="submit" value="Change e-mail address" /></div>
+ <div><input name="TopicName" type="hidden" value="%TOPIC%" /> <input name="action" type="hidden" value="changePassword" /> <input %notmodifyable%="%NOTMODIFYABLE%" type="submit" value="Change e-mail address" /></div>
</div>
</form>
<div>
<ul>
- <li><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> If you have any questions, please contact 0. </li>
- <li><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> [[Main/TWikiUsers]] has a list of other TWiki users. </li>
+ <li><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> If you have any questions, please contact 0 </li>
+ <li><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> [[Main/TWikiUsers]] has a list of other TWiki users </li>
</ul>
</div>
**_Related topics:_** [[ChangePassword]], [[ResetPassword]], [[UserToolsCategory]], [[AdminToolsCategory]]
-
-<table bgcolor="yellow">
- <tr>
- <td><strong><em>Note to administrator:</em></strong> This form applies only if TWiki uses a {PasswordManager} that supports storing e-mails (e.g. TWiki::Users::HtPasswdUser). Otherwise replace this topic with a note describing how to change registered e-mail in your organization). </td>
- </tr>
-</table>
**_Forgotten your password?_** Use [[ResetPassword]] instead.
-<form action="http://www.dementia.org/twiki/passwd/TWiki/WebHome" method="post" name="passwd">
+<form action="http://www.dementia.org/twiki/manage/TWiki/WebHome" method="post" name="manage">
<div>
- <div><strong>After submitting this form your password will be changed.</strong></div>
+ <div><strong>Sorry, the password system is currently read only, please contact 0</strong></div>
<div>
- <table border="0" cellpadding="0" cellspacing="0" style="border-width: 0px">
+ <table border="0" cellpadding="0" cellspacing="0" rules="none" style="border-width: 0px">
<tr>
- <td colspan="2" style="border-width: 0px"> Fields marked <code><font color="red">**</font></code> are required </td>
+ <td bgcolor="transparent" colspan="2" style=""> Fields marked <code><font color="red">**</font></code> are required </td>
</tr>
<tr>
- <td align="right" style="border-width: 0px"> Your [[TWiki/LoginName]]: </td>
- <td style="border-width: 0px"><input name="username" size="40" type="text" value="admin" /> <code><font color="red">**</font></code></td>
+ <td align="right" bgcolor="transparent" style=""> Your [[TWiki/LoginName]]: </td>
+ <td bgcolor="transparent" style=""><input %notmodifyable%="%NOTMODIFYABLE%" name="username" size="40" type="text" value="admin" /> <code><font color="red">**</font></code></td>
</tr>
<tr>
- <td align="right" style="border-width: 0px"> Current password: </td>
- <td style="border-width: 0px"><input name="oldpassword" size="40" type="password" value="" /> <code><font color="red">**</font></code></td>
+ <td align="right" bgcolor="transparent" style=""> Current password: </td>
+ <td bgcolor="transparent" style=""><input %notmodifyable%="%NOTMODIFYABLE%" name="oldpassword" size="40" type="password" value="" /> <code><font color="red">**</font></code></td>
</tr>
<tr>
- <td align="right" style="border-width: 0px"> New password: </td>
- <td style="border-width: 0px"><input name="password" size="40" type="password" /> <code><font color="red">**</font></code></td>
+ <td align="right" bgcolor="transparent" style=""> New password: </td>
+ <td bgcolor="transparent" style=""><input %notmodifyable%="%NOTMODIFYABLE%" name="password" size="40" type="password" /> <code><font color="red">**</font></code></td>
</tr>
<tr>
- <td align="right" style="border-width: 0px"> Retype new password: </td>
- <td style="border-width: 0px"><input name="passwordA" size="40" type="password" /> <code><font color="red">**</font></code></td>
+ <td align="right" bgcolor="transparent" style=""> Retype new password: </td>
+ <td bgcolor="transparent" style=""><input %notmodifyable%="%NOTMODIFYABLE%" name="passwordA" size="40" type="password" /> <code><font color="red">**</font></code></td>
</tr>
</table>
</div>
- <div><input name="TopicName" type="hidden" value="%TOPIC%" /> <input name="action" type="hidden" value="changePassword" /> <input type="submit" value="Change password" /></div>
+ <div><input name="TopicName" type="hidden" value="%TOPIC%" /> <input name="action" type="hidden" value="changePassword" /> <input %notmodifyable%="%NOTMODIFYABLE%" type="submit" value="Change password" /></div>
</div>
</form>
<div>
<ul>
- <li><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> If you have any questions, please contact 0. </li>
- <li><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> [[Main/TWikiUsers]] has a list of other TWiki users. </li>
+ <li><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> If you have any questions, please contact 0 </li>
+ <li><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> [[Main/TWikiUsers]] has a list of other TWiki users </li>
</ul>
</div>
**_Related topics:_** [[ResetPassword]], [[ChangeEmailAddress]], [[UserToolsCategory]], [[AdminToolsCategory]]
-
-<table bgcolor="yellow">
- <tr>
- <td><strong><em>Note to administrator:</em></strong> This form applies only if TWiki uses a {PasswordManager} that supports changing passwords. Otherwise replace this topic with a note describing how to change the password in your organization. See [[Main/TWikiUserAuthentication]] for more information. </td>
- </tr>
-</table>
# <a name="Classic Skin"></a> Classic Skin
-The classic TWiki skin is the traditional TWiki skin, as seen in previous TWiki versions.
+The classic TWiki skin is a bare bone and functional skin, supporting any browser, and has a minimum of graphics
+
+This is not really a skin. It is the set of default templates, shown if no skin is activated. The default templates are part of every TWiki distribution.
## <a name="Skin Info"></a> Skin Info
<table border="1" cellpadding="0" cellspacing="0">
<tr>
<td align="right"> Description: </td>
- <td> Bare bone and functional, for any browser, with a minimum of graphics </td>
+ <td> The classic TWiki skin, bare bone and functional, for any browser, with a minimum of graphics </td>
</tr>
<tr>
<td align="right"> Screenshot: </td>
<td><a href="http://www.dementia.org/twiki//view/fullscreen.gif"><img alt="Click for full screen image" height="130" src="http://www.dementia.org/twiki//view/screenshot.gif" width="600" /></a></td>
</tr>
<tr>
- <td align="right"> Preview: </td>
- <td>[[%WEB%/%TOPIC%?skin=classic]]</td>
- </tr>
- <tr>
<td align="right"> Base Name: </td>
<td> classic </td>
</tr>
</tr>
<tr>
<td align="right"> Skin Version: </td>
- <td> 25 Jul 2004 (v1.000) </td>
+ <td> 21 May 2007 (v1.001) </td>
</tr>
<tr>
<td align="right"> Change History: </td>
<td> </td>
</tr>
<tr>
+ <td align="right"> 21 May 2007 </td>
+ <td> Bugs:Item3969 - 8bit email fix (TWiki:Main.WillNorris) </td>
+ </tr>
+ <tr>
<td align="right"> 25 Jul 2004: </td>
<td> Initial version (v1.000) </td>
</tr>
<td align="right"> Feedback: </td>
<td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev</a></td>
</tr>
- <tr>
- <td align="right"> Appraisal: </td>
- <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal</a></td>
- </tr>
</table>
**_Note:_** The Description, Screenshot and Base Name rows are needed by the [[TWikiSkinBrowser]]
-**_Related topic:_** [[TWikiSkins]], [[TWikiSkinBrowser]], [[UserDocumentationCategory]], [[AdminDocumentationCategory]]
+**_Related topic:_** [[TWikiSkins]], [[TWikiSkinBrowser]]
+
+-- TWiki:Main/PeterThoeny - 25 Jul 2004
**Comment Plugin lets users quickly post comments to a page without an edit/preview/save cycle.**
-<div style="background-color: #ffc">WARNING: TWiki-4 only. If you want to use this plugin with an earlier version of TWiki, please use <a href="http://twiki.org/cgi-bin/attach/Plugins/CommentPlugin?filename=CommentPlugin.zip&revInfo=1" target="_top">revision 31 of the zip</a>.</div>
-
-<div>
- <ul>
+<div><span>On this page:</span><ul>
<li><a href="#Features"> Features</a></li>
- <li><a href="#Syntax Rules"> Syntax Rules</a><ul>
+ <li><a href="#Syntax"> Syntax</a><ul>
<li><a href="#Positioning the comment"> Positioning the comment</a><ul>
<li><a href="#Location relative to %COMMENT ta"> Location relative to <code>%COMMENT</code> tag</a></li>
<li><a href="#Location relative to a TWiki anc"> Location relative to a TWiki anchor</a></li>
<li><a href="#The <code>PROMPT</code> template"> The PROMPT template</a><ul>
<li><a href="#Providing attribute values"> Providing attribute values</a></li>
<li><a href="#Special variables"> Special variables</a></li>
+ <li><a href="#Customisation example with custo"> Customisation example with custom form template</a></li>
</ul>
</li>
<li><a href="#The <code>OUTPUT</code> template"> The OUTPUT template</a></li>
</ul>
</div>
+Related topics: [[CommentPluginTemplates]], [[CommentPluginExamples]]
+
+<div style="background-color: #ffc">WARNING: TWiki-4 only. If you want to use this plugin with an earlier version of TWiki, please use <a href="http://twiki.org/cgi-bin/attach/Plugins/CommentPlugin?filename=CommentPlugin.zip&revInfo=1" target="_top">revision 31 of the zip</a>.</div>
+
## <a name="Features"></a> Features
Inserts an edit box into the page that allows users to type in and save comments. Comments can be made
- signed or unsigned, dated or undated (as defined by a template),
- in other topics, or other positions within the current topic.
-## <a name="Syntax Rules"></a> Syntax Rules
-
-Write the command `%COMMENT{` _attributes_ `}%` anywhere in a TWiki topic. `%COMMENT%` is also legal.
+## <a name="Syntax"></a> Syntax
-<a name="StandardAttrs"></a> The following attributes are recognized (see also [[additional attributes|Main/WebHome#MoreAttrs]]):
+<a name="StandardAttrs"></a> Write <code>%COMMENT\{_attributes_\}%</code> anywhere in a TWiki topic.
-<table border="1" cellpadding="0" cellspacing="0">
- <tr>
- <th bgcolor="#99CCCC"><strong> Name </strong></th>
- <th bgcolor="#99CCCC"><strong> Description </strong></th>
- </tr>
- <tr>
- <td><code>type</code></td>
- <td> This is the name of the template to use for this comment. Comment templates are defined in a TWiki template - see [[Main/WebHome#TemPlates]], below. If this attribute is not defined, the type is whatever is defined by COMMENTPLUGIN_DEFAULT_TYPE, either in this topic or in your [[Main/WebPreferences]]. By default this is 'below'. </td>
- </tr>
- <tr>
- <td><code>default</code></td>
- <td> Default text to put into the textarea of the prompt. </td>
- </tr>
- <tr>
- <td><code>target</code></td>
- <td> Name of the topic to add the comment to. Defaults to the current topic. </td>
- </tr>
- <tr>
- <td><code>location</code></td>
- <td> Regular expression specifying the comment location in the target topic. Read <em>carefully</em> below! </td>
- </tr>
- <tr>
- <td><code>mode</code></td>
- <td> For compatability with older versions only, synonymous with <code>type</code></td>
- </tr>
- <tr>
- <td><code>nonotify</code></td>
- <td> Set to "on" to disable change notification for target topics </td>
- </tr>
- <tr>
- <td><code>noform</code></td>
- <td> Set to "on" to disable the automatic form that encloses your comment block - <em>remember</em> to insert <code><form></code> tags yourself! See [[Main/CommentPluginExamples#noform]] for an example. </td>
- </tr>
- <tr>
- <td><code>nopost</code></td>
- <td> Set to "on" to disable insertion of the posted text into the topic. </td>
- </tr>
- <tr>
- <td><code>remove</code></td>
- <td> Set to "on" to remove the comment prompt after the first time it is clicked. </td>
- </tr>
- <tr>
- <td><code>button</code></td>
- <td> Button label text; by default <code>Add comment</code>. </td>
- </tr>
-</table>
+(See also [[additional attributes|Main/WebHome#MoreAttrs]])
### <a name="Positioning the comment"></a> Positioning the comment
will place comments above the first occurence of the string `Flights of Fancy` in the current topic.
-**Warning** of course, if a user's comment contains the string "Flights of Fancy" they may and up _changing the location_ for the next comment! Also, if you use a tag in the location, then you've just inserted another tag in the page that contains the `%COMMENT`! So be very careful how you specify the RE for `location`. Note that the RE is matched using perl "multiple line" mode, so ^ and $ match the start of a line and the end of a line respectively.
+**Warning** of course, if a user's comment contains the string "Flights of Fancy" they may and up _changing the location_ for the next comment! Also, if you use a tag in the location, then you've just inserted another tag in the page that contains the `%COMMENT`! So be very careful how you specify the RE for `location`. Note that the RE is matched using perl "multiple line" mode, so ^ and $ match the start of a line and the end of a line respectively. %BR% Also note that you cannot have the text `location="` just before the location.
I look forward to someone leveraging this feature to create - for example - threaded conversations using `%COMMENT`.
Templates are used to define the "comment style" i.e. how comments appear in the page. The default is to add comments in "Blog like" style using bulleted lists, with the most recent comment at the top, but many other styles are available such as tables or Wiki thread mode comments. It is easy to define your own customer styles as well.
-A set of default comment templates are shipped with the plugin. These are:
+A set of default comment templates are shipped with the plugin - see also [[CommentPluginTemplates]]:
<table border="1" cellpadding="0" cellspacing="0">
<tr>
<td> Comments, signed and dated (server time), added immediately below the target anchor, or the <code>%COMMENT</code> if no anchor is specified </td>
</tr>
<tr>
+ <td><code>belowthreadmode</code></td>
+ <td> Comments, signed and dated, added recurse after comment box </td>
+ </tr>
+ <tr>
<td><code>threadmode</code></td>
<td> Wiki thread mode comment, signed and dated (server time) </td>
</tr>
<td><code>tableappend</code></td>
<td> Comments, signed and dated (server time), formatted as an HTML table row, added above the anchor (which must be in an HTML <table>) </td>
</tr>
+ <tr>
+ <td><code>action</code></td>
+ <td> Action added to action table directly above comment box (requires TWiki:Plugins/ActionTrackerPlugin) </td>
+ </tr>
+ <tr>
+ <td><code>table</code></td>
+ <td> Tablerows adding on end </td>
+ </tr>
+ <tr>
+ <td><code>toctalk</code></td>
+ <td> Talk using TOC adding on end </td>
+ </tr>
+ <tr>
+ <td><code>bookmark</code></td>
+ <td> Create a list of annotated bookmarks </td>
+ </tr>
+ <tr>
+ <td><code>return</code></td>
+ <td> Post to a different topic and return </td>
+ </tr>
</table>
Your local installation may add more template types as well - see [[Customisation|Main/WebHome#TemPlates]], below.
3. To override templates on a **web-by-web basis**, add a topic `UserCommentsTemplate` to the web (this will replace TWiki.UserCommentsTemplate)
4. To override templates **for a specific skin**, add them to TWiki.UserComments<Skin>Template (where <Skin> is the name of the skin with the first letter capitalised, e.g. Pattern)
-%X% Templates are picked up by following the [[standard TWiki rules|Main/TWikiTemplates#Finding_Templates]] for locating template files. Note that you can use `%TMPL:INCLUDE` to include other files of templates.
+You can also define a **comment template in a topic**, by passing the topic location with `templatetopic`. For example:
+
+> %COMMENT{type="blogpost" templatetopic="BlogPostCommentTemplate" target="%TOPIC%" button="Add comment" }%
+>
+> `templatetopic` accepts `topic` or `web.topic` syntax. See an example in [[CommentPluginExamples:templatetopic|Main/CommentPluginExamples#TemplateTopic]].
-%X% Note that from TWiki release 4.1.0 leading and trailing whitespace is no longer stripped. This means that when you upgrade to TWiki 4.1.X you may need to remove the first line break in your custom comment templates. See [[TWikiReleaseNotes04x01]] for more information.
+%X% Templates are picked up by following the [[standard TWiki rules|Main/TWikiTemplates#Finding_Templates]] for locating template files. Note that you can use `%TMPL:INCLUDE` to include other files of templates. %BR% %X% Note that from TWiki release 4.1.0 leading and trailing whitespace is no longer stripped. This means that when you upgrade to TWiki 4.1.X you may need to remove the first line break in your custom comment templates. See [[TWikiReleaseNotes04x01]] for more information.
### <a name="Customisation example"></a> Customisation example
<td><code>comment_nopost</code></td>
<td> As passed to %COMMENT </td>
</tr>
+ <tr>
+ <td><code>comment_templatetopic</code></td>
+ <td> As passed to %COMMENT </td>
+ </tr>
</table>
Note that `comment_location` overrides `comment_anchor`, and both override `comment_index`. Example, shows an "I Approve" button that adds your approval signature to the end of the topic:
<input type="hidden" name="comment" value="I Approve" />
</form>
+#### <a name="Customisation example with custo"></a> Customisation example with custom form template
+
+Write a custom form in a topic.
+
+- In the form set the location of the prompt with `%COMMENTPROMPT%`; the prompt will be positioned here.
+- In %COMMENT use parameter `noform="on"`
+- In %COMMENT use parameter `templatetopic` to point to the topic with the form template
+
+Example form:
+
+ %TMPL:DEF{FORM:example}%
+ <form method="post" action="%SCRIPTURL{save}%/%BASEWEB%/%BASETOPIC%" enctype="application/x-www-form-urlencoded" name="examplecomment" id="examplecomment">
+ <input type="hidden" name="redirectto" value="%BASEWEB%.%BASETOPIC%" />
+ %COMMENTPROMPT%
+ </form>
+ %TMPL:END%
+
+Example comment:
+
+ %COMMENT{noform="on" type="example" templatetopic="Sandbox.CommentPluginTemplateExample" target="%TOPIC%" button="Add comment" }%
+
### <a name="The <code>OUTPUT</code> template"></a> The `OUTPUT` template
The `OUTPUT` template defines the format for the text that actually gets embedded into the topic. All the usual TWiki variables are available in the `PROMPT` definition, but note that they get expanded _when the comment is inserted in the text_, so time, date and username will refer to the time and date when the comment was made, and the user who made it.
Note that these position tags are obviously mutually exclusive. If you define more than one, the result is undefined. If none is present, the default is taken from the plugin setting `DEFAULT_TYPE`
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <td><code>%COMMENTPROMPT%</code></td>
+ <td> Use with a custom form. If present, the comment prompt will be positioned here. </td>
+ </tr>
+</table>
+
All the usual [[TWikiVariables]] that can be used in a topic template can also be used in an `OUTPUT` template. See [[TWikiVariables]] for details.
## <a name="Settings"></a> Settings
## <a name="Plugin Info"></a> Plugin Info
+Another great TWiki extension from the [ **WikiRing** ](http://wikiring.com) - working together to improve your wiki experience!
+
<table border="1" cellpadding="0" cellspacing="0">
<tr>
<td align="right"> Plugin Author: </td>
- <td> TWiki:Main.DavidWeller, TWiki:Main.PeterMasiar, TWiki:Main.CrawfordCurrie <a href="http://www.c-dot.co.uk" target="_top">http://www.c-dot.co.uk</a></td>
+ <td> TWiki:Main.CrawfordCurrie <a href="http://www.c-dot.co.uk" target="_top">http://www.c-dot.co.uk</a> inspired by the work of TWiki:Main.DavidWeller and TWiki:Main.PeterMasiar </td>
</tr>
<tr>
- <td align="right"> Copyright: </td>
- <td> © 2004, TWiki:Main.CrawfordCurrie<br />© 2004-2007 TWiki:TWiki.TWikiContributor </td>
+ <td align="right"> Plugin Version: </td>
+ <td> 15776 (22 Jan 2008) </td>
</tr>
<tr>
- <td align="right"> License: </td>
- <td> GPL (<a href="http://www.gnu.org/copyleft/gpl.html" target="_top">GNU General Public License</a>) </td>
+ <td align="right"> Change History: </td>
+ <td> </td>
</tr>
<tr>
- <td align="right"> Plugin Version: </td>
- <td> 12750 (04 Feb 2007) </td>
+ <td align="right"> 5 Sep 2007 </td>
+ <td> TWikibug:Item3689 corrected <code>location</code> handling TWikibug:Item4181 added [[Main/VarCOMMENT]] TWikibug:Item4402 corrected access check </td>
</tr>
<tr>
- <td align="right"> Change History: </td>
- <td> </td>
+ <td align="right"> 22 Jun 2007 </td>
+ <td> Removed the long-deprecated <code>%TIME</code> (use %GMTIME instead). Minor doc changes </td>
+ </tr>
+ <tr>
+ <td align="right"> 14021 </td>
+ <td> TWikibug:Item3755 Fixed incorrect handling of line terminators when targeting an anchor </td>
+ </tr>
+ <tr>
+ <td align="right"> 13311 </td>
+ <td> Added option to define a comment template in any topic. Pass the topic location with <code>templatetopic</code> (either <code>topic</code> or <code>web.topic</code>). See an example in [[Main/CommentPluginExamples#TemplateTopic]]. </td>
+ </tr>
+ <tr>
+ <td align="right"> 12822 </td>
+ <td> TWikibug:Item3598 minor doc fixes </td>
</tr>
<tr>
<td align="right"> 12750 </td>
- <td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item3510" rel="nofollow">Item3510</a> added a note about the changed template spec in TWiki 4.1.0. Code remains unchanged </td>
+ <td> TWikibug:Item3510 added a note about the changed template spec in TWiki 4.1.0. Code remains unchanged </td>
</tr>
<tr>
<td align="right"> 11358 </td>
- <td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item2802" rel="nofollow">Item2802</a> moved SHORTDESCRIPTION to .pm. Coded up TWiki:main.PankajPant's suggestions as <code>nopost</code> and <code>remove</code>. Added default text for the %COMMENT as requested by TWiki:Main.AndyGlew </td>
+ <td> TWikibug:Item2802 moved SHORTDESCRIPTION to .pm. Coded up TWiki:main.PankajPant's suggestions as <code>nopost</code> and <code>remove</code>. Added default text for the %COMMENT as requested by TWiki:Main.AndyGlew </td>
</tr>
<tr>
<td align="right"> 11118 </td>
- <td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item2322" rel="nofollow">Item2322</a> removed span tag around oneliner bullet output </td>
+ <td> TWikibug:Item2322 removed span tag around oneliner bullet output </td>
</tr>
<tr>
<td align="right"> 8788 </td>
- <td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1465" rel="nofollow">Item1465</a> Item1577: reverted 8433 to fix inclusion of correct user templates </td>
+ <td> TWikibug:Item1465 Item1577: reverted 8433 to fix inclusion of correct user templates </td>
</tr>
<tr>
<td align="right"> 8787 </td>
- <td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1573" rel="nofollow">Item1573</a> renamed standard templates topic to avoid naming clash on Windows, where filenames are case-insensitive </td>
+ <td> TWikibug:Item1573 renamed standard templates topic to avoid naming clash on Windows, where filenames are case-insensitive </td>
</tr>
<tr>
<td align="right"> 8433 </td>
- <td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item1465" rel="nofollow">Item1465</a> Fix 'TWiki.' to 'TWiki.'; also fixed include 'UserComments' to 'UserCommentsTemplate' (at least that is what the doc suggests) </td>
+ <td> TWikibug:Item1465 Fix 'TWiki.' to 'TWiki.'; also fixed include 'UserComments' to 'UserCommentsTemplate' (at least that is what the doc suggests) </td>
</tr>
<tr>
<td align="right"> 7427 </td>
- <td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item845" rel="nofollow">Item845</a> removed duplicate date in default comments; stick with server time </td>
+ <td> TWikibug:Item845 removed duplicate date in default comments; stick with server time </td>
</tr>
<tr>
<td align="right"> 7251 </td>
- <td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item810" rel="nofollow">Item810</a> fix for user template inclusion; reorganised templates to make customisation easier </td>
+ <td> TWikibug:Item810 fix for user template inclusion; reorganised templates to make customisation easier </td>
</tr>
<tr>
<td align="right"> 5906 </td>
- <td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item143" rel="nofollow">Item143</a> apache warning from comment plugin when CommentsTmpl.txt not found </td>
+ <td> TWikibug:Item143 apache warning from comment plugin when CommentsTmpl.txt not found </td>
</tr>
<tr>
<td align="right"> 5519 </td>
<td> 06 Mar 2002 initial commit </td>
</tr>
<tr>
- <td align="right"> Perl Version: </td>
- <td> >= 5.6.1 </td>
+ <td align="right"> Copyright: </td>
+ <td> © 2004, TWiki:Main.CrawfordCurrie<br />© 2004-2007 TWiki:TWiki.TWikiContributor </td>
+ </tr>
+ <tr>
+ <td align="right"> License: </td>
+ <td> GPL (<a href="http://www.gnu.org/copyleft/gpl.html" target="_top">GNU General Public License</a>) </td>
</tr>
<tr>
<td align="right"> Plugin Home: </td>
</table>
**_Related Topics:_** [[TWikiPreferences]], [[TWikiPlugins]]
-
--- TWiki:Main/CrawfordCurrie - 15:45:58 03 March 2007
<li><a href="#=bookmark="> bookmark</a></li>
<li><a href="#=return="> return</a></li>
<li><a href="#=noform="> noform</a></li>
+ <li><a href="#=templatetopic="> templatetopic</a></li>
</ul>
</li>
</ul>
</div>
</form>
+<a name="TemplateTopic"></a>
+
+### <a name="=templatetopic="></a> `templatetopic`
+
+Example of a form definition in a topic. The comment template is located in [[CommentPluginTemplateExample]].
+
+<a name="CommentDate1176024819"></a> [[TWikiContributor]] - 08 Apr 2007:
+
+templatetopic example comment output 1
+
+----
+
+<input name="comment_action" type="hidden" value="save" />
+<input name="comment_type" type="hidden" value="example" />
+<input name="comment_index" type="hidden" value="17" />
+
----
- Bottom comment output 1 -- [[TWikiContributor]] - 26 Nov 2006
#### <a name="bookmark"></a> bookmark
-Talk using TOC adding on end - TWiki:Main/FranzJosefSilli
+Create a list of annotated bookmarks - TWiki:Main/FranzJosefSilli
%TMPL:DEF{PROMPT:bookmark}%
%TABLE{databg="#ffffff" tableborder="0" cellborder="0"}%
## <a name="Answer:"></a> Answer:
-The same topic revision will be used when you save a topic again within a certain time frame (one hour by default). This is to prevent unnecessary topic revisions when you do several edit cycles in a row. Note that a new revision **_is_** created if another person edits the same topic, regardless of the time.
+The same topic revision will be used when you save a topic again within a certain time frame (one hour by default, configurable with configure item `{ReplaceIfEditedAgainWithin}`). This is to prevent unnecessary topic revisions when you do several edit cycles in a row. Note that a new revision **_is_** created if another person edits the same topic, regardless of the time.
**_Back to:_** [[TWikiFAQ]]
# <a name="Edit Table Plugin"></a><a name=" Edit Table Plugin"></a> Edit Table Plugin
-This plugin allows you to edit TWiki tables using edit fields and drop down boxes. Tables have an **[ Edit table ]** button if preceeded by an `%EDITTABLE{...}%` variable. Each column can be a text field, a drop down box, a date field, etc. Multiple tables per topic are editable, but only one at a time can be edited.
+Edit TWiki tables in place, using edit fields and drop down boxes, without having to edit the complete topic.
+
+Simply add an **[ Edit table ]** button to an existing table by writing `%EDITTABLE{}%` directly above the table. This can be added to tables that are formatted with [[TablePlugin]]: add the `EDITTABLE` variable just above or below the `TABLE` tag. It can also be used without any `TABLE` tag.
+
+Customize entry fields by specifying the format: use a text field, a drop down box, a date field, radio buttons or checkboxes.
+
+Multiple tables per topic are editable, but only one at a time can be edited.
<div>
<ul>
<li><a href="#Per Table Settings"> Per Table Settings</a><ul>
- <li><a href="#Initial Values"> Initial Values</a></li>
+ <li><a href="#Using TWiki Variables in the For"> Using TWiki Variables in the Format Parameter</a></li>
<li><a href="#Date Field Type"> Date Field Type</a></li>
</ul>
</li>
<li><a href="#Examples"> Examples</a></li>
<li><a href="#Plugin Settings"> Plugin Settings</a></li>
<li><a href="#Limitations and Known Issues"> Limitations and Known Issues</a></li>
- <li><a href="#Plugin Installation Instructions"> Plugin Installation Instructions</a></li>
+ <li><a href="#Installation Instructions"> Installation Instructions</a></li>
<li><a href="#License"> License</a></li>
<li><a href="#Plugin Info"> Plugin Info</a></li>
</ul>
## <a name="Per Table Settings"></a> Per Table Settings
-Add a `%EDITTABLE{...}%` variable just before an existing table to make it editable, or add the variable anywhere in a topic to start a new table. Parameters:
+Add a `%EDITTABLE{...}%` variable just before an existing table to make it editable, or add the variable anywhere in a topic to start a new table.
-<table border="1" cellpadding="0" cellspacing="0">
- <tr>
- <th bgcolor="#99CCCC"><strong> Parameter </strong></th>
- <th bgcolor="#99CCCC"><strong> Comment </strong></th>
- <th bgcolor="#99CCCC"><strong> Default </strong></th>
- </tr>
- <tr>
- <td><code>header</code></td>
- <td> Specify the header format of a new table like <code>"|*Food*|*Drink*|"</code>. Useful to start a table with only a button </td>
- <td> (no header) </td>
- </tr>
- <tr>
- <td><code>format</code></td>
- <td> The format of one column when editing the table. A cell can be a text input field, or any of these edit field types:%BR% • Text input field (1 line):%BR% <code>| text, <size>, <initial value> |</code> %BR% • Textarea input field:%BR% <code>| textarea, <rows>x<columns>, <initial value> |</code> %BR% • Drop down box: %BR% <code>| select, <size>, <option 1>, <option 2>, etc* |</code> %BR% <code>*</code> only one item can be selected %BR% • Radio buttons: %BR% <code>| radio, <size*>, <option 1>, <option 2>, etc |</code> %BR% <code>*</code> size indicates the number of buttons per line in edit mode %BR% • Checkboxes: %BR% <code>| checkbox, <size*>, <option 1>, <option 2>, etc |</code> %BR% <code>*</code> size indicates the number of checkboxes per line in edit mode %BR% • Fixed label: %BR% <code>| label, 0, <label text> |</code> %BR% • Row number: %BR% <code>| row, <offset> |</code> %BR% • Date: %BR% <code>| date, <size>, <initial value>, <DHTML date format> |</code> %BR% <code>*</code> see <a href="http://www.dementia.org/twiki//view/TWiki/JSCalendarContrib/doc/html/reference.html" target="_top">Mishoo documentation</a> for more infos about the DHTML date format </td>
- <td><code>"text, 16"</code> %BR% for all cells </td>
- </tr>
- <tr>
- <td><code>changerows</code></td>
- <td> Rows can be added and removed if <code>"on"</code>;<br /> Rows can be added but not removed if <code>"add"</code></td>
- <td><code>CHANGEROWS</code> %BR% Plugin setting </td>
- </tr>
- <tr>
- <td><code>quietsave</code></td>
- <td> Quiet Save button is shown if <code>"on"</code>, hidden if <code>"off"</code></td>
- <td><code>QUIETSAVE</code> %BR% Plugin setting </td>
- </tr>
- <tr>
- <td><code>include</code></td>
- <td> 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. </td>
- <td> (none) </td>
- </tr>
- <tr>
- <td><code>helptopic</code></td>
- <td> Topic name containing help text shown below the table when editing a table. The %STARTINCLUDE% and %STOPINCLUDE% variables can be used in the topic to specify what is shown. </td>
- <td> (no help text) </td>
- </tr>
- <tr>
- <td><code>headerislabel</code></td>
- <td> Table header cells are read-only (labels) if <code>"on"</code>; header cells can be edited if <code>"off"</code> or "0" </td>
- <td><code>"on"</code></td>
- </tr>
- <tr>
- <td><code>editbutton</code></td>
- <td> Set edit button text, e.g. <code>"Edit this table"</code>; set button image with alt text, e.g. <code>"Edit table, %PUBURL%/%TWIKIWEB%/TWikiDocGraphics/edittopic.gif"</code>; hide edit button at the end of the table with <code>"hide"</code> (Note: Button is automatically hidden if an edit button is present in a cell) </td>
- <td><code>EDITBUTTON</code> %BR% Plugin setting </td>
- </tr>
-</table>
+### <a name="Using TWiki Variables in the For"></a> Using TWiki Variables in the Format Parameter
-### <a name="Initial Values"></a> Initial Values
+TWiki variables like `%Y%` in `<initial value>` (of text input field) and `<label text>` (of fixed label) will get expanded when a new row is added.
-By default, variables in `<initial value>` (of text input field) and `<label text>` (of fixed label) get expanded when a new row is added. This can be used for example to add a timestamp to a label. You can escape characters if you do not want that:
+This is useful to write variables like dates into the table.
-<table border="1" cellpadding="0" cellspacing="0">
- <tr>
- <th bgcolor="#99CCCC"><strong> Text: </strong></th>
- <th bgcolor="#99CCCC"><strong> To Escape: </strong></th>
- </tr>
- <tr>
- <td><code>$quot</code></td>
- <td> Double quote (<code>"</code>). Alternatively write <code>\"</code> to escape it </td>
- </tr>
- <tr>
- <td><code>$percnt</code></td>
- <td> Percent sign (<code>%</code>) </td>
- </tr>
- <tr>
- <td><code>$dollar</code></td>
- <td> Dollar sign (<code>$</code>) </td>
- </tr>
- <tr>
- <td><code>$nop</code> or <code>$nop()</code></td>
- <td> Is a "no operation" </td>
- </tr>
-</table>
+> For example:
+>
+> %EDITTABLE{ format="| label, 0, %SERVERTIME{"$day $mon $year $hour:$min"}% |" }%
+>
+> ... will get expanded to
+>
+> `29 Jun 2010 12:07`
+>
+> when the new row is created.
+
+To prevent variable expansion: escape the format variable with [[formatting tokens|TWiki/FormatTokens]] (particularly `$percnt`).
+
+> For example:
+>
+> %EDITTABLE{ format="| text, 20, $percntY$percnt |" }%
+>
+> ... will create a new row with
+>
+> `$percntY$percnt`
+>
+> . In view mode this is temporarily translated to
+>
+> `%Y%`
+>
+> and subsequent rendered as %Y%.
+
+<a name="DateField"></a>
### <a name="Date Field Type"></a> Date Field Type
-<img src="http://www.dementia.org/twiki//view/EditTablePluginCalendarExample.gif" width="549" height="210" alt="Edit Table Calendar Example" /> The `date` field type allows one to choose a date with a popup calendar. Popup calendar works for Netscape 6.0 or better, all other Gecko-based browsers, Internet Explorer 5.0 or better for Windows, Opera 7 and Konqueror 3.1.2. The `...` button is inactive if the browser cannot support the popup calendar. It uses the nice [Mishoo DHTML calendar](http://dynarch.com/mishoo/calendar.epl), see also TWiki:Codev/JavaScriptDatePickerForForm <br />
+<img src="http://www.dementia.org/twiki//view/EditTablePluginCalendarExample.gif" width="638" height="250" alt="Edit Table Calendar Example" />
+
+The `date` field type allows one to choose a date with a popup calendar. Popup calendar works with all modern browsers. The date picker button is inactive if the browser cannot support the popup calendar or if javascript is disabled.
## <a name="Per Cell Settings"></a> Per Cell Settings
<li><input name="etaddrow" onclick="return(false);" type="submit" value="Add row" /> - add row to the table (if enabled) </li>
<li><input name="etdelrow" onclick="return(false);" type="submit" value="Delete last row" /> - remove last row from the table (if enabled) </li>
<li><input name="etcancel" onclick="return(false);" type="submit" value="Cancel" /> - cancel without saving and release edit lock </li>
+ <li><img src="http://www.dementia.org/twiki//view/btn_move.gif" /> - Move a row by clicking this button next to the row to be moved, then at a destination. </li>
+ <li><img src="http://www.dementia.org/twiki//view/btn_delete.gif" /> - Deletes the row next to this button. </li>
</ul>
</li>
</ul>
If this plugin is installed you will see an **[ Edit table ]** button above; if you were to click on it (please don't, use TWiki:Sandbox.EditTablePluginTesting for testing) you get this form:
-<form>
- <table border="1" cellpadding="0" cellspacing="1">
- <tr>
- <th bgcolor="#99CCCC"> Nr </th>
- <th bgcolor="#99CCCC"> Text field </th>
- <th bgcolor="#99CCCC"> Drop down </th>
- <th bgcolor="#99CCCC"> Mood </th>
- <th bgcolor="#99CCCC"> Timestamp </th>
- </tr>
+<a name="edittable1"></a>
+
+<div><input name="ettablenr" type="hidden" value="1" /><table border="1" cellpadding="0" cellspacing="0" id="default" rules="rows">
+ <thead>
+ <tr>
+ <th bgcolor="#6b7f93" valign="top"><a href="http://www.dementia.org/twiki/viewauth/TWiki/EditTablePlugin?ettablenr=1&etedit=on&etrows=3&x=27&y=13&sortcol=0;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Nr<input name="etcell1x1" type="hidden" value="*Nr*" /></font></a></th>
+ <th bgcolor="#6b7f93" valign="top"><a href="http://www.dementia.org/twiki/viewauth/TWiki/EditTablePlugin?ettablenr=1&etedit=on&etrows=3&x=27&y=13&sortcol=1;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Text field<input name="etcell1x2" type="hidden" value="*Text field*" /></font></a></th>
+ <th bgcolor="#6b7f93" valign="top"><a href="http://www.dementia.org/twiki/viewauth/TWiki/EditTablePlugin?ettablenr=1&etedit=on&etrows=3&x=27&y=13&sortcol=2;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Drop down<input name="etcell1x3" type="hidden" value="*Drop down*" /></font></a></th>
+ <th bgcolor="#6b7f93" valign="top"><a href="http://www.dementia.org/twiki/viewauth/TWiki/EditTablePlugin?ettablenr=1&etedit=on&etrows=3&x=27&y=13&sortcol=3;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Mood<input name="etcell1x4" type="hidden" value="*Mood*" /></font></a></th>
+ <th bgcolor="#6b7f93" valign="top"><a href="http://www.dementia.org/twiki/viewauth/TWiki/EditTablePlugin?ettablenr=1&etedit=on&etrows=3&x=27&y=13&sortcol=4;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Timestamp<input name="etcell1x5" type="hidden" value="*Timestamp*" /></font></a></th>
+ </tr>
+ </thead>
<tr>
- <td bgcolor="#FFFFFF"> 1<input name="etcell2x1" type="hidden" value="1" /></td>
- <td bgcolor="#FFFFFF"><input name="etcell2x2" size="20" type="text" value="hello table" /></td>
- <td bgcolor="#FFFFFF"><select name="etcell2x3" size="1"><option selected>one</option>
+ <td bgcolor="#ffffff" valign="top"><span>1<input name="etcell2x1" type="hidden" value="1" /></span></td>
+ <td bgcolor="#ffffff" valign="top"><input name="etcell2x2" size="20" type="text" value="hello table" /></td>
+ <td bgcolor="#ffffff" valign="top"><select name="etcell2x3" size="1"><option selected>one</option>
<option>two</option>
<option>three</option>
<option>four</option></select></td>
- <td bgcolor="#FFFFFF"><input checked name="etcell2x4" type="radio" value=":-)" /> <img alt="smile" border="0" src="http://www.dementia.org/twiki//view/%WEB%/SmiliesPlugin/smile.gif" title="smile" /> <input name="etcell2x4" type="radio" value=":-I" /> <img alt="indifferent" border="0" src="http://www.dementia.org/twiki//view/%WEB%/SmiliesPlugin/indifferent.gif" title="indifferent" /> <input name="etcell2x4" type="radio" value=":-(" /> <img alt="frown" border="0" src="http://www.dementia.org/twiki//view/%WEB%/SmiliesPlugin/frown.gif" title="frown" /></td>
- <td bgcolor="#FFFFFF"> 26 Jun 2002 12:30<input name="etcell2x5" type="hidden" value="26 Jun 2002 12:30" /></td>
+ <td bgcolor="#ffffff" valign="top"><input checked name="etcell2x4" type="radio" value=":-)" /> <img alt="smile" border="0" src="http://www.dementia.org/twiki//view/TWiki/SmiliesPlugin/smile.gif" title="smile" /> <input name="etcell2x4" type="radio" value=":-I" /> <img alt="indifferent" border="0" src="http://www.dementia.org/twiki//view/TWiki/SmiliesPlugin/indifferent.gif" title="indifferent" /> <input name="etcell2x4" type="radio" value=":-(" /> <img alt="frown" border="0" src="http://www.dementia.org/twiki//view/TWiki/SmiliesPlugin/frown.gif" title="frown" /></td>
+ <td bgcolor="#ffffff" valign="top"> 26 Jun 2002 12:30<input name="etcell2x5" type="hidden" value="26 Jun 2002 12:30" /></td>
</tr>
<tr>
- <td bgcolor="#FFFF99"> 2<input name="etcell3x1" type="hidden" value="2" /></td>
- <td bgcolor="#FFFF99"><input name="etcell3x2" size="20" type="text" value="" /></td>
- <td bgcolor="#FFFF99"><select name="etcell3x3" size="1"><option>one</option>
+ <td bgcolor="#edf4f9" valign="top"><span>2<input name="etcell3x1" type="hidden" value="2" /></span></td>
+ <td bgcolor="#edf4f9" valign="top"><input name="etcell3x2" size="20" type="text" value="" /></td>
+ <td>
+ <p>
+ </p>
+ </td>
+ <td bgcolor="#edf4f9" valign="top"><select name="etcell3x3" size="1"><option>one</option>
<option selected>two</option>
<option>three</option>
<option>four</option></select></td>
- <td bgcolor="#FFFF99"><input name="etcell2x4" type="radio" value=":-)" /> <img alt="smile" border="0" src="http://www.dementia.org/twiki//view/%WEB%/SmiliesPlugin/smile.gif" title="smile" /> <input name="etcell2x4" type="radio" value=":-I" /> <img alt="indifferent" border="0" src="http://www.dementia.org/twiki//view/%WEB%/SmiliesPlugin/indifferent.gif" title="indifferent" /> <input checked name="etcell2x4" type="radio" value=":-(" /> <img alt="frown" border="0" src="http://www.dementia.org/twiki//view/%WEB%/SmiliesPlugin/frown.gif" title="frown" /></td>
- <td bgcolor="#FFFF99"> 27 Jun 2002 12:40<input name="etcell3x5" type="hidden" value="27 Jun 2002 12:40" /></td>
+ <td bgcolor="#edf4f9" valign="top"><input name="etcell3x4" type="radio" value=":-)" /> <img alt="smile" border="0" src="http://www.dementia.org/twiki//view/TWiki/SmiliesPlugin/smile.gif" title="smile" /> <input name="etcell3x4" type="radio" value=":-I" /> <img alt="indifferent" border="0" src="http://www.dementia.org/twiki//view/TWiki/SmiliesPlugin/indifferent.gif" title="indifferent" /> <input checked name="etcell3x4" type="radio" value=":-(" /> <img alt="frown" border="0" src="http://www.dementia.org/twiki//view/TWiki/SmiliesPlugin/frown.gif" title="frown" /></td>
+ <td bgcolor="#edf4f9" valign="top"> 27 Jun 2002 12:40<input name="etcell3x5" type="hidden" value="27 Jun 2002 12:40" /></td>
</tr>
- </table><input name="etsave" onclick="return(false);" type="submit" value="Save table" /> <input name="etqsave" onclick="return(false);" type="submit" value="Quiet save" /> <input name="etaddrow" onclick="return(false);" type="submit" value="Add row" /> <input name="etdelrow" onclick="return(false);" type="submit" value="Delete last row" /> <input name="etcancel" onclick="return(false);" type="submit" value="Cancel" /> (demo only, these buttons do not work) </form>
+ </table><input name="etrows" type="hidden" value="3" /> <input id="etsave" name="etsave" type="submit" value="Save table" /> <input id="etqsave" name="etqsave" type="submit" value="Quiet save" /> <input id="etaddrow" name="etaddrow" type="submit" value="Add row" /> <input id="etdelrow" name="etdelrow" type="submit" value="Delete last row" /> <input id="etcancel" name="etcancel" type="submit" value="Cancel" /></div>
The following example shows a simple table with key/value rows. The default edit field type for the value column is a text field. This is overloaded by a selector for the Gender, and a date picker for the DOB. This is typically used by TWiki applications where new topics with tables are created based on a template topic.
-<table>
+<table cellpadding="6" style="background: #f2f2f2">
+ <tr>
+ <th> You type: </th>
+ <th> You get: </th>
+ <th> Table in edit mode: </th>
+ </tr>
<tr>
- <td valign="top"> You type: <pre>
-%EDITTABLE{ format="| label | text, 40 |" }%
+ <td valign="top"><pre>
+%EDITTABLE{ format="| label | text, 40 |" changerows="off" }%
|*Key*|*Value*|
| Name: | John Smith |
| Gender: | M %EDITCELL{select, 1, , F, M}% |
| DOB: | 1999/12/31 %EDITCELL{date, 10}% |
| City: | New York |
</pre></td>
- <td valign="top"> Screenshot: <img alt="EDITCELL Example in view mode" height="141" src="http://www.dementia.org/twiki//view/ScreenshotEditCell1.gif" width="149" /></td>
- <td valign="top"> Screenshot in edit mode: <img alt="EDITCELL Example in edit mode" height="164" src="http://www.dementia.org/twiki//view/ScreenshotEditCell2.gif" width="276" /></td>
+ <td valign="top"><img alt="EDITCELL Example in view mode" height="172" src="http://www.dementia.org/twiki//view/ScreenshotEditCell1.gif" width="150" /></td>
+ <td valign="top"><img alt="EDITCELL Example in edit mode" height="198" src="http://www.dementia.org/twiki//view/ScreenshotEditCell2.gif" width="436" /></td>
</tr>
</table>
- Set DEBUG to 1 to get debug messages in `data/debug.txt`. Default: `0`
- Set DEBUG = 0
+- Set JAVASCRIPTINTERFACE to 1 to be able to directly move and delete row without page refresh.
+ - Set JAVASCRIPTINTERFACE = 1
+
- Default for change rows flag: `on`, `off`, `add`
- Set CHANGEROWS = on
- Default flag for quiet save option: `on` to show the Quiet Save button, `off` to hide
- Set QUIETSAVE = on
-- Default edit button: Specify `button text`, or specify `alternate text, image URL`
- - #Set EDITBUTTON = Edit table
- - Set EDITBUTTON = Edit this table, 
+- Default edit button: Specify `button text`, or specify `alternate text, image URL`. Note: Texts inside `%MAKETEXT{}%` are translated into other languages.
+ - #Set EDIT\_BUTTON = Edit table
+ - Set EDIT\_BUTTON = Edit this table, 
+ - Set SAVE\_BUTTON = Save table
+ - Set QUIET\_SAVE\_BUTTON = Quiet save
+ - Set ADD\_ROW\_BUTTON = Add row
+ - Set DELETE\_LAST\_ROW\_BUTTON = Delete last row
+ - Set CANCEL\_BUTTON = Cancel
+
+- Default help texts
+ - Set INCLUDED\_TOPIC\_DOES\_NOT\_EXIST = <span>Warning: 'include' topic does not exist!</span>
**_Note:_** The Plugin uses base settings like date format, language and style from the [[JSCalendarContrib]].
- You cannot put two `%EDITTABLE{}%` statements on the same line in the source
- You can include %-vars now in select values, by quoting them with <nop>, as in %<nop>X% for %X%, say for instance: <br />`select,1,%<nop>X%,%<nop>Y%`
-## <a name="Plugin Installation Instructions"></a> Plugin Installation Instructions
-
-**_Note:_** You do not need to install anything on the browser to use this Plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running.
+## <a name="Installation Instructions"></a> Installation Instructions
- Download the ZIP file from the Plugin web (see below)
-- Unzip <code>**%TOPIC%.zip**</code> in your twiki installation directory. Content: <table border="1" cellpadding="0" cellspacing="0">
- <tr>
- <th bgcolor="#99CCCC"><strong> File: </strong></th>
- <th bgcolor="#99CCCC"><strong> Description: </strong></th>
- </tr>
- <tr>
- <td><code><b>data/TWiki/%TOPIC%.txt</b></code></td>
- <td> Plugin topic </td>
- </tr>
- <tr>
- <td><code><b>data/TWiki/%TOPIC%.txt,v</b></code></td>
- <td> Plugin topic repository </td>
- </tr>
- <tr>
- <td><code><b>lib/TWiki/Plugins/%TOPIC%.pm</b></code></td>
- <td> Plugin Perl module </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/%TOPIC%/edittable.gif</b></code></td>
- <td> Edit table button image </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/%TOPIC%/*.gif</b></code></td>
- <td> Screenshots and Mishoo DHTML calendar images </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/%TOPIC%/README</b></code></td>
- <td> Mishoo DHTML calendar README </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/%TOPIC%/release-notes.html</b></code></td>
- <td> Mishoo DHTML calendar release notes </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/%TOPIC%/*.js</b></code></td>
- <td> Mishoo DHTML calendar JavaScript files </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/%TOPIC%/calendar-system.css</b></code></td>
- <td> Mishoo DHTML calendar stylesheet </td>
- </tr>
-</table>
+- Unzip <code>**%TOPIC%.zip**</code> in your ($TWIKI\_ROOT) directory.
+- Alternatively,
+ - Manually resolve the dependencies listed below. None
- The Plugin depends on the `viewauth` script to authenticate the user. As described in [[TWikiAccessControl]], copy the `view` script to `viewauth` (or better, create a symbolic link) and add `viewauth` to the list of authenticated scripts in the `.htaccess` file.
-- The Mishoo DHTML calendar 0.9.5 is preinstalled and should work without any configuration. If you wish to use another language, specify the in the Plugin settings, or create a new language files, attach it to the Plugin topic, and change the Plugin settings
- (Dakar) Visit `configure` in your TWiki installation, and enable the plugin in the \{Plugins\} section.
- Test if the Plugin is correctly installed:
- Check above example if there is an **[ Edit table ]** button below the table in above example
## <a name="License"></a> License
- The Edit Table Plugin is released under the [GPL](http://www.gnu.org/licenses/gpl.html)
-- The [Mishoo DHTML calendar](http://dynarch.com/mishoo/calendar.epl) bundled with this Plugin was created by Mihai Bazon and is released under the [LGPL](http://www.gnu.org/licenses/lgpl.html) -- thanks Mihai for the great tool :-)
## <a name="Plugin Info"></a> Plugin Info
<table border="1" cellpadding="0" cellspacing="0">
<tr>
<td align="right"> Plugin Author: </td>
- <td><a href="http://www.structuredwikis.com/" target="_top">Peter Thoeny</a></td>
+ <td> TWiki:Main/PeterThoeny </td>
</tr>
<tr>
<td align="right"> Copyright: </td>
- <td> © 2002-2006, TWiki:Main.PeterThoeny </td>
+ <td> © 2002-2007, TWiki:Main.PeterThoeny (<a href="http://www.twiki.net/" target="_top">TWIKI.NET</a>) and TWiki Contributors </td>
</tr>
<tr>
<td align="right"> License: </td>
</tr>
<tr>
<td align="right"> Plugin Version: </td>
- <td> 12327 </td>
+ <td> 4.7.10 (08 Jan 2008) </td>
</tr>
<tr>
<td align="right"> Change History: </td>
<td> </td>
</tr>
<tr>
+ <td align="right"> 25 Dec 2007: </td>
+ <td> 4.7.1: Arthur Clemens: Added warning if <code>include</code> parameter topic does not exist. </td>
+ </tr>
+ <tr>
+ <td align="right"> 22 Dec 2007: </td>
+ <td> 4.7: Arthur Clemens: Changed handling of escaped variables. To escape TWiki variable, use formatting tokens such as <code>$percnt</code>. </td>
+ </tr>
+ <tr>
+ <td align="right"> 16 Dec 2007: </td>
+ <td> 4.6: Kenneth Lavrsen: The plugin prevents [[Main/TablePlugin]] from initsorting the table being edited. This is done by temporarily appending the attribute disableallsort="on" to the TABLE tag of a table being edited. Additionally all header sorting is disabled while editing a table by setting a hidden formfield <code>sort</code> to "off". Disabling sorting while editing is needed now that the [[Main/EditTablePlugin]] supports moving rows up and down. </td>
+ </tr>
+ <tr>
+ <td align="right"> 01 Dec 2007: </td>
+ <td> 4.3: Arthur Clemens: added support for [[Main/TablePlugin]] <code>headerrows</code> and <code>footerrows</code>; updated edit button </td>
+ </tr>
+ <tr>
+ <td align="right"> 16 Oct 2007: </td>
+ <td> 4.2: Arthur Clemens: refactoring, bug fixes. </td>
+ </tr>
+ <tr>
+ <td align="right"> 07 Oct 2007: </td>
+ <td> 15182: PTh: Added [[TWiki/VarEDITTABLE]] to have it listed in [[TWiki/TWikiVariables]]</td>
+ </tr>
+ <tr>
+ <td align="right"> 15 Mar 2007: </td>
+ <td> Arthur Clemens: Fixed eating of double newlines; icons for javascript buttons and interface improvements. By default the javascript interface is turned off, set <code>JAVASCRIPTINTERFACE</code> to use it in edit mode. </td>
+ </tr>
+ <tr>
+ <td align="right"> 05 Mar 2007: </td>
+ <td> Byron Darrah: Added ability to dynamically move and delete rows. </td>
+ </tr>
+ <tr>
<td align="right"> 12 Oct 2006: </td>
<td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item2982" rel="nofollow">Item2982</a> Use default date format from [[Main/JSCalendarContrib]]</td>
</tr>
</tr>
<tr>
<td align="right"> 16 Sep 2004: </td>
- <td> Added radio buttons and checkbox controls; escaped "|" pipe symbol found in input fields to preserve tables </td>
+ <td> Added radio buttons and checkbox controls; escaped "%VBAR%" pipe symbol found in input fields to preserve tables </td>
</tr>
<tr>
<td align="right"> 01 Aug 2004: </td>
</tr>
</table>
-**_Related Topics:_** [[TWikiPreferences]], [[TWikiPlugins]]
+**_Related Topics:_** [[VarEDITTABLE]], [[TWikiPreferences]], [[TWikiPlugins]]
--- TWiki:Main/PeterThoeny - 02 Oct 2006
+-- TWiki:Main/PeterThoeny - 07 Oct 2007
(none)
+## <a name="Plugin Settings"></a> Plugin Settings
+
+Plugin settings are stored as preferences variables. To reference a plugin setting write <code>**%<plugin>\_<setting>%**</code>, i.e. <code>**%EMPTYPLUGIN\_SHORTDESCRIPTION%**</code>
+
+- One line description, is shown in the [[TextFormattingRules]] topic:
+ - Set SHORTDESCRIPTION = Empty Plugin used as a template for new Plugins
+
+- Your own setting, for example:
+ - Set EXAMPLE = got it!
+
+- Debug plugin: ( TWiki sets `$debug` in your plugin. See output in `data/debug.txt`.)
+ - Set DEBUG = 0
+
## <a name="Plugin Installation Instructions"></a> Plugin Installation Instructions
- This plugin is preinstalled, you do not need to install it.
</tr>
<tr>
<td align="right"> Copyright: </td>
- <td> © 2001-2006, [[TWiki/TWikiContributor]]</td>
+ <td> © 2001-2007, [[TWiki/TWikiContributor]]</td>
</tr>
<tr>
<td align="right"> License: </td>
</tr>
<tr>
<td align="right"> Plugin Version: </td>
- <td> 01 Feb 2006 </td>
+ <td> 15942 (22 Jan 2008) </td>
</tr>
<tr>
<td align="right"> Change History: </td>
<td> </td>
</tr>
<tr>
+ <td align="right"> 20 May 2007 </td>
+ <td> Added renderWikiWordHandler </td>
+ </tr>
+ <tr>
<td align="right"> 01 Feb 2006: </td>
<td> Dakar changes </td>
</tr>
<td> $TWiki::Plugins::VERSION 1.1 </td>
</tr>
<tr>
- <td align="right"> CPAN Dependencies: </td>
- <td> none </td>
- </tr>
- <tr>
- <td align="right"> Other Dependencies: </td>
- <td> none </td>
- </tr>
- <tr>
- <td align="right"> Perl Version: </td>
- <td> 5.005 </td>
+ <td align="right"> Dependencies: </td>
+ <td> %$DEPENDENCIES </td>
</tr>
<tr>
<td align="right"> TWiki:Plugins/Benchmark: </td>
+# <a name="File Attachments"></a> File Attachments
+
+_Each topic can have one or more files of any type attached to it by using the Attach screen to upload (or download) files from your local PC. Attachments are stored under revision control: uploads are automatically backed up; all previous versions of a modified file can be retrieved._
+
<div>
<ul>
<li><a href="#File Attachments"> File Attachments</a><ul>
</ul>
</div>
-# <a name="File Attachments"></a> File Attachments
-
-_Each topic can have one or more files of any type attached to it by using the Attach screen to upload (or download) files from your local PC. Attachments are stored under revision control: uploads are automatically backed up; all previous versions of a modified file can be retrieved._
-
## <a name="What Are Attachments Good For?"></a> What Are Attachments Good For?
File Attachments can be used to archive data, or to create powerful customized groupware solutions, like file sharing and document management systems, and quick Web page authoring.
<th align="center" bgcolor="#ffffff" style="text-align: center; vertical-align: middle" valign="middle"><a href="%TOPIC%?sortcol=6;table=1;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#0066cc">Comment</font></a></th>
</tr>
<tr>
- <td align="center" bgcolor="#ffffff" style="text-align: center; vertical-align: top" valign="top"><img align="top" alt="txt" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/txt.gif" width="16" /><span>txt</span></td>
+ <td align="center" bgcolor="#ffffff" style="text-align: center; vertical-align: top" valign="top"><img align="top" alt="txt" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/txt.gif" width="16" /><span>txt</span></td>
<td align="left" bgcolor="#ffffff" style="text-align: left; vertical-align: top" valign="top"><a href="/twiki4/MAIN/bin/viewfile/TWiki/FileAttachment?rev=;filename=Sample.txt">Sample.txt</a></td>
<td align="left" bgcolor="#ffffff" style="text-align: left; vertical-align: top" valign="top"><a href="/twiki4/MAIN/bin/attach/TWiki/FileAttachment?filename=Sample.txt&revInfo=1" rel="nofollow" title="change, update, previous revisions, move, delete...">manage</a></td>
<td align="right" bgcolor="#ffffff" style="text-align: right; vertical-align: top" valign="top"> 0.1 K </td>
<td align="left" bgcolor="#ffffff" style="text-align: left; vertical-align: top" valign="top"> Just a sample </td>
</tr>
<tr>
- <td align="center" bgcolor="#ffffff" style="text-align: center; vertical-align: top" valign="top"><img align="top" alt="gif" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/gif.gif" width="16" /><span>gif</span></td>
+ <td align="center" bgcolor="#ffffff" style="text-align: center; vertical-align: top" valign="top"><img align="top" alt="gif" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/gif.gif" width="16" /><span>gif</span></td>
<td align="left" bgcolor="#ffffff" style="text-align: left; vertical-align: top" valign="top"><a href="/twiki4/MAIN/bin/viewfile/TWiki/FileAttachment?rev=;filename=Smile.gif">Smile.gif</a></td>
<td align="left" bgcolor="#ffffff" style="text-align: left; vertical-align: top" valign="top"><a href="/twiki4/MAIN/bin/attach/TWiki/FileAttachment?filename=Smile.gif&revInfo=1" rel="nofollow" title="change, update, previous revisions, move, delete...">manage</a></td>
<td align="right" bgcolor="#ffffff" style="text-align: right; vertical-align: top" valign="top"> 0.1 K </td>
The "Force New Revision" checkbox is a way to force it to create a separate revision each time you save.
-The [[TWiki.TWikiPreferences|TWiki/TWikiPreferences]] variable `FORCENEWREVISIONCHECKBOX` controls whether this is checked by default or not.
+The [[%SYSTEMWEB%.TWikiPreferences|SYSTEMWEB/TWikiPreferences]] variable `FORCENEWREVISIONCHECKBOX` controls whether this is checked by default or not.
On a related note, you can force **_every_** save to be a new revision number by setting `ReplaceIfEditedAgainWithin` to 0.
--- /dev/null
+## <a name="Formatting Tokens"></a> Formatting Tokens
+
+TWiki defines some standard special tokens that can be used to replace characters in some parameters - notably those to [[FormattedSearch]] and [[IfStatements]] - to defer evaluation of the parameter until later. These special tokens are often called "escapes", because they allow the character to "escape" from its normal meaning.
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <td><code>$n</code> or <code>$n()</code></td>
+ <td> New line. Use <code>$n()</code> if followed by alphanumeric character, e.g. write <code>Foo$n()Bar</code> instead of <code>Foo$nBar</code></td>
+ </tr>
+ <tr>
+ <td><code>$nop</code> or <code>$nop()</code></td>
+ <td> Is a "no operation". This variable gets removed; useful for nested search </td>
+ </tr>
+ <tr>
+ <td><code>$quot</code></td>
+ <td> Double quote (<code>"</code>) (\" also works) </td>
+ </tr>
+ <tr>
+ <td><code>$percnt</code></td>
+ <td> Percent sign (<code>%</code>) </td>
+ </tr>
+ <tr>
+ <td><code>$dollar</code></td>
+ <td> Dollar sign (<code>$</code>) </td>
+ </tr>
+</table>
+
+If you ever find yourself needing to escape an escape, you can use `$dollar` to escape the leading dollar, thus: `$dollarpercnt`.
+# <a name="TWiki Formatted Search"></a> TWiki Formatted Search
+
+_Inline search feature allows flexible formatting of search result_
+
+The default output format of a <code>[[%SEARCH{...}%|Main/VarSEARCH]]</code> 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 variables, such as `%SEARCH{ "food" format="| $topic | $summary |" }%`. See <code>[[%SEARCH{...}%|Main/VarSEARCH]]</code> for other search parameters, such as `separator=""`.
+
<div>
<ul>
<li><a href="#TWiki Formatted Search"> TWiki Formatted Search</a><ul>
</ul>
</div>
-# <a name="TWiki Formatted Search"></a> TWiki Formatted Search
-
-_Inline search feature allows flexible formatting of search result_
-
-The default output format of a <code>[[%SEARCH{...}%|Main/VarSEARCH]]</code> 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 variables, such as `%SEARCH{ "food" format="| $topic | $summary |" }%`. See <code>[[%SEARCH{...}%|Main/VarSEARCH]]</code> for other search parameters, such as `separator=""`.
-
## <a name="Syntax"></a> Syntax
Two parameters can be used to specify a customized search result:
<td><code>$web</code></td>
<td> Name of the web </td>
</tr>
- <tr>
- <td><code>$n</code> or <code>$n()</code></td>
- <td> New line. Use <code>$n()</code> if followed by alphanumeric character, e.g. write <code>Foo$n()Bar</code> instead of <code>Foo$nBar</code></td>
- </tr>
- <tr>
- <td><code>$nop</code> or <code>$nop()</code></td>
- <td> Is a "no operation". This variable gets removed; useful for nested search </td>
- </tr>
- <tr>
- <td><code>$quot</code></td>
- <td> Double quote (<code>"</code>). Alternatively write <code>\"</code> to escape it </td>
- </tr>
- <tr>
- <td><code>$percnt</code></td>
- <td> Percent sign (<code>%</code>) </td>
- </tr>
- <tr>
- <td><code>$dollar</code></td>
- <td> Dollar sign (<code>$</code>) </td>
- </tr>
</table>
### <a name="2. <code>format="..."</code> parameter"></a> 2. `format="..."` parameter
</tr>
<tr>
<td><code>$date</code></td>
- <td> Time stamp of last topic update, e.g. <code>29 Jun 2010 - 16:02</code></td>
+ <td> Time stamp of last topic update, e.g. <code>29 Jun 2010 - 16:07</code></td>
</tr>
<tr>
<td><code>$isodate</code></td>
- <td> Time stamp of last topic update, e.g. <code>2010-06-29T16:02Z</code></td>
+ <td> Time stamp of last topic update, e.g. <code>2010-06-29T16:07Z</code></td>
</tr>
<tr>
<td><code>$rev</code></td>
</tr>
<tr>
<td><code>$wikiusername</code></td>
- <td> Wiki user name of last topic update, like <code>Main.JohnSmith</code></td>
+ <td> Wiki user name of last topic update, like <code>%USERSWEB%.JohnSmith</code></td>
</tr>
<tr>
<td><code>$createdate</code></td>
</tr>
<tr>
<td><code>$createwikiusername</code></td>
- <td> Wiki user name of topic revision 1, e.g. <code>Main.JohnSmith</code></td>
+ <td> Wiki user name of topic revision 1, e.g. <code>%USERSWEB%.JohnSmith</code></td>
</tr>
<tr>
<td><code>$summary</code></td>
<td><code>$count(reg-exp)</code></td>
<td> 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 <code>$pattern(reg-exp)</code>. Example: <code>$count(.*?(---[+][+][+][+]) .*)</code> counts the number of <H4> headers in a page. </td>
</tr>
- <tr>
- <td><code>$n</code> or <code>$n()</code></td>
- <td> New line. Use <code>$n()</code> if followed by alphanumeric character, e.g. write <code>Foo$n()Bar</code> instead of <code>Foo$nBar</code></td>
- </tr>
- <tr>
- <td><code>$nop</code> or <code>$nop()</code></td>
- <td> Is a "no operation". This variable gets removed; useful for nested search </td>
- </tr>
- <tr>
- <td><code>$quot</code></td>
- <td> Double quote (<code>"</code>). Alternatively write <code>\"</code> to escape it </td>
- </tr>
- <tr>
- <td><code>$percnt</code></td>
- <td> Percent sign (<code>%</code>) </td>
- </tr>
- <tr>
- <td><code>$dollar</code></td>
- <td> Dollar sign (<code>$</code>) </td>
- </tr>
</table>
## <a name="Examples"></a> Examples
Enter a topic name to quickly jump to the topic, for example:
- **WebNotify** to jump to WebNotify in the current web
-- **Main.WebNotify** to jump to WebNotify in the Main web
-- **Main.** to jump to the home of the Main web
+- **%USERSWEB%.WebNotify** to jump to WebNotify in the %USERSWEB% web
+- **%USERSWEB%.** to jump to the home of the %USERSWEB% web
- **BrandNewTopic** to jump to a non existing topic in the current web, which is useful to create orphaned topics
Enter part of a topic name to get a list of similar topics, for example:
- **faq** to get
# TWiki Installation Error
Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
-- **Main.users** to jump to the Main web from any web, and get a list of topics about users (all in one step)
+- **%USERSWEB%.users** to jump to the %USERSWEB% web from any web, and get a list of topics about users (all in one step)
**_%T% Tip:_** Entering part of a topic name is a simple, yet powerful way to quickly navigate to content of interest, also in a large wiki.
- For **external site links**, you can type URLs directly into the text - `http://etcete.ra/...` - it'll be clear to anyone where they're headed on click.
-- TWiki is intended for world-wide use, and an internationally understood date format like <code>**01 Sep 2003**</code> or <code>**2003/09/01**</code> is preferred. It's clearer than the xx/xx/xx format, where a date like 9/1/01 can mean either Jan or Sep, depending on the local conventions of the readers. For months, use the first three letters: Jan, Feb, Mar, Apr,...
+- TWiki is intended for world-wide use, and an internationally understood date format like <code>**01 Sep 2010**</code> or <code>**2010-09-01**</code> is preferred. It's clearer than the xx/xx/xx format, where a date like 9/1/01 can mean either Jan or Sep, depending on the local conventions of the readers. For months, use the first three letters: Jan, Feb, Mar, Apr,...
- **TIP:** Check the source when you want to find out how something is formatted: click <code>**Edit**</code> on the lower toolbar. To see earlier versions, click <code>**More**</code>, then check <code>**Raw text format**</code> and click <code>**View revision**</code>. A bit of HTML experience can't hurt, but you'll soon see with [[TWikiShorthand]] how far that is from necessary.
**_Related Topics:_** [[UserDocumentationCategory]]
+
+-- **_Contributors:_** TWiki:Main.MikeMannix, TWiki:Main.PeterThoeny
### <a name="Displaying the Parent - Current"></a><a name="Displaying the Parent - Current "></a> Displaying the Parent - Current - Children block
-> %INCLUDE{"%TWIKIWEB%.HierarchicalNavigation" section="all"}%
+> %INCLUDE{"%SYSTEMWEB%.HierarchicalNavigation" section="all"}%
generates:
### <a name="Displaying child topics"></a> Displaying child topics
> *Child topics:*
-> %INCLUDE{"%TWIKIWEB%.HierarchicalNavigation" section="children"}%
+> %INCLUDE{"%SYSTEMWEB%.HierarchicalNavigation" section="children"}%
generates:
-# <a name="=IF= Statements"></a> `IF` Statements
+# <a name="IF Statements"></a> IF Statements
The `%IF%` construct gives TWiki the power to include content in topics based on the value of simple expressions.
In the example above, if CONDITION evaluates to TRUE, then THEN will be included in the topic; otherwise ELSE will be included.
-What can be included in the THEN and ELSE parameters is obviously limited by standard TWiki syntax for parameters.
+Note that because of the way TWiki evaluates, then whatever is in the THEN and ELSE parameters will already have been expanded by the time the condition is actually evaluated. The standard [[FormatTokens]] can be used in the THEN and ELSE parameters when you need to delay evaluation of (for example) a TWiki variable.
-The basic syntax of a condition is as follows:
+The basic syntax of a condition is the same as [[the syntax used for queries|Main/QuerySearch]], with the addition of the following special operators:
- expr ::= '(' expr ')' ;
- expr ::= andexpr | andexpr 'or' expr ;
- andexpr ::= notexpr | notexpr 'and' andexpr ;
- notexpr ::= basexpr | 'not' baseexpr ;
- basexpr ::= atom | uop atom | atom bop basexpr ;
- uop ::= 'context' | 'defined' | '$' ;
- bop ::= '=' | '!=' | '>' | '<' | '>=' | '<=' ;
- atom ::= context identifier, TWiki variable name, single-quoted string, or configuration item
<table border="1" cellpadding="0" cellspacing="0">
<tr>
- <th bgcolor="#99CCCC" colspan="2"><strong> Operators </strong></th>
- </tr>
- <tr>
- <td> and </td>
- <td> True if both sides are true </td>
- </tr>
- <tr>
- <td> or </td>
- <td> True if one or other side is true </td>
+ <td> context </td>
+ <td> True if the current context is set (see below) </td>
</tr>
<tr>
- <td> not </td>
- <td> negate the following expression </td>
+ <td> allows </td>
+ <td><code>'X' allows 'Y'</code> is true if web/topic 'X' exists and allows access mode 'Y' for the current user. Web access rights are only checked if there is no topic called 'X'. </td>
</tr>
<tr>
- <td> =, != </td>
- <td> String comparison </td>
+ <td> istopic </td>
+ <td><code>istopic 'X'</code> is true if topic 'X' exists </td>
</tr>
<tr>
- <td> <, >, <=, >= </td>
- <td> Number comparison (there is no explicit numeric =) </td>
+ <td> isweb </td>
+ <td><code>isweb 'X'</code> is true if web 'X' exists </td>
</tr>
<tr>
- <td> context </td>
- <td> True if the current context is set (see below) </td>
+ <td> ingroup </td>
+ <td><code>'X' ingroup 'Y'</code> is true if user 'X' is in group 'Y' </td>
</tr>
<tr>
<td> defined </td>
</tr>
<tr>
<td> $ </td>
- <td> expands a URL parameter or [[Main/TWikiVariables]]. Plugin handlers <strong>are not called</strong>. Built-in variables and user-defined preferences are supported. You can pass a limited subset of parameters to TWiki variables by enclosing the variable name in single quotes; for example, <code>$ 'VARIABLE{value}'</code>. The <code>'VARIABLE{value}'</code> string may <strong>not</strong> contain quotes (' or "). </td>
+ <td> expands a URL parameter or [[Main/TWikiVariables]] name. Plugin handlers <strong>are not called</strong>. Built-in variables and user-defined preferences are supported. You can pass a limited subset of parameters to TWiki variables by enclosing the variable name in single quotes; for example, <code>$ 'VARIABLE{value}'</code>. The <code>'VARIABLE{value}'</code> string may <strong>not</strong> contain quotes (' or "). </td>
+ </tr>
+ <tr>
+ <td> {X} </td>
+ <td> expands to the value of the configuration variable {X} - for example, <code>{ScriptUrlPath}</code></td>
</tr>
</table>
-examples:
+**_Examples:_**
+
+1. TWiki variable defined or not
- TWiki variable defined or not
%IF{"defined WIKINAME" then="WIKINAME is defined" else="WIKINAME is not defined"}%
+2. Compare TWiki variable
+
You are %IF{ "$ WIKINAME='TWikiGuest' and not defined OPEN_DAY" then="not" }% allowed to
%IF{ "context view" then="view" else="edit"}% this TWiki today.
- URL parameter
- %IF{ "defined search" then="Search: %URLPARAM{search}%" else="No search passed in"}%
+3. URL parameter
- Configuration item set or not
- %IF{ "{AntiSpam}{HideUserDetails}" then="User details are hidden" }%
+ %IF{ "defined search" then="Search: $percntURLPARAM{search}$percnt" else="No search passed in"}%
+
+4. Range test on URL parameter
url param t is %IF{ "0 < $ t and $ t < 1000" then="in" else="out of"}% range.
- Text comparison
+5. Text comparison of URL parameter
+
%IF{ "$'URLPARAM{scope}'='text'" then="Plain text search" }%
+6. Configuration item set or not
+
+ %IF{ "{AntiSpam}{HideUserDetails}" then="User details are hidden" }%
+
+7. Plugin enabled test
+
+ TablePlugin is %IF{ "context TablePluginEnabled" then="enabled" else="disabled" }%.
+
+expands to: %BR% [[TablePlugin]] is enabled.
+
+8. Check access permissions
+
+ You %IF{"'%TOPIC%' allows 'change'" then="can" else="cannot"}% change this topic.
+ You %IF{"'Sandbox.TestTopic' allows 'change'" then="can" else="cannot"}% change Sandbox.TestTopic.
+ You %IF{"'Sandbox' allows 'change'" then="can" else="cannot"}% change Sandbox web
+
+expands to: %BR% You can change this topic. You can change [[TestTopic]]. You can change Sandbox web
+
+9. Check topic existance
+
+ Topic Sandbox.TestTopic %IF{"istopic 'Sandbox.TestTopic'" then="exists" else="does not exist"}%
+ Web Sandbox.TestTopic %IF{"isweb 'Sandbox'" then="exists" else="does not exist"}%
+
+expands to: %BR% Topic [[TestTopic]] exists Web [[TestTopic]] exists
+
+10. Group membership
+
+ You %IF{"'%USERNAME%' ingroup 'TWikiAdminGroup'" then="are an admin" else="are a normal user"}%
+
+expands to: %BR% You are an admin
+
**Configuration items** are defined in [configure](http://www.dementia.org/twiki/configure). You cannot see the value of a configuration item, you can only see if the item is set or not.
**Context identifiers** are used in TWiki to label various stages of the rendering process. They are especially useful for [[skin|Main/TWikiSkins]] authors to find out where they are in the rendering process. The following context identifiers are available:
<td> in search script (see [[Main/TWikiScripts]]) </td>
</tr>
<tr>
+ <td> textareas_hijacked </td>
+ <td> provided for use by editors that highjack textareas, and want to signal this fact. This is used by skins, for example, so they can suppress extra controls when textareas have been hijacked. </td>
+ </tr>
+ <tr>
<td> view </td>
<td> in view script (see [[Main/TWikiScripts]]) </td>
</tr>
<td> rest </td>
<td> in rest script (see [[Main/TWikiScripts]]) </td>
</tr>
+ <tr>
+ <td> registration_supported </td>
+ <td> registration is supported by the current [[Main/UserMapper]]</td>
+ </tr>
+ <tr>
+ <td> registration_enabled </td>
+ <td> set if <code>{Register}{EnableNewUserRegistration}</code> is on, and registrationis supported </td>
+ </tr>
+ <tr>
+ <td> passwords_modifyable </td>
+ <td> set if the password manager support changing the password / email </td>
+ </tr>
</table>
In addition there is a context identifier for each enabled plugin; for example, if `GallousBreeksPlugin` is installed **and enabled**, then the context ID `GallousBreeksPluginEnabled` will be set. Other extensions may set additional context identifiers.
The `%IF%` statement is deliberately kept simple. In particular, note that there is no way to conditionally execute a Set statement. If you need more sophisticated control over formatting, then consider using the [[SpreadSheetPlugin]].
+
+Note also that while the [[query syntax|Main/QuerySearch]] can be used to access form fields, there are some contexts in which an IF statement may be used where there is no topic context, or the topic context is not what you expected.
<li><a href="#1. Display regression test resul"> 1. Display regression test results in a TWiki page</a></li>
<li><a href="#2. Display Google's robot.txt fi"> 2. Display Google's robot.txt file</a></li>
<li><a href="#3. Display the current time in T"> 3. Display the current time in Tokyo in a TWiki page</a></li>
+ <li><a href="#4. Include a topic _MyTopic wit"> 4. Include a topic MyTopic with two parameters</a></li>
</ul>
</li>
</ul>
## <a name="Syntax Example"></a> Syntax Example
-`%INCLUDE{ "page" pattern="reg-exp" rev="2" warn="off" section="clients" }%`
+`%INCLUDE{ "page" pattern="reg-exp" rev="2" warn="off" section="clients" PARAMETER1="value" PARAMETER2="Some value"}%`
-The `pattern` parameter is optional and allows you to extract some parts of 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).*"`. You need to make sure that the integrity of a web page is not compromised; for example, if you include a table, make sure to include everything including the table end tag.
+The `pattern` parameter is optional and allows you to extract some parts of a web page. Specify a %SYSTEMWEB%.RegularExpression that scans from start (`'^'`) to end and contains the text you want to keep in parenthesis, e.g., `pattern="^.*?(from here.*?to here).*"`. You need to make sure that the integrity of a web page is not compromised; for example, if you include a table, make sure to include everything including the table end tag.
+
+The example parameters PARAMETER1 and PARAMETER2 will be defined as a variable within the scope of the included topic. The example parameters shown will result in %PARAMETER1% and %PARAMETER2% being defined within the included topic.
[[VarINCLUDE]] explains the other parameters.
- You get:
- Tokyo:
+### <a name="4. Include a topic _MyTopic with"></a> 4. Include a topic MyTopic with two parameters
+
+You include the topic with this line
+
+ %INCLUDE{ "MyTopic" BETTER="apples" WORSE="Oranges"}%
+
+An example of a very simple MyTopic could contain
+
+ * I like %BETTER% better than %WORSE%.
+
+The result would be
+
+- I like apples better than oranges.
+
**_Related Topics:_** [[VarINCLUDE]], [[UserDocumentationCategory]]
Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
-# <a name="Plugin Diagnostics"></a> Plugin Diagnostics
+## <a name="Plugin Diagnostics"></a> Plugin Diagnostics
<table border="1">
<tr>
**Creating image variables**
-You may find it easier to write shorthand graphic notation. You can create your own image variables by defining them in a preference topic (most likely [[Main.TWikiPreferences|Main/TWikiPreferences]].)
+You may find it easier to write shorthand graphic notation. You can create your own image variables by defining them in a preference topic (most likely [[%USERSWEB%.TWikiPreferences|USERSWEB/TWikiPreferences]].)
A variable name may be one letter, like `Y`, or may be longer like `HELP`, `WARN` etc. You can also add your own images, e.g. a `NEW`, or a `ASK` to ask question.
When you're creating main gateway pages, you may want to temporarily (or permanently) restrict editing to yourself or a limited group of people. You can do this with a Preference setting that includes one or more users and groups. Only auhorized users will be able to use <code>**Edit**</code>.
-- **_Example:_** <code>**Set ALLOWTOPICCHANGE = Main.UserName, Main.GroupName**</code>
+- **_Example:_** <code>**Set ALLOWTOPICCHANGE = %USERSWEB%.UserName, %USERSWEB%.GroupName**</code>
- %T% **To hide the setting:** Use HTML comment tags - put <code>**<!--**</code> on the line \_above the setting, and <code>**-->**</code> on the line below.
----
If you'd like to have the same customised logo for all the webs, make these changes in [[TWikiPreferences]] instead of each web's WebPreferences, e.g.,
-- `Set WEBLOGOIMG = %PUBURLPATH%/Main/WebPreferences/mylogo.gif`
+- `Set WEBLOGOIMG = %PUBURLPATH%/%USERSWEB%/WebPreferences/mylogo.gif`
----
## <a name="Add Your Favorite _JavaScript Fe"></a> Add Your Favorite JavaScript Features
-You're no doubt familiar or better with HTML, JS, and "webmastering". Without getting into the [[TWikiTemplates]] system yet, you can easily edit the <code>**view.tmpl**</code> (in the `templates` directory) for some dramatic effects. The top of the template is mostly regular HTML with some variables. Open up some space in the <code>**<head>**</code> area, and you can drop in reliable JavaScripts - a pop-up window script, for example - or tag it as an external script.
+You're no doubt familiar or better with HTML, JS, and "webmastering". Without getting into the [[TWikiTemplates]] system yet, you can easily edit the <code>**view.pattern.tmpl**</code> (if you are using default pattern skin) (in the `templates` directory) for some dramatic effects. The top of the template is mostly regular HTML with some variables. Open up some space in the <code>**<head>**</code> area, and you can drop in reliable JavaScripts - a pop-up window script, for example - or tag it as an external script.
- %T% Obviously, you can do the same - place a link to an external stylesheet as well. If you set values for standard HTML tags, you can control a good deal of the type size, style and color with out adding CSS tags. **_example_**
</tr>
<tr>
<td> ISBN </td>
- <td><a href="http://service.bfast.com/bfast/click?bfmid=2181&sourceid=38704253&bfpid=" target="_top">http://service.bfast.com/bfast/click?bfmid=2181&sourceid=38704253&bfpid=</a></td>
- <td> Book with ISBN#$page (One click patent? Say no to Amazon!) </td>
+ <td><a href="http://www.bookfinder.com/search/?st=sr;ac=qr;isbn=" target="_top">http://www.bookfinder.com/search/?st=sr;ac=qr;isbn=</a></td>
+ <td> Book with ISBN $page </td>
</tr>
<tr>
<td> News </td>
<td> '$page' on TWiki.org </td>
</tr>
<tr>
+ <td> TWikibug </td>
+ <td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/" target="_top">http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/</a></td>
+ <td> '$page' on the TWiki issue tracking site </td>
+ </tr>
+ <tr>
+ <td> TWikirev </td>
+ <td><a href="http://develop.twiki.org/trac/changeset/" target="_top">http://develop.twiki.org/trac/changeset/</a></td>
+ <td> revision $page of TWiki svn </td>
+ </tr>
+ <tr>
<td> UseMod </td>
<td><a href="http://www.usemod.com/cgi-bin/wiki.pl" target="_top">http://www.usemod.com/cgi-bin/wiki.pl</a>? </td>
<td> '$page' on 'UseMod' Wiki site </td>
</tr>
<tr>
<td align="right"> Copyright: </td>
- <td> © 2006, TWiki:Main.AndreaSterbini, <a href="http://www.structuredwikis.com/" target="_top">Peter Thoeny</a></td>
+ <td> © 2001-2007, Andrea Sterbini, Peter Thoeny (<a href="http://www.twiki.net/" target="_top">TWIKI.NET</a>), [[TWiki/TWikiContributor]]</td>
</tr>
<tr>
<td align="right"> License: </td>
</tr>
<tr>
<td align="right"> Plugin Version: </td>
- <td> 11935 </td>
+ <td> 16052 (22 Jan 2008) </td>
</tr>
<tr>
<td align="right"> Change History: </td>
<td> </td>
</tr>
<tr>
+ <td align="right"> 25 Nov 2007: </td>
+ <td> 15752 - TWikibug:Item5006 - Renamed Bugs rule to TWikibug rule (PTh) </td>
+ </tr>
+ <tr>
+ <td align="right"> 13 Aug 2007: </td>
+ <td> 14545 - TWikibug:Item4451 - Added Bugs: rule (TWiki:Main.CrawfordCurrie) </td>
+ </tr>
+ <tr>
+ <td align="right"> 11 Aug 2007: </td>
+ <td> 14538 - Fixed broken ISBN link (TWiki:Main.PeterThoeny) </td>
+ </tr>
+ <tr>
<td align="right"> 08 Nov 2006: </td>
<td> 11935 - Added css <code></code> (TWiki:Main.PeterThoeny) </td>
</tr>
**_Related Topics:_** [[TWikiPlugins]], [[DeveloperDocumentationCategory]], [[AdminDocumentationCategory]], [[TWikiPreferences]], [[InterWikis]]
--- TWiki:Main.PeterThoeny - 08 Nov 2006
+-- TWiki:Main.PeterThoeny - 25 Nov 2007
# <a name="%TOPIC%"></a><a name=" %TOPIC%"></a> %TOPIC%
-[Mishoo JSCalendar](http://dynarch.com/mishoo/calendar.epl), packaged for use by plugins, skins and add-ons.
+
+
+%SHORTDESCRIPTION%
<div>
<ul>
<li><a href="#Summary of Contents"> Summary of Contents</a></li>
<li><a href="#Detailed Documentation"> Detailed Documentation</a><ul>
- <li><a href="#Settings"> Settings</a></li>
+ <li><a href="#TWiki::Contrib::_JSCalendarContr"> TWiki::Contrib::JSCalendarContrib::renderDateForEdit($name, $value, $format [, \%cssClass]) -> $html</a></li>
+ <li><a href="#TWiki::Contrib::_JSCalendarContr"> TWiki::Contrib::JSCalendarContrib::addHEAD($setup)</a></li>
+ <li><a href="#Using the Calendar in user forms"> Using the Calendar in user forms</a></li>
<li><a href="#Installation Instructions"> Installation Instructions</a></li>
<li><a href="#Contrib Info"> Contrib Info</a></li>
</ul>
## <a name="Detailed Documentation"></a> Detailed Documentation
-Read [the Mishoo documentation](http://www.dementia.org/twiki//view/doc/html/reference.html) or [visit the demo page](http://www.dementia.org/twiki//view).
+Read [the Mishoo documentation](http://www.dementia.org/twiki//view/doc/html/reference.html) or [visit the demo page](http://www.dementia.org/twiki//view) for detailed information on using the calendar widget.
+
+This package also includes a small Perl module to make using the calendar easier from TWiki plugins. This module includes the functions:
+
+### <a name="TWiki::Contrib::_JSCalendarContr"></a> TWiki::Contrib::JSCalendarContrib::renderDateForEdit($name, $value, $format [, \\%cssClass]) -> $html
+
+This is the simplest way to use calendars from a plugin.
+
+- `$name` is the name of the CGI parameter for the calendar (it should be unique),
+- `$value` is the current value of the parameter (may be undef)
+- `$format` is the format to use (optional; the default is set in `configure`). The HTML returned will display a date field and a drop-down calendar.
+- `\%options` is an optional hash containing base options for the textfield.
+
+Example:
+
+ use TWiki::Contrib::JSCalendarContrib;
+ ...
+ my $fromDate = TWiki::Contrib::JSCalendarContrib::renderDateForEdit(
+ 'from', '1 April 1999');
+ my $toDate = TWiki::Contrib::JSCalendarContrib::renderDateForEdit(
+ 'to', undef, '%Y');
+
+### <a name="TWiki::Contrib::_JSCalendarContr"></a> TWiki::Contrib::JSCalendarContrib::addHEAD($setup)
+
+This function will automatically add the headers for the calendar to the page being rendered. It's intended for use when you want more control over the formatting of your calendars than `renderDateForEdit` affords. `$setup` is the name of the calendar setup module; it can either be omitted, in which case the method described in the Mishoo documentation can be used to create calendars, or it can be `'twiki'`, in which case a Javascript helper function called 'showCalendar' is added that simplifies using calendars to set a value in a text field. For example, say we wanted to display the date with the calendar icon _before_ the text field, using the format `%Y %b %e`
+
+ # Add styles and javascript for the calendar
+ use TWiki::Contrib::JSCalendarContrib;
+ ...
-This package provides a `renderFormFieldForEditHandler` that could be invoked by a plugin to ensure that forms use the [Mishoo JSCalendar](http://dynarch.com/mishoo/calendar.epl) for editing.
+ sub commonTagsHandler {
+ ....
+ # Enable 'showCalendar'
+ TWiki::Contrib::JSCalendarContrib::addHEAD( 'twiki' );
-This package also includes a small Perl module to make using the calendar easier from TWiki plugins. This module includes the function:
+ my $cal = CGI::image_button(
+ -name => 'img_datefield',
+ -onclick =>
+ "return showCalendar('id_datefield','%Y %b %e')",
+ -src=> TWiki::Func::getPubUrlPath() . '/' .
+ TWiki::Func::getTwikiWebname() .
+ '/JSCalendarContrib/img.gif',
+ -alt => 'Calendar',
+ -align => 'middle' )
+ . CGI::textfield(
+ { name => 'date', id => "id_datefield" });
+ ....
+ }
- addHEAD( $setup )
+The first parameter to `showCalendar` is the id of the textfield, and the second parameter is the . See the Mishoo documentation for details of the '$e %B %Y' parameter.
-that can automatically add the required headers to the page being rendered. `$setup` is the name of the calendar setup module; it can either be ommitted, in which case the method described in the Mishoo documentation can be used to create calendars, or it can be `'twiki'`, in which case a helper function is added that simplifies using calendars to set a value in a text field. For example,
+`addHEAD` can be called from `commonTagsHandler` for adding the header to all pages, or from `beforeEditHandler` just for edit pages etc.
- # Add styles and javascript for the calendar
- require TWiki::Contrib::JSCalendarContrib;
- if( $@ || !$TWiki::Contrib::JSCalendarContrib::VERSION ||
- $TWiki::Contrib::JSCalendarContrib::VERSION < 0.961 ) {
- TWiki::Func::writeWarning('JSCalendarContrib >=0.961 not found '.$@);
- } else {
- TWiki::Contrib::JSCalendarContrib::addHEAD( 'twiki' );
- }
+### <a name="Using the Calendar in user forms"></a> Using the Calendar in user forms
- $html .= CGI::textfield(
- { name => 'datefield',
- id => "id_datefield" });
- $html .=
- CGI::image_button(
- -name => 'datefield_calendar',
- -onclick =>
- "return showCalendar('id_datefield','%e %B %Y')",
- -src=> TWiki::Func::getPubUrlPath() . '/' .
- TWiki::Func::getTwikiWebname() .
- '/JSCalendarContrib/img.gif',
- -alt => 'Calendar',
- -align => 'MIDDLE' );
- }
- }
+You can also use the calendar directly in your own hand-built forms, without having to write any code. Just add this inline in the topic text:
-The first parameter to showCalendar is the id of the textfield. See the Mishoo documentation for details of the '$e %B %Y' parameter.
+ %INCLUDE{"%SYSTEMWEB%/JSCalendarContribInline"}%
-Note that the header will only be added once, regardless of the number of times that addHEAD is called.
+Then, to display a calendar icon next to a text input field:
-`addHEAD` can be called from `commonTagsHandler` for adding the header to all pages, or to `beforeEditHandler` just for edit pages etc.
+ <input type="text" id="cal_val_here" />
+ <input type="image" src="%PUBURL%/%SYSTEMWEB%/JSCalendarContrib/img.gif" onclick="javascript: return showCalendar('cal_val_here','%e %B %Y')" />
-### <a name="Settings"></a> Settings
+If the contrib is installed, you will see such a field here:
-- Name of the perl package
- - Set STUB = TWiki::Contrib::JSCalendarContrib
-- What do I do
- - Set SHORTDESCRIPTION = [Mishoo JSCalendar](http://dynarch.com/mishoo/calendar.epl), packaged for use by plugins, skins and add-ons.
+<input id="cal_val_here" type="text" />
+ <input onclick="javascript: return showCalendar('cal_val_here','%e %B %Y')" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/JSCalendarContrib/img.gif" type="image" />
### <a name="Installation Instructions"></a> Installation Instructions
-- Download the archive from the Plugins web (see below)
-- Unpack it in your twiki installation directory. Content: <table border="1" cellpadding="0" cellspacing="0">
- <tr>
- <th bgcolor="#99CCCC"><strong> File: </strong></th>
- <th bgcolor="#99CCCC"><strong> Description: </strong></th>
- </tr>
- <tr>
- <td><code><b>data/TWiki/JSCalendarContrib.txt</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>lib/TWiki/Contrib/JSCalendarContrib.pm</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/twiki.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/bugtest-hidden-selects.html</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/calendar-blue2.css</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/calendar-blue.css</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/calendar-brown.css</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/calendar-green.css</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/calendar.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/calendar.php</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/calendar-setup.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/calendar-setup_stripped.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/calendar_stripped.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/calendar-system.css</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/calendar-tas.css</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/calendar-win2k-1.css</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/calendar-win2k-2.css</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/calendar-win2k-cold-1.css</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/calendar-win2k-cold-2.css</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/ChangeLog</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/dayinfo.html</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/doc/html/field-button.jpg</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/doc/html/reference.css</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/doc/html/reference.html</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/doc/html/reference-Z-S.css</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/doc/reference.pdf</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/img.gif</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/index.html</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-af.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-al.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-bg.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-big5.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-big5-utf8.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-br.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-ca.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-cs-utf8.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-cs-win.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-da.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-de.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-du.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-el.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-en.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-es.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-fi.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-fr.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-he-utf8.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-hr.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-hr-utf8.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-hu.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-it.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-jp.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-ko.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-ko-utf8.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-lt.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-lt-utf8.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-lv.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-nl.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-no.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-pl.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-pl-utf8.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-pt.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-ro.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-ru_win_.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-ru.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-si.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-sk.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-sp.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-sv.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-tr.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/calendar-zh.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/lang/cn_utf8.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/active-bg.gif</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/dark-bg.gif</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/hover-bg.gif</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/menuarrow.gif</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/normal-bg.gif</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/rowhover-bg.gif</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/status-bg.gif</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/theme.css</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/title-bg.gif</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/today-bg.gif</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/skins/aqua/transparent-bg.png</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/menuarrow.gif</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/menuarrow2.gif</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/multiple-dates.html</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/README</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/release-notes.html</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/simple-1.html</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/simple-2.html</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/simple-3.html</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/test.php</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/JSCalendarContrib/test-position.html</b></code></td>
- <td> </td>
- </tr>
-</table>
+You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.
+
+Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.
+
+- If you have TWiki 4.2 or later, you can install from the `configure` interface (Go to Plugins->Find More Extensions)
+ - See the [installation supplement](http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement) on TWiki.org for more information.
+- If you have any problems, then you can still install manually from the command-line:
+ 1. Download one of the `.zip` or `.tgz` archives
+ 2. Unpack the archive in the root directory of your TWiki installation.
+ 3. Run the installer script ( `perl <module>_installer` )
+ 4. Run `configure` and enable the module, if it is a plugin.
+ 5. Repeat for any missing dependencies.
+- If you are **still** having problems, then instead of running the installer script:
+ 1. Make sure that the file permissions allow the webserver user to access all files.
+ 2. Check in any installed files that have existing `,v` files in your existing install (take care **not** to lock the files when you check in)
+ 3. Manually edit LocalSite.cfg to set any configuration variables.
+
+<div class="twikiAlert">%X% WARNING: SYSTEMWEB is not defined in this TWiki. Please add these definitions to your [[Main/TWikiPreferences]], if they are not already there:<br /><pre> * Set SYSTEMWEB = %TWIKIWEB%<br /> * Set USERSWEB = %MAINWEB%</pre></div>
-- Make sure that all files are readable by the web server user
- An administrator can customize the appearance of the calendar by setting the following in `LocalSite.cfg`<table border="1" cellpadding="0" cellspacing="0">
<tr>
<th bgcolor="#99CCCC"><strong> Setting </strong></th>
### <a name="Contrib Info"></a> Contrib Info
+Another great TWiki extension from the [ **WikiRing** ](http://wikiring.com) - working together to improve your wiki experience!
+
<table border="1" cellpadding="0" cellspacing="0">
<tr>
<td align="right"> Author: </td>
- <td> TWiki:Main/CrawfordCurrie <a href="http://www.c-dot.co.uk" target="_top">http://www.c-dot.co.uk</a></td>
+ <td> TWiki:Main/CrawfordCurrie <a href="http://c-dot.co.uk" target="_top">http://c-dot.co.uk</a></td>
</tr>
<tr>
<td align="right"> Version: </td>
- <td> 11704 of the Mishoo calendar </td>
+ <td> 16236 (22 Jan 2008) of the Mishoo calendar </td>
</tr>
<tr>
<td align="right"> Copyright ©: </td>
<td> </td>
</tr>
<tr>
- <td> 11594 </td>
+ <td align="right"> 6 Sep 2007 </td>
+ <td> Bugs:Item4030 Added doc for using the calendar in user forms </td>
+ </tr>
+ <tr>
+ <td align="right"> 13603 </td>
+ <td> Bugs:Item2982 cleaned up the interface to the contrib, re-added a date rendering function with a more generic interface </td>
+ </tr>
+ <tr>
+ <td align="right"> 11594 </td>
<td> Allow format to be configured. </td>
</tr>
<tr>
- <td> 11415 </td>
+ <td align="right"> 11415 </td>
<td> Add a <code>renderFormFieldForEditHandler</code> so other plugins can forward to this handler to add the date field to the [[Main/TWikiForms]]. (TWiki:Main.ThomasWeigert) </td>
</tr>
<tr>
- <td> 10247 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item2054" rel="nofollow">Item2054</a> put the calendar at z-index 2000, way above pattern skin divs. </td>
+ <td align="right"> 10247 </td>
+ <td> Bugs:Item2054 put the calendar at z-index 2000, way above pattern skin divs. </td>
</tr>
<tr>
- <td> 6634 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item453" rel="nofollow">Item453</a> removed [[Main/EditTablePlugins]] private copy of the Mishoo JS calendar, and made sure it works with [[Main/JSCalendarContrib]]. Improved the documentation of the JSCalendar while I was there. </td>
+ <td align="right"> 6634 </td>
+ <td> Bugs:Item453 removed [[Main/EditTablePlugins]] private copy of the Mishoo JS calendar, and made sure it works with [[Main/JSCalendarContrib]]. Improved the documentation of the JSCalendar while I was there. </td>
</tr>
<tr>
- <td> 6626 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item468" rel="nofollow">Item468</a> updated docs for Dakar release </td>
+ <td align="right"> 6626 </td>
+ <td> Bugs:Item468 updated docs for Dakar release </td>
</tr>
<tr>
- <td> 5048 </td>
+ <td align="right"> 5048 </td>
<td> Cairo readiness </td>
</tr>
<tr>
- <td> 5039 </td>
+ <td align="right"> 5039 </td>
<td> Split from [[Main/SharedCode]]</td>
</tr>
<tr>
</tr>
</table>
-**_Related Topics:_** [[TWikiPreferences]]
+**_Related Topics:_** %SYSTEMWEB%.TWikiPreferences
--- /dev/null
+Inline include of [[JSCalendarContrib]] HTML for use in forms.
Usage:
- %INCLUDE{%TWIKIWEB%.LanguageSelector}%
+ %INCLUDE{%SYSTEMWEB%.LanguageSelector}%
Result:
-# <a name="%TOPIC%"></a><a name=" %TOPIC%"></a> %TOPIC%
+# <a name="Mailer Contrib"></a><a name=" Mailer Contrib"></a> Mailer Contrib
-Add-on to the TWiki kernel that allows users to "subscribe" to regularly scheduled e-mails containing either:
+[](http://wikiring.com)
+
+Allows users to "subscribe" to regularly scheduled e-mails containing either:
- A report on changes to all topics that have changed within a particular TWiki web.
- A report on changes to a specific topic or set of topics the user can define flexibly.
- The entire content of a specific topic or set of topics. This is referred to as "news mode."
+- The companion plugin (TWiki:Plugins.SubscribePlugin) lets you trivially add a "Subscribe to changes" button to topics
-**WARNING: TWiki-4 only. If you want to use this extension with an earlier version of TWiki, please see [here](http://twiki.org/cgi-bin/view/Plugins/%TOPIC%?rev=1.17)**
+<div>WARNING: TWiki-4 only. If you want to use this extension with an earlier version of TWiki, please use <a href="http://twiki.org/cgi-bin/attach/Plugins/%TOPIC%?filename=%TOPIC%.zip&revInfo=1" target="_top">revision 17 of the zip</a>.</div>
<div>
<ul>
- <li><a href="#tools/mailnotify"> <code>tools/mailnotify</code></a></li>
- <li><a href="#TWiki/Contrib/_MailerContrib cod"> <code>TWiki/Contrib/MailerContrib</code> code library</a></li>
- <li><a href="#package TWiki::Contrib::_MailerC"> package TWiki::Contrib::MailerContrib::WebNotify</a><ul>
- <li><a href="#ClassMethod new($web, $topic)"> ClassMethod new($web, $topic)</a></li>
- <li><a href="#ObjectMethod write_WebNotify()"> ObjectMethod writeWebNotify()</a></li>
- <li><a href="#ObjectMethod getSubscriber($name"> ObjectMethod getSubscriber($name, $noAdd)</a></li>
- <li><a href="#ObjectMethod getSubscribers()"> ObjectMethod getSubscribers()</a></li>
- <li><a href="#ObjectMethod subscribe($name, $t"> ObjectMethod subscribe($name, $topics, $depth)</a></li>
- <li><a href="#ObjectMethod unsubscribe($name,"> ObjectMethod unsubscribe($name, $topics, $depth)</a></li>
- <li><a href="#ObjectMethod stringify() -> stri"> ObjectMethod stringify() -> string</a></li>
- <li><a href="#ObjectMethod processChange($chan"> ObjectMethod processChange($change, $db, $changeSet, $seenSet, $allSet)</a></li>
- <li><a href="#ObjectMethod processCompulsory($"> ObjectMethod processCompulsory($topic, $db, \%allSet)</a></li>
- <li><a href="#ObjectMethod isEmpty() -> boolea"> ObjectMethod isEmpty() -> boolean</a></li>
- </ul>
- </li>
- <li><a href="#package TWiki::Contrib::_MailerC"> package TWiki::Contrib::MailerContrib::Subscriber</a><ul>
- <li><a href="#ClassMethod new($name)"> ClassMethod new($name)</a></li>
- <li><a href="#ObjectMethod get_EmailAddresses("> ObjectMethod getEmailAddresses() -> list</a></li>
- <li><a href="#ObjectMethod subscribe($subs)"> ObjectMethod subscribe($subs)</a></li>
- <li><a href="#ObjectMethod unsubscribe($subs)"> ObjectMethod unsubscribe($subs)</a></li>
- <li><a href="#ObjectMethod is_SubscribedTo($to"> ObjectMethod isSubscribedTo($topic) -> $subscription</a></li>
- <li><a href="#ObjectMethod is_UnsubscribedFrom"> ObjectMethod isUnsubscribedFrom($topic) -> $subscription</a></li>
- <li><a href="#ObjectMethod stringify() -> stri"> ObjectMethod stringify() -> string</a></li>
- </ul>
- </li>
- <li><a href="#package TWiki::Contrib::_MailerC"> package TWiki::Contrib::MailerContrib::Subscription</a><ul>
- <li><a href="#ClassMethod new($pages, $childDe"> ClassMethod new($pages, $childDepth, $news)</a></li>
- <li><a href="#ObjectMethod stringify() -> stri"> ObjectMethod stringify() -> string</a></li>
- <li><a href="#ObjectMethod matches($topic, $db"> ObjectMethod matches($topic, $db, $depth) -> boolean</a></li>
- <li><a href="#ObjectMethod getMode() -> $mode"> ObjectMethod getMode() -> $mode</a></li>
- </ul>
- </li>
- <li><a href="#package TWiki::Contrib::_MailerC"> package TWiki::Contrib::MailerContrib::Change</a><ul>
- <li><a href="#ClassMethod new($web)"> ClassMethod new($web)</a></li>
- <li><a href="#ObjectMethod merge($change)"> ObjectMethod merge($change)</a></li>
- <li><a href="#ObjectMethod expandHTML($html) -"> ObjectMethod expandHTML($html) -> string</a></li>
- <li><a href="#ObjectMethod expandPlain() -> st"> ObjectMethod expandPlain() -> string</a></li>
- </ul>
- </li>
- <li><a href="#package TWiki::Contrib::_MailerC"> package TWiki::Contrib::MailerContrib::UpData</a><ul>
- <li><a href="#ClassMethod new($web)"> ClassMethod new($web)</a></li>
- <li><a href="#ObjectMethod getParent($topic) -"> ObjectMethod getParent($topic) -> string</a></li>
- </ul>
- </li>
- <li><a href="#package TWiki::Contrib::Mailer"> package TWiki::Contrib::Mailer</a><ul>
- <li><a href="#StaticMethod mailNotify($webs, $"> StaticMethod mailNotify($webs, $session, $verbose)</a></li>
- </ul>
- </li>
+ <li><a href="#tools/mailnotify"> tools/mailnotify</a></li>
+ <li><a href="#TWiki/Contrib/_MailerContrib cod"> TWiki/Contrib/MailerContrib code library</a></li>
<li><a href="#Installation Instructions"> Installation Instructions</a><ul>
<li><a href="#Setting up your cron job(s)"> Setting up your cron job(s)</a></li>
</ul>
</ul>
</div>
-# <a name="tools/mailnotify"></a> `tools/mailnotify`
+## <a name="tools/mailnotify"></a> tools/mailnotify
-The central component of [[MailerContrib]] is a script, `tools/mailnotify`, that generates and sends out the emails based on analysis of
+The central component of MailerContrib is a script, `tools/mailnotify`, that generates and sends out the emails based on analysis of
1. users' subcriptions listed in the WebNotify topic in each web, and
2. changes within the respective webs.
Each web can optionally contain a topic called WebNotify.
-Users subscribe to email notifications using their [[WikiName]] or an alternative email address, and can specify the webs/topics they wish to track using one of these bullet list formats:
+Users subscribe to email notifications using their [[WikiName]] or an alternative email address, and can specify the webs/topics they wish to track, WWhole groups of users can also be subscribed for notification.
+
+The general format of a subscription is:
+
+_three spaces_ `*` _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:
-_three spaces_ \* [ _webname_ . ] _wikiName_ - _SMTP mail address_<br />_three spaces_ \* [ _webName_ . ] _wikiName_<br />_three spaces_ \* _SMTP mail address_<br />_three spaces_ \* _SMTP mail address_ : _topics_<br />_three spaces_ \* [ _webname_ . ] _wikiName_ : _topics_
+- ... **without** a _Web._ prefix
+- ...that exist in this web.
-In the above examples, _topics_ is a space-separated list of topic names. The user may further customize the specific content they will receive using the following formats:
+Users may further customize the specific content they will receive using the following controls:
-- Specify topics without a _Web._ prefix
-- Topics must exist in this web.
-- Topics may be specified using \* wildcards
-- Each topic may optionally be preceded by a '+' or '-' sign. The '+' sign means "subscribe to this topic" (the same as not putting anything). The '-' sign means "unsubscribe" or "don't send notifications regarding this topic". This allows users to elect to filter out certain topics (and their children, to an arbitrary depth). Topic filters ('-') take precedence over topic includes ('+').
+- You can use `*` in a topic name, where it is treated as a [wildcard character](http://en.wikipedia.org/wiki/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.
+- Each topic may optionally be preceded by a '+' or '-' sign. The '+' sign means "subscribe to this topic". The '-' sign means "unsubscribe" or "don't send notifications regarding this particular topic". This allows users to elect to filter out certain topics. Topic filters ('-') take precedence over topic includes ('+') i.e. if you unsubscribe from a topic it will cancel out any subscriptions to that topic.
- Each topic may optionally be followed by an integer in parentheses, indicating the depth of the tree of children below that topic. Changes in all these children will be detected and reported along with changes to the topic itself. _Note_ This uses the TWiki "Topic parent" feature.
-- Each topic may optionally be immediately followed by an exclamation mark ! or a question mark ? with no intervening spaces, indicating that the topic (and children if there is a tree depth specifier as well) should be mailed out as **complete topics** instead of change summaries. ! causes the topic to be mailed every time even if there have been no changes, ? will mail the topic only if there have been changes to it. This only makes sense for subscriptions.
+- Each topic may optionally be immediately followed by an exclamation mark ! or a question mark ? with no intervening spaces, indicating that the topic (and children if there is a tree depth specifier as well) should be mailed out as **complete topics** instead of change summaries. ! causes the topic to be mailed every time _even if there have been no changes_, and ? will mail the topic only if there have been changes to it. This only makes sense for subscriptions, and is intended for mailshotting regular newletters.
For example: Subscribe Daisy to all changes to topics in this web.
* daisy.cutter@flowers.com
-Subscribe Daisy to all changes in all webs that start with `Web`.
+Subscribe Daisy to all changes to topics that start with `Web`.
- * daisy.cutter@flowers.com: 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`
* GardenGroup: AllNewsLetters? (3)
* petunia@flowers.com: - ManureNewsLetter
-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 _TWiki group_ is listed for notification, the group will be recursively expanded to the e-mail addresses of all members.
-
-**_%T% Tip:_** List names in alphabetical order to make it easier to find the names.
-
-In the future it is intended that individual users will be able to control the frequency with which they are notified of topic changes, by changing a schedule specification in their home topic. However at present, the notification schedule is controlled by the frequency of activation of the `cron` job that runs the `mailnotify` script.
-
-%RED% **_Note_** `mailnotify` ignores permissions in webs. It is entirely possible for a user to get added to one of the subscription topics in a web, when they are not authorised to view the topics in that web. This could result in them having access to sensitive information, particularly with news mode. %ENDCOLOR%
-
-Note that when using the "news mode" ! or ? specifiers are used the entire topic text is mailed out as HTML. The `newsletter` template is used to generate the content in this mail, using whatever skin is selected in the topic being mailed.
-
-In addition, the %STARTPUBLISH% and %STOPPUBLISH% markers used by TWiki:Plugins.PublishContrib to delimit the text to be published are respected.
-
-# <a name="TWiki/Contrib/_MailerContrib cod"></a> `TWiki/Contrib/MailerContrib` code library
-
-The second part of the module is a code library that provides the services for other applications to modify the subscription topics through a clean, well documented API. This allows (for example) plugin developers to add (for example) a "Register me for this newsletter" button to their pages. The main interface is the `WebNotify` package described below.
-
-# <a name="package TWiki::Contrib::_MailerC"></a> package TWiki::Contrib::MailerContrib::WebNotify
-
-Object that represents the contents of a [[WebNotify]] topic in a TWiki web
-
-## <a name="ClassMethod new($web, $topic)"></a> [[ClassMethod]] new($web, $topic)
-
-Create a new object by parsing the content of the given topic in the given web. This is the normal way to load a [[WebNotify]] topic. If the topic does not exist, it will create an empty object.
-
-## <a name="ObjectMethod write_WebNotify()"></a> [[ObjectMethod]] writeWebNotify()
-
-Write the object to the [[WebNotify]] topic it was read from. If there is a problem writing the topic (e.g. it is locked), the method will return an error message. If everything is ok it will return undef.
-
-## <a name="ObjectMethod getSubscriber($name"></a> [[ObjectMethod]] getSubscriber($name, $noAdd)
-
-- `$name` - Name of subscriber (wikiname with no web or email address)
-- `$noAdd` - If false or undef, a new subscriber will be created for this name
-
-Get a subscriber from the list of subscribers, and return a reference to the Subscriber object. If $noAdd is true, and the subscriber is not found, undef will be returned. Otherwise a new Subscriber object will be added if necessary.
-
-## <a name="ObjectMethod getSubscribers()"></a> [[ObjectMethod]] getSubscribers()
-
-Get a list of all subscriber names (unsorted)
-
-## <a name="ObjectMethod subscribe($name, $t"></a> [[ObjectMethod]] subscribe($name, $topics, $depth)
-
-- `$name` - Name of subscriber (wikiname with no web or email address)
-- `$topics` - wildcard expression giving topics to subscribe to
-- `$depth` - Child depth to scan (default 0)
-- `$mode` - ! if this is a non-changes subscription and the topics should be mailed evebn if there are no changes. ? to mail the full topic only if there are changes. undef to mail changes only.
-
-Add a subscription, adding the subscriber if necessary.
-
-## <a name="ObjectMethod unsubscribe($name,"></a><a name="ObjectMethod unsubscribe($name, "></a> [[ObjectMethod]] unsubscribe($name, $topics, $depth)
-
-- `$name` - Name of subscriber (wikiname with no web or email address)
-- `$topics` - wildcard expression giving topics to subscribe to
-- `$depth` - Child depth to scan (default 0)
-
-Add an unsubscription, adding the subscriber if necessary. An unsubscription is a specific request to ignore notifications for a topic for this particular subscriber.
-
-## <a name="ObjectMethod stringify() - strin"></a> [[ObjectMethod]] stringify() -> string
-
-Return a string representation of this object, in [[WebNotify]] format.
-
-## <a name="ObjectMethod processChange($chan"></a> [[ObjectMethod]] processChange($change, $db, $changeSet, $seenSet, $allSet)
-
-- `$change` - ref of a TWiki::Contrib::Mailer::Change
-- `$db` - TWiki::Contrib::MailerContrib::UpData database of parent references
-- `$changeSet` - ref of a hash mapping emails to sets of changes
-- `$seenSet` - ref of a hash recording indices of topics already seen
-- `$allSet` - ref of a hash that maps topics to email addresses for news subscriptions
-
-Find all subscribers that are interested in the given change. Only the most recent change to each topic listed in the .changes file is retained. This method does _not_ change this object.
-
-## <a name="ObjectMethod processCompulsory($"></a> [[ObjectMethod]] processCompulsory($topic, $db, \\%allSet)
-
-- `$topic` - topic name
-- `$db` - TWiki::Contrib::MailerContrib::UpData database of parent references
-- `\%allSet` - ref of a hash that maps topics to email addresses for news subscriptions
-
-## <a name="ObjectMethod isEmpty() - boolean"></a> [[ObjectMethod]] isEmpty() -> boolean
-
-Return true if there are no subscribers
-
-# <a name="package TWiki::Contrib::_MailerC"></a> package TWiki::Contrib::MailerContrib::Subscriber
-
-Object that represents a subscriber to notification. A subscriber is a name (which may be a wikiName or an email address) and a list of subscriptions which describe the topis subscribed to, and unsubscriptions representing topics they are specifically not interested in. The subscriber name may also be a group, so it may expand to many email addresses.
-
-## <a name="ClassMethod new($name)"></a> [[ClassMethod]] new($name)
-
-- `$name` - Wikiname, with no web, or email address, of user targeted for notification
-
-Create a new user.
-
-## <a name="ObjectMethod get_EmailAddresses("></a> [[ObjectMethod]] getEmailAddresses() -> list
-
-Get a list of email addresses for the user(s) represented by this subscription
-
-## <a name="ObjectMethod subscribe($subs)"></a> [[ObjectMethod]] subscribe($subs)
-
-- `$subs` - Subscription object
-
-Add a new subscription to this subscriber object. The subscription will always be added, even if there is a wildcard overlap with an existing subscription.
-
-## <a name="ObjectMethod unsubscribe($subs)"></a> [[ObjectMethod]] unsubscribe($subs)
+Subscribe `IT:admins` (a non-TWiki group defined by an alternate user mapping) to all changes to Web\* topics.
-- `$subs` - Subscription object
+ * 'IT:admins' : Web*
-Add a new unsubscription to this subscriber object. The unsubscription will always be added, even if there is a wildcard overlap with an existing subscription or unsubscription.
-
-An unsubscription is a statement of the subscribers desire _not_ to be notified of changes to this topic.
-
-## <a name="ObjectMethod is_SubscribedTo($to"></a> [[ObjectMethod]] isSubscribedTo($topic) -> $subscription
-
-- `$topic` - Topic object we are checking
-- `$db` - TWiki::Contrib::MailerContrib::UpData database of parents
-
-Check if we have a subscription to the given topic. Return the subscription that matches if we do, undef otherwise.
-
-## <a name="ObjectMethod is_UnsubscribedFrom"></a> [[ObjectMethod]] isUnsubscribedFrom($topic) -> $subscription
-
-- `$topic` - Topic object we are checking
-- `$db` - TWiki::Contrib::MailerContrib::UpData database of parents
-
-Check if we have an unsubscription from the given topic. Return the subscription that matches if we do, undef otherwise.
-
-## <a name="ObjectMethod stringify() - strin"></a> [[ObjectMethod]] stringify() -> string
-
-Return a string representation of this object, in WebNotify format.
-
-# <a name="package TWiki::Contrib::_MailerC"></a> package TWiki::Contrib::MailerContrib::Subscription
-
-Object that represents a single subscription of a user to notification on a page. A subscription is expressed as a page spec (which may contain wildcards) and a depth of children of matching pages that the user is subscribed to.
-
-## <a name="ClassMethod new($pages, $childDe"></a> [[ClassMethod]] new($pages, $childDepth, $news)
-
-- `$pages` - Wildcarded expression matching subscribed pages
-- `$childDepth` - Depth of children of $topic to notify changes for. Defaults to 0
-- `$mode` - ! if this is a non-changes subscription and the topics should be mailed evebn if there are no changes. ? to mail the full topic only if there are changes. undef to mail changes only.
-
-Create a new subscription.
-
-## <a name="ObjectMethod stringify() - strin"></a> [[ObjectMethod]] stringify() -> string
-
-Return a string representation of this object, in WebNotify format.
-
-## <a name="ObjectMethod matches($topic, $db"></a> [[ObjectMethod]] matches($topic, $db, $depth) -> boolean
-
-- `$topic` - Topic object we are checking
-- `$db` - TWiki::Contrib::MailerContrib::UpData database of parent names
-- `$depth` - If non-zero, check if the parent of the given topic matches as well. undef = 0.
-
-Check if we match this topic. Recurses up the parenthood tree seeing if this is a child of a parent that matches within the depth range.
-
-## <a name="ObjectMethod getMode() - $mode"></a> [[ObjectMethod]] getMode() -> $mode
-
-Return ! if this is a non-changes subscription and the topics should be mailed even if there are no changes. ? to mail the full topic only if there are changes. undef to mail changes only.
-
-----
-
-# <a name="package TWiki::Contrib::_MailerC"></a> package TWiki::Contrib::MailerContrib::Change
-
-Object that represents a change to a topic.
-
-## <a name="ClassMethod new($web)"></a> [[ClassMethod]] new($web)
-
-- `$web` - Web name
-- `$topic` - Topic name
-- `$author` - String author of change
-- `$time` - String time of change
-- `$rev` - Revision identifier
-
-Construct a new change object.
-
-## <a name="ObjectMethod merge($change)"></a> [[ObjectMethod]] merge($change)
-
-- `$change` - Change record to merge
-
-Merge another change record with this one, so that the combined record is a reflection of both changes.
-
-## <a name="ObjectMethod expandHTML($html) -"></a> [[ObjectMethod]] expandHTML($html) -> string
-
-- `$html` - Template to expand keys within
-
-Expand an HTML template using the values in this change. The following keys are expanded: %TOPICNAME%, %AUTHOR%, %TIME%, %REVISION%, %TEXTHEAD%.
-
-Returns the expanded template.
-
-## <a name="ObjectMethod expandPlain() - str"></a> [[ObjectMethod]] expandPlain() -> string
+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).
-Generate a plaintext version of this change.
+If a _group_ is listed for notification, the group will be recursively expanded to the e-mail addresses of all members.
-# <a name="package TWiki::Contrib::_MailerC"></a> package TWiki::Contrib::MailerContrib::UpData
+\_\_%X% Warning: Because an email address is not linked to a user name, there is no way for TWiki to check access controls for email addresses. A user identified by an email address will only be sent change notifications if the topic they are asubscribed to is readable by guest users. You can limit what email addresses can be used in WebNotify, or even block use of emails altogther, using the `{MailerContrib}{EmailFilterIn} setting in =configure`.
-Object that lazy-scans topics to extract parent relationships.
+**_%T% Tip:_** List names in alphabetical order to make it easier to find the names.
-## <a name="ClassMethod new($web)"></a> [[ClassMethod]] new($web)
+In the future it is intended that individual users will be able to control the frequency with which they are notified of topic changes, by changing a schedule specification in their home topic. However at present, the notification schedule is controlled by the frequency of activation of the `cron` job that runs the `mailnotify` script.
-- `$web` - Web we are building parent relationships for
+Note that when using the "news mode" `!` or `?` specifiers the entire topic text is mailed out as HTML. The `newsletter` template is used to generate the content in this mail, using whatever skin is selected in the topic being mailed.
-Constructor for a web; initially empty, will lazy-load as topics are referenced.
+In addition, the %STARTPUBLISH% and %STOPPUBLISH% markers used by TWiki:Plugins.PublishContrib to delimit the text to be published are respected in news mode.
-## <a name="ObjectMethod getParent($topic) -"></a> [[ObjectMethod]] getParent($topic) -> string
+## <a name="TWiki/Contrib/_MailerContrib cod"></a> TWiki/Contrib/MailerContrib code library
-Get the name of the parent topic of the given topic
+The second part of the module is a code library that provides the services for other applications to modify the subscription topics through a clean, well documented API. This allows (for example) plugin developers to add (for example) a "Register me for this newsletter" button to their pages. Developers should refer to the POD documentation for the WebNotify class as their starting point.
-# <a name="package TWiki::Contrib::Mailer"></a> package TWiki::Contrib::Mailer
+## <a name="Installation Instructions"></a> Installation Instructions
-Package of support for extended WebNotify notification, supporting per-topic notification and notification of changes to children.
+You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.
-Also supported is a simple API that can be used to change the WebNotify topic from other code.
+Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.
-## <a name="StaticMethod mailNotify($webs, $"></a> [[StaticMethod]] mailNotify($webs, $session, $verbose)
+- If you have TWiki 4.2 or later, you can install from the `configure` interface (Go to Plugins->Find More Extensions)
+ - See the [installation supplement](http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement) on TWiki.org for more information.
+- If you have any problems, then you can still install manually from the command-line:
+ 1. Download one of the `.zip` or `.tgz` archives
+ 2. Unpack the archive in the root directory of your TWiki installation.
+ 3. Run the installer script ( `perl <module>_installer` )
+ 4. Run `configure` and enable the module, if it is a plugin.
+ 5. Repeat for any missing dependencies.
+- If you are **still** having problems, then instead of running the installer script:
+ 1. Make sure that the file permissions allow the webserver user to access all files.
+ 2. Check in any installed files that have existing `,v` files in your existing install (take care **not** to lock the files when you check in)
+ 3. Manually edit LocalSite.cfg to set any configuration variables.
-- `$webs` - filter list of names webs to process. Wildcards (\*) may be used.
-- `$session` - optional session object. If not given, will use a local object.
-- `$verbose` - true to get verbose (debug) output
+<div class="twikiAlert">%X% WARNING: SYSTEMWEB is not defined in this TWiki. Please add these definitions to your [[Main/TWikiPreferences]], if they are not already there:<br /><pre> * Set SYSTEMWEB = %TWIKIWEB%<br /> * Set USERSWEB = %MAINWEB%</pre></div>
-Main entry point.
+- To make sure the installation was successful, run the `mailnotify` script from the command line, with no parameters. In this case it will print out what it would have done to `STDOUT`.
-Process the WebNotify topics in each web and generate and issue notification mails. Designed to be invoked from the command line; should only be called by `mailnotify` scripts.
+**Additional settings**
-# <a name="Installation Instructions"></a> Installation Instructions
+- You can change the regular expression that matches email addresses in WebNotify using the `{MailerContrib}{EmailFilterIn} setting in =configure`. This allows you to limit the domains to which emails can be sent, or even block email addresses altogether.
-You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.
+### <a name="Setting up your cron job(s)"></a> Setting up your cron job(s)
-Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.
+You need to set up a `cron` (or equivalent) job to run the `tools/mailnotify` perl script.
-- If you have TWiki 4.1 or later, and Perl 5.8, you can install from the `configure` interface (Go to Plugins->Find More Extensions)
- - The webserver user has to have permission to write to all areas of your installation for this to work.
-- If you have a permanent connection to the internet (and Perl 5.8), you are recommended to use the automatic installer script
- - Just download the `MailerContrib_installer` perl script and run it.
-- **Notes:**
- - The installer script will:
- - Automatically resolve dependencies,
- - Copy files into the right places in your local install (even if you have renamed data directories),
- - check in new versions of any installed files that have existing RCS histories files in your existing install (such as topics).
- - If the $TWIKI\_PACKAGES environment variable is set to point to a directory, the installer will try to get archives from there. Otherwise it will try to download from twiki.org or cpan.org, as appropriate.
- - (Developers only: the script will look for twikiplugins/MailerContrib/MailerContrib.tgz before downloading from TWiki.org)
- - If you don't have a permanent connection, you can still use the automatic installer, by downloading all required TWiki archives to a local directory.
- - Point the environment variable `$TWIKI_PACKAGES` to this directory, and the installer script will look there first for required TWiki packages.
- - `$TWIKI_PACKAGES` is actually a path; you can list several directories separated by :
- - If you are behind a firewall that blocks access to CPAN, you can build a local CPAN mini-mirror, as described at [http://twiki.org/cgi-bin/view/Codev/BuildingDakar#CPAN\_local\_minimirror](http://twiki.org/cgi-bin/view/Codev/BuildingDakar#CPAN_local_minimirror)
-- If you don't want to use the installer script, or have problems on your platform (e.g. you don't have Perl 5.8), then you can still install manually:
- 1. Download and unpack one of the `.zip` or `.tgz` archives to a temporary directory.
- 2. Manually copy the contents across to the relevant places in your TWiki installation.
- 3. Check in any installed files that have existing `,v` files in your existing install (take care **not** to lock the files when you check in)
- 4. Manually edit LocalSite.cfg to set any configuration variables.
- 5. Run `configure` and enable the module, if it is a plugin.
- 6. Repeat from step 1 for any missing dependencies.
-
-- To make sure the installation was successful, run the `mailnotify` script from the command line, with no parameters. In this case it will print out what it would have done to STDOUT.
-
-## <a name="Setting up your cron job(s)"></a> Setting up your cron job(s)
-
-You need to set up a `cron` (or equivalent) job to run `tools/mailnotify`.
-
-Usage: <code>perl -I <bin> mailnotify [-q] [-news] [ _web1 web2 ... webN_ ]</code> <bin> is the path to the TWiki bin directory, so that the script can find the rest of TWiki.
+The script is used as follows: <code>perl -I _bin_ mailnotify [-q] [-news] [ _web1 web2 ... webN_ ]</code>
<table border="1" cellpadding="0" cellspacing="0">
<tr>
+ <td><em>bin</em></td>
+ <td> path to the TWiki bin directory, so that the script can find the rest of TWiki. </td>
+ </tr>
+ <tr>
<td><code>-q</code></td>
<td> Don't print progress information </td>
</tr>
</tr>
<tr>
<td><code><i>web1 web2 ... webN</i></code></td>
- <td> List of webs to process, separated by spaces or commas. Default is to process all legal TWiki webs. Wildcards (*) are supported. </td>
+ <td> List of webs to process, separated by spaces or commas. The default is to process all webs. Wildcards (*) are supported. </td>
</tr>
</table>
0 0 * * * cd /usr/local/twiki && perl -I bin tools/mailnotify -q Public Private
-will generate change notifications for the `Public` and `Private` webs every night at midnight.
+will generate change notifications for the `Public` and `Private` webs every night at midnight. (Google for `crontab` for more information on what all the `0 0 * * *` fields mean)
+
+ 0 0 * * * cd /usr/local/twiki && perl -I bin tools/mailnotify -q -Sandbox
+
+will generate change notifications for all webs, except the `Sandbox` web.
0 0 * * 0 cd /usr/local/twiki && perl -I bin tools/mailnotify -news
will generate newsletters from **all** webs every week on midnight Saturday.
-# <a name="Developer Notes"></a> Developer Notes
+## <a name="Developer Notes"></a> Developer Notes
The changes mails sent to users are based on a TWiki template called `mailnotify`. This template must contain the following definitions.
Newsletters are sent after formatting using the standard `view` template, using whatever skin is selected in the topic being mailed.
-## <a name="Contrib Info"></a> Contrib Info
+### <a name="Contrib Info"></a> Contrib Info
+
+Another great TWiki extension from the [ **WikiRing** ](http://wikiring.com) - working together to improve your wiki experience!
+
+Many thanks to the following sponsors for supporting this work:
+
+- [Wind River](http://www.windriver.com)
+- [WikiGardens](http://wikigardens.com)
<table border="1" cellpadding="0" cellspacing="0">
<tr>
<td> GPL </td>
</tr>
<tr>
+ <td align="right"> Version: </td>
+ <td> 16078 (22 Jan 2008) </td>
+ </tr>
+ <tr>
<td align="right"> Change History: </td>
<td> </td>
</tr>
<tr>
+ <td align="right"> 2 Nov 2007 </td>
+ <td> Bugs:Item4818: added quotes to support non-alphabetic and other wierd group names Bugs:Item4887: corrected minor rendering error Bugs:Item4917: removed dependence on symbolic web names </td>
+ </tr>
+ <tr>
+ <td align="right"> 9 Sep 2007 </td>
+ <td> Bugs:Item4326 workaround for possible error in WebNotify API in old releases, Should not affect most users. </td>
+ </tr>
+ <tr>
+ <td align="right"> 6 Sep 2007 </td>
+ <td> Bugs:Item4488 doc tweaks </td>
+ </tr>
+ <tr>
+ <td align="right"> 14550 </td>
+ <td> Bugs:Item4461 - 'Changed' link now points to most recent changes, not the entire history </td>
+ </tr>
+ <tr>
+ <td align="right"> 22 Jun 2007 </td>
+ <td> Bugs:Item4284 - added access control checks and email filter </td>
+ </tr>
+ <tr>
+ <td align="right"> 21 May 2007 </td>
+ <td> Bugs:Item3969 - 8bit email fix (TWiki:Main.WillNorris) </td>
+ </tr>
+ <tr>
+ <td align="right"> 13623 </td>
+ <td> Bugs:Item4014 no changes was resetting the notify time to 0. Thanks to TWiki:Main.JeffCrawford for nailing this down. </td>
+ </tr>
+ <tr>
<td align="right"> 12496 </td>
<td><a href="http://develop.twiki.org/~twiki4/cgi-bin/view/Bugs/Item3415" rel="nofollow">Item3415</a> mailnotify did not send notifications to intranet users because of wrong call to findUser. </td>
</tr>
- **Edit link:** To edit a page, simply click on the <code>**Edit**</code> link at the top or bottom of the page.
- **Auto links:** Web pages are [[linked automatically|Main/WikiWord]]. You do not need to learn HTML commands to link pages.
- **Text formatting:** Simple, powerful and easy-to-learn [[text formatting rules|Main/WikiSyntax]]. Basically you write text like you would write an e-mail.
-- **Webs:** Pages are grouped into [[TWiki webs|TWiki/SiteMap]] (or collections). This allows you to set up separate collaboration groups.
+- **Webs:** Pages are grouped into [[TWiki webs|SYSTEMWEB/SiteMap]] (or collections). This allows you to set up separate collaboration groups.
- **Search:** [[Full text search|Main/WebSearch]] with/without regular expressions. See a sample [search result](http://www.dementia.org/twiki/search/TWiki/?scope=text&search=learn).
- **E-mail notification:** Get [[automatically notified|Main/WebChangesAlert]] when something has changed in a TWiki web.
- **Structured content:** Use [[TWikiForms]] to classify and categorize unstructured web pages and to create simple workflow systems.
+# <a name="Managing Topics"></a> Managing Topics
+
+_Browser-based rename, move, and delete for individual topics_
+
<div>
<ul>
<li><a href="#Managing Topics"> Managing Topics</a><ul>
</ul>
</div>
-# <a name="Managing Topics"></a> Managing Topics
-
-_Browser-based rename, move, and delete for individual topics_
-
## <a name="Overview"></a> Overview
You can use browser-based controls to change a topic's name, move it to another TWiki web, or delete it to a hidden `Trash` web.
## <a name="Redirecting from an Old Topic"></a> Redirecting from an Old Topic
-You can use [[TWikiMetaData]] to place a command in the [[WebTopicViewTemplate]] and [[WebTopicNonWikiTemplate]] that will indicate that a topic has been moved by searching for the tag %META:TOPICMOVED\{...\}%. Customize something like this:
+You can use [[TWikiMetaData]] to place a command in the %SYSTEMWEB%.WebTopicViewTemplate and %SYSTEMWEB%.WebTopicNonWikiTemplate that will indicate that a topic has been moved by searching for the tag %META:TOPICMOVED\{...\}%. Customize something like this:
> %<nop>METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%"
> title="This topic used to exist and was moved to: "}%
### <a name="Effect of User Access Settings"></a> Effect of User Access Settings
-User permissions affect the Rename function in various ways. To rename a topic, you need both <code>**ALLOWTOPICVIEW**</code> and <code>**ALLOWTOPICCHANGE**</code> permission for that topic. To alter referring topics, you need change permission. See [[TWikiAccessControl]] for information on setting up access permissions.
+User permissions affect the 'rename' functions in various ways. To rename a topic, you need all of <code>**VIEW**</code>, <code>**CHANGE**</code> and <code>**RENAME**</code> access to that topic. To alter referring topics, you need <code>**CHANGE**</code> access. See [[TWikiAccessControl]] for information on setting up access permissions.
## <a name="Special Considerations"></a> Special Considerations
+# <a name="Manage Users"></a> Manage Users
+
+_Register users on your TWiki site; change/reset/install passwords; remove user accounts_
+
<div>
<ul>
<li><a href="#Manage Users"> Manage Users</a><ul>
</ul>
</div>
-# <a name="Manage Users"></a> Manage Users
-
-_Register users on your TWiki site; change/reset/install passwords; remove user accounts_
+%X% Some of the features below may be disabled, depending on your TWiki configuration.
## <a name="Authentication and Access Contro"></a> Authentication and Access Control
-- [[TWikiUserAuthentication]] describes options of user authentication
+- [[TWikiUserAuthentication]] describes your options for user authentication
- [[TWikiAccessControl]] describes how to define groups and how to restrict access to content
## <a name="Register User"></a> Register User
-It is not necessary to have user home pages in the TWiki system for Authentication to work - see [[TWikiUserAuthentication]] for details.
+You don't have to have user home pages in TWiki for Authentication to work - see [[TWikiUserAuthentication]] for details.
-- [[TWikiRegistration]] is for users to fill out a form
-- [[NewUserTemplate]] can be changed to customize user home pages, it can optionally use the [[UserForm]] to define user fields as meta data
-- [[BulkRegistration]] is for administrators to use to set up one or more accounts: either from a table or from an external file
+- [[TWikiRegistration]] is used when you want new users to individually register with TWiki by filling out a form
+- You can create a custom versions of [[NewUserTemplate]] and [[UserForm]]
+- [[BulkRegistration]] is used by administrators to register multiple users at the same time
## <a name="Change, Reset and Install Passwo"></a> Change, Reset and Install Passwords
-- [[ChangePassword]] is for users who can remember their password and want to change it
-- [[ResetPassword]] is for users who cannot remember their password; a system generated password is e-mailed to them
+_Note that the below features are only relevant when you use an internal password manager where TWiki can set and reset passwords._
+
+- [[ChangePassword]] is for users who _can_ remember their password and want to change it
+- [[ResetPassword]] is for users who _cannot_ remember their password; a system generated password is e-mailed to them
- [[BulkResetPassword]] if for administrators who want to reset many passwords at once
+- [[ChangeEmailAddress]] changes the hidden email address stored in the password file
## <a name="Changing User Account Names"></a> Changing User Account Names
If external authentication is used and you want to change the login name:
-- The login name needs to be changed in the directory server, such as AD or LDAP
-- In TWiki's [[Main.TWikiUsers|Main/TWikiUsers]] topic, fix the mapping from login name to [[WikiName]] such as from:%BR% ` * JohnSmith - john - 13 Sep 2006` %BR% to: %BR% ` * JohnSmith - jsmith - 13 Sep 2006`
+- The login name needs to be changed in the authentication server (e.g. Active Directory)
+- In TWiki's [[Main.TWikiUsers|Main/TWikiUsers]] topic, fix the mapping from login name to [[WikiName]]:%BR% ` * JaneSmith - jsmith - 13 Sep 2006` %BR% to: %BR% ` * JaneMiller - jmiller - 13 Sep 2006`
## <a name="Removing User Accounts"></a> Removing User Accounts
3. Remove `FredQuimby` from all groups and from all the `ALLOWWEB/ALLOWTOPIC...` declarations, if any.%BR% **_Note:_** If you fail to do this you risk creating a security hole, as the next user to register with the wikiname FredQuimby will inherit the old FredQuimby's permissions.
4. _[optional]_ Delete their user topic Main.FredQuimby (including attachments, if any.)
-**_Note:_** Consider leaving the user topic file in place so their past signatures and revision author entries don't end up looking like [[AnUncreatedTopic]]. If you want to make it clear the user is no longer with the organization or has been banished, replace the topic content with a note to that effect. The existance of the UserName topic should also prevent that user name from being re-used, sealing the potential security hole regarding inherited permissions..
+**_Note:_** Consider leaving the user topic file in place so their past signatures and revision author entries don't end up looking like [[AnUncreatedTopic]]. If you want to make it clear the user is no longer around, replace the topic content with a note to that effect. The existance of the UserName topic should also prevent that user name from being re-used, sealing the potential security hole regarding inherited permissions..
**_Related Topics:_** [[AdminDocumentationCategory]]
+# <a name="Managing Webs"></a> Managing Webs
+
+_Adding, renaming and deleting webs are all web-based operations._
+
<div>
<ul>
<li><a href="#Managing Webs"> Managing Webs</a><ul>
<li><a href="#Overview"> Overview</a></li>
<li><a href="#Choose Web Template"> Choose Web Template</a></li>
<li><a href="#Adding a New Web"> Adding a New Web</a></li>
+ <li><a href="#Hierarchical Webs"> Hierarchical Webs</a><ul>
+ <li><a href="#Subweb Preferences are Inherited"> Subweb Preferences are Inherited</a></li>
+ <li><a href="#Navigation"> Navigation</a></li>
+ </ul>
+ </li>
<li><a href="#Renaming or Deleting a Web"> Renaming or Deleting a Web</a><ul>
<li><a href="#Permissions"> Permissions</a></li>
<li><a href="#Edit Conflicts"> Edit Conflicts</a></li>
<li><a href="#Renaming the webs in the distrib"> Renaming the webs in the distribution</a></li>
</ul>
</li>
- <li><a href="#Hierarchical Webs"> Hierarchical Webs</a><ul>
- <li><a href="#Subweb Preferences are Inherited"> Subweb Preferences are Inherited</a></li>
- <li><a href="#Navigation"> Navigation</a></li>
- </ul>
- </li>
</ul>
</li>
</ul>
</div>
-# <a name="Managing Webs"></a> Managing Webs
-
-_Adding, renaming and deleting webs are all web-based operations._
-
## <a name="Overview"></a> Overview
-A [[TWikiSite]] is divided into webs; each one represents one subject, one area of collaboration. Administrators (in the [[TWikiAdminGroup]]) can add/rename/delete webs.
+A [[TWikiSite]] is divided into webs; each one represents one subject, one area of collaboration. Administrators can add/rename/delete webs.
<a name="WebTemplate"></a>
The second method is to use an existing web as a template web. This may be useful if you already have a web that you would like to use as a starting point. Only topics that have names beginning with **Web...** (like "WebHome", "WebNotify", etc.) are copied.
-In either case you will want to be sure to verify that your new web has all the custom modifications that you desire.
+In either case you will want to be sure to verify that your new web has all the custom modifications that you desire. Any [[TWikiVariables]] defined in the form below will automatically be set in the WebPreferences of the new web.
<a name="CreateNewWeb"></a>
## <a name="Adding a New Web"></a> Adding a New Web
-<form action="http://www.dementia.org/twiki/manage/%WEB%/%TOPIC%" method="post" name="admin"> Create a new web by filling out this form.%BR% <strong><em>%X% Note:</em></strong> <strong>Keep the number of webs to a minimum!</strong> It is not recommended to create a new web for each little project. You can organize content within a web using categories, [[Main/TWikiForms]] and [[Main/FormattedSearch]]. Cross-linking topics and search is easier if there are only a few larger webs. <table border="1" cellpadding="0" cellspacing="0">
+<form action="http://www.dementia.org/twiki/manage/%WEB%/%TOPIC%" method="post" name="admin"> Create a new web by filling out this form.%BR% <strong><em>%X% Note:</em></strong> <strong>Keep the number of webs to a minimum!</strong> Don't create a new web for each little project. Cross-linking topics is easier, and searches are faster, if there are only a few larger webs. <table border="1" cellpadding="0" cellspacing="0">
<tr>
<th align="right" bgcolor="#99CCCC"><strong> Name of new web: </strong></th>
<td><input name="newweb" size="16" type="text" value="" /></td>
</tr>
<tr>
<th align="right" bgcolor="#99CCCC"><strong> Web color: </strong></th>
- <td><input name="webbgcolor" size="16" type="text" value="#D0D0D0" /></td>
+ <td><input name="WEBBGCOLOR" size="16" type="text" value="#D0D0D0" /></td>
<td> Enter a [[Main/StandardColors]] code for the web </td>
</tr>
<tr>
+ <th align="right" bgcolor="#99CCCC"><strong> Site Map: </strong></th>
+ <td><input checked name="SITEMAPLIST" type="radio" value="on" /> Yes <input name="SITEMAPLIST" type="radio" value="" /> No </td>
+ <td> Include this web in the site map </td>
+ </tr>
+ <tr>
<th align="right" bgcolor="#99CCCC"><strong> Description:<br /> <br /> </strong></th>
- <td colspan="2"><input name="sitemapwhat" size="60" type="text" value="" /><br /> Enter a short description of the web. Write <code>Web.TopicName</code> instead of just <code>TopicName</code> if you include links. This will list the web in the [[TWiki/SiteMap]] (leave field empty if you prefer not to update the directory.) </td>
+ <td colspan="2"><input name="SITEMAPWHAT" size="60" type="text" value="" /><br /> Enter a short description of the web. Write <code>Web.TopicName</code> instead of just <code>TopicName</code> if you include links. This description will be used in the %SYSTEMWEB%.SiteMap </td>
</tr>
<tr>
<th align="right" bgcolor="#99CCCC"><strong> Use to...<br /> </strong></th>
- <td colspan="2"><input name="sitemapuseto" size="60" type="text" value="...collaborate on" /><br /> Continue the sentence describing the intended use. This is also for the [[TWiki/SiteMap]]</td>
+ <td colspan="2"><input name="SITEMAPUSETO" size="60" type="text" value="...collaborate on" /><br /> Continue the sentence describing the intended use. This is also for the %SYSTEMWEB%.SiteMap </td>
</tr>
<tr>
- <th align="right" bgcolor="#99CCCC"><strong> Set NOSEARCHALL: </strong></th>
- <td><input checked name="nosearchall" type="radio" value="" /> No <input name="nosearchall" type="radio" value="on" /> Yes </td>
+ <th align="right" bgcolor="#99CCCC"><strong> Hidden: </strong></th>
+ <td><input name="NOSEARCHALL" type="radio" value="on" /> Yes <input checked name="NOSEARCHALL" type="radio" value="" /> No </td>
<td> Specify if you want to exclude the web from a "search all webs" search. <strong>This will not prevent users accessing the web</strong>. It will simply hide it from searches. </td>
</tr>
<tr>
**_Notes:_**
-- You have to have `ROOTCHANGE` access to create a top-level web (one with no parent)
-- Attachments will NOT get copied over along with their topics
-- While creating the new web, TWiki will update the following variables in the [[WebPreferences]]: `WEBBGCOLOR`, `SITEMAPLIST`, `SITEMAPWHAT`, `SITEMAPUSETO` and `NOSEARCHALL`. These variables are used to dynamically generate the [[SiteMap]]
-- TWiki does not edit the [[TWiki.TWikiPreferences|TWiki/TWikiPreferences]] to update the `WIKIWEBLIST`. This must be done by hand
-
-<a name="RenameWeb"></a>
-
-## <a name="Renaming or Deleting a Web"></a> Renaming or Deleting a Web
-
-Rename a web via the Tools section in each web's [[WebPreferences]] topic. You may delete a web by moving it into a Trash web.
-
-### <a name="Permissions"></a> Permissions
-
-You may only rename a web if you have permissions to rename all the topics within that web, including any topics in that web's subwebs. You will also need permissions to update any topics containing references to that web.
-
-### <a name="Edit Conflicts"></a> Edit Conflicts
-
-If anyone is editing a topic which requires updating, or which lives in the web being renamed, a second confirmation screen will come up which will indicate which topics are still locked for edit. You may continue to hit the refresh button until an edit lease is obtained for each topic which requires updating (the "Refresh" button will change to "Submit"), or hit "Cancel", which will cancel your edit lease on all affected topics.
-
-### <a name="Renaming the webs in the distrib"></a> Renaming the webs in the distribution
-
-If you plan to rename the Main web, remember that TWiki stores user and group topics in this web. That means that every [[WikiName]] signature - `Main.SomeUserName` - points to it and would need updating (unless the variable, `%MAINWEB%.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.
-
-%X% If you want to rename the TWiki or Main webs, remember they are referred to in the TWiki configuration. You will need to change the `{SystemWebName}`, `{UsersWebName}` and/or `{LocalSitePreferences}` settings in the configuration using the [configure](http://www.dementia.org/twiki/configure) interface.
+- You must have `ROOTCHANGE` access to create a top-level web (one with no parent)
+- Only the person who created it has permission to change the WebPreferences in the new web
## <a name="Hierarchical Webs"></a> Hierarchical Webs
-Hierarchical web support is enabled by turning on the `{EnableHierarchicalWebs}` setting in [configure](http://www.dementia.org/twiki/configure). Without this setting, TWiki will only allow a single level of hierarchy (webs). If you set this, you can use multiple levels, like a directory tree, i.e. webs within webs.
+You can only create hierarchical webs (webs within webs) if the `{EnableHierarchicalWebs}` setting in [configure](http://www.dementia.org/twiki/configure) is enabled. Hierarchical webs are currently enabled.
**_%T% Note:_** You might not need hierarchical webs. TWiki topics already have a parent/child relationship within a web, which is shown in the breadcrumb. Try to keep the number of webs to a minimum in order to keep search and cross-referencing simple.
### <a name="Subweb Preferences are Inherited"></a> Subweb Preferences are Inherited
-The preferences of a subweb are inherited from the parent web and overridden locally. Preferences are ultimately inherited from the [[TWiki.TWikiPreferences|TWiki/TWikiPreferences]] topic.
+The preferences of a subweb are inherited from the parent web and overridden locally. Preferences are ultimately inherited from the [[%SYSTEMWEB%.TWikiPreferences|SYSTEMWEB/TWikiPreferences]] topic.
**Example Preference Inheritance for `Sandbox/TestWeb/SubWeb.SubWebTopic` topic:**
-1. `TWiki.TWikiPreferences` site-wide preferences
-2. `Sandbox.WebPreferences` inherits from and overrides settings in `TWiki.TWikiPreferences`
+1. `%SYSTEMWEB%.TWikiPreferences` site-wide preferences
+2. `Sandbox.WebPreferences` inherits from and overrides settings in `%SYSTEMWEB%.TWikiPreferences`
3. `Sandbox/TestWeb.WebPreferences` inherits from and overrides settings in `Sandbox.WebPreferences`
4. `Sandbox/TestWeb/SubWeb.WebPreferences` inherits from and overrides settings in `Sandbox/TestWeb.WebPreferences`
5. `Sandbox/TestWeb/SubWeb.SubWebTopic` inherits from and overrides settings in `Sandbox/TestWeb/SubWeb.WebPreferences`
The Pattern skin (default) indicates Subwebs by indenting them in the sidebar relative to their level in the hierarchy.
+<a name="RenameWeb"></a>
+
+## <a name="Renaming or Deleting a Web"></a> Renaming or Deleting a Web
+
+Rename a web via the Tools section in each [[WebPreferences]] topic. You may delete a web by moving it into a Trash web.
+
+### <a name="Permissions"></a> Permissions
+
+You may only rename a web if you have permissions to rename all the topics within that web, including any topics in that web's subwebs. You will also need permissions to update any topics containing references to that web.
+
+### <a name="Edit Conflicts"></a> Edit Conflicts
+
+If anyone is editing a topic which requires updating, or which lives in the web being renamed, a second confirmation screen will come up which will indicate which topics are still locked for edit. You may continue to hit the refresh button until an edit lease is obtained for each topic which requires updating (the "Refresh" button will change to "Submit"), or hit "Cancel", which will cancel your edit lease on all affected topics.
+
+### <a name="Renaming the webs in the distrib"></a> Renaming the webs in the distribution
+
+It is possible, though not recommended, to change the names of the webs in the distribution.
+
+If you plan to rename the %USERSWEB% web, remember that TWiki stores user topics in this web. That means that every [[WikiName]] signature - `%USERSWEB%.SomeUserName` - points to it and would need updating (unless the variable, `%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.
+
+%X% If you want to rename the %SYSTEMWEB% or %USERSWEB% webs, remember they are referred to in the TWiki configuration. You will need to change the `{SystemWebName}`, `{UsersWebName}` and/or `{LocalSitePreferences}` settings in the configuration using the [configure](http://www.dementia.org/twiki/configure) interface.
+
+%X% Renaming the webs in the distribution is not recommended because it makes upgrades much more complicated.
+
**_Related Topics:_** [[AdminDocumentationCategory]], [[AdminToolsCategory]]
--- /dev/null
+# <a name="Package <code>="></a> Package =
+
+<div>
+ <ul>
+ <li><a href="#Package =="> Package ==</a></li>
+ </ul>
+</div>
+
+Monitoring package. Instrument the code like this:
+
+use Monitor; Monitor::MARK("Description of event"); Monitor::MARK("Another event");
+
+or, to monitor all the calls to a module
+
+use Monitor; Monitor::MonitorMethod('TWiki::Users');
+
+or a function
+
+use Monitor; Monitor::MonitorMethod('TWiki::Users', 'getCanonicalUserID');
+
+Then set the environment variable TWIKI\_MONITOR to a perl true value, and run the script from the command line e.g: $ cd bin $ ./view -topic Myweb/MyTestTopic
+
+The results will be printed to STDERR at the end of the run. Two times are shown, a time relative to the last MARK and a time relative to the first MARK (which is always set the first time this package is used). The final column is total memory.
+
+NOTE: it uses /proc - so its linux specific...
-# <a name="Pattern skin"></a><a name=" Pattern skin"></a> Pattern skin
+Status: 500 Content-type: text/html
-**PatternSkin provides a CSS based default look and feel for TWiki - flexible and W3C-compliant.** Its layout and color scheme are designed to provide a nice, clean and productive _editing environment_. For use in corporate or perhaps in personal websites it should be fairly easy to tune the looks or even create a PatternSkin-based new skin.
+# Software error:
-<div><span>Page contents</span><ul>
- <li>
- <ul>
- <li><a href="#Screenshot"> Screenshot</a></li>
- </ul>
- </li>
- <li><a href="#TWiki Installation Error">TWiki Installation Error</a><ul>
- <li><a href="#Creating your own look"> Creating your own look</a><ul>
- <li><a href="#Template customization"> Template customization</a></li>
- <li><a href="#Style sheet customization"> Style sheet customization</a></li>
- </ul>
- </li>
- <li><a href="#Supported browsers"> Supported browsers</a></li>
- <li><a href="#Installation"> Installation</a><ul>
- <li><a href="#Troubleshooting"> Troubleshooting</a></li>
- </ul>
- </li>
- <li><a href="#Skin Info"> Skin Info</a></li>
- <li><a href="#Related topics"> Related topics</a></li>
- <li><a href="#Feedback"> Feedback</a></li>
- </ul>
- </li>
- </ul>
-</div>
+ Can't use an undefined value as an ARRAY reference at /tmp/TWiki/lib/TWiki/Prefs.pm line 246.
-## <a name="Screenshot"></a> Screenshot
-
-[<img src="http://www.dementia.org/twiki//view/patternskin_screenshot.jpg" width="600" height="130" alt="Click for full screen image" style="border: 1px solid #eee" />](http://www.dementia.org/twiki//view/patternskin_screenshot_full.png)
-
-## <a name="Creating your own look"></a> Creating your own look
-
-### <a name="Template customization"></a> Template customization
-
-[[PatternSkinCustomization]] - how to configure page elements
-
-### <a name="Style sheet customization"></a> Style sheet customization
-
-[[PatternSkinCssCookbook]] - how to customize the visual style
-
-## <a name="Supported browsers"></a> Supported browsers
-
-PatternSkin has been tested successfully on the following browsers:
-
-- Windows
- - Internet Explorer 6.0, 5.5 (note: Explorer 5.0 is **not** supported: will function but shows visual quirks)
- - Mozilla/Firefox
-- Mac OS X
- - Safari 2.0.3
- - Mozilla/Firefox 1.5 (note: Firefox 1.0 will show visual quirks)
-- \*nix
- - Mozilla/Firefox 1.5 (note: Firefox 1.0 will show visual quirks)
-
-## <a name="Installation"></a> Installation
-
-**Note:** You do not need to install anything on the browser to use this skin. The following instructions are for the administrator who installs the skin on the server where TWiki is running.
-
-**Note 2:** PatternSkin is included with TWiki by default. Use the following instructions only if you are upgrading PatternSkin.
-
-- Download the ZIP file from the Skin Home page (see below)
-- Unzip <code>**%TOPIC%.zip**</code> in your twiki installation directory
-- Test if installed: [[http://www.dementia.org/twiki/view/%WEB%/%TOPIC%?skin=pattern|%WEB%/%TOPIC%?skin=pattern]]
-- For skin activation see [[TWikiSkins]]
-
-### <a name="Troubleshooting"></a> Troubleshooting
-
-If you have set the SKIN variable setting to `pattern` and you still don't see the layout as on the [screenshot](http://www.dementia.org/twiki//view/patternskin_screenshot_full.png), a few settings in may have been disabled.
-
-Check these variables here:
-
-- TWIKILAYOUTURL = %TWIKILAYOUTURL%
-- TWIKISTYLEURL = %TWIKISTYLEURL%
-- TWIKICOLORSURL = %TWIKICOLORSURL%
-- SKIN = %SKIN%
-
-If TWIKILAYOUTURL or TWIKISTYLEURL don't give a value or point to non-existing files, check in [[TWikiPreferences]] that the following variables do exist and that they are set to on:
-
- * %TWIKIWEB%.PatternSkin settings:
- * Set TWIKILAYOUTURL = %PUBURLPATH%/%TWIKIWEB%/PatternSkin/layout.css
- * Set TWIKISTYLEURL = %PUBURLPATH%/%TWIKIWEB%/PatternSkin/style.css
- * Set TWIKICOLORSURL = %PUBURLPATH%/%TWIKIWEB%/PatternSkin/colors.css
-
-**NOTE:** customization of these values should be done in [[Main.TWikiPreferences|Main/TWikiPreferences]]
-
-If this still does not work, contact the administrator who installs skins.
-
-For further troubleshooting and feedback, go to TWiki:Plugins/PatternSkinDev. Report bugs in the [[Support web|TWiki:Support/WebHome]].
-
-## <a name="Skin Info"></a> Skin Info
-
-<table border="1" cellpadding="0" cellspacing="0">
- <tr>
- <td align="right"> Description: </td>
- <td> TWiki's default skin; CSS based, flexible and W3C-compliant </td>
- </tr>
- <tr>
- <td align="right"> Screenshot: </td>
- <td><a href="http://www.dementia.org/twiki//view/patternskin_screenshot_full.png"><img alt="Click for full screen image" height="130" src="http://www.dementia.org/twiki//view/patternskin_screenshot.jpg" style="border: 1px solid #eee" width="600" /></a></td>
- </tr>
- <tr>
- <td align="right"> Preview: </td>
- <td>[[%WEB%/%TOPIC%?skin=pattern]]</td>
- </tr>
- <tr>
- <td align="right"> Base Name: </td>
- <td> pattern </td>
- </tr>
- <tr>
- <td align="right"> Skin Author: </td>
- <td> TWiki:Main/ArthurClemens </td>
- </tr>
- <tr>
- <td align="right"> Skin Version: </td>
- <td> 15 Jan 2006 (v2.0.6) </td>
- </tr>
- <tr>
- <td align="right"> History: </td>
- <td> </td>
- </tr>
- <tr>
- <td align="right"> 15 Jan 2006: </td>
- <td> v.2.0.6 - TWiki 4.1.0 (Edinburgh) RELEASE VERSION </td>
- </tr>
- <tr>
- <td align="right"> 26 Sep 2006: </td>
- <td> v.2.0.5 - Fixed form background colors </td>
- </tr>
- <tr>
- <td align="right"> 22 Jul 2006: </td>
- <td> v.2.0.4 - Refactored info in colors.css; fixed textarea color </td>
- </tr>
- <tr>
- <td align="right"> 26 Jun 2006: </td>
- <td> v.2.0.3 - TWiki 4.0.3 (Dakar) RELEASE VERSION </td>
- </tr>
- <tr>
- <td align="right"> 31 Jan 2006: </td>
- <td> v.2.0.0 - TWiki 4.0.0 (Dakar) RELEASE VERSION </td>
- </tr>
- <tr>
- <td align="right"> 28 Aug 2004: </td>
- <td> v.1.0.9 - TWiki 3.0 (Cairo) RELEASE VERSION </td>
- </tr>
- <tr>
- <td align="right"> 08 Aug 2004: </td>
- <td> Initial version (v1.0.0) </td>
- </tr>
- <tr>
- <td align="right"> Dependencies: </td>
- <td> TWiki:Plugins/TwistyContrib (automatically supported by Dakar) </td>
- </tr>
- <tr>
- <td align="right"> Skin Home: </td>
- <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%</a></td>
- </tr>
- <tr>
- <td align="right"> Feedback: </td>
- <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev</a></td>
- </tr>
- <tr>
- <td align="right"> Download: </td>
- <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%</a></td>
- </tr>
-</table>
-
-## <a name="Related topics"></a> Related topics
-
-- [[TWikiCss]]
-- [[PatternSkinCss]]
-- [[PatternSkinCssCookbook]]
-- [[PatternSkinCssCookbookCenterPage]]
-- [[PatternSkinCssCookbookEditTableStyle]]
-- [[PatternSkinCssCookbookFonts]]
-- [[PatternSkinCssCookbookNoLeftBar]]
-- [[PatternSkinCssCookbookNoTopBar]]
-- [[PatternSkinCustomization]]
-- [[PatternSkinJavascripts]]
-- [[WebBottomBar]]
-- [[WebLeftBar]]
-- [[WebLeftBarCookbook]]
-- [[WebLeftBarExample]]
-- [[WebLeftBarLogin]]
-- [[WebLeftBarPersonalTemplate]]
-- [[WebLeftBarSearch]]
-- [[WebLeftBarWebsList]]
-- [[WebTopBar]]
-- [[AdminDocumentationCategory]]
-
-Other skins:
-
-- [[TWikiSkins]]
-- [[TWikiSkinBrowser]]
-
-## <a name="Feedback"></a> Feedback
-
-Leave remarks, suggestions and other feedback in TWiki:Plugins.PatternSkinDev.
+For help, please send mail to this site's webmaster, giving this error message and the time and date of the error.
-# <a name="Color scheme settings for TWiki."></a> Color scheme settings for [[PatternSkin]]
-
-**Appearance: text colors, background colors, border colors.**
+# <a name="Color scheme settings for TWiki."></a><a name=" Color scheme settings for TWiki"></a> Color scheme settings for [[PatternSkin]]
Use this topic to change the color settings of [[PatternSkin]]. When this topic is saved, the attachment `theme-colors.css` will be updated with new color values. This method relies on TWiki:Plugins.AttachContentPlugin to work.
+AttachContentPlugin is **not** installed.
+
## <a name="Usage"></a><a name=" Usage"></a> Usage
### <a name="Step 1"></a><a name=" Step 1"></a> Step 1
Let [[PatternSkin]] point to the custom-made colors style sheet. In [[Main.TWikiPreferences|Main/TWikiPreferences]] put:
- * Set USERCOLORSURL = %PUBURLPATH%/%MAINWEB%/TWikiPreferences/theme-colors.css
+ * Set USERCOLORSURL = %PUBURLPATH%/%TWIKIWEB%/PatternSkin/theme-colors.css
### <a name="Step 2"></a><a name=" Step 2"></a> Step 2
Edit this topic, and change the color variables as you like.
+### <a name="Step 3"></a><a name=" Step 3"></a> Step 3
+
+Save the topic. This will generate an [attachment](http://www.dementia.org/twiki//view/TWiki/PatternSkin/theme-colors.css) to topic [[PatternSkin]].
+
+<img src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" height="16" alt="info" /> For more help on customizing styles, see [[PatternSkinCustomization]].
+
## <a name="Color variables"></a><a name=" Color variables"></a> Color variables
<div>
<ul>
<li><a href="#Logical groupings"> Logical groupings</a><ul>
- <li><a href="#Text on background"> Text on background</a><ul>
+ <li><a href="#Text"> Text</a><ul>
<li><a href="#MAIN_TEXT_COLOR Main text color"> MAIN_TEXT_COLOR Main text color</a></li>
<li><a href="#MAIN_BACKGROUND_COLOR Main backg"> MAIN_BACKGROUND_COLOR Main background color</a></li>
<li><a href="#LIGHT_ON_DARK_TEXT_COLOR Light o"> LIGHT_ON_DARK_TEXT_COLOR Light on dark text color</a></li>
+ <li><a href="#GRAYED_TEXT_COLOR"> GRAYED_TEXT_COLOR</a></li>
+ <li><a href="#GENERAL_TEXT General text (if no"> GENERAL_TEXT General text (if not set in MAIN_BACKGROUND_COLOR) (black)</a></li>
+ <li><a href="#HEADER_TEXT Header text"> HEADER_TEXT Header text</a></li>
+ <li><a href="#CODE_TEXT Code text, left bar te"> CODE_TEXT Code text, left bar text and links</a></li>
+ <li><a href="#MUTED_TEXT Muted text (dark gray"> MUTED_TEXT Muted text (dark gray)</a></li>
+ <li><a href="#GRAYED_OUT_TEXT Grayed out text"> GRAYED_OUT_TEXT Grayed out text</a></li>
</ul>
</li>
<li><a href="#Links"> Links</a><ul>
<li><a href="#LINK_TEXT_NORMAL Link normal tex"> LINK_TEXT_NORMAL Link normal text</a></li>
<li><a href="#LINK_BACKGROUND_NORMAL Link norm"> LINK_BACKGROUND_NORMAL Link normal background</a></li>
+ <li><a href="#LINK_TEXT_NORMAL_VISITED Link no"> LINK_TEXT_NORMAL_VISITED Link normal text visited</a></li>
<li><a href="#LINK_TEXT_ACTION_BUTTON Link tex"> LINK_TEXT_ACTION_BUTTON Link text red (same as LINK_BACKGROUND_HOVER)</a></li>
<li><a href="#LINK_TEXT_HOVER Link hover text"> LINK_TEXT_HOVER Link hover text</a></li>
<li><a href="#LINK_BACKGROUND_HOVER Link backg"> LINK_BACKGROUND_HOVER Link background hover</a></li>
<li><a href="#SIDE_BAR_LINK_TEXT Side bar link"> SIDE_BAR_LINK_TEXT Side bar link text</a></li>
- <li><a href="#LINK_TEXT_NORMAL_TABLE_HEADER Ta"> LINK_TEXT_NORMAL_TABLE_HEADER Table header link text</a></li>
- <li><a href="#LINK_TEXT_NORMAL_BORDER_TABLE_HE"> LINK_TEXT_NORMAL_BORDER_TABLE_HEADER Table header link border</a></li>
- <li><a href="#LINK_TEXT_SORTED_TABLE_HEADER So"> LINK_TEXT_SORTED_TABLE_HEADER Sorted table header link text</a></li>
- <li><a href="#LINK_TEXT_HOVER_TABLE_HEADER Tab"> LINK_TEXT_HOVER_TABLE_HEADER Table header link hover text</a></li>
- <li><a href="#LINK_BORDER_TABLE_SELECTED_COLUM"> LINK_BORDER_TABLE_SELECTED_COLUMN_HEADER Link border in selected column header</a></li>
</ul>
</li>
<li><a href="#Disabled"> Disabled</a><ul>
<li><a href="#DISABLED_BORDER Disabled border"> DISABLED_BORDER Disabled border</a></li>
<li><a href="#DISABLED_TEXT Disabled text"> DISABLED_TEXT Disabled text</a></li>
<li><a href="#DISABLED_BACKGROUND Disabled bac"> DISABLED_BACKGROUND Disabled background</a></li>
+ <li><a href="#BUTTON_BORDERS_DISABLED Disabled"> BUTTON_BORDERS_DISABLED Disabled button borders</a></li>
</ul>
</li>
<li><a href="#'New'"> 'New'</a><ul>
- <li><a href="#NEW_TEXT New text (green)"> NEW_TEXT New text (green) </a></li>
- <li><a href="#NEW_BACKGROUND New background (l"> NEW_BACKGROUND New background (light green) </a></li>
+ <li><a href="#NEW_TEXT New text (green)"> NEW_TEXT New text (green)</a></li>
+ <li><a href="#NEW_BACKGROUND New background (l"> NEW_BACKGROUND New background (light green)</a></li>
</ul>
</li>
<li><a href="#Alert"> Alert</a><ul>
<li><a href="#Buttons"> Buttons</a><ul>
<li><a href="#BUTTON_TEXT Button text color (d"> BUTTON_TEXT Button text color (dark gray)</a></li>
<li><a href="#BUTTON_BORDERS Button borders"> BUTTON_BORDERS Button borders</a></li>
- <li><a href="#BUTTON_BORDERS_ACTIVE Button bor"> BUTTON_BORDERS_ACTIVE Button borders (active)</a></li>
- <li><a href="#SUBMIT_BUTTON_BACKGROUND Submit"> SUBMIT_BUTTON_BACKGROUND Submit button background (dark yellow)</a></li>
- <li><a href="#SUBMIT_BUTTON_BORDER Submit butt"> SUBMIT_BUTTON_BORDER Submit button border (blue) </a></li>
- </ul>
- </li>
- <li><a href="#Forms"> Forms</a><ul>
- <li><a href="#INPUT_FIELD_BORDERS Input field"> INPUT_FIELD_BORDERS Input field borders</a></li>
- <li><a href="#FORM_INPUT_BORDER Textarea, inpu"> FORM_INPUT_BORDER Textarea, input and select (darker gray)</a></li>
- <li><a href="#FORM_BORDER Form (same as twikiT"> FORM_BORDER Form (same as twikiTable border)</a></li>
- <li><a href="#ACTIVE_FORM_BACKGROUND Edit form"> ACTIVE_FORM_BACKGROUND Edit form, form steps</a></li>
- <li><a href="#FORMFIELD_ACTIVE Active form fie"> FORMFIELD_ACTIVE Active form field (not implemented yet)</a></li>
- </ul>
- </li>
- </ul>
- </li>
- <li><a href="#Color groupings"> Color groupings</a><ul>
- <li><a href="#Text colors"> Text colors</a><ul>
- <li><a href="#GENERAL_TEXT General text (if no"> GENERAL_TEXT General text (if not set in MAIN_BACKGROUND_COLOR) (black)</a></li>
- <li><a href="#HEADER_TEXT Header text"> HEADER_TEXT Header text</a></li>
- <li><a href="#CODE_TEXT Code text, left bar te"> CODE_TEXT Code text, left bar text and links</a></li>
- <li><a href="#MUTED_TEXT Muted text (dark gray"> MUTED_TEXT Muted text (dark gray)</a></li>
- <li><a href="#GRAYED_OUT_TEXT Grayed out text"> GRAYED_OUT_TEXT Grayed out text</a></li>
- <li><a href="#STRONG_TEXT Dark text, header (d"> STRONG_TEXT Dark text, header (dark gray)</a></li>
- <li><a href="#SEPARATOR Seperator in topic act"> SEPARATOR Seperator in topic action bar</a></li>
+ <li><a href="#BUTTON_BACKGROUND Button backgro"> BUTTON_BACKGROUND Button background</a></li>
+ <li><a href="#BUTTON_CANCEL_BACKGROUND Cancel"> BUTTON_CANCEL_BACKGROUND Cancel button background</a></li>
+ <li><a href="#SUBMIT_BUTTON_BACKGROUND Submit"> SUBMIT_BUTTON_BACKGROUND Submit button background</a></li>
+ <li><a href="#SUBMIT_BUTTON_BORDER_TEXT Submit"> SUBMIT_BUTTON_BORDER_TEXT Submit button text color</a></li>
+ <li><a href="#SELECT_BORDER Select border"> SELECT_BORDER Select border</a></li>
</ul>
</li>
<li><a href="#Background colors"> Background colors</a><ul>
<li><a href="#GENERAL_BACKGROUND General backg"> GENERAL_BACKGROUND General background color (if not set in MAIN_BACKGROUND_COLOR) (white)</a></li>
<li><a href="#SIDE_BAR_BACKGROUND Side bar bac"> SIDE_BAR_BACKGROUND Side bar background</a></li>
- <li><a href="#SIDE_BAR_PERSONAL_BACKGROUND Sid"> SIDE_BAR_PERSONAL_BACKGROUND Side bar personal background</a></li>
- <li><a href="#INFO_BACKGROUND Info (very light"> INFO_BACKGROUND Info (very light blue) (placeholder for background image)</a></li>
- <li><a href="#TOPIC_ACTION_BACKGROUND Topic ac"> TOPIC_ACTION_BACKGROUND Topic action row (light yellow)</a></li>
- <li><a href="#HEADER_BACKGROUND H1, H2, etc he"> HEADER_BACKGROUND H1, H2, etc header (light yellow) </a></li>
- <li><a href="#ATTACHMENT_AND_FORM_BACKGROUND A"> ATTACHMENT_AND_FORM_BACKGROUND Attachment, form (light yellow)</a></li>
- <li><a href="#DIFF_HEADER_BACKGROUND Diff head"> DIFF_HEADER_BACKGROUND Diff header (dark gray) (same as GRAYED_OUT_TEXT)</a></li>
+ <li><a href="#NEUTRAL_BACKGROUND"> NEUTRAL_BACKGROUND</a></li>
+ <li><a href="#TOP_BAR_BACKGROUND Top bar backg"> TOP_BAR_BACKGROUND Top bar background</a></li>
+ <li><a href="#ATTACHMENT_AND_FORM_BACKGROUND A"> ATTACHMENT_AND_FORM_BACKGROUND Attachment, form</a></li>
+ <li><a href="#TOPIC_ACTION_BACKGROUND Topic ac"> TOPIC_ACTION_BACKGROUND Topic action row</a></li>
+ <li><a href="#HEADER_BACKGROUND h2, h3"> HEADER_BACKGROUND h2, h3</a></li>
+ <li><a href="#DIFF_HEADER_BACKGROUND Diff head"> DIFF_HEADER_BACKGROUND Diff header (dark gray)</a></li>
+ <li><a href="#NOTIFICATION_BACKGROUND Info, br"> NOTIFICATION_BACKGROUND Info, broadcast message and notifications</a></li>
+ <li><a href="#INFO_BACKGROUND"> INFO_BACKGROUND</a></li>
+ </ul>
+ </li>
+ <li><a href="#Border colors"> Border colors</a><ul>
+ <li><a href="#NEUTRAL_BORDER Info (light gray)"> NEUTRAL_BORDER Info (light gray)</a></li>
+ <li><a href="#SEPARATOR_BORDER"> SEPARATOR_BORDER</a></li>
+ <li><a href="#MINOR_SEPARATOR_BORDER Header H3"> MINOR_SEPARATOR_BORDER Header H3..H6 bottom</a></li>
+ <li><a href="#LAYOUT_ELEMENT_BORDER Main layou"> LAYOUT_ELEMENT_BORDER Main layout elements (neutral tone)</a></li>
+ <li><a href="#IMAGE_BORDER Image border"> IMAGE_BORDER Image border</a></li>
+ <li><a href="#FORM_STEP_BORDER Form step borde"> FORM_STEP_BORDER Form step border</a></li>
+ <li><a href="#NOTIFICATION_BORDER Broadcast me"> NOTIFICATION_BORDER Broadcast message</a></li>
<li><a href="#Table colors"> Table colors</a><ul>
<li><a href="#TABLE_DATA_BACKGROUND Table data"> TABLE_DATA_BACKGROUND Table data background</a></li>
<li><a href="#TABLE_HEADER_BACKGROUND Table he"> TABLE_HEADER_BACKGROUND Table header background</a></li>
- <li><a href="#TABLE_SELECTED_COLUMN_HEADER_BAC"> TABLE_SELECTED_COLUMN_HEADER_BACKGROUND Sorted table column accent background </a></li>
+ <li><a href="#TABLE_SELECTED_COLUMN_HEADER_BAC"> TABLE_SELECTED_COLUMN_HEADER_BACKGROUND Sorted table column accent background</a></li>
<li><a href="#TABLE_DATA_ODD_BACKGROUND Table"> TABLE_DATA_ODD_BACKGROUND Table data background (odd row)</a></li>
<li><a href="#TABLE_DATA_EVEN_BACKGROUND Table"> TABLE_DATA_EVEN_BACKGROUND Table data background (even row)</a></li>
<li><a href="#TABLE_DATA_ODD_SELECTED_BACKGROU"> TABLE_DATA_ODD_SELECTED_BACKGROUND Table data background (odd row, selected column)</a></li>
<li><a href="#TABLE_DATA_MIX_BACKGROUND Table"> TABLE_DATA_MIX_BACKGROUND Table data background (mix between even and odd)</a></li>
</ul>
</li>
+ <li><a href="#TABLE_BORDER Table border, sup ("> TABLE_BORDER Table border, sup (light neutral tone)</a></li>
+ <li><a href="#LINK_TEXT_NORMAL_TABLE_HEADER Ta"> LINK_TEXT_NORMAL_TABLE_HEADER Table header link text</a></li>
+ <li><a href="#LINK_TEXT_NORMAL_BORDER_TABLE_HE"> LINK_TEXT_NORMAL_BORDER_TABLE_HEADER Table header link border</a></li>
+ <li><a href="#LINK_TEXT_SORTED_TABLE_HEADER So"> LINK_TEXT_SORTED_TABLE_HEADER Sorted table header link text</a></li>
+ <li><a href="#LINK_TEXT_HOVER_TABLE_HEADER Tab"> LINK_TEXT_HOVER_TABLE_HEADER Table header link hover text</a></li>
+ <li><a href="#LINK_BORDER_TABLE_SELECTED_COLUM"> LINK_BORDER_TABLE_SELECTED_COLUMN_HEADER Link border in selected column header</a></li>
</ul>
</li>
- <li><a href="#Border colors"> Border colors</a><ul>
- <li><a href="#INFO_BORDER Info (light blue)"> INFO_BORDER Info (light blue)</a></li>
- <li><a href="#SEPARATOR_BORDER HR line, bottom"> SEPARATOR_BORDER HR line, bottom of h2, attachment table, form (brown)</a></li>
- <li><a href="#MINOR_SEPARATOR_BORDER Header H3"> MINOR_SEPARATOR_BORDER Header H3..H6 bottom (75% of SEPARATOR_BORDER)</a></li>
- <li><a href="#LAYOUT_ELEMENT_BORDER Main layou"> LAYOUT_ELEMENT_BORDER Main layout elements (neutral tone) </a></li>
- <li><a href="#TABLE_BORDER Table border, sup ("> TABLE_BORDER Table border, sup (light neutral tone)</a></li>
- <li><a href="#TABLE_BORDER_LIGHT Table border"> TABLE_BORDER_LIGHT Table border light</a></li>
+ <li><a href="#Forms"> Forms</a><ul>
+ <li><a href="#INPUT_FIELD_BORDERS Input field"> INPUT_FIELD_BORDERS Input field borders</a></li>
+ <li><a href="#FORM_INPUT_BORDER Textarea, inpu"> FORM_INPUT_BORDER Textarea, input and select (darker gray)</a></li>
+ <li><a href="#FORM_BORDER Form (same as twikiT"> FORM_BORDER Form (same as twikiTable border)</a></li>
+ <li><a href="#ACTIVE_FORM_BACKGROUND Edit form"> ACTIVE_FORM_BACKGROUND Edit form, form steps</a></li>
+ <li><a href="#FORMFIELD_ACTIVE Active form fie"> FORMFIELD_ACTIVE Active form field</a></li>
+ <li><a href="#FORM_HEADER_TEXT Header text on"> FORM_HEADER_TEXT Header text on form background</a></li>
</ul>
</li>
</ul>
## <a name="Logical groupings"></a> Logical groupings
-### <a name="Text on background"></a> Text on background
+### <a name="Text"></a> Text
#### <a name="MAIN_TEXT_COLOR Main text color"></a> MAIN\_TEXT\_COLOR Main text color
- Set LIGHT\_ON\_DARK\_TEXT\_COLOR = #fff
-### <a name="Links"></a> Links
+#### <a name="GRAYED_TEXT_COLOR"></a> GRAYED\_TEXT\_COLOR
-#### <a name="LINK_TEXT_NORMAL Link normal tex"></a> LINK\_TEXT\_NORMAL Link normal text
+- Set GRAYED\_TEXT\_COLOR = #777
-- Set LINK\_TEXT\_NORMAL = #06c
+#### <a name="GENERAL_TEXT General text (if no"></a> GENERAL\_TEXT General text (if not set in MAIN\_BACKGROUND\_COLOR) (black)
-#### <a name="LINK_BACKGROUND_NORMAL Link norm"></a> LINK\_BACKGROUND\_NORMAL Link normal background
+- Set GENERAL\_TEXT = #000
-- Set LINK\_BACKGROUND\_NORMAL =
+#### <a name="HEADER_TEXT Header text"></a> HEADER\_TEXT Header text
-#### <a name="LINK_TEXT_ACTION_BUTTON Link tex"></a> LINK\_TEXT\_ACTION\_BUTTON Link text red (same as LINK\_BACKGROUND\_HOVER)
+- Set HEADER\_TEXT = #630000
-- Set LINK\_TEXT\_ACTION\_BUTTON = #D6000F
+#### <a name="CODE_TEXT Code text, left bar te"></a> CODE\_TEXT Code text, left bar text and links
-#### <a name="LINK_TEXT_HOVER Link hover text"></a> LINK\_TEXT\_HOVER Link hover text
+- Set CODE\_TEXT = #7A4707
-- Set LINK\_TEXT\_HOVER = #FBF7E8
+#### <a name="MUTED_TEXT Muted text (dark gray"></a> MUTED\_TEXT Muted text (dark gray)
-#### <a name="LINK_BACKGROUND_HOVER Link backg"></a> LINK\_BACKGROUND\_HOVER Link background hover
+- Set MUTED\_TEXT = %GRAYED\_TEXT\_COLOR%
-- Set LINK\_BACKGROUND\_HOVER = #D6000F
+#### <a name="GRAYED_OUT_TEXT Grayed out text"></a> GRAYED\_OUT\_TEXT Grayed out text
-#### <a name="SIDE_BAR_LINK_TEXT Side bar link"></a> SIDE\_BAR\_LINK\_TEXT Side bar link text
+- Set GRAYED\_OUT\_TEXT = %GRAYED\_TEXT\_COLOR%
-- Set SIDE\_BAR\_LINK\_TEXT = #666
+### <a name="Links"></a> Links
-#### <a name="LINK_TEXT_NORMAL_TABLE_HEADER Ta"></a> LINK\_TEXT\_NORMAL\_TABLE\_HEADER Table header link text
+#### <a name="LINK_TEXT_NORMAL Link normal tex"></a> LINK\_TEXT\_NORMAL Link normal text
-- Set LINK\_TEXT\_NORMAL\_TABLE\_HEADER = #fff
+- Set LINK\_TEXT\_NORMAL = #4571d0
-#### <a name="LINK_TEXT_NORMAL_BORDER_TABLE_HE"></a> LINK\_TEXT\_NORMAL\_BORDER\_TABLE\_HEADER Table header link border
+#### <a name="LINK_BACKGROUND_NORMAL Link norm"></a> LINK\_BACKGROUND\_NORMAL Link normal background
-- Set LINK\_TEXT\_NORMAL\_BORDER\_TABLE\_HEADER = #bbb
+- Set LINK\_BACKGROUND\_NORMAL =
-#### <a name="LINK_TEXT_SORTED_TABLE_HEADER So"></a> LINK\_TEXT\_SORTED\_TABLE\_HEADER Sorted table header link text
+#### <a name="LINK_TEXT_NORMAL_VISITED Link no"></a> LINK\_TEXT\_NORMAL\_VISITED Link normal text visited
-- Set LINK\_TEXT\_SORTED\_TABLE\_HEADER = #fff
+- Set LINK\_TEXT\_NORMAL\_VISITED = #666
-#### <a name="LINK_TEXT_HOVER_TABLE_HEADER Tab"></a> LINK\_TEXT\_HOVER\_TABLE\_HEADER Table header link hover text
+#### <a name="LINK_TEXT_ACTION_BUTTON Link tex"></a> LINK\_TEXT\_ACTION\_BUTTON Link text red (same as LINK\_BACKGROUND\_HOVER)
-- Set LINK\_TEXT\_HOVER\_TABLE\_HEADER = #fff
+- Set LINK\_TEXT\_ACTION\_BUTTON = #be000a
-#### <a name="LINK_BORDER_TABLE_SELECTED_COLUM"></a> LINK\_BORDER\_TABLE\_SELECTED\_COLUMN\_HEADER Link border in selected column header
+#### <a name="LINK_TEXT_HOVER Link hover text"></a> LINK\_TEXT\_HOVER Link hover text
-- Set LINK\_BORDER\_TABLE\_SELECTED\_COLUMN\_HEADER = #999
+- Set LINK\_TEXT\_HOVER = #fff
+
+#### <a name="LINK_BACKGROUND_HOVER Link backg"></a> LINK\_BACKGROUND\_HOVER Link background hover
+
+- Set LINK\_BACKGROUND\_HOVER = #ce000f
+
+#### <a name="SIDE_BAR_LINK_TEXT Side bar link"></a> SIDE\_BAR\_LINK\_TEXT Side bar link text
+
+- Set SIDE\_BAR\_LINK\_TEXT = #444
### <a name="Disabled"></a> Disabled
#### <a name="DISABLED_TEXT Disabled text"></a> DISABLED\_TEXT Disabled text
-- Set DISABLED\_TEXT = #ccc
+- Set DISABLED\_TEXT = #aaa
#### <a name="DISABLED_BACKGROUND Disabled bac"></a> DISABLED\_BACKGROUND Disabled background
-- Set DISABLED\_BACKGROUND = #f5f5f5
+- Set DISABLED\_BACKGROUND = #fafaf8
+
+#### <a name="BUTTON_BORDERS_DISABLED Disabled"></a> BUTTON\_BORDERS\_DISABLED Disabled button borders
+
+- Set BUTTON\_BORDERS\_DISABLED = #fff #ccc #ccc #fff
### <a name="'New'"></a> 'New'
#### <a name="BUTTON_TEXT Button text color (d"></a> BUTTON\_TEXT Button text color (dark gray)
-- Set BUTTON\_TEXT = #333
+- Set BUTTON\_TEXT = #000
#### <a name="BUTTON_BORDERS Button borders"></a> BUTTON\_BORDERS Button borders
-- Set BUTTON\_BORDERS = #ddd #aaa #aaa #ddd
+- Set BUTTON\_BORDERS = #fff #888 #888 #fff
-#### <a name="BUTTON_BORDERS_ACTIVE Button bor"></a> BUTTON\_BORDERS\_ACTIVE Button borders (active)
+#### <a name="BUTTON_BACKGROUND Button backgro"></a> BUTTON\_BACKGROUND Button background
-- Set BUTTON\_BORDERS\_ACTIVE = #999 #ccc #ccc #999
+- Set BUTTON\_BACKGROUND = #e2e3e3
-#### <a name="SUBMIT_BUTTON_BACKGROUND Submit"></a><a name="SUBMIT_BUTTON_BACKGROUND Submit "></a> SUBMIT\_BUTTON\_BACKGROUND Submit button background (dark yellow)
+#### <a name="BUTTON_CANCEL_BACKGROUND Cancel"></a><a name="BUTTON_CANCEL_BACKGROUND Cancel "></a> BUTTON\_CANCEL\_BACKGROUND Cancel button background
-- Set SUBMIT\_BUTTON\_BACKGROUND = #FED764
+- Set BUTTON\_CANCEL\_BACKGROUND = #f2d5d0
-#### <a name="SUBMIT_BUTTON_BORDER Submit butt"></a> SUBMIT\_BUTTON\_BORDER Submit button border (blue)
+#### <a name="SUBMIT_BUTTON_BACKGROUND Submit"></a><a name="SUBMIT_BUTTON_BACKGROUND Submit "></a> SUBMIT\_BUTTON\_BACKGROUND Submit button background
-- Set SUBMIT\_BUTTON\_BORDER = #88B6CF
+- Set SUBMIT\_BUTTON\_BACKGROUND = #06c
-### <a name="Forms"></a> Forms
-
-#### <a name="INPUT_FIELD_BORDERS Input field"></a><a name="INPUT_FIELD_BORDERS Input field "></a> INPUT\_FIELD\_BORDERS Input field borders
-
-- Set INPUT\_FIELD\_BORDERS = #aaa #ddd #ddd #aaa
-
-#### <a name="FORM_INPUT_BORDER Textarea, inpu"></a> FORM\_INPUT\_BORDER Textarea, input and select (darker gray)
-
-- Set FORM\_INPUT\_BORDER = #aaa
+#### <a name="SUBMIT_BUTTON_BORDER_TEXT Submit"></a> SUBMIT\_BUTTON\_BORDER\_TEXT Submit button text color
-#### <a name="FORM_BORDER Form (same as twikiT"></a> FORM\_BORDER Form (same as twikiTable border)
+- Set SUBMIT\_BUTTON\_BORDER\_TEXT = #fff
-- Set FORM\_BORDER = #ccc
+#### <a name="SELECT_BORDER Select border"></a> SELECT\_BORDER Select border
-#### <a name="ACTIVE_FORM_BACKGROUND Edit form"></a> ACTIVE\_FORM\_BACKGROUND Edit form, form steps
+- Set SELECT\_BORDER = #888
-- Set ACTIVE\_FORM\_BACKGROUND = #f8fbfc
+### <a name="Background colors"></a> Background colors
-#### <a name="FORMFIELD_ACTIVE Active form fie"></a> FORMFIELD\_ACTIVE Active form field (not implemented yet)
+#### <a name="GENERAL_BACKGROUND General backg"></a> GENERAL\_BACKGROUND General background color (if not set in MAIN\_BACKGROUND\_COLOR) (white)
-- Set FORMFIELD\_ACTIVE = #ffc
+- Set GENERAL\_BACKGROUND = #fff
-## <a name="Color groupings"></a> Color groupings
+#### <a name="SIDE_BAR_BACKGROUND Side bar bac"></a> SIDE\_BAR\_BACKGROUND Side bar background
-### <a name="Text colors"></a> Text colors
+- Set SIDE\_BAR\_BACKGROUND = #f6f6f6
-#### <a name="GENERAL_TEXT General text (if no"></a> GENERAL\_TEXT General text (if not set in MAIN\_BACKGROUND\_COLOR) (black)
+#### <a name="NEUTRAL_BACKGROUND"></a> NEUTRAL\_BACKGROUND
-- Set GENERAL\_TEXT = #000
+- Set NEUTRAL\_BACKGROUND = #fdfaf1
-#### <a name="HEADER_TEXT Header text"></a> HEADER\_TEXT Header text
+#### <a name="TOP_BAR_BACKGROUND Top bar backg"></a> TOP\_BAR\_BACKGROUND Top bar background
-- Set HEADER\_TEXT = #a00
+- Set TOP\_BAR\_BACKGROUND = #fefcf7
-#### <a name="CODE_TEXT Code text, left bar te"></a> CODE\_TEXT Code text, left bar text and links
+#### <a name="ATTACHMENT_AND_FORM_BACKGROUND A"></a> ATTACHMENT\_AND\_FORM\_BACKGROUND Attachment, form
-- Set CODE\_TEXT = #7A4707
+- Set ATTACHMENT\_AND\_FORM\_BACKGROUND = #f6f6f6
-#### <a name="MUTED_TEXT Muted text (dark gray"></a> MUTED\_TEXT Muted text (dark gray)
+#### <a name="TOPIC_ACTION_BACKGROUND Topic ac"></a> TOPIC\_ACTION\_BACKGROUND Topic action row
-- Set MUTED\_TEXT = #666
+- Set TOPIC\_ACTION\_BACKGROUND = %ATTACHMENT\_AND\_FORM\_BACKGROUND%
-#### <a name="GRAYED_OUT_TEXT Grayed out text"></a> GRAYED\_OUT\_TEXT Grayed out text
+#### <a name="HEADER_BACKGROUND h2, h3"></a> HEADER\_BACKGROUND h2, h3
-- Set GRAYED\_OUT\_TEXT = #8E9195
+- Set HEADER\_BACKGROUND = %TOPIC\_ACTION\_BACKGROUND%
-#### <a name="STRONG_TEXT Dark text, header (d"></a> STRONG\_TEXT Dark text, header (dark gray)
+#### <a name="DIFF_HEADER_BACKGROUND Diff head"></a> DIFF\_HEADER\_BACKGROUND Diff header (dark gray)
-- Set STRONG\_TEXT = #333
+- Set DIFF\_HEADER\_BACKGROUND = #ccc
-#### <a name="SEPARATOR Seperator in topic act"></a> SEPARATOR Seperator in topic action bar
+#### <a name="NOTIFICATION_BACKGROUND Info, br"></a> NOTIFICATION\_BACKGROUND Info, broadcast message and notifications
-- Set SEPARATOR = #aaa
+- Set NOTIFICATION\_BACKGROUND = #ffe67b
-### <a name="Background colors"></a> Background colors
+#### <a name="INFO_BACKGROUND"></a> INFO\_BACKGROUND
-#### <a name="GENERAL_BACKGROUND General backg"></a> GENERAL\_BACKGROUND General background color (if not set in MAIN\_BACKGROUND\_COLOR) (white)
+- Set INFO\_BACKGROUND = %NOTIFICATION\_BACKGROUND%
-- Set GENERAL\_BACKGROUND = #fff
+### <a name="Border colors"></a> Border colors
-#### <a name="SIDE_BAR_BACKGROUND Side bar bac"></a> SIDE\_BAR\_BACKGROUND Side bar background
+#### <a name="NEUTRAL_BORDER Info (light gray)"></a> NEUTRAL\_BORDER Info (light gray)
-- Set SIDE\_BAR\_BACKGROUND = #f7fafc
+- Set NEUTRAL\_BORDER = #ddd
-#### <a name="SIDE_BAR_PERSONAL_BACKGROUND Sid"></a> SIDE\_BAR\_PERSONAL\_BACKGROUND Side bar personal background
+#### <a name="SEPARATOR_BORDER"></a> SEPARATOR\_BORDER
-- Set SIDE\_BAR\_PERSONAL\_BACKGROUND = #e6eff5;
+- Set SEPARATOR\_BORDER = #e2e2e2
-#### <a name="INFO_BACKGROUND Info (very light"></a> INFO\_BACKGROUND Info (very light blue) (placeholder for background image)
+#### <a name="MINOR_SEPARATOR_BORDER Header H3"></a> MINOR\_SEPARATOR\_BORDER Header H3..H6 bottom
-- Set INFO\_BACKGROUND = #f8fbfc
+- Set MINOR\_SEPARATOR\_BORDER = %SEPARATOR\_BORDER%
-#### <a name="TOPIC_ACTION_BACKGROUND Topic ac"></a> TOPIC\_ACTION\_BACKGROUND Topic action row (light yellow)
+#### <a name="LAYOUT_ELEMENT_BORDER Main layou"></a> LAYOUT\_ELEMENT\_BORDER Main layout elements (neutral tone)
-- Set TOPIC\_ACTION\_BACKGROUND = #FCF8EC
+- Set LAYOUT\_ELEMENT\_BORDER = #dadada
-#### <a name="HEADER_BACKGROUND H1, H2, etc he"></a> HEADER\_BACKGROUND H1, H2, etc header (light yellow)
+#### <a name="IMAGE_BORDER Image border"></a> IMAGE\_BORDER Image border
-- Set HEADER\_BACKGROUND = #FDFAF3
+- Set IMAGE\_BORDER = #eee
-#### <a name="ATTACHMENT_AND_FORM_BACKGROUND A"></a> ATTACHMENT\_AND\_FORM\_BACKGROUND Attachment, form (light yellow)
+#### <a name="FORM_STEP_BORDER Form step borde"></a> FORM\_STEP\_BORDER Form step border
-- Set ATTACHMENT\_AND\_FORM\_BACKGROUND = #FEFCF6
+- Set FORM\_STEP\_BORDER = %SEPARATOR\_BORDER%
-#### <a name="DIFF_HEADER_BACKGROUND Diff head"></a> DIFF\_HEADER\_BACKGROUND Diff header (dark gray) (same as GRAYED\_OUT\_TEXT)
+#### <a name="NOTIFICATION_BORDER Broadcast me"></a> NOTIFICATION\_BORDER Broadcast message
-- Set DIFF\_HEADER\_BACKGROUND = #ccc
+- Set NOTIFICATION\_BORDER = #ffdf4c
#### <a name="Table colors"></a> Table colors
##### <a name="TABLE_DATA_ODD_BACKGROUND Table"></a><a name="TABLE_DATA_ODD_BACKGROUND Table "></a> TABLE\_DATA\_ODD\_BACKGROUND Table data background (odd row)
-- Set TABLE\_DATA\_ODD\_BACKGROUND = #edf4f9
+- Set TABLE\_DATA\_ODD\_BACKGROUND = #f0f6fb
##### <a name="TABLE_DATA_EVEN_BACKGROUND Table"></a> TABLE\_DATA\_EVEN\_BACKGROUND Table data background (even row)
- Set TABLE\_DATA\_MIX\_BACKGROUND = #f7fafc
-### <a name="Border colors"></a> Border colors
+#### <a name="TABLE_BORDER Table border, sup ("></a> TABLE\_BORDER Table border, sup (light neutral tone)
-#### <a name="INFO_BORDER Info (light blue)"></a> INFO\_BORDER Info (light blue)
+- Set TABLE\_BORDER = #e2e2e2
-- Set INFO\_BORDER = #D5E6F3
+#### <a name="LINK_TEXT_NORMAL_TABLE_HEADER Ta"></a> LINK\_TEXT\_NORMAL\_TABLE\_HEADER Table header link text
-#### <a name="SEPARATOR_BORDER HR line, bottom"></a> SEPARATOR\_BORDER HR line, bottom of h2, attachment table, form (brown)
+- Set LINK\_TEXT\_NORMAL\_TABLE\_HEADER = #fff
-- Set SEPARATOR\_BORDER = #E2DCC8
+#### <a name="LINK_TEXT_NORMAL_BORDER_TABLE_HE"></a> LINK\_TEXT\_NORMAL\_BORDER\_TABLE\_HEADER Table header link border
-#### <a name="MINOR_SEPARATOR_BORDER Header H3"></a> MINOR\_SEPARATOR\_BORDER Header H3..H6 bottom (75% of SEPARATOR\_BORDER)
+- Set LINK\_TEXT\_NORMAL\_BORDER\_TABLE\_HEADER = #bbb
-- Set MINOR\_SEPARATOR\_BORDER = #E9E4D2
+#### <a name="LINK_TEXT_SORTED_TABLE_HEADER So"></a> LINK\_TEXT\_SORTED\_TABLE\_HEADER Sorted table header link text
-#### <a name="LAYOUT_ELEMENT_BORDER Main layou"></a> LAYOUT\_ELEMENT\_BORDER Main layout elements (neutral tone)
+- Set LINK\_TEXT\_SORTED\_TABLE\_HEADER = #fff
-- Set LAYOUT\_ELEMENT\_BORDER = #ccc
+#### <a name="LINK_TEXT_HOVER_TABLE_HEADER Tab"></a> LINK\_TEXT\_HOVER\_TABLE\_HEADER Table header link hover text
-#### <a name="TABLE_BORDER Table border, sup ("></a> TABLE\_BORDER Table border, sup (light neutral tone)
+- Set LINK\_TEXT\_HOVER\_TABLE\_HEADER = #fff
+
+#### <a name="LINK_BORDER_TABLE_SELECTED_COLUM"></a> LINK\_BORDER\_TABLE\_SELECTED\_COLUMN\_HEADER Link border in selected column header
+
+- Set LINK\_BORDER\_TABLE\_SELECTED\_COLUMN\_HEADER = #999
+
+### <a name="Forms"></a> Forms
+
+#### <a name="INPUT_FIELD_BORDERS Input field"></a><a name="INPUT_FIELD_BORDERS Input field "></a> INPUT\_FIELD\_BORDERS Input field borders
+
+- Set INPUT\_FIELD\_BORDERS = #bbb #f2f2f2 #f2f2f2 #bbb
+
+#### <a name="FORM_INPUT_BORDER Textarea, inpu"></a> FORM\_INPUT\_BORDER Textarea, input and select (darker gray)
+
+- Set FORM\_INPUT\_BORDER = #aaa
+
+#### <a name="FORM_BORDER Form (same as twikiT"></a> FORM\_BORDER Form (same as twikiTable border)
+
+- Set FORM\_BORDER = #cfcfcf
+
+#### <a name="ACTIVE_FORM_BACKGROUND Edit form"></a> ACTIVE\_FORM\_BACKGROUND Edit form, form steps
+
+- Set ACTIVE\_FORM\_BACKGROUND = #fbfbfb
+
+#### <a name="FORMFIELD_ACTIVE Active form fie"></a> FORMFIELD\_ACTIVE Active form field
-- Set TABLE\_BORDER = #ccc
+- Set FORMFIELD\_ACTIVE = #ffffe0
-#### <a name="TABLE_BORDER_LIGHT Table border"></a><a name="TABLE_BORDER_LIGHT Table border "></a> TABLE\_BORDER\_LIGHT Table border light
+#### <a name="FORM_HEADER_TEXT Header text on"></a><a name="FORM_HEADER_TEXT Header text on "></a> FORM\_HEADER\_TEXT Header text on form background
-- Set TABLE\_BORDER\_LIGHT = #e2e7eb
+- Set FORM\_HEADER\_TEXT = #036
Do not change the text below this line unless you know what you are doing!
----
- %STARTATTACH{"theme-colors.css"}%
+ %STARTATTACH{"theme-colors.css" web="%TWIKIWEB%" topic="PatternSkin"}%
/* PatternSkin colors */
- /* Generated by AttachContentPlugin from TWiki.PatternSkinColorSettings */
+ /* Generated by AttachContentPlugin from %WEB%.%TOPIC% */
/* LAYOUT ELEMENTS */
#patternTopBar {
- background-color:%MAIN_BACKGROUND_COLOR%;
- border-color:%LAYOUT_ELEMENT_BORDER%;
+ border-color:%SEPARATOR_BORDER%;
+ background-color:%TOP_BAR_BACKGROUND%;
}
#patternMain { /* don't set a background here; use patternOuter */ }
#patternOuter {
background-color:%MAIN_BACKGROUND_COLOR%; /* Sets background of center col */
border-color:%LAYOUT_ELEMENT_BORDER%;
}
- #patternLeftBar, #patternLeftBarContents { /* don't set a background here; use patternWrapper */ }
+ #patternLeftBar,
#patternWrapper {
background-color:%SIDE_BAR_BACKGROUND%;
}
#patternBottomBar {
- background-color:%MAIN_BACKGROUND_COLOR%;
- border-color:%LAYOUT_ELEMENT_BORDER%;
+ border-color:%SEPARATOR_BORDER%;
}
#patternBottomBarContents,
#patternBottomBarContents a:link,
background-color:transparent;
}
hr {
- color:%LAYOUT_ELEMENT_BORDER%;
- background-color:%LAYOUT_ELEMENT_BORDER%;
+ color:%SEPARATOR_BORDER%;
+ background-color:%SEPARATOR_BORDER%;
}
pre, code, tt {
color:%CODE_TEXT%;
}
blockquote {
- border-color:%INFO_BORDER%;
background-color:%ACTIVE_FORM_BACKGROUND%;
+ border-color:%NEUTRAL_BORDER%;
}
- h1, h2, h3, h4, h5, h6 {
- color:%HEADER_TEXT%;
+ blockquote h2 {
+ background:none;
}
- h1 a:link,
- h1 a:visited {
+ h1, h2, h3, h4, h5, h6 {
color:%HEADER_TEXT%;
}
- h1 a:hover {
- color:%LINK_TEXT_HOVER%;
- }
h2 {
background-color:%HEADER_BACKGROUND%;
- border-color:%SEPARATOR_BORDER%;
+ border-color:%MINOR_SEPARATOR_BORDER%;
}
h3, h4, h5, h6 {
border-color:%MINOR_SEPARATOR_BORDER%;
.twikiNewLink a:link sup,
.twikiNewLink a:visited sup {
color:%MUTED_TEXT%;
- border-color:%TABLE_BORDER%;
+ border-color:%NEUTRAL_BORDER%;
}
.twikiNewLink a:hover sup {
background-color:%LINK_BACKGROUND_HOVER%;
border-color:%LINK_BACKGROUND_HOVER%;
}
.twikiNewLink {
- border-color:%TABLE_BORDER%;
+ border-color:%NEUTRAL_BORDER%;
}
:link:focus,
:visited:focus,
:visited:hover {
color:%LINK_TEXT_HOVER%;
background-color:%LINK_BACKGROUND_HOVER%;
+ background-image:none;
}
:link:hover img,
:visited:hover img {
background-color:transparent;
}
- /* fix for hover over transparent logo: */
- #patternTopBar :link:hover img,
- #patternTopBar :visited:hover img {
- background:%MAIN_BACKGROUND_COLOR%;
- }
.patternTopic a:visited {
- color:%MUTED_TEXT%;
+ color:%LINK_TEXT_NORMAL_VISITED%;
}
.patternTopic a:hover {
color:%LINK_TEXT_HOVER%;
}
+ #patternMainContents h1 a:link, #patternMainContents h1 a:visited,
+ #patternMainContents h2 a:link, #patternMainContents h2 a:visited,
+ #patternMainContents h3 a:link, #patternMainContents h3 a:visited,
+ #patternMainContents h4 a:link, #patternMainContents h4 a:visited,
+ #patternMainContents h5 a:link, #patternMainContents h5 a:visited,
+ #patternMainContents h6 a:link, #patternMainContents h6 a:visited {
+ color:%HEADER_TEXT%;
+ }
+ #patternMainContents h1 a:hover,
+ #patternMainContents h2 a:hover,
+ #patternMainContents h3 a:hover,
+ #patternMainContents h4 a:hover,
+ #patternMainContents h5 a:hover,
+ #patternMainContents h6 a:hover {
+ color:%LINK_TEXT_HOVER%;
+ }
+ .patternTopic .twikiUnvisited a:visited {
+ color:%LINK_TEXT_NORMAL%;
+ }
+ .patternTopic .twikiUnvisited a:hover {
+ color:%LINK_TEXT_HOVER%;
+ }
/* Form elements */
.twikiSubmit,
.twikiButton {
border-color:%BUTTON_BORDERS%;
+ }
+ .twikiSubmit {
+ color:%SUBMIT_BUTTON_BORDER_TEXT%;
+ background-color:%SUBMIT_BUTTON_BACKGROUND%;
+ }
+ .twikiButton {
color:%BUTTON_TEXT%;
- background-color:%GENERAL_BACKGROUND%;
+ background-color:%BUTTON_BACKGROUND%;
}
- .twikiSubmit:active,
- .twikiButton:active {
- border-color:%BUTTON_BORDERS_ACTIVE%;
- color:%GENERAL_TEXT%;
+ .twikiButtonCancel {
+ color:%BUTTON_TEXT%;
+ background-color:%BUTTON_CANCEL_BACKGROUND%;
}
.twikiSubmitDisabled,
.twikiSubmitDisabled:active {
- border-color:%DISABLED_BORDER%;
+ border-color:%BUTTON_BORDERS_DISABLED%;
color:%DISABLED_TEXT%;
- background-color:%DISABLED_BACKGROUND%;
+ background-color:%ACTIVE_FORM_BACKGROUND%;
}
+ .twikiTextarea,
.twikiInputField,
+ .twikiInputFieldDisabled,
+ .twikiInputFieldReadOnly,
.twikiSelect {
border-color:%INPUT_FIELD_BORDERS%;
+ }
+ .twikiTextarea,
+ .twikiInputField,
+ .twikiSelect {
color:%MAIN_TEXT_COLOR%;
background-color:%MAIN_BACKGROUND_COLOR%;
}
+ .twikiInputField:active,
+ .twikiInputField:focus,
+ .twikiInputFieldFocus {
+ background-color:%FORMFIELD_ACTIVE%;
+ }
+
+ .twikiTextareaRawView {
+ color:%GENERAL_TEXT%;
+ }
.twikiInputFieldDisabled {
+ color:%DISABLED_TEXT%;
+ background-color:%DISABLED_BACKGROUND%;
+ }
+ .twikiInputFieldReadOnly {
+ color:%GRAYED_TEXT_COLOR%;
+ }
+ .twikiSelect {
+ border-color:%INPUT_FIELD_BORDERS%;
+ color:%MAIN_TEXT_COLOR%;
+ background-color:%MAIN_BACKGROUND_COLOR%;
+ }
+ .twikiInputFieldDisabled,
+ .twikiSelectDisabled {
+ color:%DISABLED_TEXT%;
+ border-color:%INPUT_FIELD_BORDERS%;
+ background-color:%DISABLED_BACKGROUND%;
+ }
+ .twikiInputFieldBeforeFocus {
color:%MUTED_TEXT%;
}
/* TablePlugin */
.twikiTable,
- .twikiTable td {
- border-color:%TABLE_BORDER%;
- }
+ .twikiTable td,
.twikiTable th {
- border-color:%TABLE_BORDER% %MAIN_BACKGROUND_COLOR%;
+ border-color:%TABLE_BORDER%;
}
.twikiTable th a:link,
.twikiTable th a:visited,
/* TipsContrib */
.tipsOfTheDay {
- background-color:%INFO_BACKGROUND%;
- }
- .patternTopic .tipsOfTheDayHeader {
- color:%STRONG_TEXT%;
- }
- /* TipsContrib - in left bar */
- #patternLeftBar .tipsOfTheDay a:link,
- #patternLeftBar .tipsOfTheDay a:visited {
- color:%HEADER_TEXT%;
- }
- #patternLeftBar .tipsOfTheDay a:hover {
- color:%LINK_TEXT_HOVER%;
}
/* RevCommentPlugin */
.twikiEditForm .twikiFormTable,
.twikiEditForm .twikiFormTable th,
.twikiEditForm .twikiFormTable td {
- border-color:%TABLE_BORDER_LIGHT%;
+ border-color:%TABLE_BORDER%;
}
/* use a different table background color mix: no odd/even rows, no white background */
.twikiEditForm .twikiFormTable td {
.patternContent .twikiAttachments,
.patternContent .twikiForm {
background-color:%ATTACHMENT_AND_FORM_BACKGROUND%;
- border-color:%SEPARATOR_BORDER%;
+ border-color:%TABLE_BORDER%;
}
.twikiAttachments table,
table.twikiFormTable {
- border-color:%LAYOUT_ELEMENT_BORDER%;
+ border-color:%TABLE_BORDER%;
background-color:%MAIN_BACKGROUND_COLOR%;
}
.twikiAttachments table {
}
.twikiAttachments td,
.twikiAttachments th {
- border-color:%LAYOUT_ELEMENT_BORDER%;
+ border-color:%TABLE_BORDER%;
}
.twikiAttachments .twikiTable th font,
table.twikiFormTable th.twikiFormTableHRow font {
.twikiFormSteps {
background-color:%ACTIVE_FORM_BACKGROUND%;
- border-color:%SEPARATOR_BORDER%;
+ border-color:%FORM_STEP_BORDER%;
}
.twikiFormStep {
- border-color:%SEPARATOR_BORDER%;
+ border-color:%FORM_STEP_BORDER%;
+ }
+ .twikiFormStep h3,
+ .twikiFormStep h4 {
+ color:%FORM_HEADER_TEXT%;
}
.twikiFormStep h3,
.twikiFormStep h4 {
background-color:transparent;
}
+ .twikiActionFormStepSign {
+ color:%FORM_HEADER_TEXT%;
+ }
.twikiToc .twikiTocTitle {
color:%MUTED_TEXT%;
}
.twikiBroadcastMessage {
- background-color:yellow;
+ background-color:%NOTIFICATION_BACKGROUND%;
+ }
+ .twikiNotification {
+ background-color:%NOTIFICATION_BACKGROUND%;
+ }
+ #twikiLogin .patternLoginNotification {
+ background-color:%MAIN_BACKGROUND_COLOR%;
+ border-color:%ALERT_BORDER%;
+ }
+ .twikiHelp {
+ background-color:%INFO_BACKGROUND%;
+ }
+ .twikiHelp {
+ background-color:%ATTACHMENT_AND_FORM_BACKGROUND%;
+ border-color:%SEPARATOR_BORDER%;
}
.twikiBroadcastMessage b,
.twikiBroadcastMessage strong {
background-color:%FORM_BORDER%;
color:%FORM_BORDER%;
}
- .twikiHelp {
- background-color:%INFO_BACKGROUND%;
- border-color:%INFO_BORDER%;
- }
.twikiAccessKey {
color:inherit;
border-color:%GRAYED_OUT_TEXT%;
}
a:link .twikiAccessKey,
- a:visited .twikiAccessKey,
+ a:visited .twikiAccessKey {
+ color:inherit;
+ }
a:hover .twikiAccessKey {
color:inherit;
}
+ .twikiImage img {
+ border-color:%IMAGE_BORDER%;
+ background-color:%MAIN_BACKGROUND_COLOR%;
+ }
+ #patternTopBar .twikiImage img {
+ background-color:transparent;
+ }
+ .twikiImage a:hover img {
+ border-color:%LINK_BACKGROUND_HOVER%;
+ }
/* -----------------------------------------------------------
Pattern skin specific elements
#patternPage {
background-color:%MAIN_BACKGROUND_COLOR%;
}
- /* Left bar */
- #patternLeftBarContents {
- color:%MUTED_TEXT%;
+ .patternHomePath a:link,
+ .patternHomePath a:visited {
+ border-color:%NEUTRAL_BORDER%;
+ color:%LINK_TEXT_NORMAL_VISITED%;
}
- #patternLeftBarContents .patternWebIndicator {
- color:%GENERAL_TEXT%;
+ .patternTop a:hover {
+ border:none;
+ color:%LINK_TEXT_HOVER%;
}
- #patternLeftBarContents .patternWebIndicator a:link,
- #patternLeftBarContents .patternWebIndicator a:visited {
- color:%GENERAL_TEXT%;
+ .patternHomePath .patternRevInfo,
+ .patternHomePath .patternRevInfo a:link,
+ .patternHomePath .patternRevInfo a:visited {
+ color:%GRAYED_OUT_TEXT%;
}
- #patternLeftBarContents .patternWebIndicator a:hover {
+ .patternHomePath .patternRevInfo a:hover {
color:%LINK_TEXT_HOVER%;
}
+
+ /* Left bar */
+ #patternLeftBarContents {
+ color:%GENERAL_TEXT%;
+ }
#patternLeftBarContents hr {
- color:%SEPARATOR_BORDER%;
- background-color:%SEPARATOR_BORDER%;
+ color:%FORM_STEP_BORDER%;
+ background-color:%FORM_STEP_BORDER%;
}
#patternLeftBarContents a:link,
#patternLeftBarContents a:visited {
#patternLeftBarContents a:hover {
color:%LINK_TEXT_HOVER%;
}
+ #patternLeftBarContents .patternLeftBarPersonal,
+ #patternLeftBarContents .patternWebIndicator {
+ border-color:#dadada;
+ }
#patternLeftBarContents b,
#patternLeftBarContents strong {
- color:%STRONG_TEXT%;
- }
- #patternLeftBarContents .patternChangeLanguage {
- color:%GRAYED_OUT_TEXT%;
- }
- #patternLeftBarContents .patternLeftBarPersonal {
- background-color:%SIDE_BAR_PERSONAL_BACKGROUND%
- }
- #patternLeftBarContents .patternLeftBarPersonal a:link,
- #patternLeftBarContents .patternLeftBarPersonal a:visited,
- #patternLeftBarContents .twikiHierarchicalNavigation a:link,
- #patternLeftBarContents .twikiHierarchicalNavigation a:visited {
- color:%LINK_TEXT_NORMAL%;
- }
- #patternLeftBarContents .patternLeftBarPersonal a:hover,
- #patternLeftBarContents .twikiHierarchicalNavigation a:hover {
- color:%LINK_TEXT_HOVER%;
- background-color:%LINK_BACKGROUND_HOVER%;
- }
- #patternLeftBarContents .twikiHierarchicalNavigation {
- background:%MAIN_BACKGROUND_COLOR%;
+ color:%HEADER_TEXT%;
}
+
.patternTopicActions {
- border-color:%SEPARATOR_BORDER%;
+ border-color:%TABLE_BORDER%;
+ background-color:%TOPIC_ACTION_BACKGROUND%;
+ color:%MUTED_TEXT%;
}
.patternTopicAction {
- color:%MUTED_TEXT%;
- border-color:%SEPARATOR_BORDER%;
- background-color:%TOPIC_ACTION_BACKGROUND%;
+ border-color:%TABLE_BORDER%;
}
.patternTopicAction s,
.patternTopicAction strike {
color:%LINK_TEXT_ACTION_BUTTON%;
border-color:%LINK_TEXT_ACTION_BUTTON%;
}
+ .patternTopicAction a:hover .twikiAccessKey {
+ color:%LINK_TEXT_HOVER%;
+ }
.patternTopicAction label {
color:%GENERAL_TEXT%;
}
.patternHelpCol {
color:%GRAYED_OUT_TEXT%;
}
- .patternFormFieldDefaultColor {
- /* input fields default text color (no user input) */
- color:%GRAYED_OUT_TEXT%;
- }
-
- .patternToolBar .patternButton s,
- .patternToolBar .patternButton strike,
- .patternToolBar .patternButton a:link,
- .patternToolBar .patternButton a:visited {
- border-color:%SEPARATOR_BORDER%;
- background-color:%GENERAL_BACKGROUND%;
- }
- .patternToolBar .patternButton a:link,
- .patternToolBar .patternButton a:visited {
+ .patternSigLine {
color:%MUTED_TEXT%;
- }
- .patternToolBar .patternButton s,
- .patternToolBar .patternButton strike {
- color:%DISABLED_TEXT%;
- border-color:%DISABLED_BORDER%;
- }
- .patternToolBar .patternButton a:hover {
- background-color:%LINK_BACKGROUND_HOVER%;
- color:%LINK_TEXT_HOVER%;
- border-color:%LINK_TEXT_ACTION_BUTTON%;
- }
- .patternToolBar .patternButton img {
- background-color:transparent;
- }
- .patternToolBarBottom {
+ background-color:%ATTACHMENT_AND_FORM_BACKGROUND%;
border-color:%SEPARATOR_BORDER%;
}
.patternToolBar a:link .twikiAccessKey,
.patternToolBar a:visited .twikiAccessKey {
color:inherit;
- border-color:%MUTED_TEXT%;
+ border-color:%LINK_TEXT_NORMAL_VISITED%;
}
.patternToolBar a:hover .twikiAccessKey {
background-color:transparent;
color:inherit;
- }
-
- .patternRevInfo,
- .patternRevInfo a:link,
- .patternRevInfo a:visited {
- color:%GRAYED_OUT_TEXT%;
- }
- .patternRevInfo a:hover {
- color:%LINK_TEXT_HOVER%;
- }
-
- .patternMoved,
- .patternMoved a:link,
- .patternMoved a:visited {
- color:%GRAYED_OUT_TEXT%;
- }
- .patternMoved a:hover {
- color:%LINK_TEXT_HOVER%;
+ border-color:%LINK_TEXT_NORMAL_VISITED%;
}
.patternSaveHelp {
background-color:%MAIN_BACKGROUND_COLOR%;
}
/* WebSearch, WebSearchAdvanced */
+ table#twikiSearchTable {
+ border-color:%FORM_STEP_BORDER%;
+ }
table#twikiSearchTable th,
table#twikiSearchTable td {
background-color:%GENERAL_BACKGROUND%;
- border-color:%TABLE_BORDER%;
+ border-color:%FORM_STEP_BORDER%;
+ }
+ table#twikiSearchTable hr {
+ border-color:%FORM_STEP_BORDER%;
+ background-color:%FORM_STEP_BORDER%;
}
table#twikiSearchTable th {
color:%MAIN_TEXT_COLOR%;
}
- table#twikiSearchTable td.first {
- background-color:%TOPIC_ACTION_BACKGROUND%;
- }
/* -----------------------------------------------------------
Search results
h3.patternSearchResultsHeader,
h4.patternSearchResultsHeader {
background-color:%ATTACHMENT_AND_FORM_BACKGROUND%;
- border-color:%LAYOUT_ELEMENT_BORDER%;
+ border-color:%SEPARATOR_BORDER%;
}
h4.patternSearchResultsHeader {
color:%MAIN_TEXT_COLOR%;
color:%HEADER_TEXT%;
}
.patternSearchResult .twikiBottomRow {
- border-color:%TABLE_BORDER%;
+ border-color:%MINOR_SEPARATOR_BORDER%;
}
.patternSearchResult .twikiAlert {
color:%ALERT_TEXT%;
color:%GRAYED_OUT_TEXT%;
}
- /* oopsmore.pattern.tmpl */
-
- table.patternDiffOptions img {
- border-color:%LAYOUT_ELEMENT_BORDER%;
- }
-
/* edit.pattern.tmpl */
- .twikiChangeFormButton .twikiButton,
- .twikiChangeFormButtonHolder .twikiButton { /* looks like a link */
- color:%LINK_TEXT_NORMAL%;
- background:none;
- }
- .patternSig input {
- color:%GRAYED_OUT_TEXT%;
- background-color:%MAIN_BACKGROUND_COLOR%;
- }
-
/* preview.pattern.tmpl */
- .patternPreviewArea {
+ .twikiPreviewArea {
border-color:%ALERT_BORDER%;
background-color:%MAIN_BACKGROUND_COLOR%;
}
.patternDiff {
border-color:%TABLE_HEADER_BACKGROUND%;
}
- .patternDiff h4.patternSearchResultsHeader {
+ #patternMainContents .patternDiff h4.patternSearchResultsHeader {
background-color:%TABLE_HEADER_BACKGROUND%;
color:%LIGHT_ON_DARK_TEXT_COLOR%;
}
- .patternDiff h4.patternSearchResultsHeader a:link,
- .patternDiff h4.patternSearchResultsHeader a:visited {
+ #patternMainContents .patternDiff h4.patternSearchResultsHeader a:link,
+ #patternMainContents .patternDiff h4.patternSearchResultsHeader a:visited {
color:%LIGHT_ON_DARK_TEXT_COLOR%;
}
tr.twikiDiffDebug td {
/* IMAGES */
/* image positions are set here as well as these are dependent on the image */
- .twikiInputField {
- background-image:url(background_input.gif);
+ h2,
+ .patternTopicAction {
+ background-image:url(bg_action_gradient.gif);
background-repeat:repeat-x;
}
- .twikiInputFieldDisabled {
- background-image:none;
- border:none;
+ .twikiToc li {
+ background-image:url(bullet-toc.gif);
+ background-repeat:no-repeat;
+ background-position:0 .4em;
}
- .twikiButton {
- background-image:url(background_button.gif);
+ #patternOuter,
+ #patternTopBar {
+ /* gradient yellow of left bar and main */
+ background-image:url(bg_outer_gradient.gif);
background-repeat:repeat-x;
}
- .patternToolBarButtons .patternButton a {
- /*
- background-image:url(background_button.gif);
- background-repeat:repeat-x;
- */
+ .patternPrintPage #patternOuter {
+ background:#fff; /* white - do not change */
}
- .twikiSubmit {
- background-image:url(background_submit.gif);
+ .twikiPageForm table,
+ table#twikiSearchTable td.twikiFirstRow {
+ background-image:url(form_gradient.gif);
background-repeat:repeat-x;
+ background-color:#f5f5f5;
}
+ .twikiSubmit,
.twikiSubmitDisabled {
- background-image:none;
+ background-image:url(bg_submit_gradient.gif);
+ background-repeat:repeat-x;
}
- .twikiToc li {
- background-image:url(bullet-child-black.gif);
- background-repeat:no-repeat;
- background-position:0 .35em;
+ .twikiSubmit,
+ a.twikiSubmit:link,
+ a.twikiSubmit:visited {
+ background-position:0px 0px;
+ background-color:#06c;
+ border-color:#abcdf0 #0048b8 #0048b8 #abcdf0;
+ color:#fff;
+ }
+ .twikiSubmit:hover,
+ a.twikiSubmit:hover {
+ background-position:0px -80px;
+ background-color:#0047b7;
+ border-color:#98bce9 #0031a4 #0031a4 #98bce9;
+ color:#fff;
+ }
+ .twikiSubmit:active,
+ a.twikiSubmit:active {
+ background-position:0px -160px;
+ background-color:#73ace6;
+ border-color:#0031a4 #98bce9 #98bce9 #0031a4;
+ color:#fff;
}
- /*#patternLeftBarContents .patternLeftBarPersonal,*/
- #twikiLogin,
- #patternLeftBarContents .tipsOfTheDayContents {
- background-image:url(gradient_blue.gif);
+ .twikiSubmitDisabled,
+ .twikiSubmitDisabled:hover,
+ .twikiSubmitDisabled:active {
+ background-position:0px -240px;
+ background-color:#d9e8f7;
+ border-color:#f5f9fd #ccc #ccc #f5f9fd;
+ color:#ccc;
+ }
+ .twikiButton,
+ a.twikiButton:link,
+ a.twikiButton:visited {
+ background-image:url(bg_button_gradient.gif);
background-repeat:repeat-x;
+ background-position:0px 0px;
+ border-color:#f8f6ec #b8b6ad #b8b6ad #f8f6ec;
+ background-color:#dbd9cf;
+ color:#333;
}
- #patternOuter {
- /* gradient yellow of left bar and main */
- background-image:url(gradient_yellow.gif);
+ .twikiChangeFormButtonHolder .twikiButton {
+ background-color:#fff;
+ background-image:none;
+ color:#06c;
+ }
+ .twikiChangeFormButtonHolder .twikiButton:hover,
+ .twikiChangeFormButtonHolder .twikiButton:active {
+ background-image:url(bg_button_gradient.gif);
background-repeat:repeat-x;
}
- .patternPrintPage #patternOuter {
- background:#fff; /* white - do not change */
+ .twikiButton:hover,
+ .twikiChangeFormButtonHolder .twikiButton:hover,
+ a.twikiButton:hover {
+ background-position:0px -80px;
+ border-color:#f4f2eb #a3a092 #a3a092 #f4f2eb;
+ background-color:#c2bfae;
+ color:#222;
+ }
+ .twikiButton:active,
+ .twikiChangeFormButtonHolder .twikiButton:active,
+ a.twikiButton:active {
+ background-position:0px -160px;
+ border-color:#a3a092 #f4f2eb #f4f2eb #a3a092;
+ background-color:#e8e5d7;
+ color:#222;
+ }
+ .twikiButtonDisabled,
+ .twikiButtonDisabled:hover,
+ .twikiButtonDisabled:active {
+ background-image:url(bg_button_gradient.gif);
+ background-repeat:repeat-x;
+ background-position:0px -240px;
+ border-color:#fcfbf9 #e3e2dd #e3e2dd #fcfbf9;
+ background-color:#edece6;
+ color:#bbb;
}
- .twikiPageForm table {
- background-image:url(form_gradient.gif);
+ .twikiButtonCancel {
+ background-image:url(bg_buttoncancel_gradient.gif);
+ background-repeat:repeat-x;
+ background-position:0px 0px;
+ border-color:#f3ddd7 #b5706a #b5706a #f3ddd7;
+ background-color:#cc867f;
+ color:#333;
+ }
+ .twikiButtonCancel:hover {
+ background-position:0px -80px;
+ border-color:#eacac1 #9f564f #9f564f #eacac1;
+ background-color:#b26259;
+ color:#222;
+ }
+ .twikiButtonCancel:active {
+ background-position:0px -160px;
+ border-color:#9f564f #eacac1 #eacac1 #9f564f;
+ background-color:#e5bdb1;
+ color:#222;
+ }
+ .patternToolBar span a:link,
+ .patternToolBar span a:visited,
+ .patternToolBar span s,
+ .patternToolBar span strike {
+ background-image:url(bg_button_small_gradient.gif);
+ background-repeat:repeat-x;
+ }
+ .patternToolBar span a:link,
+ .patternToolBar span a:visited {
+ background-position:0px 0px;
+ border-color:#f8f6ec #b8b6ad #b8b6ad #f8f6ec;
+ background-color:#dbd9cf;
+ color:#333;
+ }
+ .patternToolBar span a:hover {
+ background-position:0px -80px;
+ border-color:#f4f2eb #a3a092 #a3a092 #f4f2eb;
+ background-color:#c2bfae;
+ color:#222;
+ }
+ .patternToolBar span a:active {
+ background-position:0px -160px;
+ border-color:#a3a092 #f4f2eb #f4f2eb #a3a092;
+ background-color:#e8e5d7;
+ color:#222;
+ }
+ .patternToolBar span s,
+ .patternToolBar span strike {
+ background-position:0px -240px;
+ border-color:#fcfbf9 #e3e2dd #e3e2dd #fcfbf9;
+ background-color:#edece6;
+ color:#bbb;
+ }
+ .patternTextareaButton {
+ border-color:#fffefd #b8b6ad #b8b6ad #fffefd;
+ overflow:hidden;
+ }
+ .patternButtonFontSelector {
+ background-image:url(button_font_selector.gif);
+ width:33px;
+ height:16px;
+ }
+ .patternButtonFontSelectorProportional {
+ background-position:0 0;
+ }
+ .patternButtonFontSelectorMonospace {
+ background-position:0 -16px;
+ }
+ .patternButtonEnlarge,
+ .patternButtonShrink {
+ background-image:url(button_arrow.gif);
+ width:16px;
+ height:16px;
+ }
+ .patternButtonEnlarge {
+ background-position:0 0;
+ }
+ .patternButtonEnlarge:hover {
+ background-position:0 -42px;
+ }
+ .patternButtonEnlarge:active {
+ background-position:0 -84px;
+ }
+ .patternButtonShrink {
+ background-position:16px 0;
+ }
+ .patternButtonShrink:hover {
+ background-position:16px -42px;
+ }
+ .patternButtonShrink:active {
+ background-position:16px -84px;
+ }
+ .twikiBroadcastMessage,
+ .twikiNotification {
+ background-image:url(background_alert.gif);
background-repeat:repeat-x;
}
- /* commong settings */
+ /* common settings */
.patternLeftBarPersonal li,
- .twikiHierarchicalNavigation .twikiChildTopics li,
- .twikiHierarchicalNavigation .twikiParentTopic li,
li.patternLogOut,
li.patternLogIn {
padding-left:13px;
- background-position:0 .25em;
+ background-position:0 .4em;
background-repeat:no-repeat;
}
- .patternLeftBarPersonal li,
- .twikiHierarchicalNavigation .twikiChildTopics li {
- background-image:url(bullet-blue.gif);
- }
- .twikiHierarchicalNavigation .twikiParentTopic li {
- background-image:url(bullet-parent.gif);
+ .patternLeftBarPersonal li {
+ background-image:url(bullet-personal_sidebar.gif);
}
.patternLeftBarPersonal li.patternLogOut {
background-image:url(bullet-lock.gif);
PatternSkin uses 4 stylesheets:
-- [layout.css](http://www.dementia.org/twiki//view/TWiki/PatternSkin/layout.css): positioning of block elements on the page
-- [style.css](http://www.dementia.org/twiki//view/TWiki/PatternSkin/style.css): margins, paddings, borders, font sizes
-- [colors.css](http://www.dementia.org/twiki//view/TWiki/PatternSkin/colors.css): text colors, background colors, border colors
-- [print.css](http://www.dementia.org/twiki//view/TWiki/PatternSkin/print.css): optimalizations for printed page
+- [layout.css](http://www.dementia.org/twiki//view/%SYSTEMWEB%/PatternSkin/layout.css): positioning of block elements on the page
+- [style.css](http://www.dementia.org/twiki//view/%SYSTEMWEB%/PatternSkin/style.css): margins, paddings, borders, font sizes
+- [colors.css](http://www.dementia.org/twiki//view/%SYSTEMWEB%/PatternSkin/colors.css): text colors, background colors, border colors
+- [print.css](http://www.dementia.org/twiki//view/%SYSTEMWEB%/PatternSkin/print.css): optimalizations for printed page
If you want to learn how to create your own look or skin based on PatternSkin, read further in [[PatternSkin]].
- #patternMain - center area
- #patternMainContents - holder of patternTop, patternTopic, twikiForm, twikiAttachments, etc.
- #patternTopBar - top bar area
- - #patternTopBarContents - header art / logo; contains topic [[WebTopBar]]
+ - #patternTopBarContents - header art / logo; contains topic %SYSTEMWEB%.WebTopBar
- #patternBottomBar - bottom bar area
- #patternBottomBarContents - copyright
- View
- .patternContent - container around .patternTopic in `view.pattern.tmpl` only; to be able to give .twikiAttachments and .twikiForm a different appearance when they are not enclosed by it, for example the personal data form on the user pages (where the user form is positioned outside, above the topic text)
- - .patternTopBarLogo - logo position in patternTopBar (topic [[WebTopBar]])
+ - .patternTopBarLogo - logo position in patternTopBar (topic %SYSTEMWEB%.WebTopBar)
- .patternTopBarOverlay - striped white image background
- .patternTopic - TWiki topic text
- .patternTop - area at top of topic text, with patternHomePath, revision and action buttons
- .patternMoved - topic moved info (only visible when the topic has changed name or web)
- .patternWebIndicator - colored block at the top of the left bar to indicate the current web
- .patternFormHolder - container around form to manage the size of form elements
- - .patternLeftBarPersonal - block of personal links (included topic %MAINWEB%.%USERNAME%LeftBar)
+ - .patternLeftBarPersonal - block of personal links (included topic %USERSWEB%.%USERNAME%LeftBar)
- .patternHomePath - breadcrumb at top
- .patternHomePathTitle - "You are here" text
- .patternRevInfo - revision info and author name
- .patternSearchResultCount - the number of results
- .patternSearched - feedback on the string used to search
-- [[WebLeftBarSearch]]
- - .patternFormButton
- - .patternChangeLanguage - change language button (deprecated)
-
**_Related Topics:_** [[TWikiSkins]], [[AdminDocumentationCategory]]
-# <a name="TWiki._PatternSkin CSS Cookbook"></a><a name=" TWiki._PatternSkin CSS Cookbook"></a> [[PatternSkin]] CSS Cookbook
+# <a name="%SYSTEMWEB%._PatternSkin CSS Coo"></a><a name=" %SYSTEMWEB%._PatternSkin CSS Co"></a> %SYSTEMWEB%.PatternSkin CSS Cookbook
**Questions and answers on how to customize the default look of TWiki for your own needs, using style sheets.** For configuring page elements, see [[PatternSkinCustomization]].
## <a name="First Read: How to modify _Patte"></a> First Read: How to modify PatternSkin styles
-PatternSkin uses 3 style sheets (attached to [[PatternSkin]]):
+PatternSkin uses 3 style sheets (attached to %SYSTEMWEB%.PatternSkin):
-- [layout.css](http://www.dementia.org/twiki//view/TWiki/PatternSkin/layout.css) - the positioning of main page elements (blocks), widths and heights
-- [style.css](http://www.dementia.org/twiki//view/TWiki/PatternSkin/style.css) - fonts, sizes, margins and paddings
-- [colors.css](http://www.dementia.org/twiki//view/TWiki/PatternSkin/colors.css) - border colors, text colors and background colors
+- [layout.css](http://www.dementia.org/twiki//view/%SYSTEMWEB%/PatternSkin/layout.css) - the positioning of main page elements (blocks), widths and heights
+- [style.css](http://www.dementia.org/twiki//view/%SYSTEMWEB%/PatternSkin/style.css) - fonts, sizes, margins and paddings
+- [colors.css](http://www.dementia.org/twiki//view/%SYSTEMWEB%/PatternSkin/colors.css) - border colors, text colors and background colors
When customizing your TWiki installation, you can either choose to completely rewrite all css styles, or to selectively override some styles. The latter option is by far less time consuming, but all depends on your graphical wishes.
- Create a new topic that will contain your new CSS files
- Attach 3 new style sheets to the topic
-- Point the CSS variables in [[TWiki.TWikiPreferences|TWiki/TWikiPreferences]] to your new files:
+- Point the CSS variables in [[%SYSTEMWEB%.TWikiPreferences|SYSTEMWEB/TWikiPreferences]] to your new files:
- * Set TWIKILAYOUTURL = %PUBURLPATH%/%TWIKIWEB%/YourNewTopic/layout.css
- * Set TWIKISTYLEURL = %PUBURLPATH%/%TWIKIWEB%/YourNewTopic/style.css
- * Set TWIKICOLORSURL = %PUBURLPATH%/%TWIKIWEB%/YourNewTopic/colors.css
+ * Set TWIKILAYOUTURL = %PUBURLPATH%/%SYSTEMWEB%/YourNewTopic/layout.css
+ * Set TWIKISTYLEURL = %PUBURLPATH%/%SYSTEMWEB%/YourNewTopic/style.css
+ * Set TWIKICOLORSURL = %PUBURLPATH%/%SYSTEMWEB%/YourNewTopic/colors.css
### <a name="When you need to make small adju"></a> When you need to make small adjustments: Adding to existing CSS
- Create a new topic that will contain your new CSS files
- Attach 1, 2 or 3 new style sheets to the topic, dependent on your CSS setup (if you don't change much, you might as well put everything in one CSS file, layout, margins and colors)
-- Point the CSS variables in [[TWiki.TWikiPreferences|TWiki/TWikiPreferences]] to your new files (below the `TWIKIXXXURL` variables):
+- Point the CSS variables in [[%SYSTEMWEB%.TWikiPreferences|SYSTEMWEB/TWikiPreferences]] to your new files (below the `TWIKIXXXURL` variables):
- * Set USERLAYOUTURL = %PUBURLPATH%/%TWIKIWEB%/YourNewTopic/layout.css
- * Set USERSTYLEURL = %PUBURLPATH%/%TWIKIWEB%/YourNewTopic/style.css
- * Set USERCOLORSURL = %PUBURLPATH%/%TWIKIWEB%/YourNewTopic/colors.css
+ * Set USERLAYOUTURL = %PUBURLPATH%/%SYSTEMWEB%/YourNewTopic/layout.css
+ * Set USERSTYLEURL = %PUBURLPATH%/%SYSTEMWEB%/YourNewTopic/style.css
+ * Set USERCOLORSURL = %PUBURLPATH%/%SYSTEMWEB%/YourNewTopic/colors.css
- If you use only little CSS and you've only attached one file, write:
- * Set USERSTYLEURL = %PUBURLPATH%/%TWIKIWEB%/YourNewTopic/style.css
+ * Set USERSTYLEURL = %PUBURLPATH%/%SYSTEMWEB%/YourNewTopic/style.css
-Instead of setting these variables in [[TWiki.TWikiPreferences|TWiki/TWikiPreferences]], you can set these in your home topic, or in any other topic. Setting style URL variables in:
+Instead of setting these variables in [[%SYSTEMWEB%.TWikiPreferences|SYSTEMWEB/TWikiPreferences]], you can set these in your home topic, or in any other topic. Setting style URL variables in:
-- [[TWiki.TWikiPreferences|TWiki/TWikiPreferences]]: the style is visible for all users, site-wide
+- [[%SYSTEMWEB%.TWikiPreferences|SYSTEMWEB/TWikiPreferences]]: the style is visible for all users, site-wide
- [[WebPreferences]]: the style is visible for all users in one web
- Home topic: the style is visible for that one user when viewing the site
- Some other topic: the style is only visible in that one topic
## <a name="Style sheet documentation"></a> Style sheet documentation
-See [[PatternSkinCss]] for documentation of PatternSkin CSS classes
+See %SYSTEMWEB%.PatternSkinCss for documentation of PatternSkin CSS classes
<div> This line loads the extra style definition: <pre>
* Set USERSTYLEURL = %ATTACHURL%/centerpage.css
-</pre> You can write this line in [[TWiki/TWikiPreferences]], in [[Main/WebPreferences]], in your user topic or on a single page. </div>
+</pre> You can write this line in %SYSTEMWEB%.TWikiPreferences, in [[Main/WebPreferences]], in your user topic or on a single page. </div>
<div> This line loads the extra style definition: <pre>
* Set USERSTYLEURL = %ATTACHURL%/centerpageborder.css
-</pre> You can write this line in [[TWiki/TWikiPreferences]], in [[Main/WebPreferences]], in your user topic or on a single page. </div>
+</pre> You can write this line in %SYSTEMWEB%.TWikiPreferences, in [[Main/WebPreferences]], in your user topic or on a single page. </div>
Add the dynamic variable link to the logo image to the topic text:
background-repeat:repeat-x;
}
#patternPageShadow {
- background-image:url("%PUBURLPATH%/%TWIKIWEB%/PatternSkin/striped_pageshadow.gif");
+ background-image:url("%PUBURLPATH%/%SYSTEMWEB%/PatternSkin/striped_pageshadow.gif");
}
</style>
<div><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> If you don't write this overloading style in a template and use an external <code>.css</code> file, you need to set the image to the absolute url: <pre>
<div> This line loads the extra style definition: <pre>
* Set USERSTYLEURL = %ATTACHURL%/edittable.css
-</pre> You can write this line in [[TWiki/TWikiPreferences]], in [[Main/WebPreferences]], in your user topic or on a single page. </div>
+</pre> You can write this line in %SYSTEMWEB%.TWikiPreferences, in [[Main/WebPreferences]], in your user topic or on a single page. </div>
<div> This line loads the extra style definition: <pre>
* Set USERSTYLEURL = %ATTACHURL%/fonts.css
-</pre> You can write this line in [[TWiki/TWikiPreferences]], in [[Main/WebPreferences]], in your user topic or on a single page. </div>
+</pre> You can write this line in %SYSTEMWEB%.TWikiPreferences, in [[Main/WebPreferences]], in your user topic or on a single page. </div>
<div> This line loads the extra style definition: <pre>
* Set USERSTYLEURL = %ATTACHURL%/hideleftbar.css
-</pre> You can write this line in [[TWiki/TWikiPreferences]], in [[Main/WebPreferences]], in your user topic, or on a single page. </div>
+</pre> You can write this line in %SYSTEMWEB%.TWikiPreferences, in [[Main/WebPreferences]], in your user topic, or on a single page. </div>
<div> This line loads the extra style definition: <pre>
* Set USERSTYLEURL=%ATTACHURL%/notopbar.css
-</pre> You can write this line in [[TWiki/TWikiPreferences]], in [[Main/WebPreferences]], in your user topic or on a single page. </div>
+</pre> You can write this line in %SYSTEMWEB%.TWikiPreferences, in [[Main/WebPreferences]], in your user topic or on a single page. </div>
Add the dynamic variable link to the logo image to the topic text:
-# <a name="TWiki._PatternSkin Customization"></a><a name=" TWiki._PatternSkin Customizatio"></a> [[PatternSkin]] Customization
+# <a name="%SYSTEMWEB%._PatternSkin Customi"></a><a name=" %SYSTEMWEB%._PatternSkin Custom"></a> %SYSTEMWEB%.PatternSkin Customization
**Questions and answers on configuring page elements.** For styling your TWiki, see [[PatternSkinCssCookbook]].
<div>
<ul>
- <li><a href="#First Read: How to modify _Patt"> First Read: How to modify PatternSkin templates</a></li>
+ <li><a href="#First Read: How to modify _Patt"> First Read: How to modify PatternSkin templates</a><ul>
+ <li><a href="#The template approach"> The template approach</a></li>
+ <li><a href="#The topic template approach (usi"> The topic template approach (using VIEW_TEMPLATE)</a></li>
+ </ul>
+ </li>
+ <li><a href="#Reference: pattern skin template"> Reference: pattern skin template INCLUDE tree</a></li>
<li><a href="#Logo"> Logo</a><ul>
<li><a href="#How can I change the web logo?"> How can I change the web logo?</a></li>
<li><a href="#How do I set a site-wide logo?"> How do I set a site-wide logo?</a></li>
</ul>
</li>
<li><a href="#Top bar"> Top bar</a><ul>
+ <li><a href="#The search box won't find topics"> The search box won't find topics in other webs</a></li>
+ <li><a href="#I want to change the height of t"> I want to change the height of the top bar</a></li>
<li><a href="#I want to set or change the top"> I want to set or change the top background image</a></li>
<li><a href="#I want to have the web color in"> I want to have the web color in the top bar</a></li>
<li><a href="#I want to remove the Jump and Se"> I want to remove the Jump and Search boxes from the top bar </a></li>
</li>
<li><a href="#Left bar"> Left bar</a><ul>
<li><a href="#I want to hide the left bar"> I want to hide the left bar</a></li>
+ <li><a href="#I want to make the left bar wide"> I want to make the left bar wider</a></li>
</ul>
</li>
<li><a href="#Other page parts"> Other page parts</a><ul>
<li><a href="#I want to hide the edit buttons"> I want to hide the edit buttons from certain users</a></li>
<li><a href="#I want to remove the History but"> I want to remove the History button from the bottom</a></li>
<li><a href="#I want to insert text outside of"> I want to insert text outside of the topic content</a></li>
+ <li><a href="#I want to place the form at the"> I want to place the form at the top</a></li>
+ <li><a href="#I only want to show the WYSIWYG"> I only want to show the WYSIWYG button on explicit pages</a></li>
</ul>
</li>
</ul>
## <a name="First Read: How to modify _Patte"></a> First Read: How to modify PatternSkin templates
-If you need to change any of the elements that are visible on the common 'view' pages, you need to change the 'view' _template_: `/templates/view.pattern.tmpl`. The quickest way would be to simply change the text in the template. A safer way - strongly recommended, because it will survive a TWiki update - is to create your own custom skin. That may sound like an awful lot of work, but in reality a skin may be as much as 1 file that consists of only a few lines of code.
+Everything you see on the common 'view' page is written by the `view` template. For pattern skin this file is `/templates/view.pattern.tmpl`.
+
+We describe two approaches to override this template:
+
+1. By creating a custom skin file in the `templates` directory
+2. By creating a custom topic template
+
+Which approach is best?
+
+- If you want to change the appearance for a lot of pages or even site-wide, the template approach is the easiest.
+- If you want to change the appearance of a single topic, or a set of topics, use a topic template.
+
+### <a name="The template approach"></a> The template approach
+
+To change templates you will need shell access. If you don't have this read on below in [[The topic template approach|Main/WebHome#TopicTemplates]].
+
+The quickest way to change the view template would be to simply change the text in the template. A safer way - strongly recommended, because it will survive a TWiki update - is to create your own custom skin. That may sound like an awful lot of work, but in reality a skin may be as much as 1 file that consists of only a few lines of code.
**Example** %BR% Let's say you want to simplify the bottom toolbar and remove all links except for "More topic actions". You would need to target `%TMPL:DEF{"topicactionbuttons"}%`, which is located in `view.pattern.tmpl`.
1. Think up a name for your skin. Let us use `myskin` for now.
2. Create a new (empty) view template file in `/templates` called `view.myskin.tmpl`.
-3. In `view.myskin.tmpl` you write: %BR% `%TMPL:INCLUDE{"view"}%` %BR% `%TMPL:DEF{"topicactionbuttons"}%%TMPL:P{"activatable_more"}%%TMPL:END%`
-4. Now the skin is set. For testing, view any topic and append to the topic name: `?cover=myskin`. You should see an effect now.
+3. In `view.myskin.tmpl` you write:
+> %TMPL:INCLUDE{"view"}%
+> %TMPL:DEF{"topicactionbuttons"}%%TMPL:P{"activatable_more"}%%TMPL:END%
+4. For testing, view any topic and append to the topic name: `?cover=myskin`. You should see an effect now.
5. To make the changes visible on all pages, go to [[Main.TWikiPreferences|Main/TWikiPreferences]] (to keep [[TWikiPreferences]] intact) and write:
> * Set COVER = myskin
>
> * Set SKIN = myskin,pattern
+Test by appending `?cover=myskin` to the url.
+
+<a name="TopicTemplates"></a>
+
+### <a name="The topic template approach (usi"></a> The topic template approach (using VIEW\_TEMPLATE)
+
+Template overrides can be written in a topic, a so-called _topic template_. Topic template names end with `Template`, for instance `BlogPostViewTemplate`.
+
+Call this template by setting `VIEW_TEMPLATE`:
+
+> * Set VIEW_TEMPLATE = BlogPostView
+
+- Note that you don't use the `Template` extension now
+- You can make this setting hidden by writing this in the Settings screen: go to More and then Topic Settings
+- On topic creation you can set the topic template by passing `templatetopic`:
+ <input type="hidden" name="templatetopic" value="BlogPostViewTemplate" />
+
+We can use the same example as above. In a topic write:
+
+> %TMPL:INCLUDE{"view"}%
+> %TMPL:DEF{"topicactionbuttons"}%%TMPL:P{"activatable_more"}%%TMPL:END%
+
+You can also test this by appending `?template=PersonalInfoView` to the url.
+
+## <a name="Reference: pattern skin template"></a> Reference: pattern skin template INCLUDE tree
+
+ view
+ page
+ constants
+ javascript
+ styles
+ stylesdynamic
+ body
+ viewtopbar
+ %SYSTEMWEB%.WebTopBar
+ viewtoolbar
+ viewleftbar
+ %WEB%.WebLeftBar
+ viewtopicactionbuttons
+ viewbottombar
+ %SYSTEMWEB%.WebBottomBar
+
## <a name="Logo"></a> Logo
### <a name="How can I change the web logo?"></a> How can I change the web logo?
**Using logo.gif:**
-> - Create a new image named `logo.gif` and attach it to the web's [[WebPreferences]] topic. [[PatternSkin]]'s stylesheet assumes the logo is 40px high. More about that later.
+> - Create a new image named `logo.gif` and attach it to the web's [[WebPreferences]] topic. %SYSTEMWEB%.PatternSkin's stylesheet assumes the logo is 40px high. More about that later.
> - You can also upload the image with FTP to `/pub/YourWeb/WebPreferences/`.
> - Copy the above instructions ("Redefine your custom variables") and insert your logo name.
### <a name="My logo does not fit the top bar"></a> My logo does not fit the top bar
+See [[I want to change the height of the top bar|Main/WebHome#TopBarChangeHeight]]
+
+### <a name="I want to change the white space"></a> I want to change the white space above and below the logo
+
+Change the table style in topic %SYSTEMWEB%.WebTopBar. The default top padding is 11px.
+
+## <a name="Top bar"></a> Top bar
+
+### <a name="The search box won't find topics"></a> The search box won't find topics in other webs
+
+In [[WebTopBar]] you can find the line:
+
+ <input type="hidden" name="web" value="%BASEWEB%" />
+
+To search all webs, write:
+
+> <input type="hidden" name="web" value="all" />
+
+To search a couple of webs, for instance the webs Main and TWiki, write:
+
+> <input type="hidden" name="web" value="Main,TWiki" />
+
+See also: [[Search variable|TWiki/VarSEARCH]]
+
+<a name="TopBarChangeHeight"></a>
+
+### <a name="I want to change the height of t"></a> I want to change the height of the top bar
+
The top bar is 64 pixels high by default.
-**Using templates:**
+**Using templates:** %BR% Using either a template or a topic template, copy this definition in your custom template:
-> Change the height of the top bar in
->
-> `templates/viewtopbar.pattern.tmpl`
->
-> :
->
-> %TMPL:DEF{"topbardimensions"}%
+> %TMPL:DEF{"topbardimensions"}%
> #patternTopBar,
> #patternClearHeaderCenter,
> #patternClearHeaderLeft,
> #patternClearHeaderRight,
> #patternTopBarContentsOuter {
-> height:64px; /* top bar height; make room for header columns */
-> overflow:hidden;
+> height:64px; /* top bar height; make room for header columns */
+> overflow:hidden;
> }
> %TMPL:END%
>
-> Only change the number from 64px to another value.
+> And change the number from 64px to a different value.
**Using style sheets:**
>
> `USERLAYOUTURL`
>
-> to that topic attachment. See
->
-> [[PatternSkinCssCookbook]]
->
-> about creating custom styles.
-
-### <a name="I want to change the white space"></a> I want to change the white space above and below the logo
-
-Change the table style in topic [[WebTopBar]]. The default top padding is 11px.
-
-## <a name="Top bar"></a> Top bar
+> to that topic attachment. See %SYSTEMWEB%.PatternSkinCssCookbook about creating custom styles.
### <a name="I want to set or change the top"></a><a name="I want to set or change the top "></a> I want to set or change the top background image
Redefine your custom variables in [[Main.TWikiPreferences|Main/TWikiPreferences]] (to keep [[TWikiPreferences]] intact):
-> * Set WEBHEADERART = %PUBURLPATH%/%TWIKIWEB%/PatternSkin/TWiki_header.gif
+> * Set WEBHEADERART = %PUBURLPATH%/%SYSTEMWEB%/PatternSkin/TWiki_header.gif
> * Set WEBHEADERBGCOLOR = somehexcolor (no quotes, for example: #ffffff)
You can also set `WEBHEADERART` per web, by defining the variable in the Web's WebPreferences.
If you have localization enabled, you will also see a language dropdown box at the far right.
-You can remove these items from [[WebTopBar]].
+You can remove these items from %SYSTEMWEB%.WebTopBar.
### <a name="I want to hide the top bar"></a> I want to hide the top bar
Each included template draws a part of the screen.%BR% Omit `%TMPL:INCLUDE{"viewtopbar"}%` to hide the top bar.
-Another approach is to clear the contents of module `topbar`; for example in `view.myskin.tmpl`:
+Another approach is to clear the contents of module `topbar`. Using either a template or a topic template, write in your custom template:
> %TMPL:INCLUDE{"view"}%
->
> %TMPL:INCLUDE{"topbar"}%%TMPL:END%
>
> and add:
> #patternClearHeaderLeft,
> #patternClearHeaderRight,
> #patternTopBarContentsOuter {
-> height:0px;
+> height:0px;
> }%TMPL:END%
-**Using style sheets:**
-
-> See
->
-> [[PatternSkinCssCookbookNoTopBar]]
->
-> .
+**Using style sheets:** %BR% See [[PatternSkinCssCookbookNoTopBar]]
## <a name="Left bar"></a> Left bar
### <a name="I want to hide the left bar"></a> I want to hide the left bar
-**Using templates:**
+**Using templates:** %BR% Omit `%TMPL:INCLUDE{"viewleftbar"}%` to hide the left bar, or in a custom template clear it using
-> Omit
->
-> `%TMPL:INCLUDE{"viewleftbar"}%`
->
-> to hide the left bar, or in a view template clear it using
->
-> `%TMPL:DEF{"viewleftbar"}%%TMPL:END%`
+> %TMPL:DEF{"viewleftbar"}%%TMPL:END%
-**Using style sheets:**
+**Using style sheets:** %BR% See [[PatternSkinCssCookbookNoLeftBar]]
-> See
->
-> [[PatternSkinCssCookbookNoLeftBar]]
+### <a name="I want to make the left bar wide"></a> I want to make the left bar wider
+
+**Using templates:** %BR%
+
+The left bar is 12 em wide by default.
+
+**Using templates:** %BR% Using either a template or a topic template, copy this definition in your custom template:
+
+> %TMPL:DEF{"leftbardimensions"}%#patternOuter {
+> margin-left:12em;
+> }
+> #patternLeftBar {
+> width:12em;
+> margin-left:-12em;
+> }%TMPL:END%
>
-> .
+> And change the number from 12em to a different value (3 occurrences).
## <a name="Other page parts"></a> Other page parts
### <a name="I want to hide the edit buttons"></a><a name="I want to hide the edit buttons "></a> I want to hide the edit buttons from certain users
-It may defy the wiki-ness of your TWiki installation, but in certain circumstances it could be useful to hide the edit buttons from users that are not logged in, for instance for customers.
+It may defy the wiki-ness of your TWiki installation, but in certain circumstances it could be useful to hide the edit buttons from users that are not logged in, for instance for clients that have gotten viewing rights only.
-Create in the template directory the file `view.customer.tmpl`. 'Empty' `topicaction` and `toolbar` by writing in the template:
+Using either a template or a topic template, 'empty' `topicaction` and `toolbar` by writing:
> %TMPL:INCLUDE{"view"}%
> %TMPL:DEF{"topicaction"}%%TMPL:END%
> %TMPL:DEF{"toolbar"}%%TMPL:END%
-In [[TWikiGuest]], set the cover to
+In the user page of %USERSWEB%.TWikiGuest, set the cover to
> * Set COVER = customer
-By default this topic is editable only by TWikiAdminGroup members.
+By default this topic is editable only by TWiki admins.
### <a name="I want to remove the History but"></a> I want to remove the History button from the bottom
-All action buttons are defined in `viewtopicactionbuttons.pattern.tmpl`. Remove module `revisions` from `%TMPL:DEF{"topicactionbuttons"}%`. %BR%
+All action buttons are defined in `viewtopicactionbuttons.pattern.tmpl`. The history buttons or in module `revisions`:
-> <code> %TMPL:DEF\{"topicactionbuttons"\}%%TMPL:P\{"activatable\_raw\_edit"\}%%TMPL:P\{"sep"\}% %TMPL:P\{context="WysiwygPluginEnabled" then="activatable\_edit\_wysiwyg"\}%%TMPL:P\{context="WysiwygPluginEnabled" then="sep"\}% %TMPL:P\{"activatable\_attach"\}%%TMPL:P\{"sep"\}% %TMPL:P\{"printable"\}%%TMPL:P\{"sep"\}% %TMPL:P\{"raw"\}%%TMPL:P\{"sep"\}% %TMPL:P\{"backlinks"\}%%TMPL:P\{"sep"\}% <span><font><s>%TMPL:P\{"revisions"\}%%TMPL:P\{"sep"\}%</s></font></span> %TMPL:P\{"activatable\_more"\}%%TMPL:END% </code>
+> <code> %TMPL:DEF\{"topicactionbuttons"\}%%TMPL:P\{"activatable\_raw\_edit"\}%%TMPL:P\{"sep"\}% %TMPL:P\{context="WysiwygPluginEnabled" then="activatable\_edit\_wysiwyg"\}% %TMPL:P\{context="WysiwygPluginEnabled" then="sep"\}% %TMPL:P\{"activatable\_attach"\}%%TMPL:P\{"sep"\}% %TMPL:P\{"printable"\}%%TMPL:P\{"sep"\}% %TMPL:P\{"raw"\}%%TMPL:P\{"sep"\}% %TMPL:P\{"backlinks"\}%%TMPL:P\{"sep"\}% %TMPL:P\{"revisions"\}%%TMPL:P\{"sep"\}% <span><font>< HERE</font></span> %TMPL:P\{"activatable\_more"\}%%TMPL:END% </code>
-In your `view.myskin.tmpl` file (see above) you write:
+If we emptied module `revisions` we would end up with 2 separators, so we need to remove the line altogether. We do this by copying the block and omitting the line. %BR% Using either a template or a topic template, to remove the history buttons write in your custom template:
> %TMPL:INCLUDE{"view"}%
>
-> %TMPL:DEF{"topicactionbuttons"}% |
+> %TMPL:DEF{"topicactionbuttons"}%%TMPL:P{"activatable_raw_edit"}%%TMPL:P{"sep"}%
> %TMPL:P{context="WysiwygPluginEnabled" then="activatable_edit_wysiwyg"}%
-> %TMPL:P{"activatable_attach"}% |
-> %TMPL:P{"printable"}% |
-> %TMPL:P{"raw"}% |
-> %TMPL:P{"backlinks"}% |
+> %TMPL:P{context="WysiwygPluginEnabled" then="sep"}%
+> %TMPL:P{"activatable_attach"}%%TMPL:P{"sep"}%
+> %TMPL:P{"printable"}%%TMPL:P{"sep"}%
+> %TMPL:P{"raw"}%%TMPL:P{"sep"}%
+> %TMPL:P{"backlinks"}%%TMPL:P{"sep"}%
> %TMPL:P{"activatable_more"}%%TMPL:END%
>
> Remove all newlines if you copy-paste above text.
-Test by appending `?cover=myskin` to any topic.
-
### <a name="I want to insert text outside of"></a> I want to insert text outside of the topic content
PatternSkin has 2 'buckets' to write additional content to: `beforetextcontents` and `aftertextcontents`, both defined in `view.pattern.tmpl`. These containers can contain text or html and are placed directly before and after the topic text.
- `beforetextcontents` - wrapped in `div` of class `twikiBeforeText`
- `aftertextcontents` - wrapped in `div` of class `twikiAfterText`
-To put contents before the main text, use the custom skin approach as described above.%BR% So our `view.myskin.tmpl` file contains:
+To put contents **before** the main text, use the custom skin approach as described above.%BR% So our custom template contains:
> %TMPL:INCLUDE{"view"}%
->
> %TMPL:DEF{"beforetextcontents"}%This is the text before%TMPL:END%
-Test by appending `?cover=myskin` to any topic.
-
-Use the same procedure for contents to be put after the topic text:
+Use the same procedure for contents to be put **after** the topic text:
> %TMPL:INCLUDE{"view"}%
->
> %TMPL:DEF{"aftertextcontents"}%This is the text after%TMPL:END%
+
+### <a name="I want to place the form at the"></a><a name="I want to place the form at the "></a> I want to place the form at the top
+
+Pattern skin has 2 buckets for the form: `formattop` (form-at-the-top) and `formatbottom` (form-at-the-bottom):
+
+> %TMPL:DEF{"formattop"}%%TMPL:END%
+> %TMPL:DEF{"formatbottom"}%%TMPL:P{"form"}%%TMPL:END%
+
+You simply swap the bucket contents. Using either a template or a topic template, write in your custom template:
+
+> %TMPL:INCLUDE{"view"}%
+> %TMPL:DEF{"formattop"}%%TMPL:P{"form"}%%TMPL:END%
+> %TMPL:DEF{"formatbottom"}%%TMPL:END%
+
+### <a name="I only want to show the WYSIWYG"></a><a name="I only want to show the WYSIWYG "></a> I only want to show the WYSIWYG button on explicit pages
+
+In [[Main.TWikiPreferences|Main/TWikiPreferences]], set `COMPOSER` to a blank value:
+
+> * Set COMPOSER =
+
+In the topic, set the `COMPOSER` variable to `kupu`:
+
+> * Set COMPOSER = kupu
-<div><strong>NOTE:</strong> Edit and Attach will be disabled today between 05:00 PM and 06:00 PM PDT (00:00 to 01:00 GMT) for a scheduled TWiki maintenance.</div>
-
# <a name="h1 headerwith link"></a><a name=" h1 headerwith link"></a> h1 header [[with link|Main/TOPIC]]
**Intro text.** Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text.
<ul>
<li><a href="#h2 headerwith link"> h2 header with link</a></li>
<li><a href="#h2 headerwith link - no newline"> h2 header with link - no newline</a><ul>
- <li><a href="#h3 headerwith link"> h3 header with link</a><ul>
+ <li><a href="#h3 headerwith link and a very lo"> h3 header with link and a very long header text a very long header text a very long header text a very long header text a very long header text a very long header text a very long header text</a><ul>
<li><a href="#h4 headerwith link"> h4 header with link</a><ul>
<li><a href="#h5 headerwith link"> h5 header with link</a><ul>
<li><a href="#h6 headerwith link"> h6 header with link</a></li>
**Intro text.** Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text.
-### <a name="h3 headerwith link"></a> h3 header [[with link|Main/TOPIC]]
+### <a name="h3 headerwith link and a very lo"></a> h3 header [[with link|Main/TOPIC]] and a very long header text a very long header text a very long header text a very long header text a very long header text a very long header text a very long header text
**Intro text.** Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text. Normal text.
Bullet list:
- Item A
-- Item B
+- Item B a very long list text a very long list text a very long list text a very long list text a very long list text a very long list text a very long list text a very long list text a very long list text
- Item B.1
- Item B.2
- Item C
Numbered list:
1. Item 1
-2. Item 2
+2. Item 2 a very long list text a very long list text a very long list text a very long list text a very long list text a very long list text a very long list text a very long list text a very long list text
1. Item 2.1
2. Item 2.2
3. Item 3
<div>
<ul>
- <li><strong>Help:</strong> Please see <a href="" onclick="return launchWindow('TWiki','FileAttachment')" rel="nofollow" target="TWikiVariables">FileAttachment</a> for more information about attaching files. </li>
+ <li><strong>Help:</strong> Please see [[%SYSTEMWEB%/FileAttachment]] for more information about attaching files. </li>
<li><strong>Bug:</strong> Internet Explorer 4.0 or earlier: If you get an "Internal Server Error" message when you upload a file, you need to try again. It should work the second time. </li>
</ul>
</div>
--- /dev/null
+# <a name="PatternSkin Graphics"></a><a name=" _PatternSkin Graphics"></a> PatternSkin Graphics
+
+This topic contains original Photoshop files of the graphics used in [[PatternSkin]].
--- /dev/null
+%TMPL:INCLUDE\{"WebCreateNewTopic"\}%
+
+%TMPL:DEF\{"script:topictemplate"\}%%TMPL:END%
+
+%TMPL:DEF\{"formstartstep"\}%
+
+<div>%TMPL:END% <p> %TMPL:DEF{"formendstep"}%</p>
+</div>
+
+%TMPL:END%
+
+%TMPL:DEF\{"titlestep"\}%
+
+<div>
+ <h2><a name="Create New Topic in Main Web"></a> Create New Topic in Main Web </h2>
+</div>
+
+%TMPL:END%
+
+%TMPL:DEF\{"topicnamestep"\}%
+
+<div>
+ <h3><a name="Topic name:"></a> Topic name: </h3>
+ <p><span id="webTopicCreatorFeedback"></span></p>
+</div>
+
+%TMPL:END%
+
+%TMPL:DEF\{"topicparentstep"\}%
+
+<div>
+ <h3><a name="Topic parent:"></a> Topic parent: </h3>
+ <p>
+ </p>
+ <p>
+ </p>
+</div>
+
+%TMPL:END%
+
+%TMPL:DEF\{"topictemplatestep"\}%
+
+<div>
+ <h3><a name="Use template:"></a> Use template: </h3>
+ <p>
+ </p>
+ <p>
+ </p>
+</div>
+
+%TMPL:END%
+
+%TMPL:DEF\{"submitstep"\}%
+
+<div>
+ <p>
+ </p>
+ <p>
+ </p>
+</div>
+
+%TMPL:END%
# <a name="Plain Skin"></a> Plain Skin
-The plain skin is used to get the rendered topic text without any page decoration such as side, top or bottom bars. For example, TWiki uses this skin for pop-up help windows. It also can be used to display topic content inside an [IFRAME](http://www.htmlhelp.com/reference/html40/special/iframe.html).
+The plain skin is used to get the rendered topic text without any page decoration such as side, top or bottom bars. The text is shown without any markup styles. It can be used to display topic content inside an [IFRAME](http://www.htmlhelp.com/reference/html40/special/iframe.html).
This skin is part of every TWiki distribution.
+This skin has been used to show topics in a pop-up window; this has been replaced with template `viewplain`.
+
## <a name="Skin Info"></a> Skin Info
<table border="1" cellpadding="0" cellspacing="0">
</tr>
</table>
-**_Note:_** The Description, Screenshot and Base Name rows are needed by the [[TWikiSkinBrowser]]
+**_Note:_** The Description, Screenshot and Base Name rows are needed by the %SYSTEMWEB%.TWikiSkinBrowser
-**_Related topic:_** [[TWikiSkins]], [[TWikiSkinBrowser]], [[UserDocumentationCategory]], [[AdminDocumentationCategory]]
+**_Related topic:_** %SYSTEMWEB%.TWikiSkins, %SYSTEMWEB%.TWikiSkinBrowser, %SYSTEMWEB%.UserDocumentationCategory, %SYSTEMWEB%.AdminDocumentationCategory
-<form action="http://www.dementia.org/twiki/viewauth/Main/WebHome" enctype="multipart/form-data" method="post" name="editpreferences">
- <p>
- </p>
- <h1><a name="%TOPIC%"></a><a name=" %TOPIC%"></a> %TOPIC% </h1>
- <p> Allows editing of preferences using fields predefined in a [[TWiki/TWikiForms]]. However, the edit fields are inlined in the text, similar to how tables are edited in TWiki:Plugins/EditTablePlugin. </p>
- <p>
- </p>
- <div>
- <ul>
- <li><a href="#Syntax Rules"> Syntax Rules</a></li>
- <li><a href="#Examples"> Examples</a></li>
- <li><a href="#Plugin Settings"> Plugin Settings</a></li>
- <li><a href="#Plugin Installation Instructions"> Plugin Installation Instructions</a></li>
- <li><a href="#Plugin Info"> Plugin Info</a></li>
- </ul>
- </div>
- <p> Insert the <code>%EDITPREFERENCES%</code> variable (see below) anywhere in your topic. It will be replaced by a button that allows editing each preference in its predefined input format (or a text box, when no format is defined for this preference). </p>
- <p> In edit mode, the edit button is replaced by save and cancel buttons, with their obvious meanings. </p>
- <p>
- </p>
- <h2><a name="Syntax Rules"></a> Syntax Rules </h2>
- <p>
- </p>
+# <a name="%TOPIC%"></a><a name=" %TOPIC%"></a> %TOPIC%
+
+Allows editing of preferences using fields predefined in a %SYSTEMWEB%.TWikiForms. However, the edit fields are inlined in the text, similar to how tables are edited in TWiki:Plugins/EditTablePlugin.
+
+<div>
<ul>
- <li><code>%EDITPREFERENCES{ "</code> <em>topic</em> <code>" }%</code><ul>
- <li><em>topic</em> references a [[TWiki/TWikiForms]] defining the format of the edit fields for preferences. It may be prefixed by a web. </li>
- <li> If a preference setting is not mentioned in the form referenced by <em>topic</em>, a text input box of the specified length is provided. </li>
- <li> Otherwise, the input can be through textareas, select, radio, checkbox, date, or text, as provided by [[TWiki/TWikiForms]]. </li>
- </ul>
- </li>
+ <li><a href="#Syntax Rules"> Syntax Rules</a></li>
+ <li><a href="#Examples"> Examples</a></li>
+ <li><a href="#Plugin Settings"> Plugin Settings</a></li>
+ <li><a href="#Plugin Installation Instructions"> Plugin Installation Instructions</a></li>
+ <li><a href="#Plugin Info"> Plugin Info</a></li>
</ul>
- <p>
- </p>
- <h2><a name="Examples"></a> Examples </h2>
- <p>
- </p>
- <ul>
- <li><code>%EDITPREFERENCES{ "%TWIKIWEB%.TWikiPreferencesForm" }%</code></li>
- </ul>
- <p>
- </p>
- <h2><a name="Plugin Settings"></a> Plugin Settings </h2>
- <p> Plugin settings are stored as preferences variables. To reference a plugin setting write <code><b>%<plugin>_<setting>%</b></code>, i.e. <code><b>%PREFERENCESPLUGIN_SHORTDESCRIPTION%</b></code></p>
- <p>
- </p>
- <ul>
- <li> One line description, is shown in the [[TWiki/TextFormattingRules]] topic: <ul>
- <li> Set SHORTDESCRIPTION = Allows editing of preferences using fields predefined in a form </li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <h2><a name="Plugin Installation Instructions"></a> Plugin Installation Instructions </h2>
- <p><strong><em>Note:</em></strong> You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running. </p>
- <p>
- </p>
- <ul>
- <li> Download the ZIP file from the Plugin web (see below) </li>
- <li> Unzip <code><b>%TOPIC%.zip</b></code> in your twiki installation directory. Content: <table border="1" cellpadding="0" cellspacing="0">
- <tr>
- <th bgcolor="#99CCCC"><strong> File: </strong></th>
- <th bgcolor="#99CCCC"><strong> Description: </strong></th>
- </tr>
- <tr>
- <td><code><b>data/TWiki/%TOPIC%.txt</b></code></td>
- <td> Plugin topic </td>
- </tr>
- <tr>
- <td><code><b>data/TWiki/%TOPIC%.txt,v</b></code></td>
- <td> Plugin topic repository </td>
- </tr>
- <tr>
- <td><code><b>lib/TWiki/Plugins/%TOPIC%.pm</b></code></td>
- <td> Plugin Perl module </td>
- </tr>
- <tr>
- <td><code><b>data/TWiki/TWikiPreferencesForm.txt</b></code></td>
- <td> Example form </td>
- </tr>
- </table>
- </li>
- <li> (Dakar) Visit <code>configure</code> in your TWiki installation, and enable the plugin in the {Plugins} section. </li>
- <li> If the installation was successful, an edit button should appear below: <input name="prefsaction" type="submit" value="Edit" /></li>
- </ul>
- <p>
- </p>
- <h2><a name="Plugin Info"></a> Plugin Info </h2>
- <p>
- </p>
- <table border="1" cellpadding="0" cellspacing="0">
- <tr>
- <td align="right"> Plugin Author: </td>
- <td> TWiki:Main.ThomasWeigert </td>
- </tr>
- <tr>
- <td align="right"> Plugin Version: </td>
- <td> 15 Apr 2006 </td>
- </tr>
- <tr>
- <td align="right"> Change History: </td>
- <td> </td>
- </tr>
- <tr>
- <td align="right"> 15 Apr 2006: </td>
- <td> Adding css classes to buttons. Removed debug print statement causing 500s on SunOne. Prevent extra space in settings on saves. Switched to earlier handler. Converted all SCRIPTURL to SCRIPTURLPATH, and added support. The only SCRIPTURLs should be the one in the BASE tag and those in mail notification templates. Because the forms package was throwing an exception when it failed to create a form, the edit preferences plugin was aborting the whole of the session whenever the form specified in EDITPREFERENCES didn't exist. Changed it so that the Form constructor does not throw, but returns undef on a non-existant form, and changed preferences plugin to be tolerant of missing forms (ie defaults all fields to text if the form is missing, of is a Set exists which is not in the form). </td>
- </tr>
- <tr>
- <td align="right"> 26 May 2005: </td>
- <td> Crawford Currie recoded to use code from Form.pm to render form fields. </td>
- </tr>
- <tr>
- <td align="right"> 08 May 2005: </td>
- <td> Add plugin preference to define default input length </td>
- </tr>
- <tr>
- <td align="right"> 07 May 2005: </td>
- <td> Initial version </td>
- </tr>
- <tr>
- <td align="right"> TWiki Dependency: </td>
- <td> $TWiki::Plugins::VERSION 1.026 </td>
- </tr>
- <tr>
- <td align="right"> CPAN Dependencies: </td>
- <td> none </td>
- </tr>
- <tr>
- <td align="right"> Other Dependencies: </td>
- <td> none </td>
- </tr>
- <tr>
- <td align="right"> Perl Version: </td>
- <td> 5.005 </td>
- </tr>
- <tr>
- <td align="right"> License: </td>
- <td> GPL (<a href="http://www.gnu.org/copyleft/gpl.html" target="_top">GNU General Public License</a>) </td>
- </tr>
- <tr>
- <td align="right"> TWiki:Plugins/Benchmark: </td>
- <td>[[TWiki/GoodStyle]] nn%, [[TWiki/FormattedSearch]] nn%, %TOPIC% nn% </td>
- </tr>
- <tr>
- <td align="right"> Plugin Home: </td>
- <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%</a></td>
- </tr>
- <tr>
- <td align="right"> Feedback: </td>
- <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev</a></td>
- </tr>
- <tr>
- <td align="right"> Appraisal: </td>
- <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal</a></td>
- </tr>
- </table>
- <p><strong><em>Related Topics:</em></strong> [[TWiki/TWikiPreferences]], [[TWiki/TWikiForms]]</p>
- <p> -- TWiki:Main.ThomasWeigert - 08 May 2005 </p>
- <p>
- </p>
-</form>
+</div>
+
+Insert the `%EDITPREFERENCES%` variable (see below) anywhere in your topic. It will be replaced by a button that allows editing each preference in its predefined input format (or a text box, when no format is defined for this preference).
+
+In edit mode, the edit button is replaced by Save and Cancel buttons, with their obvious meanings.
+
+## <a name="Syntax Rules"></a> Syntax Rules
+
+- `%EDITPREFERENCES{ "` _topic_ `" }%`
+ - _topic_ references a [[TWikiForm|SYSTEMWEB/TWikiForms]] defining the format of the edit fields for preferences. It may be prefixed by a web.
+ - If a preference setting is not mentioned in the form referenced by _topic_, a text input box of the specified length is provided.
+ - Otherwise, the input can be through textareas, select, radio, checkbox, date, or text, as provided by %SYSTEMWEB%.TWikiForms.
+- `%EDITPREFERENCES%`
+ - Edit existing preferences in the topic using a simple text field.
+
+## <a name="Examples"></a> Examples
+
+- `%EDITPREFERENCES%`
+- `%EDITPREFERENCES{ "%SYSTEMWEB%.TWikiPreferencesForm" }%`
+
+## <a name="Plugin Settings"></a> Plugin Settings
+
+- One line description, shown in the %SYSTEMWEB%.TextFormattingRules topic:
+ - Set SHORTDESCRIPTION = Allows editing of preferences using fields predefined in a form
+
+## <a name="Plugin Installation Instructions"></a> Plugin Installation Instructions
+
+You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.
+
+Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.
+
+- If you have TWiki 4.2 or later, you can install from the `configure` interface (Go to Plugins->Find More Extensions)
+ - See the [installation supplement](http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement) on TWiki.org for more information.
+- If you have any problems, then you can still install manually from the command-line:
+ 1. Download one of the `.zip` or `.tgz` archives
+ 2. Unpack the archive in the root directory of your TWiki installation.
+ 3. Run the installer script ( `perl <module>_installer` )
+ 4. Run `configure` and enable the module, if it is a plugin.
+ 5. Repeat for any missing dependencies.
+- If you are **still** having problems, then instead of running the installer script:
+ 1. Make sure that the file permissions allow the webserver user to access all files.
+ 2. Check in any installed files that have existing `,v` files in your existing install (take care **not** to lock the files when you check in)
+ 3. Manually edit LocalSite.cfg to set any configuration variables.
+
+<div class="twikiAlert">%X% WARNING: SYSTEMWEB is not defined in this TWiki. Please add these definitions to your [[Main/TWikiPreferences]], if they are not already there:<br /><pre> * Set SYSTEMWEB = %TWIKIWEB%<br /> * Set USERSWEB = %MAINWEB%</pre></div>
+
+- If the installation was successful, an edit button should appear below:
+
+%EDITPREFERENCES%
+
+## <a name="Plugin Info"></a> Plugin Info
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <td align="right"> Plugin Author: </td>
+ <td> TWiki:Main.ThomasWeigert </td>
+ </tr>
+ <tr>
+ <td align="right"> Plugin Version: </td>
+ <td> 15487 (22 Jan 2008) </td>
+ </tr>
+ <tr>
+ <td align="right"> Change History: </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td align="right"> 05 Nov 2007: </td>
+ <td> Kenneth Lavrsen fixed problem when settings are hidden in html comments. These settings are now ignored. </td>
+ </tr>
+ <tr>
+ <td align="right"> 23 Jun 2007: </td>
+ <td> Crawford Currie added testcases, recoded to work without a form definition, fixed for TWiki 4.2 </td>
+ </tr>
+ <tr>
+ <td align="right"> 08 Feb 2007: </td>
+ <td> Arthur Clemens added access keys for Save and Cancel, bold style for editable preference names, and a descriptive Save button label. </td>
+ </tr>
+ <tr>
+ <td align="right"> 15 Apr 2006: </td>
+ <td> Adding css classes to buttons. Removed debug print statement causing 500s on SunOne. Prevent extra space in settings on saves. Switched to earlier handler. Converted all SCRIPTURL to SCRIPTURLPATH, and added support. The only SCRIPTURLs should be the one in the BASE tag and those in mail notification templates. Because the forms package was throwing an exception when it failed to create a form, the edit preferences plugin was aborting the whole of the session whenever the form specified in EDITPREFERENCES didn't exist. Changed it so that the Form constructor does not throw, but returns undef on a non-existant form, and changed preferences plugin to be tolerant of missing forms (ie defaults all fields to text if the form is missing, of is a Set exists which is not in the form). </td>
+ </tr>
+ <tr>
+ <td align="right"> 26 May 2005: </td>
+ <td> Crawford Currie recoded to use code from Form.pm to render form fields. </td>
+ </tr>
+ <tr>
+ <td align="right"> 08 May 2005: </td>
+ <td> Add plugin preference to define default input length </td>
+ </tr>
+ <tr>
+ <td align="right"> 07 May 2005: </td>
+ <td> Initial version </td>
+ </tr>
+ <tr>
+ <td align="right"> TWiki Dependency: </td>
+ <td> $TWiki::Plugins::VERSION 1.026 </td>
+ </tr>
+ <tr>
+ <td align="right"> CPAN Dependencies: </td>
+ <td> none </td>
+ </tr>
+ <tr>
+ <td align="right"> Other Dependencies: </td>
+ <td> none </td>
+ </tr>
+ <tr>
+ <td align="right"> Perl Version: </td>
+ <td> 5.005 </td>
+ </tr>
+ <tr>
+ <td align="right"> License: </td>
+ <td> GPL (<a href="http://www.gnu.org/copyleft/gpl.html" target="_top">GNU General Public License</a>) </td>
+ </tr>
+ <tr>
+ <td align="right"> TWiki:Plugins/Benchmark: </td>
+ <td> %SYSTEMWEB%.GoodStyle nn%, %SYSTEMWEB%.FormattedSearch nn%, %TOPIC% nn% </td>
+ </tr>
+ <tr>
+ <td align="right"> Plugin Home: </td>
+ <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%</a></td>
+ </tr>
+ <tr>
+ <td align="right"> Feedback: </td>
+ <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev</a></td>
+ </tr>
+ <tr>
+ <td align="right"> Appraisal: </td>
+ <td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal</a></td>
+ </tr>
+</table>
+
+**_Related Topics:_** %SYSTEMWEB%.TWikiPreferences, %SYSTEMWEB%.TWikiForms
</tr>
</table>
-**_Note:_** The Description, Screenshot and Base Name rows are needed by the [[TWikiSkinBrowser]]
+**_Note:_** The Description, Screenshot and Base Name rows are needed by the %SYSTEMWEB%.TWikiSkinBrowser
-**_Related topic:_** [[TWikiSkins]], [[TWikiSkinBrowser]], [[UserDocumentationCategory]], [[AdminDocumentationCategory]]
+**_Related topic:_** %SYSTEMWEB%.TWikiSkins, %SYSTEMWEB%.TWikiSkinBrowser, %SYSTEMWEB%.UserDocumentationCategory, %SYSTEMWEB%.AdminDocumentationCategory
--- /dev/null
+# <a name="Query Search"></a> Query Search
+
+Query searches help you search the contents of forms attached to your topics, as well as the values of other meta-data attached to the topic. Using query searches you can search:
+
+1. The fields of forms
+2. Parent relationships
+3. File attachment information (but **not** the attached files themselves)
+
+Query searches are defined using a simple SQL-like query language. The language consists of _field specifiers_ and _constants_ joined with _operators_.
+
+<div>
+ <ul>
+ <li><a href="#Query Search"> Query Search</a><ul>
+ <li><a href="#Field specifiers"> Field specifiers</a></li>
+ <li><a href="#Constants"> Constants</a></li>
+ <li><a href="#Operators"> Operators</a></li>
+ <li><a href="#Putting it all together"> Putting it all together</a></li>
+ <li><a href="#Examples"> Examples</a><ul>
+ <li><a href="#Query examples"> Query examples</a></li>
+ <li><a href="#Search examples"> Search examples</a></li>
+ </ul>
+ </li>
+ </ul>
+ </li>
+ </ul>
+</div>
+
+## <a name="Field specifiers"></a> Field specifiers
+
+You use field specifiers to say what value from the topic you are interested in.
+
+All meta-data in a topic is referenced according to a to a simple plan.
+
+- `name` - name of the topic
+- `web` - name of the web the topic is within
+- `text` - the body text of the topic
+- `META:FILEATTACHMENT`
+ - _for each attachment_
+ - `name`
+ - `attr`
+ - `path`
+ - `size`
+ - `user`
+ - `rev`
+ - `date`
+ - `comment`
+- `META:TOPICPARENT`
+ - `name`
+- `META:TOPICINFO`
+ - `author`
+ - `date`
+ - `format`
+ - `version`
+- `META:TOPICMOVED`
+ - `by`
+ - `date`
+ - `from`
+ - `to`
+- `META:FORM` - the main form of the topic
+ - `name` (known as the _formname_)
+- `META:FIELD` - the fields in the form.
+ - _for each field in the form_
+ - `name`
+ - `title`
+ - `value`
+- `META:PREFERENCE`
+ - _for each preference in the topic_
+ - `name`
+ - `value`
+
+See [[TWikiMetaData]] for details of what all these entries mean.
+
+Most things at the top level of the plan - `META:TOPICPARENT`, `META:TOPICINFO` etc - are _structures_ which are indexed by _keys_. For example, `META:TOPICINFO` has 4 entries, which are indexed by the keys `author`, `date`, `format` and `version`. `META:FILEATTACHMENT`, `META:FIELD` and `META:PREFERENCE` are all _arrays_, which means they can have any number of records under them. Arrays are indexed by _numbers_ - for example, the first entry in the `META:FIELD` array is entry 0.
+
+It's a bit clumsy having to type `META:FILEATTACHMENT` every time you want to refer to the array of attachments in a topic, so there are some predefined aliases that make it a bit less typing:
+
+- `attachments` means the same as `META:FILEATTACHMENT`
+- `info` means the same as `META:TOPICINFO`
+- `parent` means the same as `META:TOPICPARENT`
+- `moved` means the same as `META:TOPICMOVED`
+- `form` means the same as `META:FORM`
+- `fields` means the same as `META:FIELD`, You can also use the name of the form (the value of `form.name` e.g. `PersonForm`)
+- `preferences` means the same as `META:PREFERENCE`
+
+This plan is referenced using a simple syntax:
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th bgcolor="#99CCCC"><strong> Syntax </strong></th>
+ <th bgcolor="#99CCCC"><strong> Means </strong></th>
+ <th bgcolor="#99CCCC"><strong> Examples </strong></th>
+ </tr>
+ <tr>
+ <td><code>X</code></td>
+ <td> refers to the field named <code>X</code>. </td>
+ <td><code>info</code>, <code>META:TOPICMOVED</code>, <code>attachments</code>, <code>name</code>. </td>
+ </tr>
+ <tr>
+ <td><code>X.Y</code></td>
+ <td> refers to the entry with the key <code>Y</code> in the structure named <code>X</code></td>
+ <td><code>info.date</code>, <code>moved.by</code>, <code>META:TOPICPARENT.name</code></td>
+ </tr>
+ <tr>
+ <td><code>X[<i>query</i>]</code></td>
+ <td> refers to all the elements of the array <code>X</code> that match <em>query</em>. If <i>query</i> is of the form <code>name='Y'</code> then you can use the same <code>X.Y</code> syntax as is used for accessing structures. </td>
+ <td><code>attachments[size>1024]</code>, <code>DocumentForm[name!='Summary' AND value~'top secret'].value</code>, <code>DocumentForm.Summary</code></td>
+ </tr>
+ <tr>
+ <td><code>X[N]</code></td>
+ <td> where <code>X</code> is an array and <code>N</code> is an integer number >= 0, gets the Nth element of the array <code>X</code></td>
+ <td><code>attachments[3]</code></td>
+ </tr>
+ <tr>
+ <td><code>X/Y</code></td>
+ <td> accesses <code>Y</code> from the topic specified by the <em>value</em> of <code>X</code>. <code>X</code> must evaluate to a topic name </td>
+ <td><code>parent.name/(form.name='ExampleForm')</code> will evaluate to true if (1) the topic has a parent, (2) the parent topic has the main form type <code>ExampleForm</code>. </td>
+ </tr>
+</table>
+
+Note: at some point TWiki may support multiple forms in the same topic. For this reason you are recommended **not** to use the `fields` shortcut when accessing form fields, but always use the name of the form instead.
+
+There is a shortcut for accessing form fields. If you use the name of a field (for example, `LastName`) in the query without a . before it, that is taken to mean "the value of the field named this". This works if and only if the field name isn't the same as of the top level entry names or their aliases described above. For example, the following expressions will all evaluate to the same thing:
+
+- `PersonForm[name='Lastname'].value`
+- `Lastname`
+- `PersonForm.Lastname`
+
+If `X` would conflict with the name of an entry or alias (e.g. it's `moved` or maybe `parent`), you can prepend the name of the form followed by a dot, as shown in the last example.
+
+## <a name="Constants"></a> Constants
+
+You use constants for the values that you compare with fields. Constants are either strings, or numbers. Strings are always delimited by single-quotes (you can escape a quote using backslash). Numbers can be any integer or floating point number.
+
+## <a name="Operators"></a> Operators
+
+Field specifiers and constants are combined using _operators_ to create queries.
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th bgcolor="#99CCCC"><strong> Operator </strong></th>
+ <th bgcolor="#99CCCC"><strong> Meaning </strong></th>
+ </tr>
+ <tr>
+ <td><code>=</code></td>
+ <td> Left-hand side (LHS) exactly matches the value on the Right-hand side (RHS). Numbers and strings can be compared. </td>
+ </tr>
+ <tr>
+ <td><code>!=</code></td>
+ <td> Inverse of <code>=</code>. </td>
+ </tr>
+ <tr>
+ <td><code>~</code></td>
+ <td> wildcard match ('*' will match any number of characters, '?' will match any single character e.g. "PersonForm.Surname ~ '*Smit?'") Note: Surname ~ 'Smith' is the same as Surname = 'Smith' </td>
+ </tr>
+ <tr>
+ <td><code><</code></td>
+ <td> LHS is less that RHS. If both sides are numbers, the order is numeric. Otherwise it is alphabetic (applies to all comparison operators) </td>
+ </tr>
+ <tr>
+ <td><code>></code></td>
+ <td> > </td>
+ </tr>
+ <tr>
+ <td><code>>=</code></td>
+ <td> &gte; </td>
+ </tr>
+ <tr>
+ <td><code><=</code></td>
+ <td> &lte; </td>
+ </tr>
+ <tr>
+ <td><code>lc(x)</code></td>
+ <td> Converts x to lower case, Use for caseless comparisons. </td>
+ </tr>
+ <tr>
+ <td><code>uc(x)</code></td>
+ <td> Converts x to UPPER CASE. Use for caseless comparisons. </td>
+ </tr>
+ <tr>
+ <td><code>d2n(x)</code></td>
+ <td> Converts a date (expressed in [[Main/TimeSpecifications]]) to a number of seconds since 1st Jan 1970. This is the format dates are stored in inside TWiki, and you have to convert a string date using <code>d2n</code> before you can compare it with - for example - the date an attachment was uploaded. Times without a timezone are assumed to be in server local time. If you have date fields in your forms, note that they are <strong>not</strong> stored in TWiki's internal format, but are stored as text strings. You should still use <code>d2n</code> to convert them to numbers for comparisons, though. </td>
+ </tr>
+ <tr>
+ <td><code>NOT</code></td>
+ <td> Invert the result of the subquery </td>
+ </tr>
+ <tr>
+ <td><code>AND</code></td>
+ <td> Combine two subqueries </td>
+ </tr>
+ <tr>
+ <td><code>OR</code></td>
+ <td> Combine two subqueries </td>
+ </tr>
+ <tr>
+ <td><code>()</code></td>
+ <td> Bracketed subquery </td>
+ </tr>
+</table>
+
+%I% The same operators are supported for [[%IF statements|Main/VarIF]].
+
+## <a name="Putting it all together"></a> Putting it all together
+
+When a query is applied to a topic, the goal is to reduce to a TRUE or FALSE value that indicates whether the topic matches that query or not. If the query returns TRUE, then the topic is included in the search results.
+
+A query matches if the query returns one or more values when it is applied to the topic. So if I have a very simple query, such as `"attachments"`, then this will return TRUE for all topics that have one or more attachments. If I write `"attachments[size>1024 AND name ~ '*.gif']"` then it will return TRUE for all topics that have at least one attachment larger than 1024 bytes with a name ending in `.gif`.
+
+## <a name="Examples"></a> Examples
+
+### <a name="Query examples"></a> Query examples
+
+- `attachments[name='purdey.gif']` - true if there is an attachment call `purdey.gif` on the topic
+- `(fields[name='Firstname'].value='Emma' OR fields[name=Firstname].value='John') AND fields[name='Lastname'].value='Peel'` - true for 'Emma Peel' and 'John Peel' but **not** 'Robert Peel' or 'Emma Thompson'
+- `(Firstname='Emma' OR Firstname='John') AND Lastname='Peel'` - shortcut form of the previous query
+- `HistoryForm[name='Age'].value>2` - true if the topic has a `HistoryForm`, and the form has a field called `Age` with a value > 2
+- `HistoryForm.Age > 2` - shortcut for the previous query
+- =preferences[name='FaveColour' AND value='Tangerine'] - true if the topic has the given preference setting and value
+- <code>Person/([[ClothesForm]][name='Headgear'].value ~ '\*Bowler\*' AND attachments[name~'\*hat.gif' AND date < d2n('2007-01-01')])</code> - true if the form attached to the topic has a field called `Person` that has a value that is the name of a topic, and that topic contains the form `ClothesForm`, with a field called `Headgear`, and the value of that field contains the string `'Bowler'`, and the topic also has at least one attachment that has a name matching `*hat.gif` and a date before 1st Jan 2007. (Phew!)
+
+### <a name="Search examples"></a> Search examples
+
+Find all topics that are children of this topic in the current web
+
+ %SEARCH{"parent.name = '%TOPIC%'" web="%WEB%" type="query"}%
+
+Find all topics that have an attachment called 'grunge.gif'
+
+ %SEARCH{"attachments[name='grunge.gif']" type="query"}%
+
+Find all topics that have form `ColourForm` where the form field 'Shades' is 'green' or 'yellow' but not 'brown'
+
+ %SEARCH{"(lc(Shades)='green' OR lc(Shades)='yellow') AND NOT(lc(Shades) ~ 'brown')" type="query"}%
+
+Find all topics that have PNG attachments that have been added since 26th March 2007
+
+ %SEARCH{"attachments[name ~ '*.png' AND date >= d2n('2007-03-26')"}%
+
+Find all topics that have a field 'Threat' set to 'Amber' and 'cold virus' somewhere in the topic text.
+
+ %SEARCH{"Threat='Amber' AND text ~ '*cold virus*'"}%
Attachments are made when people first register, held pending until the registration is confirmed and approved, and are removed when registration is completed.
-- Set ALLOWTOPICVIEW = [[TWikiAdminGroup]]
-- Set ALLOWTOPICCHANGE = [[TWikiAdminGroup]]
+- Set ALLOWTOPICVIEW = %USERSWEB%.TWikiAdminGroup
+- Set ALLOWTOPICCHANGE = %USERSWEB%.TWikiAdminGroup
+- Set ALLOWTOPICRENAME = %USERSWEB%.TWikiAdminGroup
**_Related Topics:_** [[AdminToolsCategory]]
- <img src="http://www.dementia.org/twiki//view/Main/WebHome/move.gif" width="16" height="16" alt="move" /> **Rename, move or delete this web:**
- - **[Rename/move/delete web...](http://www.dementia.org/twiki/rename/Main/WebHome?action=renameweb)**, looking for references in _all public webs_ - See also: [[ManagingWebs]]
+ - **[Rename/move/delete web...](http://www.dementia.org/twiki/rename/Main/WebHome?action=renameweb)**, looking for references in _all public webs_ - See also: %SYSTEMWEB%.ManagingWebs
<tr>
<td bgcolor="#EEEEEE" valign="top"><pre>
%RENDERLIST{"thread"}%
- * one
- * one.a
- * one.a.x
- * one.b
- * one.b.x
- continue
- * one.b.y
- * icon:person Tim
- * icon:person Mico
- * two
- * three
+ * one
+ * one.a
+ * one.a.x
+ * one.b
+ * one.b.x
+ continue
+ * one.b.y
+ * icon:person Tim
+ * icon:person Mico
+ * two
+ * three
</pre></td>
<td bgcolor="#EEEEEE" valign="top">
<p>
<tr>
<td bgcolor="#EEEEEE" valign="top"><pre>
%RENDERLIST{"org"}%
- * one
- * one.a
- * one.a.x
- * one.b
- * one.b.x
- continue
- * one.b.y
- * icon:person Tim
- * icon:person Mico
- * two
- * three
+ * one
+ * one.a
+ * one.a.x
+ * one.b
+ * one.b.x
+ continue
+ * one.b.y
+ * icon:person Tim
+ * icon:person Mico
+ * two
+ * three
</pre></td>
<td bgcolor="#EEEEEE" valign="top">
<p>
<tr>
<td bgcolor="#EEEEEE" valign="top"><pre>
%RENDERLIST{ "org" focus="one.b" }%
- * one
- * one.a
- * one.a.x
- * one.b
- * one.b.x
- continue
- * one.b.y
- * icon:person Tim
- * icon:person Mico
- * two
- * three
+ * one
+ * one.a
+ * one.a.x
+ * one.b
+ * one.b.x
+ continue
+ * one.b.y
+ * icon:person Tim
+ * icon:person Mico
+ * two
+ * three
</pre></td>
<td bgcolor="#EEEEEE" valign="top">
<p>
**_Note:_** You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.
-- Download the ZIP file from the Plugin web (see below)
+- Download the ZIP file from the Plugin Home (see below)
- Unzip <code>**%TOPIC%.zip**</code> in your twiki installation directory. Content: <table border="1" cellpadding="0" cellspacing="0">
<tr>
<th bgcolor="#99CCCC"><strong> File: </strong></th>
</tr>
<tr>
<td align="right"> Copyright: </td>
- <td> © 2006, <a href="http://www.structuredwikis.com/peter.html" target="_top">Peter Thoeny</a></td>
+ <td> © 2006-2007, <a href="mailto:Peter@Thoeny.org">Peter@Thoeny.org</a>, <a href="http://www.twiki.net/" target="_top">TWIKI.NET</a></td>
</tr>
<tr>
<td align="right"> License: </td>
</tr>
<tr>
<td align="right"> Plugin Version: </td>
- <td> 23 Sep 2006 (V1.034) </td>
+ <td> 15 Jan 2008 (2.0) </td>
</tr>
<tr>
<td align="right"> Change History: </td>
<td> </td>
</tr>
<tr>
+ <td align="right"> 15 Jan 2008: </td>
+ <td> 2.0: Kenneth Lavrsen. No more reporting warnings in the error log when a render list starts at deeper level than 1 </td>
+ </tr>
+ <tr>
+ <td align="right"> 30 Sep 2007: </td>
+ <td> Added [[TWiki/VarRENDERLIST]] to have it listed in [[TWiki/TWikiVariables]]</td>
+ </tr>
+ <tr>
<td align="right"> 23 Sep 2006: </td>
<td> Support for img tag and image URL after <code>icon:</code> (suggested by TWiki:Main.JanFilipsky); support for [[TWiki/TWikiDocGraphics]] icons, such as <code>%ICON{folder}%</code> instead of <code>icon:folder</code>; added files.gif and folders.gif (contributed by TWiki:Main.SteveHobbs) </td>
</tr>
**_Related Topics:_** [[TWikiPlugins]], [[DeveloperDocumentationCategory]], [[AdminDocumentationCategory]], [[TWikiPreferences]], TWiki:Plugins/TreePlugin
--- TWiki:Main/PeterThoeny - 23 Sep 2006
+-- TWiki:Main/PeterThoeny - 30 Sep 2007
**_Remember your password?_** Use [[ChangePassword]] instead. Otherwise, use this form to get a new one e-mailed to you.
-<form action="http://www.dementia.org/twiki/passwd/Main/WebHome" method="post" name="passwd">
+<form action="http://www.dementia.org/twiki/resetpasswd/Main/WebHome" method="post" name="resetpasswd">
<div>
- <div><strong>After submitting this form, you will receive an e-mail with your new, <strong>system-generated</strong> password, and a link to a page where you can change it.</strong><p> %X% you <strong>must</strong> have at least one valid registered e-mail to be able to reset your password. If none of your registered e-mail addresses is valid, and you have forgotten your password, contact 0. </p>
+ <div>
+ <p><strong>Sorry, the password system is currently read only, please contact 0</strong></p>
+ <p> %X% you <strong>must</strong> have at least one valid registered e-mail to be able to reset your password. If none of your registered e-mail addresses is valid, and you have forgotten your password, contact 0. </p>
</div>
<div>
- <table border="0" cellpadding="0" cellspacing="0" style="border-width: 0px">
+ <table border="0" cellpadding="0" cellspacing="0" rules="none" style="border-width: 0px">
<tr>
- <td colspan="2" style="border-width: 0px"> Fields marked <code><font color="red">**</font></code> are required </td>
+ <td bgcolor="transparent" colspan="2" style=""> Fields marked <code><font color="red">**</font></code> are required </td>
</tr>
<tr>
- <td align="right" style="border-width: 0px"> Your [[TWiki/LoginName]]: </td>
- <td style="border-width: 0px"><input name="LoginName" size="40" type="text" value="" /> <code><font color="red">**</font></code></td>
+ <td align="right" bgcolor="transparent" style=""> Your [[TWiki/LoginName]]: </td>
+ <td bgcolor="transparent" style=""><input %notmodifyable%="%NOTMODIFYABLE%" name="LoginName" size="40" type="text" value="" /> <code><font color="red">**</font></code></td>
</tr>
</table>
</div>
- <div><input name="action" type="hidden" value="resetPassword" /> <input name="TopicName" type="hidden" value="%TOPIC%" /> <input type="submit" value=" Reset password " /></div>
+ <div><input name="action" type="hidden" value="resetPassword" /> <input name="TopicName" type="hidden" value="%TOPIC%" /> <input %notmodifyable%="%NOTMODIFYABLE%" type="submit" value=" Reset password " /></div>
</div>
</form>
<div>
<ul>
- <li><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> [[Main/TWikiUsers]] has a list of other TWiki users. </li>
- <li><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> If you have any questions, please contact 0. </li>
+ <li><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> [[Main/TWikiUsers]] has a list of other TWiki users </li>
+ <li><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> If you have any questions, please contact 0 </li>
</ul>
</div>
**_Related topics:_** [[ChangePassword]], [[ChangeEmailAddress]], [[UserToolsCategory]], [[AdminToolsCategory]]
-
-<table bgcolor="yellow">
- <tr>
- <td><strong><em>Note to administrator:</em></strong> This form applies only if TWiki uses a {PasswordManager} that supports changing passwords. Otherwise replace this topic with a note describing how to change the password in your organization. See [[Main/TWikiUserAuthentication]] for more information. </td>
- </tr>
-</table>
### <a name="Solution 1: Appropriate for Sep"></a><a name="Solution 1: Appropriate for Sep "></a> Solution 1: Appropriate for Sep 2004 TWiki (Cairo)
- <form name="testing" action="%SCRIPTURLPATH{"view"}%/%MAINWEB%" method="get">
+ <form name="testing" action="%SCRIPTURLPATH{"view"}%/%USERSWEB%" method="get">
<select name="topic">
<option>Select user...</option>
- %SEARCH{ "Name:;Email:;Country:" web="%MAINWEB%" type="regex" nosearch="on" nototal="on" format="<option>$topic</option>" }%
+ %SEARCH{ "Name:;Email:;Country:" web="%USERSWEB%" type="regex" nosearch="on" nototal="on" format="<option>$topic</option>" }%
</select>
<input type="submit" value="Go" />
</form>
Which expands to this: (here limited to all Z\* users because TWiki.org has so many)
-<form action="http://www.dementia.org/twiki/view/Main" method="get" name="testing"><select name="topic"><option>Select user...</option>
+<form action="http://www.dementia.org/twiki/view/%USERSWEB%" method="get" name="testing"><select name="topic"><option>Select user...</option>
<h1><a name="TWiki Installation Error"></a> TWiki Installation Error </h1>Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags) </select> <input type="submit" value="Go" /></form>
-This searches all topics in the Main web that contain "Name", "Email" and "Country" bullets. Alternatively, do a [[FormattedSearch]] with `multiple="on"` on the [[Main.TWikiUsers|Main/TWikiUsers]] topic.
+This searches all topics in the Main web that contain "Name", "Email" and "Country" bullets. Alternatively, do a %SYSTEMWEB%.FormattedSearch with `multiple="on"` on the [[%USERSWEB%.TWikiUsers|USERSWEB/TWikiUsers]] topic.
### <a name="Solution 2: As Solution 1, but w"></a> Solution 2: As Solution 1, but with possibility for multi-selecting usernames
The abovementioned modification is, in effect:
-<form action="http://www.dementia.org/twiki/view/Main" method="get" name="testing"><select multiple="MULTIPLE" name="topic" size="2"><option>Select user...</option>
+<form action="http://www.dementia.org/twiki/view/%USERSWEB%" method="get" name="testing"><select multiple="MULTIPLE" name="topic" size="2"><option>Select user...</option>
<h1><a name="TWiki Installation Error"></a> TWiki Installation Error </h1>Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags) </select> <input type="submit" value="Go" /></form>
### <a name="Solution 3: Appropriate for TWik"></a> Solution 3: Appropriate for TWiki 4 (Dakar)
When the User information is stored in a [[UserForm]] (as is default in Dakar) then this list can be generated as follows:
- <form name="testing" action="%SCRIPTURLPATH{"view"}%/%MAINWEB%" method="get">
+ <form name="testing" action="%SCRIPTURLPATH{"view"}%/%USERSWEB%" method="get">
<select name="topic">
<option>Select user...</option>
- %SEARCH{"%META:FORM.*[U]serForm" web="%MAINWEB%" type="regex" casesensitive="on" nosearch="on" format="<option>$topic</option>" sort="topic" excludetopic="Test*, TWiki*"}%
+ %SEARCH{"%META:FORM.*[U]serForm" web="%USERSWEB%" type="regex" casesensitive="on" nosearch="on" format="<option>$topic</option>" sort="topic" excludetopic="Test*, TWiki*"}%
</select>
<input type="submit" value="Go" />
</form>
<tr bgcolor="#ffffff">
<td valign="top"> Legend of icons: </td>
<td valign="top"> </td>
- <td valign="top"><img alt="Home of web" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/home.gif" width="16" /> = Go to the home of the web%BR% <img alt="Search web" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/searchtopic.gif" width="16" /> = Search the web </td>
+ <td valign="top"><img alt="Home of web" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/home.gif" width="16" /> = Go to the home of the web%BR% <img alt="Search web" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/searchtopic.gif" width="16" /> = Search the web </td>
<td valign="top"> </td>
- <td valign="top"><img alt="Recent changes in the web" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/recentchanges.gif" width="16" /> = See recent changes in the web%BR% <img alt="Get notified of changes to the web" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/notify.gif" width="16" /> = Subscribe to get notified of changes by e-mail </td>
+ <td valign="top"><img alt="Recent changes in the web" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/recentchanges.gif" width="16" /> = See recent changes in the web%BR% <img alt="Get notified of changes to the web" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/notify.gif" width="16" /> = Subscribe to get notified of changes by e-mail </td>
</tr>
</table>
<th bgcolor="#99CCCC" colspan="2"><strong> RENAME </strong></th>
</tr>
<tr>
- <td> ^ </td>
+ <th bgcolor="#99CCCC"><strong> </strong></th>
<th bgcolor="#99CCCC"><strong> Listed </strong></th>
<th bgcolor="#99CCCC"><strong> DENY </strong></th>
<th bgcolor="#99CCCC"><strong> ALLOW </strong></th>
Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
-See [[TWikiAccessControl]] for details
-
**_Please Note:_**
- A blank in the the above table may mean _either_ the corresponding control is absent or commented out _or_ that it has been set to a null value. The two conditions have dramatically different and possibly opposed semantics.
-- [[TWikiGuest]] is the guest account - used by unauthenticated users.
-- The TWiki web must not deny view to [[TWikiGuest]]; otherwise, people will not be able to register.
+- %USERSWEB%.TWikiGuest is the guest account - used by unauthenticated users.
+- The TWiki web must not deny view to %USERSWEB%.TWikiGuest; otherwise, people will not be able to register.
+
+See [[TWikiAccessControl]] for details
**_Related Topics:_** [[SiteMap]], [[UserDocumentationCategory]], [[AdminDocumentationCategory]], [[AdminToolsCategory]]
# <a name="Slide Show Plugin"></a><a name=" Slide Show Plugin"></a> Slide Show Plugin
-This Plugin converts a topic with headings into a slide show.
+This plugin converts a topic with headings into a slideshow.
<div>
<ul>
<li><a href="#Introduction"> Introduction</a></li>
<li><a href="#Syntax Rules"> Syntax Rules</a><ul>
- <li><a href="#How to Create a Slide Show"> How to Create a Slide Show</a></li>
+ <li><a href="#How to Create a Slideshow"> How to Create a Slideshow</a></li>
<li><a href="#How to Create Your own Slide Tem"> How to Create Your own Slide Template</a></li>
</ul>
</li>
<li><a href="#Example"> Example</a><ul>
- <li><a href="#Slide 1: Silly Sample Slide Show"> Slide 1: Silly Sample Slide Show</a></li>
+ <li><a href="#Slide 1: Silly Sample Slideshow"> Slide 1: Silly Sample Slideshow</a></li>
<li><a href="#Slide 2: Agenda"> Slide 2: Agenda</a></li>
<li><a href="#Slide 3: Silly Introduction"> Slide 3: Silly Introduction</a><ul>
<li><a href="#Comments"> Comments</a></li>
## <a name="Introduction"></a> Introduction
-There is already a defacto standard for presentations, why this Plugin? This Plugin makes sense for organizations that do already have lots of content in TWiki: It is easy to create a web based presentation that contains many links to related content. The Plugin does not try to compete with the bells and whistles of the other presentation program, but the markup of TWiki and other Plugins like TWiki:Plugins/ChartPlugin, TWiki:Plugins/GaugePlugin, TWiki:Plugins/SpreadSheetPlugin, TWiki:Plugins/TWikiDrawPlugin can be used to create an appealing presentation.
+There is already a defacto standard for presentations, why this plugin? This plugin makes sense for organizations that do already have lots of content in TWiki: It is easy to create a web based presentation that contains many links to related content. The plugin does not try to compete with the bells and whistles of the other presentation program, but the markup of TWiki and other plugins like TWiki:Plugins/ChartPlugin, TWiki:Plugins/GaugePlugin, TWiki:Plugins/SpreadSheetPlugin, TWiki:Plugins/TWikiDrawPlugin can be used to create appealing presentations.
-Any topic with headings can be converted into a slide show. Each slide starts with a `"---++"` heading. There are two modes to view a topic:
+Any topic with headings can be converted into a slideshow. Each slide starts with a `"---++"` heading. There are two modes to view a topic:
-- Normal topic view mode: Headings and text is shown in the usual TWiki rendering, representing the outline of the slide show. This mode is useful to print handouts.
+- Normal topic view mode: Headings and text is shown in the usual TWiki rendering, representing the outline of the slideshow. This mode is useful to print handouts.
- Presentation mode: Each heading with text is shown as a slide; the format is based on a slide template. Navigation buttons are added to go to the "First", "Previous", and "Next" slide. Slide navigation is quick because it is done with anchor jumps to the same page.
You can start the presentation by clicking on the "Start presentation" button.
## <a name="Syntax Rules"></a> Syntax Rules
-### <a name="How to Create a Slide Show"></a> How to Create a Slide Show
+### <a name="How to Create a Slideshow"></a> How to Create a Slideshow
- Start with `%SLIDESHOWSTART%`
- Use the optional `template` parameter to specify your own slide template topic, e.g. `%SLIDESHOWSTART{ template="MyOwnSlideTemplate" }%`
- Create the slides. Start each slide with a `"---++"` heading and add text like paragraphs, bullets, tables and images.
- **_Hint:_** Make sure to keep each slide short enough so that you do not need to scroll to see all text of a slide during the presentation.
- **_Note:_** You can use any heading level you like, but use the same for all slides.
-- End your slide show with `%SLIDESHOWEND%`
+- End your slideshow with `%SLIDESHOWEND%`
### <a name="How to Create Your own Slide Tem"></a> How to Create Your own Slide Template
-To create your own template topic, copy the "Default Slide Template" section below into your own slide template topic and customize it to your needs. It can be activated as the default template in the Plugin's `TEMPLATE` setting, or per slide show with the `%SLIDESHOWSTART{ template="MyOwnSlideTemplate" }%` setting.
+To create your own template topic, copy the "Default Slide Template" section below into your own slide template topic and customize it to your needs. It can be activated as the default template in the plugin's `TEMPLATE` setting, or per slideshow with the `%SLIDESHOWSTART{ template="MyOwnSlideTemplate" }%` setting.
- Use an HTML table that defines a slide. For example, create one row for the slide title, another one for the slide text.
- These keywords can be used: <table border="1" cellpadding="0" cellspacing="0">
## <a name="Example"></a> Example
-This is a short example of a slide show. You should see a "Start presentation" button if this Plugin is installed:
+This is a short example of a slideshow. You should see a "Start presentation" button if this plugin is installed:
<a name="StartPresentation"></a> <span>[[Main/WebHome?slideshow=on;skin=print#GoSlide1]]</span>
-### <a name="Slide 1: Silly Sample Slide Show"></a> Slide 1: Silly Sample Slide Show
+### <a name="Slide 1: Silly Sample Slideshow"></a> Slide 1: Silly Sample Slideshow
%BR%
-<center> By TWiki:Main/PeterThoeny <p> San Jose, 17 Nov 2002 </p>
+<center> By TWiki:Main/PeterThoeny <p> San Jose, 29 Sep 2007 </p>
</center>
### <a name="Slide 2: Agenda"></a> Slide 2: Agenda
- foo is bar
- bar is foo
-This text is not part of the slide show
+This text is not part of the slideshow
## <a name="%TOPIC% Global Settings"></a> %TOPIC% Global Settings
Plugin settings are stored as preferences variables. To reference a plugin setting write <code>**%<plugin>\_<setting>%**</code>, i.e. <code>**%SLIDESHOWPLUGIN\_SHORTDESCRIPTION%**</code>
-- One line description, is shown in the [[TextFormattingRules]] topic:
+- One line description, is shown in the %SYSTEMWEB%.TextFormattingRules topic:
- Set SHORTDESCRIPTION = Create web based presentations based on topics with headings.
- Debug plugin: (See output in `data/debug.txt`)
**_Note:_** You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the server where TWiki is running.
-- Download the ZIP file from the Plugin web (see below)
+- Download the ZIP file from the Plugin Home (see below)
- Unzip <code>**%TOPIC%.zip**</code> in your twiki installation directory. Content: <table border="1" cellpadding="0" cellspacing="0">
<tr>
<th bgcolor="#99CCCC"><strong> File: </strong></th>
</tr>
<tr>
<td align="right"> Copyright: </td>
- <td> © 2006, <a href="http://www.structuredwikis.com/peter/" target="_top">Peter Thoeny</a></td>
+ <td> © 2006-2007, Peter Thoeny, <a href="http://www.twiki.net/" target="_top">TWIKI.NET</a></td>
</tr>
<tr>
<td align="right"> License: </td>
</tr>
<tr>
<td align="right"> Plugin Version: </td>
- <td> 12011 </td>
+ <td> 29 Sep 2007 (15091) </td>
</tr>
<tr>
<td align="right"> Change History: </td>
<td> </td>
</tr>
<tr>
+ <td align="right"> 29 Sep 2007: </td>
+ <td> Added %SYSTEMWEB%.VarSLIDESHOWSTART and %SYSTEMWEB%.VarSLIDESHOWEND to have them listed in %SYSTEMWEB%.TWikiVariables </td>
+ </tr>
+ <tr>
<td align="right"> 12 Feb 2007: </td>
<td> fixed construction of view urls (TWiki:Main/MichaelDaum) </td>
</tr>
</tr>
<tr>
<td align="right"> TWiki:Plugins/Benchmark: </td>
- <td>[[TWiki/GoodStyle]] 98%, [[TWiki/FormattedSearch]] 99%, [[Main/SlideShowPlugin]] 99% </td>
+ <td> %SYSTEMWEB%.GoodStyle 98%, %SYSTEMWEB%.FormattedSearch 99%, [[Main/SlideShowPlugin]] 99% </td>
</tr>
<tr>
<td align="right"> Plugin Home: </td>
</tr>
</table>
-**_Related Topics:_** [[TWikiPreferences]], [[TWikiPlugins]]
+**_Related Topics:_** %SYSTEMWEB%.TWikiPreferences, %SYSTEMWEB%.TWikiPlugins
<tr>
<td> :love: </td>
<td><img alt="love.gif" src="http://www.dementia.org/twiki//view/love.gif" /></td>
- <td> "in love" </td>
+ <td> "I love it!" </td>
</tr>
<tr>
<td> :skull: </td>
<td><img alt="skull.gif" src="http://www.dementia.org/twiki//view/skull.gif" /></td>
- <td> "skull" </td>
+ <td> "dead!" </td>
</tr>
</table>
<td> TWiki:Main.AndreaSterbini, TWiki:Main.PeterThoeny </td>
</tr>
<tr>
+ <td align="right"> Copyright: </td>
+ <td> © 2001-2007, Andrea Sterbini, Peter Thoeny, TWiki Contributors </td>
+ </tr>
+ <tr>
<td align="right"> Plugin Version: </td>
- <td> 1.004 </td>
+ <td> 21 Nov 2007 </td>
</tr>
<tr>
<td align="right"> Change History: </td>
<td> </td>
</tr>
<tr>
+ <td align="right"> 21 Nov 2007: </td>
+ <td> Doc improvements </td>
+ </tr>
+ <tr>
<td align="right"> 16 Mar 2005: </td>
<td> Fixed typo "scull" </td>
</tr>
<div>
<ul>
+ <li><a href="#"> </a></li>
+ <li><a href="#"> </a></li>
+ <li><a href="#"> </a></li>
+ <li><a href="#"> </a></li>
+ <li><a href="#"> </a></li>
+ <li><a href="#"> </a></li>
+ <li><a href="#"> </a></li>
+ <li><a href="#"> </a></li>
+ <li><a href="#"> </a></li>
+ <li><a href="#"> </a></li>
+ <li><a href="#"> </a></li>
+ <li><a href="#"> </a></li>
+ <li><a href="#"> </a></li>
+ <li><a href="#"> </a></li>
+ <li><a href="#"> </a></li>
+ <li><a href="#"> </a></li>
+ <li><a href="#"> </a></li>
+ <li><a href="#"> </a></li>
<li><a href="#TWiki::_AccessControlException"> TWiki::AccessControlException </a></li>
<li><a href="#TWiki::Access"> TWiki::Access </a></li>
+ <li><a href="#TWiki::_AggregateIterator"> TWiki::AggregateIterator </a></li>
<li><a href="#TWiki::Attach"> TWiki::Attach </a></li>
<li><a href="#TWiki::Attrs"> TWiki::Attrs </a></li>
- <li><a href="#TWiki::Client::_ApacheLogin"> TWiki::Client::ApacheLogin </a></li>
- <li><a href="#TWiki::Client"> TWiki::Client </a></li>
- <li><a href="#ObjectData =twiki="> ObjectData twiki</a></li>
- <li><a href="#TWiki::Client::_TemplateLogin"> TWiki::Client::TemplateLogin </a></li>
<li><a href="#TWiki::Compatibility"> TWiki::Compatibility </a></li>
<li><a href="#TWiki::Configure::Load"> TWiki::Configure::Load </a></li>
<li><a href="#Purpose"> Purpose</a></li>
<li><a href="#"> </a></li>
<li><a href="#TWiki"> TWiki </a></li>
+ <li><a href="#Public Data members"> Public Data members</a></li>
<li><a href="#TWiki::Form"> TWiki::Form </a></li>
+ <li><a href="#TWiki::Form::_FieldDefinition"> TWiki::Form::FieldDefinition </a></li>
+ <li><a href="#TWiki::Form::_ListFieldDefinitio"> TWiki::Form::ListFieldDefinition </a></li>
+ <li><a href="#"> </a></li>
<li><a href="#TWiki::Func"> TWiki::Func </a></li>
<li><a href="#TWiki::_I18N"> TWiki::I18N </a></li>
<li><a href="#TWiki::_I18N::Extract"> TWiki::I18N::Extract </a></li>
- <li><a href="#TWiki::If"> TWiki::If </a></li>
+ <li><a href="#TWiki::If::Node"> TWiki::If::Node </a></li>
+ <li><a href="#TWiki::If::Parser"> TWiki::If::Parser </a></li>
+ <li><a href="#TWiki::Infix::Error"> TWiki::Infix::Error </a></li>
+ <li><a href="#TWiki::Infix::Node"> TWiki::Infix::Node </a></li>
+ <li><a href="#TWiki::Infix::Parser"> TWiki::Infix::Parser </a></li>
+ <li><a href="#TWiki::_LineIterator"> TWiki::LineIterator </a></li>
+ <li><a href="#TWiki::_ListIterator"> TWiki::ListIterator </a></li>
+ <li><a href="#TWiki::_LoginManager::_ApacheLog"> TWiki::LoginManager::ApacheLogin </a></li>
+ <li><a href="#TWiki::_LoginManager"> TWiki::LoginManager </a></li>
+ <li><a href="#ObjectData =twiki="> ObjectData twiki</a></li>
+ <li><a href="#TWiki::_LoginManager::_TemplateL"> TWiki::LoginManager::TemplateLogin </a></li>
<li><a href="#TWiki::Merge"> TWiki::Merge </a></li>
<li><a href="#TWiki::Meta"> TWiki::Meta </a></li>
<li><a href="#TWiki::Net"> TWiki::Net </a></li>
+ <li><a href="#TWiki::Net::HTTPResponse"> TWiki::Net::HTTPResponse </a></li>
<li><a href="#TWiki::_OopsException"> TWiki::OopsException </a></li>
- <li><a href="#"> </a></li>
- <li><a href="#TWiki::Plugins"> TWiki::Plugins </a></li>
- <li><a href="#TWiki::Plurals"> TWiki::Plurals </a></li>
- <li><a href="#TWiki::Prefs"> TWiki::Prefs </a></li>
- <li><a href="#TWiki::Prefs::Parser"> TWiki::Prefs::Parser </a></li>
- <li><a href="#TWiki::Prefs::_PrefsCache"> TWiki::Prefs::PrefsCache </a></li>
- <li><a href="#TWiki::Render"> TWiki::Render </a></li>
- <li><a href="#TWiki::Sandbox"> TWiki::Sandbox </a></li>
- <li><a href="#TWiki::Search"> TWiki::Search </a></li>
- <li><a href="#TWiki::Store"> TWiki::Store </a></li>
- <li><a href="#TWiki::Store::_RcsFile"> TWiki::Store::RcsFile </a></li>
- <li><a href="#TWiki::Store::_RcsLite"> TWiki::Store::RcsLite </a></li>
- <li><a href="#File format"> File format</a></li>
- <li><a href="#TWiki::Store::_RcsWrap"> TWiki::Store::RcsWrap </a></li>
- <li><a href="#TWiki::Store::_SearchAlgorithms:"> TWiki::Store::SearchAlgorithms::Forking </a></li>
- <li><a href="#search($searchString, $topics, $"> search($searchString, $topics, $options, $sDir) -> \%seen</a></li>
- <li><a href="#TWiki::Store::_SearchAlgorithms:"> TWiki::Store::SearchAlgorithms::Native </a></li>
- <li><a href="#search($searchString, $topics, $"> search($searchString, $topics, $options, $sDir) -> \%seen</a></li>
- <li><a href="#TWiki::Store::_SearchAlgorithms:"> TWiki::Store::SearchAlgorithms::PurePerl </a></li>
- <li><a href="#search($searchString, $topics, $"> search($searchString, $topics, $options, $sDir) -> \%seen</a></li>
- <li><a href="#TWiki::Templates"> TWiki::Templates </a></li>
- <li><a href="#TWiki::Time"> TWiki::Time </a></li>
- <li><a href="#TWiki::UI::_ChangeForm"> TWiki::UI::ChangeForm </a></li>
- <li><a href="#TWiki::UI"> TWiki::UI </a></li>
- <li><a href="#TWiki::UI::Edit"> TWiki::UI::Edit </a></li>
- <li><a href="#TWiki::UI::Manage"> TWiki::UI::Manage </a></li>
- <li><a href="#TWiki::UI::Oops"> TWiki::UI::Oops </a></li>
- <li><a href="#TWiki::UI::RDiff"> TWiki::UI::RDiff </a></li>
- <li><a href="#TWiki::UI::Register"> TWiki::UI::Register </a></li>
- <li><a href="#TWiki::UI::Save"> TWiki::UI::Save </a></li>
- <li><a href="#TWiki::UI::Search"> TWiki::UI::Search </a></li>
- <li><a href="#TWiki::UI::Statistics"> TWiki::UI::Statistics </a></li>
- <li><a href="#TWiki::UI::Upload"> TWiki::UI::Upload </a></li>
- <li><a href="#TWiki::UI::View"> TWiki::UI::View </a></li>
- <li><a href="#TWiki::User"> TWiki::User </a></li>
- <li><a href="#TWiki::Users::_ApacheHtpasswdUse"> TWiki::Users::ApacheHtpasswdUser </a></li>
- <li><a href="#TWiki::Users"> TWiki::Users </a></li>
- <li><a href="#TWiki::Users::Password"> TWiki::Users::Password </a></li>
- <li><a href="#TWiki::Users::_TWikiUserMapping"> TWiki::Users::TWikiUserMapping </a></li>
</ul>
</div>
-## <a name="TWiki::_AccessControlException"></a> [[TWiki::AccessControlException|Main/TWikiAccessControlExceptionDotPm]]
+## <> \[[CGISessionDotPm]\[]]
-Exception used raise an access control violation.
+This package doesn't smell
+
+## <> \[[CGISessionDriverDBIDotPm]\[]]
This package doesn't smell
-## <a name="TWiki::Access"></a> [[TWiki::Access|Main/TWikiAccessDotPm]]
+## <> \[[CGISessionDriverDb\_fileDotPm]\[]]
-A singleton object of this class manages the access control database.
+This package doesn't smell
+
+## <> \[[CGISessionDriverDotPm]\[]]
This package doesn't smell
-## <a name="TWiki::Attach"></a> [[TWiki::Attach|Main/TWikiAttachDotPm]]
+## <> \[[CGISessionDriverFileDotPm]\[]]
-A singleton object of this class is used to deal with attachments to topics.
+This package doesn't smell
-This package has smell factor of **1**
+## <> \[[CGISessionDriverMysqlDotPm]\[]]
-## <a name="TWiki::Attrs"></a> [[TWiki::Attrs|Main/TWikiAttrsDotPm]]
+This package doesn't smell
-Class of attribute sets, designed for parsing and storing attribute values from a TWiki tag e.g. `%TAG{fred='bad' "sad" joe="mad"}%`
+## <> \[[CGISessionDriverPostgresqlDotPm]\[]]
-An attribute set is a map containing an entry for each parameter. The default parameter (unnamed quoted string) is named `_DEFAULT` in the map.
+This package doesn't smell
-Attributes declared later in the string will override those of the same name defined earlier. The one exception to this is the \_DEFAULT key, where the _first_ instance of a setting is always taken.
+## <> \[[CGISessionDriverSqliteDotPm]\[]]
-As well as standard TWiki syntax (parameter values double-quoted) it also parses single-quoted values, unquoted spaceless values, spaces around the =, and commas as well as spaces separating values, though none of these alternatives is advertised in documentation and the extended syntax can be turned off by passing the 'strict' parameter to `new`.
+This package doesn't smell
-This class replaces the old TWiki::extractNameValuePair and TWiki::extractParameters.
+## <> \[[CGISessionErrorHandlerDotPm]\[]]
This package doesn't smell
-## <a name="TWiki::Client::_ApacheLogin"></a> [[TWiki::Client::ApacheLogin|Main/TWikiClientApacheLoginDotPm]]
+## <> \[[CGISessionIDIncrDotPm]\[]]
-This is login manager that you can specify in the security setup section of [configure](http://www.dementia.org/twiki/configure). It instructs TWiki to cooperate with your web server (typically Apache) to require authentication information (username & password) from users. It requires that you configure your web server to demand authentication for scripts named "login" and anything ending in "auth". The latter should be symlinks to existing scripts; e.g., `viewauth -> view`, `editauth -> edit`, and so on.
+This package doesn't smell
-See also [[TWikiUserAuthentication]].
+## <> \[[CGISessionIDMd5DotPm]\[]]
+
+This package doesn't smell
-Subclass of TWiki::Client; see that class for documentation of the methods of this class.
+## <> \[[CGISessionSerializeDefaultDotPm]\[]]
This package doesn't smell
-## <a name="TWiki::Client"></a> [[TWiki::Client|Main/TWikiClientDotPm]]
+## <> \[[CGISessionSerializeFreezethawDotPm]\[]]
-The package is also a Factory for login managers and also the base class for all login managers.
+This package doesn't smell
-On it's own, an object of this class is used when you specify 'none' in the security setup section of [configure](http://www.dementia.org/twiki/configure). When it is used, logins are not supported. If you want to authenticate users then you should consider [[TemplateLogin]] or [[ApacheLogin]], which are subclasses of this class.
+## <> \[[CGISessionSerializeJsonDotPm]\[]]
-If you are building a new login manager, then you should write a new subclass of this class, implementing the methods marked as **VIRTUAL**. There are already examples in the `lib/TWiki/Client` directory.
+This package doesn't smell
-The class has extensive tracing, which is enabled by $TWiki::cfg\{Trace\}\{Client.pm\}. The tracing is done in such a way as to let the perl optimiser optimise out the trace function as a no-op if tracing is disabled.
+## <> \[[CGISessionSerializeStorableDotPm]\[]]
-Here's an overview of how it works:
+This package doesn't smell
-Early in TWiki::new, the login manager is created. The creation of the login manager does two things:
+## <> \[[CGISessionSerializeYamlDotPm]\[]]
-1. If sessions are in use, it loads CGI::Session but doesn't initialise the session yet.
-2. Creates the login manager object
+This package doesn't smell
-Slightly later in TWiki::new, loginManager->loadSession is called.
+## <> \[[CGISessionTutorialDotPm]\[]]
-1. Calls loginManager->getUser to get the username **before** the session is created
- - TWiki::Client::ApacheLogin looks at REMOTE\_USER
- - TWiki::Client::TemplateLogin just returns undef
-2. reads the TWIKISID cookie to get the SID (or the TWIKISID parameters in the CGI query if cookies aren't available, or [[IP2SID]] mapping if that's enabled).
-3. Creates the CGI::Session object, and the session is thereby read.
-4. If the username still isn't known, reads it from the cookie. Thus TWiki::Client::ApacheLogin overrides the cookie using REMOTE\_USER, and TWiki::Client::TemplateLogin **always** uses the session.
+This package doesn't smell
-Later again in TWiki::new, plugins are given a chance to **override** the username found from the loginManager.
+## <> \[[MonitorDotPm]\[]]
-The last step in TWiki::new is to find the user, using whatever user mapping manager is in place.
+This package doesn't smell
-## <a name="ObjectData <code>twiki="></a> [[ObjectData]] =twiki
+## <a name="TWiki::_AccessControlException"></a> [[TWiki::AccessControlException|Main/TWikiAccessControlExceptionDotPm]]
-The TWiki object this login manager is attached to.
+Exception used raise an access control violation. This exception has the following fields:
-This package has smell factor of **2**
+- `web` - the web which was being accessed
+- `topic` - the topic being accessed (if any)
+- `user` - canonical username of the person doing the accessing. Use the methods of the TWiki::Users class to get more information about the user.
+- `mode` - the access mode e.g. CHANGE, VIEW etc
+- `reason` a text string giving the reason for the refusal.
-## <a name="TWiki::Client::_TemplateLogin"></a> [[TWiki::Client::TemplateLogin|Main/TWikiClientTemplateLoginDotPm]]
+The exception may be thrown by plugins. If a plugin throws the exception, it will normally be caught and the browser redirected to a login screen (if the user is not logged in) or reported (if they are and just don't have access).
-This is a login manager that you can specify in the security setup section of [configure](http://www.dementia.org/twiki/configure). It provides users with a template-based form to enter usernames and passwords, and works with the [[PasswordManager]] that you specify to verify those passwords.
+This package doesn't smell
-Subclass of TWiki::Client; see that class for documentation of the methods of this class.
+## <a name="TWiki::Access"></a> [[TWiki::Access|Main/TWikiAccessDotPm]]
-This package has smell factor of **1**
+A singleton object of this class manages the access control database.
+
+This package doesn't smell
+
+## <a name="TWiki::_AggregateIterator"></a> [[TWiki::AggregateIterator|Main/TWikiAggregateIteratorDotPm]]
+
+combine multiple iterators
+
+This package doesn't smell
+
+## <a name="TWiki::Attach"></a> [[TWiki::Attach|Main/TWikiAttachDotPm]]
+
+A singleton object of this class is used to deal with attachments to topics.
+
+This package doesn't smell
+
+## <a name="TWiki::Attrs"></a> [[TWiki::Attrs|Main/TWikiAttrsDotPm]]
+
+Class of attribute sets, designed for parsing and storing attribute values from a TWiki tag e.g. `%TAG{"joe" fred="bad" joe="mad"}%`
+
+An attribute set is a hash containing an entry for each parameter. The default parameter (unnamed quoted string) is named `_DEFAULT` in the hash.
+
+Attributes declared later in the string will override those of the same name defined earlier. The one exception to this is the \_DEFAULT key, where the _first_ instance is always taken.
+
+As well as the default TWiki syntax (parameter values double-quoted) this class also parses single-quoted values, unquoted spaceless values, spaces around the =, and commas as well as spaces separating values. The extended syntax has to be enabled by passing the `$friendly` parameter to `new`.
+
+This package doesn't smell
## <a name="TWiki::Compatibility"></a> [[TWiki::Compatibility|Main/TWikiCompatibilityDotPm]]
Global variables are avoided wherever possible to avoid problems with CGI accelerators such as mod\_perl.
-This package has smell factor of **25**
+## <a name="Public Data members"></a> Public Data members
+
+- `cgiQuery` Pointer to the CGI::
+- `context` Hash of context ids
+- moved: `loginManager` TWiki::LoginManager singleton (moved to TWiki::Users)
+- `plugins` TWiki::Plugins singleton
+- `prefs` TWiki::Prefs singleton
+- `remoteUser` Login ID when using [[ApacheLogin]]. Maintained for compatibility only, do not use.
+- `requestedWebName` Name of web found in URL path or `web` URL parameter
+- `sandbox` TWiki::Sandbox singleton
+- `scriptUrlPath` URL path to the current script. May be dynamically extracted from the URL path if \{GetScriptUrlFromCgi\}. Only required to support \{GetScriptUrlFromCgi\} and not consistently used. Avoid.
+- `security` TWiki::Access singleton
+- `SESSION_TAGS` Hash of TWiki variables whose value is specific to the current CGI request.
+- `store` TWiki::Store singleton
+- `topicName` Name of topic found in URL path or `topic` URL parameter
+- `urlHost` Host part of the URL (including the protocol) determined during intialisation and defaulting to \{DefaultUrlHost\}
+- `user` Unique user ID of logged-in user
+- `users` TWiki::Users singleton
+- `webName` Name of web found in URL path, or `web` URL parameter, or \{UsersWebName\}
+
+This package has smell factor of **32**
## <a name="TWiki::Form"></a> [[TWiki::Form|Main/TWikiFormDotPm]]
Object representing a single form definition.
-This package has smell factor of **9**
+Form definitions are mainly used to control rendering of a form for editing, though there is some application login there that handles transferring values between edits and saves.
+
+A form definition consists of a TWiki::Form object, which has a list of field definitions. Each field definition is an object of a type derived from TWiki::Form::FieldDefinition. These objects are responsible for the actual syntax and semantics of the field type. Form definitions are parsed from TWiki tables, and the types are mapped by name to a class declared in TWiki::Form::\* - for example, the `text` type is mapped to `TWiki::Form::Text` and the `checkbox` type to `TWiki::Form::Checkbox`.
+
+The `TWiki::Form::FieldDefinition` class declares default behaviours for types that accept a single value in their definitions. The `TWiki::Form::ListFieldDefinition` extends this for types that have lists of possible values.
+
+This package has smell factor of **4**
+
+## <a name="TWiki::Form::_FieldDefinition"></a> [[TWiki::Form::FieldDefinition|Main/TWikiFormFieldDefinitionDotPm]]
+
+Base class of all field definition classes.
+
+Type-specific classes are derived from this class to define specific per-type behaviours. This class also provides default behaviours for when a specific type cannot be loaded.
+
+This package doesn't smell
+
+## <a name="TWiki::Form::_ListFieldDefinitio"></a> [[TWiki::Form::ListFieldDefinition|Main/TWikiFormListFieldDefinitionDotPm]]
+
+Form field definitions that accept lists of values in the field definition. This is different to being multi-valued, which means the field type can **store** multiple values.
+
+This package has smell factor of **1**
+
+## <> \[[TWikiFormSelectDotPm]\[]]
+
+This package doesn't smell
## <a name="TWiki::Func"></a> [[TWiki::Func|Main/TWikiFuncDotPm]]
_Official list of stable TWiki functions for Plugin developers_
-This module defines official functions that [[Plugins|TWiki/TWikiPlugins]] can use to interact with the TWiki engine and content.
+This module defines official functions that [[Plugins|SYSTEMWEB/TWikiPlugins]] can use to interact with the TWiki engine and content.
Refer to [[EmptyPlugin]] and lib/TWiki/Plugins/EmptyPlugin.pm for a template Plugin and documentation on how to write a Plugin.
Deprecated functions will still work in older code, though they should _not_ be called in new Plugins and should be replaced in older Plugins as soon as possible.
-The version of the TWiki::Func module is defined by the VERSION number of the TWiki::Plugins module, currently 1.11. This can be shown by the `%PLUGINVERSION%` variable. The 'Since' field in the function documentation refers to the VERSION number and the date that the function was addded.
-
-**_Note:_** Beware! These methods should only ever be called from the context of a TWiki Plugin. They require a Plugins SESSION context to be established before they are called, and will not work if simply called from another TWiki module. For example,
-
- use TWiki;
- print TWiki::Func::getSkin(),"\n";
-
-will fail with `Can't call method "getSkin" on an undefined value at TWiki/Func.pm line 83`.
+The version of the TWiki::Func module is defined by the VERSION number of the TWiki::Plugins module, currently 1.11. This can be shown by the `%PLUGINVERSION%` TWiki variable, and accessed in code using `$TWiki::Plugins::VERSION`. The 'Since' field in the function documentation refers to `$TWiki::Plugins::VERSION`.
-If you want to call the methods outside the context of a plugin, you can create a Plugins SESSION object. For example, the script:
+Notes on use of `$TWiki::Plugins::VERSION` (from 1.2 forwards):
- use TWiki:
- $TWiki::Plugins::SESSION = new TWiki();
- print TWiki::Func::getSkin(),"\n";
+- If the **major** version (e.g. `1.`) is the same then any plugin coded to use any **earlier** revision of the `1.` API will still work. No function has been removed from the interface, nor has any API published in that version changed in such a way as to **require** plugins to be recoded.
+- If the **minor** version (e.g. 1.1) is incremented there may be changes in the API that may help improve the coding of some plugins - for example, new interfaces giving access to previously hidden core functions. In addition, **deprecation** of functions in the interface trigger a minor version increment. Note that deprecated functions are not _removed_, they are merely frozen, and plugin authors are recommended to stop using them.
+- Any additional digits in the version number relate to minor changes, such as the addition of parameters to the existing functions, or addition of utility functions that are unlikely to require significant changes to existing plugins.
+- `TWiki::Plugins::VERSION` also applies to the plugin handlers. The handlers are documented in the EmptyPlugin, and that module indicates what version of `TWiki::Plugins::VERSION` it relates to.
-will work happily.
+A full history of the changes to this API can be found at the end of this topic.
This package has smell factor of **1**
This package has smell factor of **1**
-## <a name="TWiki::If"></a> [[TWiki::If|Main/TWikiIfDotPm]]
+## <a name="TWiki::If::Node"></a> [[TWiki::If::Node|Main/TWikiIfNodeDotPm]]
+
+Node class for the result of an If statement parse
+
+This package doesn't smell
+
+## <a name="TWiki::If::Parser"></a> [[TWiki::If::Parser|Main/TWikiIfParserDotPm]]
+
+Support for the conditions in %IF\{\} statements.
+
+This package doesn't smell
+
+## <a name="TWiki::Infix::Error"></a> [[TWiki::Infix::Error|Main/TWikiInfixErrorDotPm]]
+
+Class of errors used with TWiki::Infix::Parser
+
+This package doesn't smell
+
+## <a name="TWiki::Infix::Node"></a> [[TWiki::Infix::Node|Main/TWikiInfixNodeDotPm]]
+
+Base class for node types generated by Infix::Parser. You don't **have** to use it, but it may be useful.
+
+This package doesn't smell
+
+## <a name="TWiki::Infix::Parser"></a> [[TWiki::Infix::Parser|Main/TWikiInfixParserDotPm]]
+
+A simple stack-based parser that parses infix expressions with nonary, unary and binary operators specified using an operator table.
+
+Escapes are supported in strings, using backslash.
+
+This package doesn't smell
+
+## <a name="TWiki::_LineIterator"></a> [[TWiki::LineIterator|Main/TWikiLineIteratorDotPm]]
+
+Iterator over the lines in a file
+
+This package doesn't smell
+
+## <a name="TWiki::_ListIterator"></a> [[TWiki::ListIterator|Main/TWikiListIteratorDotPm]]
-Support for the conditions in %IF\{\} statements. Basically a simple stack-based parser for infix expressions that generates a parse tree that can subsequently be evaluated.
+Iterator over a list
This package doesn't smell
+## <a name="TWiki::_LoginManager::_ApacheLog"></a> [[TWiki::LoginManager::ApacheLogin|Main/TWikiLoginManagerApacheLoginDotPm]]
+
+This is login manager that you can specify in the security setup section of [configure](http://www.dementia.org/twiki/configure). It instructs TWiki to cooperate with your web server (typically Apache) to require authentication information (username & password) from users. It requires that you configure your web server to demand authentication for scripts named "login" and anything ending in "auth". The latter should be symlinks to existing scripts; e.g., `viewauth -> view`, `editauth -> edit`, and so on.
+
+See also [[TWikiUserAuthentication]].
+
+Subclass of TWiki::LoginManager; see that class for documentation of the methods of this class.
+
+This package has smell factor of **1**
+
+## <a name="TWiki::_LoginManager"></a> [[TWiki::LoginManager|Main/TWikiLoginManagerDotPm]]
+
+The package is also a Factory for login managers and also the base class for all login managers.
+
+On it's own, an object of this class is used when you specify 'none' in the security setup section of [configure](http://www.dementia.org/twiki/configure). When it is used, logins are not supported. If you want to authenticate users then you should consider [[TemplateLogin]] or [[ApacheLogin]], which are subclasses of this class.
+
+If you are building a new login manager, then you should write a new subclass of this class, implementing the methods marked as **VIRTUAL**. There are already examples in the `lib/TWiki/LoginManager` directory.
+
+The class has extensive tracing, which is enabled by $TWiki::cfg\{Trace\}\{LoginManager.pm\}. The tracing is done in such a way as to let the perl optimiser optimise out the trace function as a no-op if tracing is disabled.
+
+Here's an overview of how it works:
+
+Early in TWiki::new, the login manager is created. The creation of the login manager does two things:
+
+1. If sessions are in use, it loads CGI::Session but doesn't initialise the session yet.
+2. Creates the login manager object
+
+Slightly later in TWiki::new, loginManager->loadSession is called.
+
+1. Calls loginManager->getUser to get the username **before** the session is created
+ - TWiki::LoginManager::ApacheLogin looks at REMOTE\_USER (only for authenticated scripts)
+ - TWiki::LoginManager::TemplateLogin just returns undef
+2. reads the TWIKISID cookie to get the SID (or the TWIKISID parameters in the CGI query if cookies aren't available, or [[IP2SID]] mapping if that's enabled).
+3. Creates the CGI::Session object, and the session is thereby read.
+4. If the username still isn't known, reads it from the cookie. Thus TWiki::LoginManager::ApacheLogin overrides the cookie using REMOTE\_USER, and TWiki::LoginManager::TemplateLogin **always** uses the session.
+
+Later again in TWiki::new, plugins are given a chance to **override** the username found from the loginManager.
+
+The last step in TWiki::new is to find the user, using whatever user mapping manager is in place.
+
+## <a name="ObjectData <code>twiki="></a> [[ObjectData]] =twiki
+
+The TWiki object this login manager is attached to.
+
+This package has smell factor of **7**
+
+## <a name="TWiki::_LoginManager::_TemplateL"></a> [[TWiki::LoginManager::TemplateLogin|Main/TWikiLoginManagerTemplateLoginDotPm]]
+
+This is a login manager that you can specify in the security setup section of [configure](http://www.dementia.org/twiki/configure). It provides users with a template-based form to enter usernames and passwords, and works with the [[PasswordManager]] that you specify to verify those passwords.
+
+Subclass of TWiki::LoginManager; see that class for documentation of the methods of this class.
+
+This package has smell factor of **2**
+
## <a name="TWiki::Merge"></a> [[TWiki::Merge|Main/TWikiMergeDotPm]]
Support for merging strings
## <a name="TWiki::Meta"></a> [[TWiki::Meta|Main/TWikiMetaDotPm]]
-Meta-data handling.
+All TWiki topics have **data** (text) and **meta-data** (information about the topic). Meta-data includes information such as file attachments, form fields, topic parentage etc. When TWiki loads a topic from the store, it represents the meta-data in the topic using an object of this class.
A meta-data object is a hash of different types of meta-data (keyed on the type, such as 'FIELD' and 'TOPICINFO').
Each entry in the hash is an array, where each entry in the array contains another hash of the key=value pairs, corresponding to a single meta-datum.
-If there may be multiple entries of the same top-level type (i.e. for FIELD and FILEATTACHMENT) then the array hash multiple entries. These types are referred to as "keyed" types. The array entries are keyed with the attribute 'name' which must be in each entry in the array.
+If there may be multiple entries of the same top-level type (i.e. for FIELD and FILEATTACHMENT) then the array has multiple entries. These types are referred to as "keyed" types. The array entries are keyed with the attribute 'name' which must be in each entry in the array.
For unkeyed types, the array has only one entry.
-The module knows nothing about how meta-data is stored. That is entirely the responsibility of the Store module.
+Pictorially,
-Meta-data objects are created by the Store engine when topics are read. They are populated using the `put` method.
+- TOPICINFO
+ - author => '...'
+ - date => '...'
+ - ...
+- FILEATTACHMENT
+ - [0] -> \{ name => '...' ... \}
+ - [1] -> \{ name => '...' ... \}
+- FIELD
+ - [0] -> \{ name => '...' ... \}
+ - [1] -> \{ name => '...' ... \}
-This package has smell factor of **3**
+As well as the meta-data, the object also stores the web name, topic name and remaining text after meta-data extraction.
+
+This package has smell factor of **2**
## <a name="TWiki::Net"></a> [[TWiki::Net|Main/TWikiNetDotPm]]
Object that brokers access to network resources.
-This package has smell factor of **2**
+This package has smell factor of **3**
+
+## <a name="TWiki::Net::HTTPResponse"></a> [[TWiki::Net::HTTPResponse|Main/TWikiNetHTTPResponseDotPm]]
+
+Fakeup of HTTP::Response for use when LWP is not available. Only implements a small subset of the HTTP::Response methods:
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <td><code>code()</code></td>
+ </tr>
+ <tr>
+ <td><code>message()</code></td>
+ </tr>
+ <tr>
+ <td><code>header($field)</code></td>
+ </tr>
+ <tr>
+ <td><code>content()</code></td>
+ </tr>
+ <tr>
+ <td><code>is_error()</code></td>
+ </tr>
+ <tr>
+ <td><code>is_redirect()</code></td>
+ </tr>
+</table>
+
+See the documentation of HTTP::Response for information about the methods.
+
+This package doesn't smell
## <a name="TWiki::_OopsException"></a> [[TWiki::OopsException|Main/TWikiOopsExceptionDotPm]]
-Exception used to raise a request to redirect to an Oops URL. An [[OopsException]] thrown anywhere in the code will redirect the browser to a url based on the `oops` script. `oops` requires a `template` parameter, that is the name of a template file from the `templates` directory. This file will be expanded and the parameter values passed to the exception instantiated. The result will be shown in the browser.
+Exception used to raise a request to redirect to an Oops URL.
-This package doesn't smell
+An [[OopsException]] thrown anywhere in the code will redirect the browser to a url based on the `oops` script. `oops` requires the name of an oops template file from the `templates` directory. This file will be expanded and the parameter values passed to the exception instantiated. The result will be shown in the browser.
-## <> \[[TWikiPluginDotPm]\[]]
+Plugins may throw TWiki::OopsException. For example:
-This package has smell factor of **2**
+ use Error;
-## <a name="TWiki::Plugins"></a> [[TWiki::Plugins|Main/TWikiPluginsDotPm]]
+ ...
-This module defines the singleton object that handles Plugins loading, initialization and execution.
+ throw TWiki::OopsException( 'bathplugin',
+ def => 'toestuck',
+ web => $web,
+ topic => $topic,
+ params => [ 'bigtoe', 'hot tap' ] );
-This class uses Chain of Responsibility (GOF) pattern to dispatch handler calls to registered plugins.
+ This package doesn't smell
-This package doesn't smell
+ ---++ [[TWikiPluginDotPm][]]
-## <a name="TWiki::Plurals"></a> [[TWiki::Plurals|Main/TWikiPluralsDotPm]]
+ This package has smell factor of *2*
-Handle conversion of plural topic names to singular form.
+ ---++ [[TWikiPluginsDotPm][TWiki::Plugins]]
-This package has smell factor of **3**
+ This module defines the singleton object that handles Plugins
+ loading, initialization and execution.
-## <a name="TWiki::Prefs"></a> [[TWiki::Prefs|Main/TWikiPrefsDotPm]]
+ This class uses Chain of Responsibility (GOF) pattern to dispatch
+ handler calls to registered plugins.
-The Prefs class is a singleton that implements management of preferences. It uses a stack of TWiki::Prefs::PrefsCache objects to store the preferences for global, web, user and topic contexts, and provides the means to look up preferences in these.
+ This package doesn't smell
-Preferences from different places stack on top of each other, so there are global preferences, then site, then web (and subweb and subsubweb), then topic, included topic and so on. Each level of the stack is tagged with a type identifier.
+ ---++ [[TWikiPluralsDotPm][TWiki::Plurals]]
-The module also maintains a separate of the preferences found in every topic and web it reads. This supports the lookup of preferences for webs and topics that are not on the stack, and must not be chained in (you can't allow a user to override protections from their home topic!)
+ Handle conversion of plural topic names to singular form.
-This package doesn't smell
+ This package has smell factor of *3*
-## <a name="TWiki::Prefs::Parser"></a> [[TWiki::Prefs::Parser|Main/TWikiPrefsParserDotPm]]
+ ---++ [[TWikiPrefsDotPm][TWiki::Prefs]]
-This Prefs-internal class is used to parse \* Set and \* Local statements from arbitrary text, and extract settings from meta objects. It is used by [[TopicPrefs]] to parse preference settings from topics.
+ The Prefs class is a singleton that implements management of preferences.
+ It uses a stack of TWiki::Prefs::PrefsCache objects to store the
+ preferences for global, web, user and topic contexts, and provides
+ the means to look up preferences in these.
-This class does no validation or duplicate-checking on the settings; it simply returns the recognized settings in the order it sees them in.
+ Preferences from different places stack on top of each other, so there
+ are global preferences, then site, then web (and subweb and subsubweb),
+ then topic, included topic and so on. Each level of the stack is tagged with
+ a type identifier.
-This package has smell factor of **1**
+ The module also maintains a separate of the preferences found in every topic
+ and web it reads. This supports the lookup of preferences for webs and topics
+ that are not on the stack, and must not be chained in (you can't allow
+ a user to override protections from their home topic!)
-## <a name="TWiki::Prefs::_PrefsCache"></a> [[TWiki::Prefs::PrefsCache|Main/TWikiPrefsPrefsCacheDotPm]]
+ This package doesn't smell
-The [[PrefsCache]] package holds a cache of topics that have been read in, using the [[TopicPrefs]] class. These functions manage that cache.
+ ---++ [[TWikiPrefsParserDotPm][TWiki::Prefs::Parser]]
-We maintain 2 hashes of values:
+ This Prefs-internal class is used to parse * Set and * Local statements
+ from arbitrary text, and extract settings from meta objects. It is used
+ by TopicPrefs to parse preference settings from topics.
-- \{locals\} Contains all locals at this level. Locals are values that only apply when the current topic is the topic where the local is defined. The variable names are decorated with the locality where they apply.
-- \{values\} contains all sets, locals, and all values inherited from the parent level
+ This class does no validation or duplicate-checking on the settings; it
+ simply returns the recognized settings in the order it sees them in.
-As each cache level is built, the values are copied down from the parent cache level. This sounds monstrously inefficient, but in fact perl does this a lot better than doing a multi-level lookup when a value is referenced. This is especially important when many prefs lookups may be done in a session, for example when searching.
+ This package has smell factor of *1*
-This package doesn't smell
+ ---++ [[TWikiPrefsPrefsCacheDotPm][TWiki::Prefs::PrefsCache]]
-## <a name="TWiki::Render"></a> [[TWiki::Render|Main/TWikiRenderDotPm]]
+ The PrefsCache package holds a cache of topics that have been read in, using
+ the TopicPrefs class. These functions manage that cache.
-This module provides most of the actual HTML rendering code in TWiki.
+ We maintain 2 hashes of values:
+ * {locals} Contains all locals at this level. Locals are values that
+ only apply when the current topic is the topic where the local is
+ defined. The variable names are decorated with the locality where
+ they apply.
+ * {values} contains all sets, locals, and all values inherited from
+ the parent level
-This package has smell factor of **19**
+ As each cache level is built, the values are copied down from the parent
+ cache level. This sounds monstrously inefficient, but in fact perl does
+ this a lot better than doing a multi-level lookup when a value is referenced.
+ This is especially important when many prefs lookups may be done in a
+ session, for example when searching.
-## <a name="TWiki::Sandbox"></a> [[TWiki::Sandbox|Main/TWikiSandboxDotPm]]
+ This package doesn't smell
-This object provides an interface to the outside world. All calls to system functions, or handling of file names, should be brokered by this object.
+ ---++ [[TWikiQueryHoistREsDotPm][TWiki::Query::HoistREs]]
-This package has smell factor of **3**
+ Static functions to extract regular expressions from queries. The REs can
+ be used in caching stores that use the TWiki standard inline meta-data
+ representation to pre-filter topic lists for more efficient query matching.
+
+ See =Store/RcsFile.pm= for an example of usage.
+
+ This package doesn't smell
+
+ ---++ [[TWikiQueryNodeDotPm][TWiki::Query]]
+
+ A Query object is a representation of a query over the TWiki database.
+
+ Fields are given by name, and values by strings or numbers. Strings should always be surrounded by 'single-quotes'. Numbers can be signed integers or decimals. Single quotes in values may be escaped using backslash (\).
+
+ See TWiki.QuerySearch for details of the query language. At the time of writing
+ only a subset of the entire query language is supported, for use in searching.
+
+ A query object implements the =evaluate= method as its general
+ contract with the rest of the world. This method does a "hard work" evaluation
+ of the parser tree. Of course, smarter Store implementations should be
+ able to do it better....
+
+ This package has smell factor of *2*
+
+ ---++ [[TWikiQueryParserDotPm][TWiki::Query::Parser]]
+
+ Parser for queries
+
+ This package doesn't smell
+
+ ---++ [[TWikiRenderDotPm][TWiki::Render]]
+
+ This module provides most of the actual HTML rendering code in TWiki.
+
+ This package has smell factor of *20*
-## <a name="TWiki::Search"></a> [[TWiki::Search|Main/TWikiSearchDotPm]]
+ ---++ [[TWikiSandboxDotPm][TWiki::Sandbox]]
-This module implements all the search functionality.
+ This object provides an interface to the outside world. All calls to
+ system functions, or handling of file names, should be brokered by
+ this object.
-This package has smell factor of **20**
+ NOTE: TWiki creates a singleton sandbox that is *shared* by all TWiki
+ runs under a single mod_perl instance. If any TWiki run modifies the
+ sandbox, that modification will carry over in to subsequent runs.
+ Be very, very careful!
-## <a name="TWiki::Store"></a> [[TWiki::Store|Main/TWikiStoreDotPm]]
+ This package has smell factor of *4*
-This module hosts the generic storage backend. This module provides the interface layer between the "real" store provider - which is hidden behind a handler - and the rest of the system. it is responsible for checking for topic existance, access permissions, and all the other general admin tasks that are common to all store implementations.
+ ---++ [[TWikiSearchDotPm][TWiki::Search]]
-This module knows nothing about how the data is actually _stored_ - that knowledge is entirely encapsulated in the handlers.
+ This module implements all the search functionality.
-The general contract for methods in the class requires that errors are signalled using exceptions. TWiki::AccessControlException is used for access control exceptions, and Error::Simple for all other types of error.
+ This package has smell factor of *15*
-This package has smell factor of **17**
+ ---++ [[TWikiStoreDotPm][TWiki::Store]]
-## <a name="TWiki::Store::_RcsFile"></a> [[TWiki::Store::RcsFile|Main/TWikiStoreRcsFileDotPm]]
+ This module hosts the generic storage backend. This module provides
+ the interface layer between the "real" store provider - which is hidden
+ behind a handler - and the rest of the system. it is responsible for
+ checking for topic existance, access permissions, and all the other
+ general admin tasks that are common to all store implementations.
-This class is PACKAGE PRIVATE to Store, and should never be used from anywhere else. Base class of implementations of stores that manipulate RCS format files.
+ This module knows nothing about how the data is actually _stored_ -
+ that knowledge is entirely encapsulated in the handlers.
-The general contract of the methods on this class and its subclasses calls for errors to be signalled by Error::Simple exceptions.
+ The general contract for methods in the class requires that errors
+ are signalled using exceptions. TWiki::AccessControlException is
+ used for access control exceptions, and Error::Simple for all other
+ types of error.
-Refer to Store.pm for models of usage.
+ This package has smell factor of *14*
-This package has smell factor of **9**
+ ---++ [[TWikiStoreQueryAlgorithmsBruteForceDotPm][TWiki::Store::QueryAlgorithms::BruteForce]]
-## <a name="TWiki::Store::_RcsLite"></a> [[TWiki::Store::RcsLite|Main/TWikiStoreRcsLiteDotPm]]
+ Default brute-force query algorithm
-This package does not publish any methods. It implements the virtual methods of the [[TWiki::Store::RcsFile|Main/TWikiStoreRcsFileDotPm]] superclass.
+ Has some basic optimisation: it hoists regular expressions out of the
+ query to use with grep, so we can narrow down the set of topics that we
+ have to evaluate the query on.
-Simple replacement for RCS. Doesn't support:
+ Not sure exactly where the breakpoint is between the
+ costs of hoisting and the advantages of hoisting. Benchmarks suggest
+ that it's around 6 topics, though this may vary depending on disk
+ speed and memory size. It also depends on the complexity of the query.
-- branches
-- locking
+ This package doesn't smell
-Neither of which are used (or needed) by TWiki.
+ ---++ [[TWikiStoreRcsFileDotPm][TWiki::Store::RcsFile]]
-This module doesn't know anything about the content of the topic
+ This class is PACKAGE PRIVATE to Store, and should never be
+ used from anywhere else. It is the base class of implementations of stores
+ that manipulate RCS format files.
-There is one of these object for each file stored under RCSLite.
+ The general contract of the methods on this class and its subclasses
+ calls for errors to be signalled by Error::Simple exceptions.
-This object is PACKAGE PRIVATE to Store, and should NEVER be used from anywhere else.
+ Refer to Store.pm for models of usage.
-FIXME:
+ This package has smell factor of *11*
-- need to tidy up dealing with \\n for differences
-- still have difficulty on line ending at end of sequences, consequence of doing a line based diff
+ ---++ [[TWikiStoreRcsLiteDotPm][TWiki::Store::RcsLite]]
-## <a name="File format"></a> File format
+ This package does not publish any methods. It implements the virtual
+ methods of the [[TWikiStoreRcsFileDotPm][TWiki::Store::RcsFile]] superclass.
+ Simple replacement for RCS. Doesn't support:
+ * branches
+ * locking
+ Neither of which are used (or needed) by TWiki.
+
+ This module doesn't know anything about the content of the topic
+
+ There is one of these object for each file stored under RCSLite.
+
+ This object is PACKAGE PRIVATE to Store, and should NEVER be
+ used from anywhere else.
+
+ FIXME:
+ * need to tidy up dealing with \n for differences
+ * still have difficulty on line ending at end of sequences, consequence of doing a line based diff
+
+ ---++ File format
+
+ <verbatim>
rcstext ::= admin {delta}* desc {deltatext}*
admin ::= head {num};
{ branch {num}; }
string ::= @{any character, with @ doubled}*@
newphrase ::= id word* ;
word ::= id | num | string | :
+ </verbatim>
+ Identifiers are case sensitive. Keywords are in lower case only. The
+ sets of keywords and identifiers can overlap. In most environments RCS
+ uses the ISO 8859/1 encoding: visible graphic characters are codes
+ 041-176 and 240-377, and white space characters are codes 010-015 and 040.
-Identifiers are case sensitive. Keywords are in lower case only. The sets of keywords and identifiers can overlap. In most environments RCS uses the ISO 8859/1 encoding: visible graphic characters are codes 041-176 and 240-377, and white space characters are codes 010-015 and 040.
+ Dates, which appear after the date keyword, are of the form Y.mm.dd.hh.mm.ss,
+ where Y is the year, mm the month (01-12), dd the day (01-31), hh the hour
+ (00-23), mm the minute (00-59), and ss the second (00-60). Y contains just
+ the last two digits of the year for years from 1900 through 1999, and all
+ the digits of years thereafter. Dates use the Gregorian calendar; times
+ use UTC.
-Dates, which appear after the date keyword, are of the form Y.mm.dd.hh.mm.ss, where Y is the year, mm the month (01-12), dd the day (01-31), hh the hour (00-23), mm the minute (00-59), and ss the second (00-60). Y contains just the last two digits of the year for years from 1900 through 1999, and all the digits of years thereafter. Dates use the Gregorian calendar; times use UTC.
+ The newphrase productions in the grammar are reserved for future extensions
+ to the format of RCS files. No newphrase will begin with any keyword already
+ in use.
-The newphrase productions in the grammar are reserved for future extensions to the format of RCS files. No newphrase will begin with any keyword already in use.
+ Revisions consist of a sequence of 'a' and 'd' edits that need to be
+ applied to rev N+1 to get rev N. Each edit has an offset (number of lines
+ from start) and length (number of lines). For 'a', the edit is followed by
+ length lines (the lines to be inserted in the text). For example:
-Revisions consist of a sequence of 'a' and 'd' edits that need to be applied to rev N+1 to get rev N. Each edit has an offset (number of lines from start) and length (number of lines). For 'a', the edit is followed by length lines (the lines to be inserted in the text). For example:
+ d1 3 means "delete three lines starting with line 1
+ a4 2 means "insert two lines at line 4'
+ xxxxxx is the new line 4
+ yyyyyy is the new line 5
-d1 3 means "delete three lines starting with line 1 a4 2 means "insert two lines at line 4' xxxxxx is the new line 4 yyyyyy is the new line 5
+ This package has smell factor of *2*
-This package has smell factor of **2**
+ ---++ [[TWikiStoreRcsWrapDotPm][TWiki::Store::RcsWrap]]
-## <a name="TWiki::Store::_RcsWrap"></a> [[TWiki::Store::RcsWrap|Main/TWikiStoreRcsWrapDotPm]]
+ This package does not publish any methods. It implements the
+ virtual methods of the [[TWikiStoreRcsFileDotPm][TWiki::Store::RcsFile]] superclass.
-This package does not publish any methods. It implements the virtual methods of the [[TWiki::Store::RcsFile|Main/TWikiStoreRcsFileDotPm]] superclass.
+ Wrapper around the RCS commands required by TWiki.
+ There is one of these object for each file stored under RCS.
-Wrapper around the RCS commands required by TWiki. There is one of these object for each file stored under RCS.
+ This package has smell factor of *3*
-This package has smell factor of **2**
+ ---++ [[TWikiStoreSearchAlgorithmsForkingDotPm][TWiki::Store::SearchAlgorithms::Forking]]
-## <a name="TWiki::Store::_SearchAlgorithms:"></a> [[TWiki::Store::SearchAlgorithms::Forking|Main/TWikiStoreSearchAlgorithmsForkingDotPm]]
+ Forking implementation of the RCS cache search.
-Forking implementation of the RCS cache search.
+ ---++ search($searchString, $topics, $options, $sDir) -> \%seen
+ Search .txt files in $dir for $searchString. See RcsFile::searchInWebContent
+ for details.
-## <a name="search($searchString, $topics, $"></a> search($searchString, $topics, $options, $sDir) -> \\%seen
+ This package has smell factor of *1*
-Search .txt files in $dir for $string. See [[RcsFile]]::searchInWebContent for details.
+ ---++ [[TWikiStoreSearchAlgorithmsPurePerlDotPm][TWiki::Store::SearchAlgorithms::PurePerl]]
-This package has smell factor of **2**
+ Pure perl implementation of the RCS cache search.
-## <a name="TWiki::Store::_SearchAlgorithms:"></a> [[TWiki::Store::SearchAlgorithms::Native|Main/TWikiStoreSearchAlgorithmsNativeDotPm]]
+ ---++ search($searchString, $topics, $options, $sDir) -> \%seen
+ Search .txt files in $dir for $string. See RcsFile::searchInWebContent
+ for details.
-Native implementation of the RCS cache search. Requires tools/native\_search to be built and installed.
+ This package doesn't smell
-## <a name="search($searchString, $topics, $"></a> search($searchString, $topics, $options, $sDir) -> \\%seen
+ ---++ [[TWikiTemplatesDotPm][TWiki::Templates]]
-Search .txt files in $dir for $string. See [[RcsFile]]::searchInWebContent for details.
+ Support for the TWiki template language.
-Rude and crude, this makes no attempt to handle UTF-8.
+ This package has smell factor of *2*
-This package doesn't smell
+ ---++ [[TWikiTimeDotPm][TWiki::Time]]
-## <a name="TWiki::Store::_SearchAlgorithms:"></a> [[TWiki::Store::SearchAlgorithms::PurePerl|Main/TWikiStoreSearchAlgorithmsPurePerlDotPm]]
+ Time handling functions.
-Pure perl implementation of the RCS cache search.
+ This package has smell factor of *7*
-## <a name="search($searchString, $topics, $"></a> search($searchString, $topics, $options, $sDir) -> \\%seen
+ ---++ [[TWikiUIChangeFormDotPm][TWiki::UI::ChangeForm]]
-Search .txt files in $dir for $string. See [[RcsFile]]::searchInWebContent for details.
+ Service functions used by the UI packages
-This package doesn't smell
+ This package doesn't smell
-## <a name="TWiki::Templates"></a> [[TWiki::Templates|Main/TWikiTemplatesDotPm]]
+ ---++ [[TWikiUIDotPm][TWiki::UI]]
-Support for the TWiki template language.
+ Service functions used by the UI packages
-This package has smell factor of **2**
+ This package doesn't smell
-## <a name="TWiki::Time"></a> [[TWiki::Time|Main/TWikiTimeDotPm]]
+ ---++ [[TWikiUIEditDotPm][TWiki::UI::Edit]]
-Time handling functions.
+ Edit command handler
-This package has smell factor of **7**
+ This package has smell factor of *1*
-## <a name="TWiki::UI::_ChangeForm"></a> [[TWiki::UI::ChangeForm|Main/TWikiUIChangeFormDotPm]]
+ ---++ [[TWikiUIManageDotPm][TWiki::UI::Manage]]
-Service functions used by the UI packages
+ UI functions for web, topic and user management
-This package doesn't smell
+ This package has smell factor of *5*
-## <a name="TWiki::UI"></a> [[TWiki::UI|Main/TWikiUIDotPm]]
+ ---++ [[TWikiUIOopsDotPm][TWiki::UI::Oops]]
-Service functions used by the UI packages
+ UI delegate for oops function
-This package doesn't smell
+ This package doesn't smell
-## <a name="TWiki::UI::Edit"></a> [[TWiki::UI::Edit|Main/TWikiUIEditDotPm]]
+ ---++ [[TWikiUIRDiffDotPm][TWiki::UI::RDiff]]
-Edit command handler
+ UI functions for diffing.
-This package has smell factor of **1**
+ This package has smell factor of *12*
-## <a name="TWiki::UI::Manage"></a> [[TWiki::UI::Manage|Main/TWikiUIManageDotPm]]
+ ---++ [[TWikiUIRegisterDotPm][TWiki::UI::Register]]
-UI functions for web, topic and user management
+ User registration handling.
-This package has smell factor of **5**
+ This package has smell factor of *5*
-## <a name="TWiki::UI::Oops"></a> [[TWiki::UI::Oops|Main/TWikiUIOopsDotPm]]
+ ---++ [[TWikiUISaveDotPm][TWiki::UI::Save]]
-UI delegate for oops function
+ UI delegate for save function
-This package doesn't smell
+ This package has smell factor of *1*
-## <a name="TWiki::UI::RDiff"></a> [[TWiki::UI::RDiff|Main/TWikiUIRDiffDotPm]]
+ ---++ [[TWikiUISearchDotPm][TWiki::UI::Search]]
-UI functions for diffing.
+ UI functions for searching.
-This package has smell factor of **12**
+ This package has smell factor of *2*
-## <a name="TWiki::UI::Register"></a> [[TWiki::UI::Register|Main/TWikiUIRegisterDotPm]]
+ ---++ [[TWikiUIStatisticsDotPm][TWiki::UI::Statistics]]
-User registration handling.
+ Statistics extraction and presentation
-This package has smell factor of **19**
+ This package has smell factor of *4*
-## <a name="TWiki::UI::Save"></a> [[TWiki::UI::Save|Main/TWikiUISaveDotPm]]
+ ---++ [[TWikiUIUploadDotPm][TWiki::UI::Upload]]
-UI delegate for save function
+ UI delegate for attachment management functions
-This package has smell factor of **1**
+ This package has smell factor of *3*
-## <a name="TWiki::UI::Search"></a> [[TWiki::UI::Search|Main/TWikiUISearchDotPm]]
+ ---++ [[TWikiUIViewDotPm][TWiki::UI::View]]
-UI functions for searching.
+ UI delegate for view function
-This package has smell factor of **3**
+ This package has smell factor of *2*
-## <a name="TWiki::UI::Statistics"></a> [[TWiki::UI::Statistics|Main/TWikiUIStatisticsDotPm]]
-
-Statistics extraction and presentation
-
-This package has smell factor of **4**
+ ---++ [[TWikiUserMappingDotPm][TWiki::UserMapping]]
-## <a name="TWiki::UI::Upload"></a> [[TWiki::UI::Upload|Main/TWikiUIUploadDotPm]]
+ This is a virtual base class (a.k.a an interface) for all user mappers. It is
+ *not* useable as a mapping in TWiki - use the BaseUserMapping for default
+ behaviour.
-UI delegate for attachment management functions
+ User mapping is the process by which TWiki maps from a username (a login name)
+ to a display name and back. It is also where groups are maintained.
-This package has smell factor of **3**
+ See TWiki::Users::BaseUserMapping and TWiki::Users::TWikiUserMapping for
+ the default implementations of this interface.
-## <a name="TWiki::UI::View"></a> [[TWiki::UI::View|Main/TWikiUIViewDotPm]]
+ If you want to write a user mapper, you will need to implement the methods
+ described in this class.
-UI delegate for view function
+ User mappings work by mapping both login names and display names to a
+ _canonical user id_. This user id is composed from a prefix that defines
+ the mapper in use (something like 'BaseUserMapping_' or 'LdapUserMapping_')
+ and a unique user id that the mapper uses to identify the user.
-This package has smell factor of **2**
+ The null prefix is reserver for the TWikiUserMapping for compatibility
+ with old TWiki releases.
-## <a name="TWiki::User"></a> [[TWiki::User|Main/TWikiUserDotPm]]
+ __Note:__ in all the following documentation, =$user= refers to a
+ *canonical user id*.
-A User object is an internal representation of a user in the real world. The object knows about users having login names, wiki names, personal topics, and email addresses.
+ This package has smell factor of *1*
-This package has smell factor of **4**
+ ---++ [[TWikiUsersApacheHtpasswdUserDotPm][TWiki::Users::ApacheHtpasswdUser]]
-## <a name="TWiki::Users::_ApacheHtpasswdUse"></a> [[TWiki::Users::ApacheHtpasswdUser|Main/TWikiUsersApacheHtpasswdUserDotPm]]
+ Password manager that uses Apache::HtPasswd to manage users and passwords.
-Password manager that uses Apache::HtPasswd to manage users and passwords.
+ Subclass of [[TWikiUsersPasswordDotPm][ =TWiki::Users::Password= ]].
+ See documentation of that class for descriptions of the methods of this class.
-Subclass of [[ TWiki::Users::Password |Main/TWikiUsersPasswordDotPm]]. See documentation of that class for descriptions of the methods of this class.
+ Duplicates functionality of
+ [[TWikiUsersHtPasswdUserDotPm][ =TWiki::Users::HtPasswdUser=]];
+ provided mainly as an example of how to write a new password manager.
-Duplicates functionality of [[ =TWiki::Users::HtPasswdUser=|Main/TWikiUsersHtPasswdUserDotPm]]; provided mainly as an example of how to write a new password manager.
+ This package has smell factor of *1*
-This package doesn't smell
+ ---++ [[TWikiUsersDotPm][TWiki::Users]]
+ This package provides services for the lookup and manipulation of login and
+ wiki names of users, and their authentication.
-## <a name="TWiki::Users"></a> [[TWiki::Users|Main/TWikiUsersDotPm]]
+ It is a Facade that presents a common interface to the User Mapping
+ and Password modules. The rest of the core should *only* use the methods
+ of this package, and should *never* call the mapping or password managers
+ directly.
-Singleton object that handles mapping of users to wikinames and vice versa, and user authentication checking.
+ TWiki uses the concept of a _login name_ which is used to authenticate a
+ user. A login name maps to a _wiki name_ that is used to identify the user
+ for display. Each login name is unique to a single user, though several
+ login names may map to the same wiki name.
-This package has smell factor of **2**
+ Using this module (and the associated plug-in user mapper) TWiki supports
+ the concept of _groups_. Groups are sets of login names that are treated
+ equally for the purposes of access control. Group names do not have to be
+ wiki names, though it is helpful for display if they are.
-## <a name="TWiki::Users::Password"></a> [[TWiki::Users::Password|Main/TWikiUsersPasswordDotPm]]
+ Internally in the code TWiki uses something referred to as a _canonical user
+ id_ or just _user id_. The user id is also used externally to uniquely identify
+ the user when (for example) recording topic histories. The user id is *usually*
+ just the login name, but it doesn't need to be. It just has to be a unique
+ 7-bit alphanumeric and underscore string that can be mapped to/from login
+ and wiki names by the user mapper.
-Base class of all password handlers. Default behaviour is no passwords, so anyone can be anyone they like.
+ The canonical user id should *never* be seen by a user. On the other hand,
+ core code should never use anything *but* a canonical user id to refer
+ to a user.
-The methods of this class should be overridded by subclasses that want to implement other password handling methods.
+ *Terminology*
+ * A *login name* is the name used to log in to TWiki. Each login name is
+ assumed to be unique to a human. The Password module is responsible for
+ authenticating and manipulating login names.
+ * A *canonical user id* is an internal TWiki representation of a user. Each
+ canonical user id maps 1:1 to a login name.
+ * A *wikiname* is how a user is displayed. Many user ids may map to a
+ single wikiname. The user mapping module is responsible for mapping
+ the user id to a wikiname.
+ * A *group id* represents a group of users and other groups.
+ The user mapping module is responsible for mapping from a group id to
+ a list of canonical user ids for the users in that group.
+ * An *email* is an email address asscoiated with a *login name*. A single
+ login name may have many emails.
-This package has smell factor of **1**
+ *NOTE:*
+ * wherever the code references $user, its a canonical_id
+ * wherever the code references $group, its a group_name
-## <a name="TWiki::Users::_TWikiUserMapping"></a> [[TWiki::Users::TWikiUserMapping|Main/TWikiUsersTWikiUserMappingDotPm]]
+ This package has smell factor of *5*
-User mapping is the process by which TWiki maps from a username (a login name) to a wikiname and back. It is also where groups are maintained.
+ ---++ [[TWikiUsersHtPasswdUserDotPm][TWiki::Users::HtPasswdUser]]
-By default TWiki maintains user topics and group topics in the Main that define users and group. These topics are
+ Support for htpasswd and htdigest format password files.
-- TWikiUsers - stores a mapping from usernames to TWiki names
-- WikiName - for each user, stores info about the user
-- GroupNameGroup - for each group, a topic ending with "Group" stores a list of users who are part of that group.
+ Subclass of [[TWikiUsersPasswordDotPm][ =TWiki::Users::Password= ]].
+ See documentation of that class for descriptions of the methods of this class.
-Many sites will want to override this behaviour, for example to get users and groups from a corporate database.
+ This package has smell factor of *3*
-This class implements the basic TWiki behaviour using topics to store users, but is also designed to be subclassed so that other services can be used.
+ ---++ [[TWikiUsersPasswordDotPm][TWiki::Users::Password]]
-Subclasses should be named 'XxxxUserMapping' so that configure can find them.
+ Base class of all password handlers. Default behaviour is no passwords,
+ so anyone can be anyone they like.
-**All** methods in this class should be implemented by subclasses.
+ The methods of this class should be overridded by subclasses that want
+ to implement other password handling methods.
-This package has smell factor of **3**
+ This package doesn't smell
-There were a total of **200** smells
+ There were a total of *192* smells
<li><a href="#EXACT( text1, text2 ) -- compare"> EXACT( text1, text2 ) -- compare two text strings</a></li>
<li><a href="#EXEC( formula ) -- execute a spr"> EXEC( formula ) -- execute a spreadsheet formula</a></li>
<li><a href="#EXISTS( topic ) -- check if topi"> EXISTS( topic ) -- check if topic exists</a></li>
+ <li><a href="#EXP( num ) -- exponent (e) raise"> EXP( num ) -- exponent (e) raised to the power of a number</a></li>
<li><a href="#FIND( string, text, start ) -- f"> FIND( string, text, start ) -- find one string within another string</a></li>
- <li><a href="#FORMAT( type, prec, number ) --"> FORMAT( type, prec, number ) -- format a number to a certain type and precision</a></li>
- <li><a href="#FORMATTIME( serial, text ) -- co"> FORMATTIME( serial, text ) -- convert a serialized date into a date string</a></li>
+ <li><a href="#FORMAT( type, precision, number"> FORMAT( type, precision, number ) -- format a number to a certain type and precision</a></li>
<li><a href="#FORMATGMTIME( serial, text ) --"> FORMATGMTIME( serial, text ) -- convert a serialized date into a GMT date string</a></li>
+ <li><a href="#FORMATTIME( serial, text ) -- co"> FORMATTIME( serial, text ) -- convert a serialized date into a date string</a></li>
+ <li><a href="#FORMATTIMEDIFF( unit, precision,"> FORMATTIMEDIFF( unit, precision, time ) -- convert elapsed time to a string</a></li>
<li><a href="#GET( name ) -- get the value of"> GET( name ) -- get the value of a previously set variable</a></li>
<li><a href="#IF( condition, value if true, va"> IF( condition, value if true, value if 0 ) -- return a value based on a condition</a></li>
<li><a href="#INT( formula ) -- evaluate formu"> INT( formula ) -- evaluate formula and round down to nearest integer</a></li>
<li><a href="#LISTSORT( list ) -- sort a list"> LISTSORT( list ) -- sort a list</a></li>
<li><a href="#LISTTRUNCATE( size, list ) -- tr"> LISTTRUNCATE( size, list ) -- truncate list to size</a></li>
<li><a href="#LISTUNIQUE( list ) -- remove all"> LISTUNIQUE( list ) -- remove all duplicates from a list</a></li>
+ <li><a href="#LN( num ) -- natural logarithm o"> LN( num ) -- natural logarithm of a number</a></li>
+ <li><a href="#LOG( num, base ) -- logarithm of"> LOG( num, base ) -- logarithm of a number to a given base</a></li>
<li><a href="#LOWER( text ) -- lower case stri"> LOWER( text ) -- lower case string of a text</a></li>
<li><a href="#MAX( list ) - biggest value of a"> MAX( list ) - biggest value of a list or range of cells</a></li>
<li><a href="#MEDIAN( list ) -- median of a li"> MEDIAN( list ) -- median of a list or range of cells</a></li>
<li><a href="#ODD( num ) -- test for odd numbe"> ODD( num ) -- test for odd number</a></li>
<li><a href="#OR( list ) -- logical OR of a li"> OR( list ) -- logical OR of a list</a></li>
<li><a href="#PERCENTILE( num, list ) -- perce"> PERCENTILE( num, list ) -- percentile of a list or range of cells</a></li>
+ <li><a href="#PI( ) -- mathematical constant P"> PI( ) -- mathematical constant Pi, 3.14159265358979</a></li>
<li><a href="#PRODUCT( list ) -- product of a"> PRODUCT( list ) -- product of a list or range of cells</a></li>
<li><a href="#PROPER( text ) -- properly capit"> PROPER( text ) -- properly capitalize text</a></li>
<li><a href="#PROPERSPACE( text ) -- properly"> PROPERSPACE( text ) -- properly space out WikiWords</a></li>
<li><a href="#SETIFEMPTY( name, value ) -- set"> SETIFEMPTY( name, value ) -- set a variable only if empty</a></li>
<li><a href="#SETM( name, formula ) -- update"> SETM( name, formula ) -- update an existing variable based on a formula</a></li>
<li><a href="#SIGN( num ) -- sign of a number"> SIGN( num ) -- sign of a number</a></li>
+ <li><a href="#SQRT( num ) -- square root of a"> SQRT( num ) -- square root of a number</a></li>
<li><a href="#SUBSTITUTE( text, old, new, inst"> SUBSTITUTE( text, old, new, instance, option ) -- substitute text</a></li>
<li><a href="#SUM( list ) -- sum of a list or"> SUM( list ) -- sum of a list or range of cells</a></li>
<li><a href="#SUMDAYS( list ) -- sum the days"> SUMDAYS( list ) -- sum the days in a list or range of cells</a></li>
### <a name="EVAL( formula ) -- evaluate a si"></a> EVAL( formula ) -- evaluate a simple mathematical formula
- Addition, substraction, multiplication, division and modulus of numbers are supported. Any nesting is permitted
+- Numbers may be decimal integers (`1234`), binary integers (`0b1110011`), octal integers (`01234`), hexadecimal integers (`0x1234`) or of exponential notation (`12.34e-56`)
- Syntax: <code>**$EVAL( formula )**</code>
- Example: <code>**%CALC\{"$EVAL( (5 \* 3) / 2 + 1.1 )"\}%**</code> returns <code>**8\.6**</code>
- Related: <code>[[$EXEC()|Main/WebHome#FuncEXEC]]</code>, <code>[[$INT()|Main/WebHome#FuncINT]]</code>, <code>[[$MOD()|Main/WebHome#FuncMOD]]</code>, <code>[[$ROUND()|Main/WebHome#FuncROUND]]</code>, <code>[[$VALUE()|Main/WebHome#FuncVALUE]]</code>
### <a name="EXISTS( topic ) -- check if topi"></a> EXISTS( topic ) -- check if topic exists
-- Topic can be `TopicName` or a `Web.TopicName`
+- Topic can be `TopicName` or a `Web.TopicName`. Current web is used if web is not specified.
- Syntax: <code>**$EXISTS( topic )**</code>
- Example: <code>**%CALC\{"$EXISTS(WebHome)"\}%**</code> returns <code>**1**</code>
- Example: <code>**%CALC\{"$EXISTS(ThisDoesNotExist)"\}%**</code> returns <code>****</code>
+<a name="FuncEXP"></a>
+
+### <a name="EXP( num ) -- exponent (e) raise"></a> EXP( num ) -- exponent (e) raised to the power of a number
+
+- EXP is the inverse of the LN function
+- Syntax: <code>**$EXP( num )**</code>
+- Example: <code>**%CALC\{"$EXP(1)"\}%**</code> returns <code>**2\.71828182845905**</code>
+- Related: <code>[[$LN()|Main/WebHome#FuncLN]]</code>, <code>[[$LOG()|Main/WebHome#FuncLOG]]</code>
+
<a name="FuncFIND"></a>
### <a name="FIND( string, text, start ) -- f"></a> FIND( string, text, start ) -- find one string within another string
<a name="FuncFORMAT"></a>
-### <a name="FORMAT( type, prec, number ) --"></a><a name="FORMAT( type, prec, number ) -- "></a> FORMAT( type, prec, number ) -- format a number to a certain type and precision
-
-- Type can be COMMA for comma format, DOLLAR for Dollar format, KB for Kilo Byte format, MB for Mega Byte format, KBMB for Kilo/Mega/Giga/Tera Byte auto-adjust format, NUMBER for number, and PERCENT for percent format
+### <a name="FORMAT( type, precision, number"></a><a name="FORMAT( type, precision, number "></a> FORMAT( type, precision, number ) -- format a number to a certain type and precision
+
+- Supported `type`:
+ - `COMMA` for comma format, such as `12,345.68`
+ - `DOLLAR` for Dollar format, such as `$12,345.68`
+ - `KB` for Kilo Byte format, such as `1205.63 KB`
+ - `MB` for Mega Byte format, such as `1.18 MB`
+ - `KBMB` for Kilo/Mega/Giga/Tera Byte auto-adjust format
+ - `NUMBER` for number, such as `12345.7`
+ - `PERCENT` for percent format, such as `12.3%`
+- The `precision` indicates the the number of digits after the dot
- Syntax: <code>**$FORMAT( type, prec, number )**</code>
- Example: <code>**%CALC\{"$FORMAT(COMMA, 2, 12345.6789)"\}%**</code> returns <code>**12,345.68**</code>
- Example: <code>**%CALC\{"$FORMAT(DOLLAR, 2, 12345.67)"\}%**</code> returns <code>**$12,345.68**</code>
- Example: <code>**%CALC\{"$FORMAT(KBMB, 2, 1234567890)"\}%**</code> returns <code>**1\.15 GB**</code>
- Example: <code>**%CALC\{"$FORMAT(NUMBER, 1, 12345.67)"\}%**</code> returns <code>**12345\.7**</code>
- Example: <code>**%CALC\{"$FORMAT(PERCENT, 1, 0.1234567)"\}%**</code> returns <code>**12\.3%**</code>
-- Related: <code>[[$ROUND()|Main/WebHome#FuncROUND]]</code>
+- Related: <code>[[$FORMATTIME()|Main/WebHome#FuncFORMATTIME]]</code>, <code>[[$FORMATTIMEDIFF()|Main/WebHome#FuncFORMATTIMEDIFF]]</code>, <code>[[$ROUND()|Main/WebHome#FuncROUND]]</code>
+
+<a name="FuncFORMATGMTIME"></a>
+
+### <a name="FORMATGMTIME( serial, text ) --"></a><a name="FORMATGMTIME( serial, text ) -- "></a> FORMATGMTIME( serial, text ) -- convert a serialized date into a GMT date string
+
+- The date string represents the time in Greenwich time zone. Same variable expansion as in `$FORMATTIME()`.
+- Syntax: <code>**$FORMATGMTIME( serial, text )**</code>
+- Example: <code>**%CALC\{"$FORMATGMTIME(1041379200, $day $mon $year)"\}%**</code> returns <code>**01 Jan 2003**</code>
+- Related: <code>[[$FORMATTIME()|Main/WebHome#FuncFORMATTIME]]</code>, <code>[[$FORMATTIMEDIFF()|Main/WebHome#FuncFORMATTIMEDIFF]]</code>, <code>[[$TIME()|Main/WebHome#FuncTIME]]</code>, <code>[[$TIMEADD()|Main/WebHome#FuncTIMEADD]]</code>, <code>[[$TIMEDIFF()|Main/WebHome#FuncTIMEDIFF]]</code>, <code>[[$TODAY()|Main/WebHome#FuncTODAY]]</code>
<a name="FuncFORMATTIME"></a>
- The following variables in `text` are expanded: `$second` (seconds, 00..59); `$minute` (minutes, 00..59); `$hour` (hours, 00..23); `$day` (day of month, 01..31); `$month` (month, 01..12); `$mon` (month in text format, Jan..Dec); `$year` (4 digit year, 1999); `$ye` (2 digit year, 99), `$wd` (day number of the week, 1 for Sunday, 2 for Monday, etc), `$wday` (day of the week, Sun..Sat), `$weekday` (day of the week, Sunday..Saturday), `$yearday` (day of the year, 1..365, or 1..366 in leap years). Date is assumed to be server time; add `GMT` to indicate Greenwich time zone.
- Syntax: <code>**$FORMATTIME( serial, text )**</code>
- Example: <code>**%CALC\{"$FORMATTIME(0, $year/$month/$day GMT)"\}%**</code> returns <code>**1970/01/01 GMT**</code>
-- Related: <code>[[$FORMATGMTIME()|Main/WebHome#FuncFORMATGMTIME]]</code>, <code>[[$TIME()|Main/WebHome#FuncTIME]]</code>, <code>[[$TIMEADD()|Main/WebHome#FuncTIMEADD]]</code>, <code>[[$TIMEDIFF()|Main/WebHome#FuncTIMEDIFF]]</code>, <code>[[$TODAY()|Main/WebHome#FuncTODAY]]</code>
+- Related: <code>[[$FORMATGMTIME()|Main/WebHome#FuncFORMATGMTIME]]</code>, <code>[[$TIME()|Main/WebHome#FuncTIME]]</code>, <code>[[$FORMATTIMEDIFF()|Main/WebHome#FuncFORMATTIMEDIFF]]</code>, <code>[[$TIMEADD()|Main/WebHome#FuncTIMEADD]]</code>, <code>[[$TIMEDIFF()|Main/WebHome#FuncTIMEDIFF]]</code>, <code>[[$TODAY()|Main/WebHome#FuncTODAY]]</code>
-<a name="FuncFORMATGMTIME"></a>
+<a name="FuncFORMATTIMEDIFF"></a>
-### <a name="FORMATGMTIME( serial, text ) --"></a><a name="FORMATGMTIME( serial, text ) -- "></a> FORMATGMTIME( serial, text ) -- convert a serialized date into a GMT date string
+### <a name="FORMATTIMEDIFF( unit, precision,"></a> FORMATTIMEDIFF( unit, precision, time ) -- convert elapsed time to a string
-- The date string represents the time in Greenwich time zone. Same variable expansion as in `$FORMATTIME()`.
-- Syntax: <code>**$FORMATGMTIME( serial, text )**</code>
-- Example: <code>**%CALC\{"$FORMATGMTIME(1041379200, $day $mon $year)"\}%**</code> returns <code>**01 Jan 2003**</code>
-- Related: <code>[[$FORMATTIME()|Main/WebHome#FuncFORMATTIME]]</code>, <code>[[$TIME()|Main/WebHome#FuncTIME]]</code>, <code>[[$TIMEADD()|Main/WebHome#FuncTIMEADD]]</code>, <code>[[$TIMEDIFF()|Main/WebHome#FuncTIMEDIFF]]</code>, <code>[[$TODAY()|Main/WebHome#FuncTODAY]]</code>
+- Convert elapsed `time` to a human readable format, such as: `12 hours and 3 minutes`
+- The input `unit` can be `second`, `minute`, `hour`, `day`, `month`, `year`. Note: An approximation is used for month and year calculations.
+- The `precision` indicates the number of output units to use
+- Syntax: <code>**$FORMATTIMEDIFF( unit, precision, time )**</code>
+- Example: <code>**%CALC\{"$FORMATTIMEDIFF(min, 1, 200)"\}%**</code> returns <code>**3 hours**</code>
+- Example: <code>**%CALC\{"$FORMATTIMEDIFF(min, 2, 200)"\}%**</code> returns <code>**3 hours and 20 minutes**</code>
+- Example: <code>**%CALC\{"$FORMATTIMEDIFF(min, 1, 1640)"\}%**</code> returns <code>**1 day**</code>
+- Example: <code>**%CALC\{"$FORMATTIMEDIFF(min, 2, 1640)"\}%**</code> returns <code>**1 day and 3 hours**</code>
+- Example: <code>**%CALC\{"$FORMATTIMEDIFF(min, 3, 1640)"\}%**</code> returns <code>**1 day, 3 hours and 20 minutes**</code>
+- Related: <code>[[$FORMATTIME()|Main/WebHome#FuncFORMATTIME]]</code>, <code>[[$TIME()|Main/WebHome#FuncTIME]]</code>, <code>[[$TIMEADD()|Main/WebHome#FuncTIMEADD]]</code>, <code>[[$TIMEDIFF()|Main/WebHome#FuncTIMEDIFF]]</code>
<a name="FuncGET"></a>
### <a name="INT( formula ) -- evaluate formu"></a> INT( formula ) -- evaluate formula and round down to nearest integer
- Addition, substraction, multiplication, division and modulus of numbers are supported. Any nesting is permitted
+- Numbers may be decimal integers (`1234`), binary integers (`0b1110011`), octal integers (`01234`), hexadecimal integers (`0x1234`) or of exponential notation (`12.34e-56`)
+- If you expect a single decimal integer value with leading zeros, use <code>**$INT( $VALUE( number ) )**</code>
- Syntax: <code>**$INT( formula )**</code>
- Example: <code>**%CALC\{"$INT(10 / 4)"\}%**</code> returns <code>**2**</code>
+- Example: <code>**%CALC\{"$INT($VALUE(09))"\}%**</code> returns <code>**9**</code>
- Related: <code>[[$EVAL()|Main/WebHome#FuncEVAL]]</code>, <code>[[$ROUND()|Main/WebHome#FuncROUND]]</code>, <code>[[$VALUE()|Main/WebHome#FuncVALUE]]</code>
<a name="FuncLEFT"></a>
- Example: <code>**%CALC\{"$LISTUNIQUE(Apple, Orange, Apple, Kiwi)"\}%**</code> returns <code>**Apple, Orange, Kiwi**</code>
- Related: <code>[[$COUNTITEMS()|Main/WebHome#FuncCOUNTITEMS]]</code>, <code>[[$COUNTSTR()|Main/WebHome#FuncCOUNTSTR]]</code>, <code>[[$LIST()|Main/WebHome#FuncLIST]]</code>, <code>[[$LISTIF()|Main/WebHome#FuncLISTIF]]</code>, <code>[[$LISTITEM()|Main/WebHome#FuncLISTITEM]]</code>, <code>[[$LISTMAP()|Main/WebHome#FuncLISTMAP]]</code>, <code>[[$LISTREVERSE()|Main/WebHome#FuncLISTREVERSE]]</code>, <code>[[$LISTSIZE()|Main/WebHome#FuncLISTSIZE]]</code>, <code>[[$LISTSORT()|Main/WebHome#FuncLISTSORT]]</code>, <code>[[$SUM()|Main/WebHome#FuncSUM]]</code>
+<a name="FuncLN"></a>
+
+### <a name="LN( num ) -- natural logarithm o"></a> LN( num ) -- natural logarithm of a number
+
+- LN is the inverse of the EXP function
+- Syntax: <code>**$LN( num )**</code>
+- Example: <code>**%CALC\{"$LN(10)"\}%**</code> returns <code>**2\.30258509299405**</code>
+- Related: <code>[[$EXP()|Main/WebHome#FuncEXP]]</code>, <code>[[$LOG()|Main/WebHome#FuncLOG]]</code>
+
+<a name="FuncLOG"></a>
+
+### <a name="LOG( num, base ) -- logarithm of"></a> LOG( num, base ) -- logarithm of a number to a given base
+
+- base-10 logarithm of a number (if base is 0 or not specified), else logarithm of a number to the given base
+- Syntax: <code>**$LOG( num, _base_ )**</code>
+- Example: <code>**%CALC\{"$LOG(1000)"\}%**</code> returns <code>**3**</code>
+- Example: <code>**%CALC\{"$LOG(16, 2)"\}%**</code> returns <code>**4**</code>
+- Related: <code>[[$EXP()|Main/WebHome#FuncEXP]]</code>, <code>[[$LN()|Main/WebHome#FuncLN]]</code>
+
<a name="FuncLOWER"></a>
### <a name="LOWER( text ) -- lower case stri"></a> LOWER( text ) -- lower case string of a text
- Example: <code>**%CALC\{"$PERCENTILE(75, 400, 200, 500, 100, 300)"\}%**</code> returns <code>**450**</code>
- Related: <code>[[$LIST()|Main/WebHome#FuncLIST]]</code>, <code>[[$MAX()|Main/WebHome#FuncMAX]]</code>, <code>[[$MEDIAN()|Main/WebHome#FuncMEDIAN]]</code>, <code>[[$MIN()|Main/WebHome#FuncMIN]]</code>
+<a name="FuncPI"></a>
+
+### <a name="PI( ) -- mathematical constant P"></a> PI( ) -- mathematical constant Pi, 3.14159265358979
+
+- Syntax: <code>**$PI( )**</code>
+- Example: <code>**%CALC\{"$PI()"\}%**</code> returns <code>**3\.14159265358979**</code>
+
<a name="FuncPRODUCT"></a>
### <a name="PRODUCT( list ) -- product of a"></a><a name="PRODUCT( list ) -- product of a "></a> PRODUCT( list ) -- product of a list or range of cells
- Capitalize letters that follow any character other than a letter; convert all other letters to lowercase letters
- Syntax: <code>**$PROPER( text )**</code>
-- Example: <code>**%CALC\{"PROPER(a small STEP)"\}%**</code> returns <code>**A Small Step**</code>
-- Example: <code>**%CALC\{"PROPER(f1 (formula-1))"\}%**</code> returns <code>**F1 (Formula-1)**</code>
+- Example: <code>**%CALC\{"$PROPER(a small STEP)"\}%**</code> returns <code>**A Small Step**</code>
+- Example: <code>**%CALC\{"$PROPER(f1 (formula-1))"\}%**</code> returns <code>**F1 (Formula-1)**</code>
- Related: <code>[[$LOWER()|Main/WebHome#FuncLOWER]]</code>, <code>[[$PROPERSPACE()|Main/WebHome#FuncPROPERSPACE]]</code>, <code>[[$TRIM()|Main/WebHome#FuncTRIM]]</code>, <code>[[$UPPER()|Main/WebHome#FuncUPPER]]</code>
<a name="FuncPROPERSPACE"></a>
### <a name="PROPERSPACE( text ) -- properly"></a><a name="PROPERSPACE( text ) -- properly "></a> PROPERSPACE( text ) -- properly space out WikiWords
-- Properly spaces out [[WikiWords]] preceeded by white space, parenthesis, or <code>**]\[**</code>. Words listed in the DONTSPACE [[TWikiPreferences]] variable or DONTSPACE Plugins setting are excluded
+- Properly spaces out %SYSTEMWEB%.WikiWords preceeded by white space, parenthesis, or <code>**]\[**</code>. Words listed in the DONTSPACE %SYSTEMWEB%.TWikiPreferences variable or DONTSPACE Plugins setting are excluded
- Syntax: <code>**$PROPERSPACE( text )**</code>
- Example: Assuming DONTSPACE contains MacDonald: <code>**%CALC\{"$PROPERSPACE(Old MacDonald had a ServerFarm, EeEyeEeEyeOh)"\}%**</code> returns <code>**Old MacDonald had a Server Farm, Ee Eye Ee Eye Oh**</code>
- Related: <code>[[$LOWER()|Main/WebHome#FuncLOWER]]</code>, <code>[[$PROPER()|Main/WebHome#FuncPROPER]]</code>, <code>[[$TRIM()|Main/WebHome#FuncTRIM]]</code>, <code>[[$UPPER()|Main/WebHome#FuncUPPER]]</code>
### <a name="SEARCH( string, text, start ) --"></a> SEARCH( string, text, start ) -- search a string within a text
-- Finds one text `string`, within another `text`, and returns the number of the starting position of `string`, from the first character of `text`. This search is a [[RegularExpression]] search; use `$FIND()` for non-regular expression searching. Starting position is 1; a 0 is returned if nothing is matched
+- Finds one text `string`, within another `text`, and returns the number of the starting position of `string`, from the first character of `text`. This search is a %SYSTEMWEB%.RegularExpression search; use `$FIND()` for non-regular expression searching. Starting position is 1; a 0 is returned if nothing is matched
- Syntax: <code>**$SEARCH( string, text, _start_ )**</code>
- Example: <code>**%CALC\{"$SEARCH([uy], fluffy)"\}%**</code> returns <code>**3**</code>
- Example: <code>**%CALC\{"$SEARCH([uy], fluffy, 3)"\}%**</code> returns <code>**6**</code>
- Example: <code>**%CALC\{"$SIGN(-12.5)"\}%**</code> returns <code>**-1**</code>
- Related: <code>[[$ABS()|Main/WebHome#FuncABS]]</code>, <code>[[$EVAL()|Main/WebHome#FuncEVAL]]</code>, <code>[[$EVEN()|Main/WebHome#FuncEVEN]]</code>, <code>[[$INT()|Main/WebHome#FuncINT]]</code>, <code>[[$NOT()|Main/WebHome#FuncNOT]]</code>, <code>[[$ODD()|Main/WebHome#FuncODD]]</code>
+<a name="FuncSQRT"></a>
+
+### <a name="SQRT( num ) -- square root of a"></a><a name="SQRT( num ) -- square root of a "></a> SQRT( num ) -- square root of a number
+
+- Syntax: <code>**$SQRT( num )**</code>
+- Example: <code>**%CALC\{"$SQRT(16)"\}%**</code> returns <code>**4**</code>
+
<a name="FuncSUBSTITUTE"></a>
### <a name="SUBSTITUTE( text, old, new, inst"></a> SUBSTITUTE( text, old, new, instance, option ) -- substitute text
-- Substitutes `new` text for `old` text in a `text` string. `instance` specifies which occurance of `old` you want to replace. If you specify `instance`, only that instance is replaced. Otherwise, every occurance is changed to the new text. A literal search is performed by default; a [[RegularExpression]] search if the `option` is set to <code>**r**</code>
+- Substitutes `new` text for `old` text in a `text` string. `instance` specifies which occurance of `old` you want to replace. If you specify `instance`, only that instance is replaced. Otherwise, every occurance is changed to the new text. A literal search is performed by default; a %SYSTEMWEB%.RegularExpression search if the `option` is set to <code>**r**</code>
- Syntax: <code>**$SUBSTITUTE( text, old, _new_, _instance_, _option_ )**</code>
- Example: <code>**%CALC\{"$SUBSTITUTE(Good morning, morning, day)"\}%**</code> returns <code>**Good day**</code>
- Example: <code>**%CALC\{"$SUBSTITUTE(Q2-2002,2,3)"\}%**</code> returns <code>**Q3-3003**</code>
- Serialized date is seconds since the Epoch, e.g. midnight, 01 Jan 1970. Current time is taken if the date string is empty. Supported date formats: `31 Dec 2009`; `31 Dec 2009 GMT`; `31 Dec 09`; `31-Dec-2009`; `31/Dec/2009`; `2009/12/31`; `2009-12-31`; `2009/12/31`; `2009/12/31 23:59`; `2009/12/31 - 23:59`; `2009-12-31-23-59`; `2009/12/31 - 23:59:59`; `2009.12.31.23.59.59`. Date is assumed to be server time; add `GMT` to indicate Greenwich time zone
- Syntax: <code>**$TIME( _text_ )**</code>
- Example: <code>**%CALC\{"$TIME(2003/10/14 GMT)"\}%**</code> returns <code>**1066089600**</code>
-- Related: <code>[[$FORMATTIME()|Main/WebHome#FuncFORMATTIME]]</code>, <code>[[$FORMATGMTIME()|Main/WebHome#FuncFORMATGMTIME]]</code>, <code>[[$TIMEADD()|Main/WebHome#FuncTIMEADD]]</code>, <code>[[$TIMEDIFF()|Main/WebHome#FuncTIMEDIFF]]</code>, <code>[[$TODAY()|Main/WebHome#FuncTODAY]]</code>, <code>[[$WORKINGDAYS()|Main/WebHome#FuncWORKINGDAYS]]</code>
+- Related: <code>[[$FORMATGMTIME()|Main/WebHome#FuncFORMATGMTIME]]</code>, <code>[[$FORMATTIME()|Main/WebHome#FuncFORMATTIME]]</code>, <code>[[$FORMATTIMEDIFF()|Main/WebHome#FuncFORMATTIMEDIFF]]</code>, <code>[[$TIMEADD()|Main/WebHome#FuncTIMEADD]]</code>, <code>[[$TIMEDIFF()|Main/WebHome#FuncTIMEDIFF]]</code>, <code>[[$TODAY()|Main/WebHome#FuncTODAY]]</code>, <code>[[$WORKINGDAYS()|Main/WebHome#FuncWORKINGDAYS]]</code>
<a name="FuncTIMEADD"></a>
### <a name="TIMEADD( serial, value, unit ) -"></a> TIMEADD( serial, value, unit ) -- add a value to a serialized date
-- The unit is seconds if not specified; unit can be `second`, `minute`, `hour`, `day`, `week`, `month`, `year`. Note: An approximation is used for month and year calculations
+- The `unit` is seconds if not specified; unit can be `second`, `minute`, `hour`, `day`, `week`, `month`, `year`. Note: An approximation is used for month and year calculations
- Syntax: <code>**$TIMEADD( serial, value, _unit_ )**</code>
- Example: <code>**%CALC\{"$TIMEADD($TIME(), 2, week)"\}%**</code> returns the serialized date two weeks from now
- Related: <code>[[$FORMATTIME()|Main/WebHome#FuncFORMATTIME]]</code>, <code>[[$FORMATGMTIME()|Main/WebHome#FuncFORMATGMTIME]]</code>, <code>[[$TIME()|Main/WebHome#FuncTIME]]</code>, <code>[[$TIMEDIFF()|Main/WebHome#FuncTIMEDIFF]]</code>, <code>[[$TODAY()|Main/WebHome#FuncTODAY]]</code>
### <a name="TIMEDIFF( serial_1, serial_2, un"></a> TIMEDIFF( serial\_1, serial\_2, unit ) -- time difference between two serialized dates
-- The unit is seconds if not specified; unit can be specified as in `$TIMEADD()`. Note: An approximation is used for month and year calculations. Use `$FORMAT()` or `$INT()` to format real numbers
+- The `unit` is seconds if not specified; unit can be specified as in `$TIMEADD()`. Note: An approximation is used for month and year calculations. Use `$FORMAT()`, `$FORMATTIMEDIFF()` or `$INT()` to format real numbers
- Syntax: <code>**$TIMEDIFF( serial\_1, serial\_2, _unit_ )**</code>
- Example: <code>**%CALC\{"$TIMEDIFF($TIME(), $EVAL($TIME()+90), minute)"\}%**</code> returns <code>**1\.5**</code>
-- Related: <code>[[$FORMAT()|Main/WebHome#FuncFORMAT]]</code>, <code>[[$FORMATTIME()|Main/WebHome#FuncFORMATTIME]]</code>, <code>[[$FORMATGMTIME()|Main/WebHome#FuncFORMATGMTIME]]</code>, <code>[[$INT()|Main/WebHome#FuncINT]]</code>, <code>[[$TIME()|Main/WebHome#FuncTIME]]</code>, <code>[[$TIMEADD()|Main/WebHome#FuncTIMEADD]]</code>, <code>[[$TODAY()|Main/WebHome#FuncTODAY]]</code>, <code>[[$WORKINGDAYS()|Main/WebHome#FuncWORKINGDAYS]]</code>
+- Related: <code>[[$FORMAT()|Main/WebHome#FuncFORMAT]]</code>, <code>[[$FORMATGMTIME()|Main/WebHome#FuncFORMATGMTIME]]</code>, <code>[[$FORMATTIME()|Main/WebHome#FuncFORMATTIME]]</code>, <code>[[$FORMATTIMEDIFF()|Main/WebHome#FuncFORMATTIMEDIFF]]</code>, <code>[[$INT()|Main/WebHome#FuncINT]]</code>, <code>[[$TIME()|Main/WebHome#FuncTIME]]</code>, <code>[[$TIMEADD()|Main/WebHome#FuncTIMEADD]]</code>, <code>[[$TODAY()|Main/WebHome#FuncTODAY]]</code>, <code>[[$WORKINGDAYS()|Main/WebHome#FuncWORKINGDAYS]]</code>
<a name="FuncTODAY"></a>
### <a name="Can I use CALC in a formatted se"></a> Can I use CALC in a formatted search?
-Specifically, how can I output some conditional text in a [[FormattedSearch]]?
+Specifically, how can I output some conditional text in a %SYSTEMWEB%.FormattedSearch?
-You need to escape the CALC so that it executes once per search hit. This can be done by escaping the `%` signs of `%CALC{...}%` with `$percnt`. For example, to execute `$IF($EXACT($formfield(Tested), Yes), %PUBURL%/%TWIKIWEB%/TWikiDocGraphics/choice-yes.gif, %PUBURL%/%TWIKIWEB%/TWikiDocGraphics/choice-no.gif)` in the `format=""` parameter, write this:
+You need to escape the CALC so that it executes once per search hit. This can be done by escaping the `%` signs of `%CALC{...}%` with `$percnt`. For example, to execute `$IF($EXACT($formfield(Tested), Yes), %PUBURL%/%SYSTEMWEB%/TWikiDocGraphics/choice-yes.gif, %PUBURL%/%SYSTEMWEB%/TWikiDocGraphics/choice-no.gif)` in the `format=""` parameter, write this:
-`%SEARCH{ .... format="| $topic | $percntCALC{$IF($EXACT($formfield(Tested), Yes), %PUBURL%/%TWIKIWEB%/TWikiDocGraphics/choice-yes.gif, %PUBURL%/%TWIKIWEB%/TWikiDocGraphics/choice-no.gif)}$percnt |" }%`
+`%SEARCH{ .... format="| $topic | $percntCALC{$IF($EXACT($formfield(Tested), Yes), %PUBURL%/%SYSTEMWEB%/TWikiDocGraphics/choice-yes.gif, %PUBURL%/%SYSTEMWEB%/TWikiDocGraphics/choice-no.gif)}$percnt |" }%`
### <a name="How can I easily repeat a formul"></a> How can I easily repeat a formula in a table?
Plugin settings are stored as preferences variables. To reference a plugin setting write <code>**%<plugin>\_<setting>%**</code>, i.e. <code>**%SPREADSHEETPLUGIN\_SHORTDESCRIPTION%**</code>
-- One line description, is shown in the [[TextFormattingRules]] topic:
+- One line description, is shown in the %SYSTEMWEB%.TextFormattingRules topic:
- Set SHORTDESCRIPTION = Add spreadsheet calculation like `"$SUM( $ABOVE() )"` to TWiki tables and other topic text
- Debug plugin: (See output in `data/debug.txt`)
- Do not handle `%CALC{}%` variable in included topic while including topic: (default: 1)
- Set SKIPINCLUDE = 1
-- [[WikiWords|TWiki/WikiWord]] to exclude from being spaced out by the <code>**$PROPERSPACE(text)**</code> function. This comma delimited list can be overloaded by a DONTSPACE preferences variable:
+- [[WikiWords|SYSTEMWEB/WikiWord]] to exclude from being spaced out by the <code>**$PROPERSPACE(text)**</code> function. This comma delimited list can be overloaded by a DONTSPACE preferences variable:
- Set DONTSPACE = CodeWarrior, MacDonald, McIntosh, RedHat, SuSE
## <a name="Plugin Installation Instructions"></a> Plugin Installation Instructions
</tr>
<tr>
<td align="right"> Copyright: </td>
- <td> © 2001-2007, <a href="mailto:Peter@Thoeny.org">Peter@Thoeny.org</a>, <a href="http://www.structuredwikis.com/" target="_top">StructuredWikis LLC</a></td>
+ <td> © 2001-2007, Peter Thoeny, <a href="http://www.twiki.net/" target="_top">TWIKI.NET</a></td>
</tr>
<tr>
<td align="right"> License: </td>
</tr>
<tr>
<td align="right"> Plugin Version: </td>
- <td> 23 Jan 2007 (r12607) </td>
+ <td> 13 Oct 2007 (15270) </td>
</tr>
<tr>
<td align="right"> Change History: </td>
<td> </td>
</tr>
<tr>
+ <td align="right"> 13 Oct 2007: </td>
+ <td> Added $FORMATTIMEDIFF() </td>
+ </tr>
+ <tr>
+ <td align="right"> 09 Sep 2007: </td>
+ <td> Enhanced documentation for $EVAL() and $INT() </td>
+ </tr>
+ <tr>
+ <td align="right"> 02 Jun 2007: </td>
+ <td> Added [[TWiki/VarCALC]] to have <code>%CALC{}%</code> listed in [[TWiki/TWikiVariables]]</td>
+ </tr>
+ <tr>
+ <td align="right"> 14 Apr 2007: </td>
+ <td> Fixing bug in $EXISTS() that required full <code>web.topic</code> instead of just <code>topic</code></td>
+ </tr>
+ <tr>
+ <td align="right"> 11 Mar 2007: </td>
+ <td> Fixing bug in $VALUE() and $INT(), introduced by version 09 Mar 2007 </td>
+ </tr>
+ <tr>
+ <td align="right"> 09 Mar 2007: </td>
+ <td> Added $EXP(), $LN(), $LOG(), $PI(), $SQRT(); fixed $ROUND() bug, contributed by TWiki:Main/SergejZnamenskij </td>
+ </tr>
+ <tr>
<td align="right"> 23 Jan 2007: </td>
<td> Enhanced documentation </td>
</tr>
</tr>
<tr>
<td align="right"> TWiki:Plugins/Benchmark: </td>
- <td>[[TWiki/GoodStyle]] 99%, [[TWiki/FormattedSearch]] 99%, %TOPIC% 95% </td>
+ <td> %SYSTEMWEB%.GoodStyle 99%, %SYSTEMWEB%.FormattedSearch 99%, %TOPIC% 95% </td>
</tr>
<tr>
<td align="right"> Other Dependencies: </td>
</tr>
</table>
-**_Related Topics:_** [[TWikiPreferences]], [[TWikiPlugins]]
+**_Related Topics:_** %SYSTEMWEB%.TWikiPreferences, %SYSTEMWEB%.TWikiPlugins, %SYSTEMWEB%.VarCALC
--- TWiki:Main/PeterThoeny - 23 Jan 2007
+-- TWiki:Main/PeterThoeny - 13 Oct 2007
+# <a name="TWiki Access Control"></a> TWiki Access Control
+
+_Restricting read and write access to topics and webs, by Users and groups_
+
+TWiki Access Control allows you restrict access to single topics and entire webs, by individual user and by user Groups. Access control, combined with [[TWikiUserAuthentication]], lets you easily create and manage an extremely flexible, fine-grained privilege system.
+
+**_%T% Tip:_** TWiki:TWiki.TWikiAccessControlSupplement on TWiki.org has additional documentation on access control.
+
<div>
<ul>
<li><a href="#TWiki Access Control"> TWiki Access Control</a><ul>
</li>
<li><a href="#Access Control quick recipes"> Access Control quick recipes</a><ul>
<li><a href="#Obfuscating Webs"> Obfuscating Webs</a></li>
+ <li><a href="#Restrict Access to Whole TWiki S"> Restrict Access to Whole TWiki Site</a></li>
<li><a href="#Authenticate all Webs and Restri"> Authenticate all Webs and Restrict Selected Webs</a></li>
<li><a href="#Authenticate and Restrict Select"> Authenticate and Restrict Selected Webs Only</a></li>
<li><a href="#Hide Control Settings"> Hide Control Settings</a></li>
</ul>
</div>
-# <a name="TWiki Access Control"></a> TWiki Access Control
-
-_Restricting read and write access to topics and webs, by Users and groups_
-
-TWiki Access Control allows you restrict access to single topics and entire webs, by individual user and by user Groups. Access control, combined with [[TWikiUserAuthentication]], lets you easily create and manage an extremely flexible, fine-grained privilege system.
-
-**_%T% Tip:_** TWiki:TWiki.TWikiAccessControlSupplement on TWiki.org has additional documentation on access control.
-
<a name="ImportantConsideration"></a>
## <a name="An Important Control Considerati"></a> An Important Control Consideration
- **Peer influence** is enough to ensure that only relevant content is posted.
- **Peer editing** - the ability for anyone to rearrange all content on a page - keeps topics focused.
- In TWiki, content is transparently preserved under **revision control**:
- - Edits can be undone by the administrator (per default a member of [[TWikiAdminGroup]]; see [[#ManagingGroups|Main/WebHome#ManagingGroups]]).
+ - Edits can be undone by the administrator (per default a member of %USERSWEB%.TWikiAdminGroup; see [[#ManagingGroups|Main/WebHome#ManagingGroups]]).
- Users are encouraged to edit and refactor (condense a long topic), since there's a safety net.
As a **collaboration guideline**:
- [[WikiName]] and encrypted password are recorded using the password manager if authentication is enabled.
- A confirmation e-mail is sent to the user.
-- A user home page with the [[WikiName]] of the user is created in the Main web.
-- The user is added to the [[TWikiUsers]] topic.
+- A user home page with the [[WikiName]] of the user is created in the %USERSWEB% web.
+- The user is added to the %USERSWEB%.TWikiUsers topic.
-The default visitor name is [[TWikiGuest]]. This is the non-authenticated user.
+The default visitor name is %USERSWEB%.TWikiGuest. This is the non-authenticated user.
<a name="ManagingGroups"></a>
The following describes the standard TWiki support for groups. Your local TWiki may have an alternate group mapping manager installed. Check with your TWiki administrator if you are in doubt.
-Groups are defined by group topics located in the <code>**Main**</code> web. To create a new group, visit [[TWikiGroups]] and enter the name of the new group ending in <code>**Group**</code> into the "new group" form field. This will create a new group topic with two important settings:
+Groups are defined by group topics located in the <code>**%USERSWEB%**</code> web. To create a new group, visit %USERSWEB%.TWikiGroups and enter the name of the new group ending in <code>**Group**</code> into the "new group" form field. This will create a new group topic with two important settings:
- <code>**Set GROUP = < list of Users and/or Groups >**</code>
- <code>**Set ALLOWTOPICCHANGE = < list of Users and/or Groups >**</code>
The GROUP setting is a comma-separated list of users and/or other groups. Example:
-- <code>**Set GROUP = Main.SomeUser, Main.OtherUser, Main.SomeGroup**</code>
+- <code>**Set GROUP = %USERSWEB%.SomeUser, %USERSWEB%.OtherUser, %USERSWEB%.SomeGroup**</code>
The ALLOWTOPICCHANGE setting defines who is allowed to change the group topic; it is a comma delimited list of users and groups. You typically want to restrict that to the members of the group itself, so it should contain the name of the topic. This prevents users not in the group from editing the topic to give themselves or others access. For example, for the KasabianGroup topic write:
-- <code>**Set ALLOWTOPICCHANGE = Main.KasabianGroup**</code>
+- <code>**Set ALLOWTOPICCHANGE = %USERSWEB%.KasabianGroup**</code>
**_%X% Note:_** TWiki has strict formatting rules. Make sure you have three spaces, an asterisk, and an extra space in front of any access control rule.
A number of TWiki functions (for example, renaming webs) are only available to administrators. Administrators are simply users who belong to the **SuperAdminGroup**. This is a standard user group, the name of which is defined by \{SuperAdminGroup\} setting in [configure](http://www.dementia.org/twiki/configure). The default name of this group is the `TWikiAdminGroup`. The system administrator may have chosen a different name for this group if your local TWiki uses an alternate group mapping manager but for simplicity we will use the default name TWikiAdminGroup in the rest of this topic.
-You can create new administrators simply by adding them to the [[TWikiAdminGroup]] topic. For example,
+You can create new administrators simply by adding them to the %USERSWEB%.TWikiAdminGroup topic. For example,
-- <code>**Set GROUP= Main.ElizabethWindsor, Main.TonyBlair**</code>
+- <code>**Set GROUP = %USERSWEB%.ElizabethWindsor, %USERSWEB%.TonyBlair**</code>
A member of the Super Admin Group has unrestricted access throughout the TWiki, so only trusted staff should be added to this group.
You can define who is allowed to read or write to a web or a topic. Note that some plugins may not respect access permissions.
-- Restricting VIEW blocks viewing and searching of content.
+- Restricting VIEW blocks viewing and searching of content. When you restric VIEW to a topic or web, this also restricts [[INCLUDE|Main/VarINCLUDE]] and [[Formatted SEARCH|Main/FormattedSearch]] from showing the content of the topics.
- Restricting CHANGE blocks creating new topics, changing topics or attaching files.
- Restricting RENAME prevents renaming of topics within a web.
- <code>**Set DENYWEBRENAME = < comma-delimited list of Users and Groups >**</code>
- <code>**Set ALLOWWEBRENAME = < comma-delimited list of Users and Groups >**</code>
-If your site allows hierarchical webs, then access to sub-webs is determined from the access controls of the parent web, plus the access controls in the sub-web. So, if the parent web has <code>**ALLOWWEBVIEW**</code> set, this will also apply to the subweb.
+If your site allows hierarchical webs, then access to sub-webs is determined from the access controls of the parent web, plus the access controls in the sub-web. So, if the parent web has <code>**ALLOWWEBVIEW**</code> set, this will also apply to the subweb. Also note that you will need to ensure that the parent web's <code>**FINALPREFERENCES**</code> 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|Main/WebHome#RootWebs]]). Renaming is additionally restricted by the setting of WEBRENAME in the web itself.
+**_Note:_** If you restrict access to the %USERSWEB%, make sure to add the `TWikiRegistrationAgent` so that users can register. Example:
+
+- - <code>**Set ALLOWWEBCHANGE = TWikiAdminGroup, TWikiRegistrationAgent**</code>
+
**_Note:_** For Web level access rights Setting any of these settings to an empty value has the same effect as not setting them at all. Please note that the documentation of TWiki 4.0 and earlier versions of TWiki 4.1 did not reflect the actual implementation, e.g. an empty ALLOWWEBVIEW does _not_ prevent anyone from viewing the web, and an an empty DENYWEBVIEW does _not_ allow all to view the web.
### <a name="Controlling access to a Topic"></a> Controlling access to a Topic
Top level webs are a special case, because they don't have a parent web with a [[WebPreferences]]. So there has to be a special control just for the root level.
-- You can define these settings in the Main.%TWIKIPREFSTOPIC% topic, preferable towards the end of the topic:
+- You can define these settings in the %USERSWEB%.%TWIKIPREFSTOPIC% topic, preferable towards the end of the topic:
- <code>**Set DENYROOTCHANGE = < comma-delimited list of Users and Groups >**</code>
- <code>**Set ALLOWROOTCHANGE = < comma-delimited list of Users and Groups >**</code>
**_%X% Note:_** Obfuscating a web without view access control is **very** insecure, as anyone who knows the URL can access the web.
+### <a name="Restrict Access to Whole TWiki S"></a> Restrict Access to Whole TWiki Site
+
+For a firewalled TWiki, e.g. an intranet wiki or extranet wiki, you want to allow only invited people to access your TWiki. In this case, enable [[user authentication with ApacheLogin|Main/TWikiUserAuthentication#ApacheLogin]] and lock down access to the whole `twiki/bin` and `twiki/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.
+
+**_Note:_** With this configuration, someone with access to the site needs to register new users.
+
### <a name="Authenticate all Webs and Restri"></a> Authenticate all Webs and Restrict Selected Webs
Use the following setup to authenticate users for topic viewing in all webs and to restrict access to selected webs. Requires [[TWikiUserAuthentication]] to be enabled.
-1. **Restrict** view access to selected Users and Groups. Set one or both of these variables in its [[WebPreferences]] topic:
+1. Set `require valid-user` on your `view` script in .htaccess or the appropriate Apache .conf file. As of 4.x, this looks like: `FilesMatch "(attach|edit|manage|rename|save|view|upload|mail|logon|.*auth).*"` (normally `view` is not in that list).
+2. **Restrict** view access to selected Users and Groups. Set one or both of these variables in its [[WebPreferences]] topic:
- <code>**Set DENYWEBVIEW = < list of Users and Groups >**</code>
- <code>**Set ALLOWWEBVIEW = < list of Users and Groups >**</code>
- - **_Note:_** `DENYWEBVIEW` is evaluated before `ALLOWWEBVIEW`. Access is denied if the authenticated person is in the `DENYWEBVIEW` list, or not in the `ALLOWWEBVIEW` list. Access is granted in case `DENYWEBVIEW` and `ALLOWWEBVIEW` is not defined.
+ - **_Note:_** `DENYWEBVIEW` is evaluated before `ALLOWWEBVIEW`. Access is denied if the authenticated person is in the `DENYWEBVIEW` list, or not in the `ALLOWWEBVIEW` list. Access is granted if `DENYWEBVIEW` and `ALLOWWEBVIEW` are not defined.
+3. If you still want public users to be able to register automatically follow TWiki:TWiki.RegisterOnViewRestrictedSite.
### <a name="Authenticate and Restrict Select"></a> Authenticate and Restrict Selected Webs Only
1. **Restrict** view access to selected Users and Groups. Set one or both of these variables in its [[WebPreferences]] topic:
- <code>**Set DENYWEBVIEW = < list of Users and Groups >**</code>
- <code>**Set ALLOWWEBVIEW = < list of Users and Groups >**</code>
- - **_Note:_** `DENYWEBVIEW` is evaluated before `ALLOWWEBVIEW`. Access is denied if the authenticated person is in the `DENYWEBVIEW` list, or not in the `ALLOWWEBVIEW` list. Access is granted in case `DENYWEBVIEW` and `ALLOWWEBVIEW` is not defined.
+ - **_Note:_** `DENYWEBVIEW` is evaluated before `ALLOWWEBVIEW`. Access is denied if the authenticated person is in the `DENYWEBVIEW` list, or not in the `ALLOWWEBVIEW` list. Access is granted if `DENYWEBVIEW` and `ALLOWWEBVIEW` are not defined.
### <a name="Hide Control Settings"></a> Hide Control Settings
>
> <br />
>
-> <code>** \* Set DENYTOPICCHANGE = Main.SomeGroup**</code>
+> <code>** \* Set DENYTOPICCHANGE = %USERSWEB%.SomeGroup**</code>
>
> <br />
>
# <a name="Package <code>TWiki::_AccessControlEx"></a> Package =TWiki::AccessControlException
-**extends** `Error`
+Exception used raise an access control violation. This exception has the following fields:
-Exception used raise an access control violation.
+- `web` - the web which was being accessed
+- `topic` - the topic being accessed (if any)
+- `user` - canonical username of the person doing the accessing. Use the methods of the TWiki::Users class to get more information about the user.
+- `mode` - the access mode e.g. CHANGE, VIEW etc
+- `reason` a text string giving the reason for the refusal.
+
+The exception may be thrown by plugins. If a plugin throws the exception, it will normally be caught and the browser redirected to a login screen (if the user is not logged in) or reported (if they are and just don't have access).
<div>
<ul>
## <a name="ClassMethod <strong>new</strong> ($mode,$user,$"></a> [[ClassMethod]] **new** `($mode,$user,$web,$topic,$reason)`
- `$mode` - mode of access (view, change etc)
-- `$user` - user object doing the accessing
+- `$user` - canonical user name of user doing the accessing
- `$web` - web being accessed
- `$topic` - topic being accessed
- `$reason` - string reason for failure
## <a name="ObjectMethod <strong>stringify</strong> () - $s"></a> [[ObjectMethod]] **stringify** `() -> $string`
-Generate a summary string
+Generate a summary string. This is mainly for debugging.
<div>
<ul>
<li><a href="#Package =TWiki::Access="> Package TWiki::Access</a><ul>
- <li><a href="#ClassMethod <strong>new</strong> ()"> ClassMethod new <tt>()</tt></a></li>
- <li><a href="#ObjectMethod <strong>permissionsSet</strong> ($"> ObjectMethod permissionsSet <tt>($web) -> $boolean</tt></a></li>
+ <li><a href="#ClassMethod <strong>new</strong> ($session)"> ClassMethod new <tt>($session)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
<li><a href="#ObjectMethod <strong>getReason</strong> () -> $"> ObjectMethod getReason <tt>() -> $string</tt></a></li>
<li><a href="#ObjectMethod *check_AccessPermis"> ObjectMethod checkAccessPermission <tt>($action,$user,$text,$meta,$topic,$web) -> $boolean</tt></a></li>
</ul>
</ul>
</div>
-## <a name="ClassMethod <strong>new</strong> ()"></a> [[ClassMethod]] **new** `()`
+## <a name="ClassMethod <strong>new</strong> ($session)"></a> [[ClassMethod]] **new** `($session)`
-Construct a new singleton object to manage the permissions database.
+Constructor.
-## <a name="ObjectMethod <strong>permissionsSet</strong> ($"></a> [[ObjectMethod]] **permissionsSet** `($web) -> $boolean`
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
-Are there any security restrictions for this Web (ignoring settings on individual pages).
+Break circular references.
## <a name="ObjectMethod <strong>getReason</strong> () - $s"></a> [[ObjectMethod]] **getReason** `() -> $string`
Check if user is allowed to access topic
- `$action` - 'VIEW', 'CHANGE', 'CREATE', etc.
-- `$user` - User object
+- `$user` - User id (**not** wikiname)
- `$text` - If undef or '': Read '$theWebName.$theTopicName' to check permissions
- `$meta` - If undef, but `$text` is defined, then metadata will be parsed from `$text`. If defined, then metadata embedded in `$text` will be ignored. Always ignored if `$text` is undefined. Settings in `$meta` override \* Set settings in plain text.
- `$topic` - Topic name to check, e.g. 'SomeTopic' \*undef to check web perms only)
+# <a name="TWiki Add-Ons"></a> TWiki Add-Ons
+
+_Add functionality to TWiki with extensions not based on the TWiki scripts._
+
<div>
<ul>
<li><a href="#TWiki Add-Ons"> TWiki Add-Ons</a><ul>
</ul>
</div>
-# <a name="TWiki Add-Ons"></a> TWiki Add-Ons
-
-_Add functionality to TWiki with extensions not based on the TWiki scripts._
-
## <a name="Overview"></a> Overview
-An add-on runs separately from the TWiki scripts, e.g. for data import, export to static HTML, etc. Add-Ons normally do not call any TWiki code directly, though may invoke TWiki scripts. There are different types on add-ons, they may be stand alone scripts, browser plugins, office tool extensions, or even a set of TWiki topics that form a TWiki application.
+An add-on runs separately from the TWiki scripts, e.g. for data import, export to static HTML, etc. Add-Ons normally do not call any TWiki code directly, though may invoke TWiki scripts. There are different types of add-ons, they may be stand alone scripts, browser plugins, office tool extensions, or even a set of TWiki topics that form a TWiki application.
**_Relevant links on TWiki.org:_**
--- /dev/null
+# <a name="Package <code>TWiki::_AggregateIterat"></a> Package =TWiki::AggregateIterator
+
+combine multiple iterators
+
+<div>
+ <ul>
+ <li><a href="#Package =TWiki::_AggregateIterat"> Package TWiki::AggregateIterator</a><ul>
+ <li><a href="#new(\@list, $unique)"> new(\@list, $unique)</a></li>
+ <li><a href="#hasNext() -> $boolean"> hasNext() -> $boolean</a></li>
+ <li><a href="#next() -> $data"> next() -> $data</a></li>
+ </ul>
+ </li>
+ </ul>
+</div>
+
+## <a name="new(\@list, $unique)"></a> new(\\@list, $unique)
+
+Create a new iterator over the given list of iterators. The list is not damaged in any way.
+
+if $unique is set, we try to not repeat values. Warning: $unique assumes that the values are strings (so works for cUID's )
+
+## <a name="hasNext() - $boolean"></a> hasNext() -> $boolean
+
+Returns false when the iterator is exhausted.
+
+ my $it = new TWiki::ListIterator(\@list);
+ while ($it->hasNext()) {
+ ...
+
+## <a name="next() - $data"></a> next() -> $data
+
+Return the next entry in the list.
+
+The iterator object can be customised to pre- and post-process entries from the list before returning them. This is done by setting two fields in the iterator object:
+
+- `{filter}` can be defined to be a sub that filters each entry. The entry will be ignored (next() will not return it) if the filter returns false.
+- `{process}` can be defined to be a sub to process each entry before it is returned by next. The value returned from next is the value returned by the process function.
<ul>
<li><a href="#Package =TWiki::Attach="> Package TWiki::Attach</a><ul>
<li><a href="#ClassMethod <strong>new</strong> ($session)"> ClassMethod new <tt>($session)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
<li><a href="#ObjectMethod <strong>render_MetaData</strong> ("> ObjectMethod renderMetaData <tt>($web,$topic,$meta,$args) -> $text</tt></a></li>
<li><a href="#ObjectMethod <strong>formatVersions</strong> ($"> ObjectMethod formatVersions <tt>($web,$topic,$attrs) -> $text</tt></a></li>
<li><a href="#ObjectMethod *get_AttachmentLink"> ObjectMethod getAttachmentLink <tt>($user,$web,$topic,$name,$meta) -> $html</tt></a></li>
- <li><a href="#ObjectMethod *migrate_ToFileAtta"> ObjectMethod migrateToFileAttachmentMacro <tt>($meta,$text) -> $text</tt></a></li>
- <li><a href="#ObjectMethod *upgradeFrom1v0beta"> ObjectMethod upgradeFrom1v0beta <tt>($meta) -> $text</tt></a></li>
</ul>
</li>
</ul>
## <a name="ClassMethod <strong>new</strong> ($session)"></a> [[ClassMethod]] **new** `($session)`
-Constructor
+Constructor.
+
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
+
+Break circular references.
## <a name="ObjectMethod <strong>render_MetaData</strong> ("></a> [[ObjectMethod]] **renderMetaData** `($web,$topic,$meta,$args) -> $text`
- `$meta` - Meta object that contains the meta info
Build a link to the attachment, suitable for insertion in the topic.
-
-## <a name="ObjectMethod <strong>migrate_ToFileAtta"></a> [[ObjectMethod]] \*migrateToFileAttachmentMacro `($meta,$text) -> $text`
-
-Migrate old HTML format
-
-## <a name="ObjectMethod <strong>upgradeFrom1v0beta"></a> [[ObjectMethod]] \*upgradeFrom1v0beta `($meta) -> $text`
-
-CODE\_SMELL: Is this really necessary? upgradeFrom1v0beta?
# <a name="Package <code>TWiki::Attrs="></a> Package =TWiki::Attrs
-Class of attribute sets, designed for parsing and storing attribute values from a TWiki tag e.g. `%TAG{fred='bad' "sad" joe="mad"}%`
+Class of attribute sets, designed for parsing and storing attribute values from a TWiki tag e.g. `%TAG{"joe" fred="bad" joe="mad"}%`
-An attribute set is a map containing an entry for each parameter. The default parameter (unnamed quoted string) is named `_DEFAULT` in the map.
+An attribute set is a hash containing an entry for each parameter. The default parameter (unnamed quoted string) is named `_DEFAULT` in the hash.
-Attributes declared later in the string will override those of the same name defined earlier. The one exception to this is the \_DEFAULT key, where the _first_ instance of a setting is always taken.
+Attributes declared later in the string will override those of the same name defined earlier. The one exception to this is the \_DEFAULT key, where the _first_ instance is always taken.
-As well as standard TWiki syntax (parameter values double-quoted) it also parses single-quoted values, unquoted spaceless values, spaces around the =, and commas as well as spaces separating values, though none of these alternatives is advertised in documentation and the extended syntax can be turned off by passing the 'strict' parameter to `new`.
-
-This class replaces the old TWiki::extractNameValuePair and TWiki::extractParameters.
+As well as the default TWiki syntax (parameter values double-quoted) this class also parses single-quoted values, unquoted spaceless values, spaces around the =, and commas as well as spaces separating values. The extended syntax has to be enabled by passing the `$friendly` parameter to `new`.
<div>
<ul>
<li><a href="#ObjectMethod <strong>isEmpty</strong> () -> boo"> ObjectMethod isEmpty <tt>() -> boolean</tt></a></li>
<li><a href="#ObjectMethod <strong>remove</strong> ($key) ->"> ObjectMethod remove <tt>($key) -> $value</tt></a></li>
<li><a href="#ObjectMethod <strong>stringify</strong> () -> $"> ObjectMethod stringify <tt>() -> $string</tt></a></li>
- <li><a href="#StaticMethod <strong>extractValue</strong> () -"> StaticMethod extractValue <tt>() -> $string</tt></a></li>
- <li><a href="#ObjectMethod <strong>get</strong> ($key) -> $va"> ObjectMethod get <tt>($key) -> $value</tt></a></li>
</ul>
</li>
</ul>
## <a name="ObjectMethod <strong>remove</strong> ($key) - $"></a> [[ObjectMethod]] **remove** `($key) -> $value`
-<table border="1" cellpadding="0" cellspacing="0">
- <tr>
- <td> $key </td>
- <td> Attribute to remove </td>
- </tr>
-</table>
+- `$key` - Attribute to remove
Remove an attr value from the map, return old value. After a call to `remove` the attribute is no longer defined.
## <a name="ObjectMethod <strong>stringify</strong> () - $s"></a> [[ObjectMethod]] **stringify** `() -> $string`
-Generate a printed form for the map, using standard attribute syntax, with only the single-quote extension syntax observed (no \{\} brackets, though).
-
-## <a name="StaticMethod <strong>extractValue</strong> () -"></a> [[StaticMethod]] **extractValue** `() -> $string`
-
-Legacy support, formerly known as extractNameValuePair. This static method uses context information to determine how a value string is to be parsed. For example, if you have an attribute string like this:
-
-"abc def="ghi" jkl" def="qqq"
-
-then call extractValue( "def" ), it will return "ghi".
-
-## <a name="ObjectMethod <strong>get</strong> ($key) - $val"></a> [[ObjectMethod]] **get** `($key) -> $value`
-
-<table border="1" cellpadding="0" cellspacing="0">
- <tr>
- <td> $key </td>
- <td> Attribute to get </td>
- </tr>
-</table>
-
-Get an attr value from the map.
-
-Synonymous with $attrs->\{$key\}. Retained mainly for compatibility with the old [[AttrsContrib]].
+Generate a printed form for the map, using strict attribute syntax, with only the single-quote extension syntax observed (no \{\} brackets, though).
<ul>
<li><a href="#Package =TWiki::Compatibility="> Package TWiki::Compatibility</a><ul>
<li><a href="#StaticMethod *upgrade_CategoryTa"> StaticMethod upgradeCategoryTable <tt>($session,$web,$topic,$meta,$text) -> $text</tt></a></li>
+ <li><a href="#migrate_ToFileAttachmentMacro ("> migrateToFileAttachmentMacro ( $session, $meta, $text ) -> $text</a></li>
+ <li><a href="#upgradeFrom1v0beta ( $session, $"> upgradeFrom1v0beta ( $session, $meta ) -> $text</a></li>
</ul>
</li>
</ul>
Upgrade old style category table
May throw TWiki::OopsException
+
+## <a name="migrate_ToFileAttachmentMacro ("></a><a name="migrate_ToFileAttachmentMacro ( "></a> migrateToFileAttachmentMacro ( $session, $meta, $text ) -> $text
+
+Migrate old HTML format
+
+## <a name="upgradeFrom1v0beta ( $session, $"></a> upgradeFrom1v0beta ( $session, $meta ) -> $text
+# <a name="TWiki Contribs"></a> TWiki Contribs
+
+_Reusable code that may be used over several plugins and add-ons._
+
<div>
<ul>
<li><a href="#TWiki Contribs"> TWiki Contribs</a><ul>
</ul>
</div>
-# <a name="TWiki Contribs"></a> TWiki Contribs
-
-_Reusable code that may be used over several plugins and add-ons._
-
## <a name="Overview"></a> Overview
TWiki contribs extend the functionality of TWiki, typically used by plugins and add-ons. They may also provide alternative implementations for sections of the TWiki core e.g. user management, or when an extension just can't be implemented as a plugin because it requires very close access to TWiki internals.
**_Disclaimer:_** TWiki gets installed on many public web sites. The TWiki contributors are not affiliated in any way with those sites.
-**_Releated Topics:_** [[TWikiHistory]], and the List of Production Releases in TWiki:Codev/TWikiReleases
+**_Releated Topics:_** %SYSTEMWEB%.TWikiHistory, and the List of Production Releases in TWiki:Codev/TWikiReleases
+# <a name="Appendix C: TWiki CSS"></a> Appendix C: TWiki CSS
+
+_Listing of CSS class names emitted from TWiki core code and standard plugins, for the Dakar release._
+
<div>
<ul>
<li><a href="#Appendix C: TWiki CSS"> Appendix C: TWiki CSS</a><ul>
<li><a href="#Who should read this document?"> Who should read this document?</a></li>
<li><a href="#Naming conventions"> Naming conventions</a><ul>
<li><a href="#TWiki styles in core code"> TWiki styles in core code</a></li>
- <li><a href="#TWiki Styles in Plugins"> TWiki Styles in Plugins</a></li>
+ <li><a href="#TWiki Styles in Plugins"> TWiki Styles in Plugins</a><ul>
+ <li><a href="#TablePlugin"> TablePlugin</a></li>
+ </ul>
+ </li>
<li><a href="#TWiki Styles in Templates"> TWiki Styles in Templates</a></li>
<li><a href="#TWiki Styles used in =configure="> TWiki Styles used in configure</a></li>
<li><a href="#TWiki Styles in topics"> TWiki Styles in topics</a></li>
<li><a href="#TWiki Styles in Skins"> TWiki Styles in Skins</a></li>
+ <li><a href="#Reserved Styles"> Reserved Styles</a></li>
</ul>
</li>
<li><a href="#Tips"> Tips</a></li>
</ul>
</div>
-# <a name="Appendix C: TWiki CSS"></a> Appendix C: TWiki CSS
-
-_Listing of CSS class names emitted from TWiki core code and standard plugins, for the Dakar release._
-
## <a name="Who should read this document?"></a> Who should read this document?
Most html elements generated by TWiki core code now have Cascading Style Sheet (CSS) tags. **_Skin builders_** and others who want to change the appearance of the default TWiki installation or any of the skins can use this document to see what styles can be created for these html elements.
<td> .twikiDiffLineNumberHeader </td>
<td> RDiff.pm </td>
</tr>
+ <tr>
+ <td> .twikiDiffDebug </td>
+ <td> RDiff.pm </td>
+ </tr>
+ <tr>
+ <td> .twikiDiffDebugRight </td>
+ <td> RDiff.pm </td>
+ </tr>
+ <tr>
+ <td> .twikiDiffDebugLeft </td>
+ <td> RDiff.pm </td>
+ </tr>
</table>
<table border="1" cellpadding="0" cellspacing="0">
### <a name="TWiki Styles in Plugins"></a> TWiki Styles in Plugins
+#### <a name="TablePlugin"></a> [[TablePlugin]]
+
<table border="1" cellpadding="0" cellspacing="0">
<tr>
- <td> .twikiTable </td>
- <td>[[Main/TablePlugin]]</td>
+ <td><code>.twikiTable</code></td>
+ <td> The table </td>
</tr>
<tr>
- <td> .twikiSortedAscendingCol </td>
- <td>[[Main/TablePlugin]]</td>
+ <td><code>.twikiSortedCol</code></td>
+ <td> A sorted column </td>
</tr>
<tr>
- <td> .twikiSortedDescendingCol </td>
- <td>[[Main/TablePlugin]]</td>
+ <td><code>.twikiSortedAscendingCol</code></td>
+ <td> Sorted column, ascending </td>
</tr>
<tr>
- <td> .twikiFirstCol </td>
- <td>[[Main/TablePlugin]]</td>
+ <td><code>.twikiSortedDescendingCol</code></td>
+ <td> Sorted column, descending </td>
</tr>
<tr>
- <td> .twikiTableEven </td>
- <td>[[Main/TablePlugin]]</td>
+ <td><code>.tableSortIcon</code></td>
+ <td> The sort icon holder (span) </td>
</tr>
<tr>
- <td> .twikiTableOdd </td>
- <td>[[Main/TablePlugin]]</td>
+ <td><code>.twikiFirstCol</code></td>
+ <td> The first column </td>
+ </tr>
+ <tr>
+ <td><code>.twikiTableEven</code></td>
+ <td> Even numbered rows </td>
+ </tr>
+ <tr>
+ <td><code>.twikiTableOdd</code></td>
+ <td> Odd numbered rows </td>
+ </tr>
+ <tr>
+ <td><code>.twikiTableCol</code> + column number </td>
+ <td> Unique column identifier, for instance: <code>twikiTableCol0</code></td>
+ </tr>
+ <tr>
+ <td><code>.twikiTableRow</code> + type + row number </td>
+ <td> Unique row identifier, for instance: <code>twikiTableRowdataBg0</code></td>
</tr>
</table>
<table border="1" cellpadding="0" cellspacing="0">
<tr>
+ <td> .twikiPage </td>
+ <td> twiki.tmpl </td>
+ </tr>
+ <tr>
+ <td> .twikiMiddleContainer </td>
+ <td> twiki.tmpl </td>
+ </tr>
+ <tr>
+ <td> .twikiMain </td>
+ <td> twiki.tmpl </td>
+ </tr>
+ <tr>
<td> .twikiFormTable </td>
<td> formtables.tmpl, form.tmpl </td>
</tr>
<td> </td>
</tr>
<tr>
+ <td> .twikiInputFieldReadOnly </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td> .twikiInputFieldFocus </td>
+ <td> For Internet Explorer that does not recognize the <code>:focus</code> pseudo class selector </td>
+ </tr>
+ <tr>
+ <td> .twikiInputFieldBeforeFocus </td>
+ <td> for use with Javascript: the color of the input text when not clicked in the field </td>
+ </tr>
+ <tr>
+ <td> .twikiTextarea </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td> .twikiTextareaRawView </td>
+ <td> </td>
+ </tr>
+ <tr>
<td> .twikiButton </td>
<td> </td>
</tr>
<tr>
+ <td> .twikiFocus </td>
+ <td> Behaviour marker so a field can be given input focus </td>
+ </tr>
+ <tr>
<td> .twikiLeft </td>
<td> </td>
</tr>
<td> .twikiFormStep </td>
<td> form row </td>
</tr>
+ <tr>
+ <td> .twikiNoBreak </td>
+ <td> no break on whitespace </td>
+ </tr>
+ <tr>
+ <td> .twikiMakeVisible </td>
+ <td> For elements that should only be visible with javascript on: default set to hidden, is made visible by javascript. Defaults to inline. </td>
+ </tr>
+ <tr>
+ <td> .twikiMakeVisibleInline </td>
+ <td> For <code>span</code> elements that should only be visible with javascript on: default set to hidden, is made visible by javascript. </td>
+ </tr>
+ <tr>
+ <td> .twikiMakeVisibleBlock </td>
+ <td> For <code>div</code> elements that should only be visible with javascript on: default set to hidden, is made visible by javascript. </td>
+ </tr>
+ <tr>
+ <td> .twikiMakeHidden </td>
+ <td> For elements that should be <strong>hidden</strong> with javascript on: no default style, is made hidden by javascript. </td>
+ </tr>
+ <tr>
+ <td> .twikiFooterNote </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td> .twikiPopUp </td>
+ <td> Behaviour marker so a popup-window can be invoked </td>
+ </tr>
</table>
### <a name="TWiki Styles used in <code>configure="></a> TWiki Styles used in =configure
<table border="1" cellpadding="0" cellspacing="0">
<tr>
<td> .twikiBroadcastMessage </td>
- <td>[[TWiki/TWikiPreferences]]</td>
+ <td> %SYSTEMWEB%.TWikiPreferences </td>
</tr>
<tr>
<td> #twikiSearchTable </td>
- <td>[[TWiki/WebSearch]], [[TWiki/WebSearchAdvanced]]</td>
+ <td> %SYSTEMWEB%.WebSearch, %SYSTEMWEB%.WebSearchAdvanced </td>
</tr>
</table>
</tr>
</table>
+### <a name="Reserved Styles"></a> Reserved Styles
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <td> .twikiImage </td>
+ <td> defined in [[Main/PatternSkin]]</td>
+ <td> div creates border around enclosed image </td>
+ </tr>
+ <tr>
+ <td> .twikiNotification </td>
+ <td> defined in [[Main/PatternSkin]]</td>
+ <td> temporary alert, lighter than broadcast message </td>
+ </tr>
+ <tr>
+ <td> .twikiUnvisited </td>
+ <td> defined in [[Main/PatternSkin]]</td>
+ <td> link style that ignores the visited link state; useful for form links </td>
+ </tr>
+</table>
+
## <a name="Tips"></a> Tips
PatternSkin makes extensive use of CSS in its templates. Read the [[PatternSkin]] topic and [[PatternSkinCss]] to learn more about creating your own CSS-based skin.
<td bgcolor="#ffffff" style=""><code>%ICON{book}%</code></td>
</tr>
<tr>
+ <td bgcolor="#ffffff" style=""><img alt="Blank" src="http://www.dementia.org/twiki//view/blank.gif" title="Blank" /></td>
+ <td bgcolor="#ffffff" style=""><code>blank.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Blank box </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{blank}%</code></td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><img alt="Blank" src="http://www.dementia.org/twiki//view/blank-bg.gif" title="Blank" /></td>
+ <td bgcolor="#ffffff" style=""><code>blank-bg.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Blank box, transparent </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{blank-bg}%</code></td>
+ </tr>
+ <tr>
<td bgcolor="#ffffff" style=""><img alt="Speech bubble" src="http://www.dementia.org/twiki//view/bubble.gif" title="Speech bubble" /></td>
<td bgcolor="#ffffff" style=""><code>bubble.gif</code></td>
<td bgcolor="#ffffff" style=""> Speech bubble </td>
<td bgcolor="#ffffff" style=""><code>%ICON{download}%</code></td>
</tr>
<tr>
+ <td bgcolor="#ffffff" style=""><img alt="Fax" src="http://www.dementia.org/twiki//view/fax.gif" title="Fax" /></td>
+ <td bgcolor="#ffffff" style=""><code>fax.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Fax </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{fax}%</code></td>
+ </tr>
+ <tr>
<td bgcolor="#ffffff" style=""><img alt="Filter" src="http://www.dementia.org/twiki//view/filter.gif" title="Filter" /></td>
<td bgcolor="#ffffff" style=""><code>filter.gif</code></td>
<td bgcolor="#ffffff" style=""> Filter </td>
<td bgcolor="#ffffff" style=""><code>%ICON{globe}%</code></td>
</tr>
<tr>
+ <td bgcolor="#ffffff" style=""><img alt="Map" src="http://www.dementia.org/twiki//view/map.gif" title="Map" /></td>
+ <td bgcolor="#ffffff" style=""><code>map.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Map </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{map}%</code></td>
+ </tr>
+ <tr>
<td bgcolor="#ffffff" style=""><img alt="Pointing hand" src="http://www.dementia.org/twiki//view/hand.gif" title="Pointing hand" /></td>
<td bgcolor="#ffffff" style=""><code>hand.gif</code></td>
<td bgcolor="#ffffff" style=""> Pointing hand </td>
<td bgcolor="#ffffff" style=""><code>%ICON{hourglass}%</code></td>
</tr>
<tr>
+ <td bgcolor="#ffffff" style=""><img alt="Megaphone" src="http://www.dementia.org/twiki//view/megaphone.gif" title="Megaphone" /></td>
+ <td bgcolor="#ffffff" style=""><code>megaphone.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Megaphone </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{megaphone}%</code></td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><img alt="Mobile" src="http://www.dementia.org/twiki//view/mobile.gif" title="Mobile" /></td>
+ <td bgcolor="#ffffff" style=""><code>mobile.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Mobile </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{mobile}%</code></td>
+ </tr>
+ <tr>
<td bgcolor="#ffffff" style=""><img alt="Read more" src="http://www.dementia.org/twiki//view/more.gif" title="Read more" /></td>
<td bgcolor="#ffffff" style=""><code>more.gif</code></td>
<td bgcolor="#ffffff" style=""> Read more </td>
<td bgcolor="#ffffff" style=""><code>%ICON{parked}%</code></td>
</tr>
<tr>
+ <td bgcolor="#ffffff" style=""><img alt="Parts" src="http://www.dementia.org/twiki//view/parts.gif" title="Parts" /></td>
+ <td bgcolor="#ffffff" style=""><code>parts.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Parts </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{parts}%</code></td>
+ </tr>
+ <tr>
<td bgcolor="#ffffff" style=""><img alt="Pencil / Refactor / Edit" src="http://www.dementia.org/twiki//view/pencil.gif" title="Pencil / Refactor / Edit" /></td>
<td bgcolor="#ffffff" style=""><code>pencil.gif</code></td>
<td bgcolor="#ffffff" style=""> Pencil / Refactor / Edit </td>
<td bgcolor="#ffffff" style=""><code>%P%</code>, <code>%ICON{pencil}%</code></td>
</tr>
<tr>
+ <td bgcolor="#ffffff" style=""><img alt="Phone" src="http://www.dementia.org/twiki//view/phone.gif" title="Phone" /></td>
+ <td bgcolor="#ffffff" style=""><code>phone.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Phone </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{phone}%</code></td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><img alt="Photo" src="http://www.dementia.org/twiki//view/photo.gif" title="Photo" /></td>
+ <td bgcolor="#ffffff" style=""><code>photo.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Photo, 13x10 </td>
+ <td bgcolor="#ffffff" style=""><code><img src="%ICONURL{photo}%" width="13" height="10" alt="Photo" border="0" /></code></td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><img alt="Presentation" src="http://www.dementia.org/twiki//view/presentation.gif" title="Presentation" /></td>
+ <td bgcolor="#ffffff" style=""><code>presentation.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Presentation </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{presentation}%</code></td>
+ </tr>
+ <tr>
<td bgcolor="#ffffff" style=""><img alt="Puzzle" src="http://www.dementia.org/twiki//view/puzzle.gif" title="Puzzle" /></td>
<td bgcolor="#ffffff" style=""><code>puzzle.gif</code></td>
<td bgcolor="#ffffff" style=""> Puzzle </td>
<td bgcolor="#ffffff" style=""><code>%ICON{question}%</code></td>
</tr>
<tr>
+ <td bgcolor="#ffffff" style=""><img alt="Quiet" src="http://www.dementia.org/twiki//view/quiet.gif" title="Quiet" /></td>
+ <td bgcolor="#ffffff" style=""><code>quiet.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Quiet </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{quiet}%</code></td>
+ </tr>
+ <tr>
<td bgcolor="#ffffff" style=""><img alt="Request for comments" src="http://www.dementia.org/twiki//view/rfc.gif" title="Request for comments" /></td>
<td bgcolor="#ffffff" style=""><code>rfc.gif</code></td>
<td bgcolor="#ffffff" style=""> Request for comments </td>
<td bgcolor="#ffffff" style=""><code>%ICON{rfc}%</code></td>
</tr>
<tr>
+ <td bgcolor="#ffffff" style=""><img alt="Site map" src="http://www.dementia.org/twiki//view/sitemap.gif" title="Site map" /></td>
+ <td bgcolor="#ffffff" style=""><code>sitemap.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Site map </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{sitemap}%</code></td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><img alt="Site tree" src="http://www.dementia.org/twiki//view/sitetree.gif" title="Site tree" /></td>
+ <td bgcolor="#ffffff" style=""><code>sitetree.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Site tree </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{sitetree}%</code></td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><img alt="Skype" src="http://www.dementia.org/twiki//view/skype.gif" title="Skype" /></td>
+ <td bgcolor="#ffffff" style=""><code>skype.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Skype </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{skype}%</code></td>
+ </tr>
+ <tr>
<td bgcolor="#ffffff" style=""><img alt="Sort" src="http://www.dementia.org/twiki//view/sort.gif" title="Sort" /></td>
<td bgcolor="#ffffff" style=""><code>sort.gif</code></td>
<td bgcolor="#ffffff" style=""> Sort </td>
<td bgcolor="#ffffff" style=""><code>%T%</code>, <code>%ICON{tip}%</code></td>
</tr>
<tr>
+ <td bgcolor="#ffffff" style=""><img alt="Video" src="http://www.dementia.org/twiki//view/video.gif" title="Video" /></td>
+ <td bgcolor="#ffffff" style=""><code>video.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Video, 13x10 </td>
+ <td bgcolor="#ffffff" style=""><code><img src="%ICONURL{video}%" width="13" height="10" alt="Video" border="0" /></code></td>
+ </tr>
+ <tr>
<td bgcolor="#ffffff" style=""><img alt="Warning, important" src="http://www.dementia.org/twiki//view/warning.gif" title="Warning, important" /></td>
<td bgcolor="#ffffff" style=""><code>warning.gif</code></td>
<td bgcolor="#ffffff" style=""> Warning, important </td>
<td bgcolor="#ffffff" style=""> Folder </td>
<td bgcolor="#ffffff" style=""><code>%ICON{folder}%</code></td>
</tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><img alt="Table" src="http://www.dementia.org/twiki//view/table.gif" title="Table" /></td>
+ <td bgcolor="#ffffff" style=""><code>table.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Table </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{table}%</code></td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><img alt="Edit table" src="http://www.dementia.org/twiki//view/edittable.gif" title="Edit table" /></td>
+ <td bgcolor="#ffffff" style=""><code>edittable.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Edit table </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{edittable}%</code></td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><img alt="Edit" src="http://www.dementia.org/twiki//view/uweb-bo.gif" title="Edit" /></td>
+ <td bgcolor="#ffffff" style=""><code>uweb-bo.gif</code></td>
+ <td bgcolor="#ffffff" style=""> UWEB (<a href="http://www.aboutus.org/UniversalWikiEditButton" target="_top">Universal Wiki Edit Button</a>), blue, outline </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{uweb-bo}%</code></td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><img alt="Edit" src="http://www.dementia.org/twiki//view/uweb-bo12.gif" title="Edit" /></td>
+ <td bgcolor="#ffffff" style=""><code>uweb-bo12.gif</code></td>
+ <td bgcolor="#ffffff" style=""> UWEB, blue, outline, small 12x12 </td>
+ <td bgcolor="#ffffff" style=""><code><img src="%ICONURL{uweb-bo12}%" width="12" height="12" alt="Edit" border="0" /></code></td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><img alt="Edit" src="http://www.dementia.org/twiki//view/uweb-g.gif" title="Edit" /></td>
+ <td bgcolor="#ffffff" style=""><code>uweb-g.gif</code></td>
+ <td bgcolor="#ffffff" style=""> UWEB, green (default) </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{uweb-g}%</code></td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><img alt="Edit" src="http://www.dementia.org/twiki//view/uweb-gs.gif" title="Edit" /></td>
+ <td bgcolor="#ffffff" style=""><code>uweb-gs.gif</code></td>
+ <td bgcolor="#ffffff" style=""> UWEB, green, square </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{uweb-gs}%</code></td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><img alt="Edit" src="http://www.dementia.org/twiki//view/uweb-m12.gif" title="Edit" /></td>
+ <td bgcolor="#ffffff" style=""><code>uweb-m12.gif</code></td>
+ <td bgcolor="#ffffff" style=""> UWEB, black, small 12x12 </td>
+ <td bgcolor="#ffffff" style=""><code><img src="%ICONURL{uweb-m12}%" width="12" height="12" alt="Edit" border="0" /></code></td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><img alt="Edit" src="http://www.dementia.org/twiki//view/uweb-o.gif" title="Edit" /></td>
+ <td bgcolor="#ffffff" style=""><code>uweb-o.gif</code></td>
+ <td bgcolor="#ffffff" style=""> UWEB, orange </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{uweb-o}%</code></td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><img alt="Edit" src="http://www.dementia.org/twiki//view/uweb-o12.gif" title="Edit" /></td>
+ <td bgcolor="#ffffff" style=""><code>uweb-o12.gif</code></td>
+ <td bgcolor="#ffffff" style=""> UWEB, orange, small 12x12 </td>
+ <td bgcolor="#ffffff" style=""><code><img src="%ICONURL{uweb-o12}%" width="12" height="12" alt="Edit" border="0" /></code></td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><img alt="Edit" src="http://www.dementia.org/twiki//view/uweb-oo.gif" title="Edit" /></td>
+ <td bgcolor="#ffffff" style=""><code>uweb-oo.gif</code></td>
+ <td bgcolor="#ffffff" style=""> UWEB, orange, outline </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{uweb-oo}%</code></td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><img alt="Edit" src="http://www.dementia.org/twiki//view/uweb-os.gif" title="Edit" /></td>
+ <td bgcolor="#ffffff" style=""><code>uweb-os.gif</code></td>
+ <td bgcolor="#ffffff" style=""> UWEB, orange, square </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{uweb-os}%</code></td>
+ </tr>
</table>
### <a name="Person, group, access icons"></a><a name=" Person, group, access icons"></a> <img src="http://www.dementia.org/twiki//view/Main/WebHome/person.gif" width="16" height="16" alt="person" /> Person, <img src="http://www.dementia.org/twiki//view/Main/WebHome/group.gif" width="16" height="16" alt="group" /> group, <img src="http://www.dementia.org/twiki//view/Main/WebHome/lock.gif" width="16" height="16" alt="lock" /> access icons
<td bgcolor="#ffffff" style=""><code>%ICON{notify}%</code></td>
</tr>
<tr>
+ <td bgcolor="#ffffff" style=""><img alt="Feed" src="http://www.dementia.org/twiki//view/feed.gif" title="Feed" /></td>
+ <td bgcolor="#ffffff" style=""><code>feed.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Feed </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{feed}%</code></td>
+ </tr>
+ <tr>
<td bgcolor="#ffffff" style=""><img alt="RSS feed" src="http://www.dementia.org/twiki//view/rss-feed.gif" title="RSS feed" /></td>
<td bgcolor="#ffffff" style=""><code>rss-feed.gif</code></td>
<td bgcolor="#ffffff" style=""> RSS feed, 36x14 </td>
<td bgcolor="#ffffff" style=""><code>%ICON{home}%</code></td>
</tr>
<tr>
- <td bgcolor="#ffffff" style=""><img alt="External site" src="http://www.dementia.org/twiki//view/external.gif" title="External site" /></td>
- <td bgcolor="#ffffff" style=""><code>external.gif</code></td>
- <td bgcolor="#ffffff" style=""> External site </td>
- <td bgcolor="#ffffff" style=""><code>%ICON{external}%</code></td>
+ <td bgcolor="#ffffff" style=""><img alt="Site map" src="http://www.dementia.org/twiki//view/sitemap.gif" title="Site map" /></td>
+ <td bgcolor="#ffffff" style=""><code>sitemap.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Site map </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{sitemap}%</code></td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><img alt="Site tree" src="http://www.dementia.org/twiki//view/sitetree.gif" title="Site tree" /></td>
+ <td bgcolor="#ffffff" style=""><code>sitetree.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Site tree </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{sitetree}%</code></td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><img alt="Topic back-links" src="http://www.dementia.org/twiki//view/topicbacklinks.gif" title="Topic back-links" /></td>
+ <td bgcolor="#ffffff" style=""><code>topicbacklinks.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Topic back-links </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{topicbacklinks}%</code></td>
</tr>
<tr>
<td bgcolor="#ffffff" style=""><img alt="Meet here (arrows to red dot)" src="http://www.dementia.org/twiki//view/arrowdot.gif" title="Meet here (arrows to red dot)" /></td>
<td bgcolor="#ffffff" style=""><code>%ICON{arrowdot}%</code></td>
</tr>
<tr>
+ <td bgcolor="#ffffff" style=""><img alt="External site" src="http://www.dementia.org/twiki//view/external.gif" title="External site" /></td>
+ <td bgcolor="#ffffff" style=""><code>external.gif</code></td>
+ <td bgcolor="#ffffff" style=""> External site </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{external}%</code></td>
+ </tr>
+ <tr>
<td bgcolor="#ffffff" style=""><img alt="Left" src="http://www.dementia.org/twiki//view/left.gif" title="Left" /></td>
<td bgcolor="#ffffff" style=""><code>left.gif</code></td>
<td bgcolor="#ffffff" style=""> Left </td>
<td bgcolor="#ffffff" style=""><img alt="Sort table" src="http://www.dementia.org/twiki//view/tablesortdiamond.gif" title="Sort table" /></td>
<td bgcolor="#ffffff" style=""><code>tablesortdiamond.gif</code></td>
<td bgcolor="#ffffff" style=""> Sort table </td>
- <td bgcolor="#ffffff" style=""><code>%ICON{tablesortdiamond}%</code></td>
+ <td bgcolor="#ffffff" style=""><code><img src="%ICONURL{tablesortdiamond}%" width="11" height="13" alt="Sort table" border="0" /></code></td>
</tr>
<tr>
<td bgcolor="#ffffff" style=""><img alt="Sort table descending" src="http://www.dementia.org/twiki//view/tablesortdown.gif" title="Sort table descending" /></td>
<td bgcolor="#ffffff" style=""><code>tablesortdown.gif</code></td>
<td bgcolor="#ffffff" style=""> Sort table descending </td>
- <td bgcolor="#ffffff" style=""><code>%ICON{tablesortdown}%</code></td>
+ <td bgcolor="#ffffff" style=""><code><img src="%ICONURL{tablesortdown}%" width="11" height="13" alt="Sort table descending" border="0" /></code></td>
</tr>
<tr>
<td bgcolor="#ffffff" style=""><img alt="Sort table ascending" src="http://www.dementia.org/twiki//view/tablesortup.gif" title="Sort table ascending" /></td>
<td bgcolor="#ffffff" style=""><code>tablesortup.gif</code></td>
<td bgcolor="#ffffff" style=""> Sort table ascending </td>
- <td bgcolor="#ffffff" style=""><code>%ICON{tablesortup}%</code></td>
+ <td bgcolor="#ffffff" style=""><code><img src="%ICONURL{tablesortup}%" width="11" height="13" alt="Sort table ascending" border="0" /></code></td>
</tr>
<tr>
<td bgcolor="#ffffff" style=""><img alt="Open toggle, Twisty open toggle" src="http://www.dementia.org/twiki//view/toggleopen.gif" title="Open toggle, Twisty open toggle" /></td>
<tr>
<td bgcolor="#ffffff" style=""><img alt="Web" src="http://www.dementia.org/twiki//view/web-bg.gif" title="Web" /></td>
<td bgcolor="#ffffff" style=""><code>web-bg.gif</code></td>
- <td bgcolor="#ffffff" style=""> Web background, used in [[TWiki/WebLeftBarWebsList]]</td>
+ <td bgcolor="#ffffff" style=""> Web background, used in %SYSTEMWEB%.WebLeftBarWebsList </td>
<td bgcolor="#ffffff" style=""><code>%ICON{web-bg}%</code></td>
</tr>
<tr>
<td bgcolor="#ffffff" style=""><code>%ICON{ps}%</code></td>
</tr>
<tr>
+ <td bgcolor="#ffffff" style=""><img alt="psd" src="http://www.dementia.org/twiki//view/psd.gif" title="psd" /></td>
+ <td bgcolor="#ffffff" style=""><code>psd.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Photoshop document </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{psd}%</code></td>
+ </tr>
+ <tr>
<td bgcolor="#ffffff" style=""><img alt="py" src="http://www.dementia.org/twiki//view/py.gif" title="py" /></td>
<td bgcolor="#ffffff" style=""><code>py.gif</code></td>
<td bgcolor="#ffffff" style=""> Python source code file </td>
<td bgcolor="#ffffff" style=""><code>%ICON{txt}%</code></td>
</tr>
<tr>
+ <td bgcolor="#ffffff" style=""><img alt="vsd" src="http://www.dementia.org/twiki//view/vsd.gif" title="vsd" /></td>
+ <td bgcolor="#ffffff" style=""><code>vsd.gif</code></td>
+ <td bgcolor="#ffffff" style=""> Visio document </td>
+ <td bgcolor="#ffffff" style=""><code>%ICON{vsd}%</code></td>
+ </tr>
+ <tr>
<td bgcolor="#ffffff" style=""><img alt="wav" src="http://www.dementia.org/twiki//view/wav.gif" title="wav" /></td>
<td bgcolor="#ffffff" style=""><code>wav.gif</code></td>
<td bgcolor="#ffffff" style=""> Waveform sound file </td>
> In
>
-> [[Main.TWikiPreferences|Main/TWikiPreferences]]
+> [[%USERSWEB%.TWikiPreferences|USERSWEB/TWikiPreferences]]
>
> set a variable to an ICON, for example:
>
> In any topic, write
>
-> `%PUBURL%/%TWIKIWEB%/TWikiDocGraphics/help.gif`
+> `%PUBURL%/%SYSTEMWEB%/TWikiDocGraphics/help.gif`
>
> to show
>
-> 
+> 
>
> You are not restricted to use the TWikiDocGraphics topic - in a similar way you can show attached images by replacing `TWikiDocGraphics` with the topic name.
**_Related Topics:_** [[TWikiSkins]], [[DeveloperDocumentationCategory]], [[AdminDocumentationCategory]]
-**_Contributors:_** Most icons on this page were originally designed by TWiki:Main.PeterThoeny. All icons were recreated by TWiki:Main.ArthurClemens, except for led-color icons, dot graph and line graph images.
+**_Contributors:_** Most icons on this page were originally designed by TWiki:Main.PeterThoeny. Many icons were recreated by TWiki:Main.ArthurClemens.
# <a name="TWiki Reference Manual (TWiki-4."></a><a name=" TWiki Reference Manual (TWiki-4"></a> TWiki Reference Manual (TWiki-4.1.2, Sat, 03 Mar 2007, build 13046)
-This page contains all documentation topics as one long, complete reference sheet.%BR% **_Doubleclick anywhere_** to return to the top of the page.
+This page contains all documentation topics as one long, complete reference sheet.
**_Related Topics:_** [[TWikiSite]], [[TWikiHistory]], [[TWikiPlannedFeatures]], [[TWikiEnhancementRequests]], [[UserDocumentationCategory]], [[AdminDocumentationCategory]]
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+[[Back to top|Main/WebHome#PageTop]]
+
----
+
+[[Back to top|Main/WebHome#PageTop]]
Global variables are avoided wherever possible to avoid problems with CGI accelerators such as mod\_perl.
+## <a name="Public Data members"></a> Public Data members
+
+- `cgiQuery` Pointer to the CGI::
+- `context` Hash of context ids
+- moved: `loginManager` TWiki::LoginManager singleton (moved to TWiki::Users)
+- `plugins` TWiki::Plugins singleton
+- `prefs` TWiki::Prefs singleton
+- `remoteUser` Login ID when using [[ApacheLogin]]. Maintained for compatibility only, do not use.
+- `requestedWebName` Name of web found in URL path or `web` URL parameter
+- `sandbox` TWiki::Sandbox singleton
+- `scriptUrlPath` URL path to the current script. May be dynamically extracted from the URL path if \{GetScriptUrlFromCgi\}. Only required to support \{GetScriptUrlFromCgi\} and not consistently used. Avoid.
+- `security` TWiki::Access singleton
+- `SESSION_TAGS` Hash of TWiki variables whose value is specific to the current CGI request.
+- `store` TWiki::Store singleton
+- `topicName` Name of topic found in URL path or `topic` URL parameter
+- `urlHost` Host part of the URL (including the protocol) determined during intialisation and defaulting to \{DefaultUrlHost\}
+- `user` Unique user ID of logged-in user
+- `users` TWiki::Users singleton
+- `webName` Name of web found in URL path, or `web` URL parameter, or \{UsersWebName\}
+
<div>
<ul>
<li><a href="#Package =TWiki="> Package TWiki</a><ul>
+ <li><a href="#Public Data members"> Public Data members</a></li>
<li><a href="#StaticMethod <strong>get_TWikiLibDir</strong> ("> StaticMethod getTWikiLibDir <tt>() -> $path</tt></a></li>
- <li><a href="#ObjectMethod *_UTF82SiteCharSet*"> ObjectMethod UTF82SiteCharSet <tt>($utf8) -> $ascii</tt></a></li>
+ <li><a href="#StaticMethod *_UTF82SiteCharSet*"> StaticMethod UTF82SiteCharSet <tt>($utf8) -> $ascii</tt></a></li>
<li><a href="#ObjectMethod *write_CompletePage"> ObjectMethod writeCompletePage <tt>($text,$pageType,$contentType)</tt></a></li>
- <li><a href="#ObjectMethod *write_PageHeader*"> ObjectMethod writePageHeader <tt>($query,$pageType,$contentType,$contentLength)</tt></a></li>
- <li><a href="#ObjectMethod <strong>redirect</strong> ($url,$p"> ObjectMethod redirect <tt>($url,$passthrough)</tt></a></li>
+ <li><a href="#ObjectMethod *generateHTTPHeader"> ObjectMethod generateHTTPHeaders <tt>($query,$pageType,$contentType,$contentLength) -> $header</tt></a></li>
+ <li><a href="#StaticMethod <strong>is_RedirectSafe</strong> ("> StaticMethod isRedirectSafe <tt>($redirect)=>$ok</tt></a></li>
+ <li><a href="#ObjectMethod <strong>redirect</strong> ($url,$p"> ObjectMethod redirect <tt>($url,$passthrough,$action_redirectto)</tt></a></li>
<li><a href="#ObjectMethod <strong>cacheQuery</strong> () ->"> ObjectMethod cacheQuery <tt>() -> $queryString</tt></a></li>
<li><a href="#StaticMethod *is_ValidWikiWord*"> StaticMethod isValidWikiWord <tt>($name) -> $boolean</tt></a></li>
<li><a href="#StaticMethod *is_ValidTopicName*"> StaticMethod isValidTopicName <tt>($name) -> $boolean</tt></a></li>
<li><a href="#ObjectMethod <strong>get_PubUrl</strong> ($abso"> ObjectMethod getPubUrl <tt>($absolute,$web,$topic,$attachment) -> $url</tt></a></li>
<li><a href="#ObjectMethod <strong>get_IconUrl</strong> ($abs"> ObjectMethod getIconUrl <tt>($absolute,$iconName) -> $iconURL</tt></a></li>
<li><a href="#ObjectMethod *map_ToIconFileName"> ObjectMethod mapToIconFileName <tt>($fileName,$default) -> $fileName</tt></a></li>
- <li><a href="#ObjectMethod <strong>get_OopsUrl</strong> ($tem"> ObjectMethod getOopsUrl <tt>($template,@options) -> $absoluteOopsURL</tt></a></li>
<li><a href="#ObjectMethod *normalize_WebTopic"> ObjectMethod normalizeWebTopicName <tt>($theWeb,$theTopic) -> ($theWeb,$theTopic)</tt></a></li>
<li><a href="#ClassMethod <strong>new</strong> ($loginName,$q"> ClassMethod new <tt>($loginName,$query,\%initialContext)</tt></a></li>
- <li><a href="#ObjectMethod *finish*"> ObjectMethod finish <tt></tt></a></li>
+ <li><a href="#ObjectMethod <strong>renderer</strong> ()"> ObjectMethod renderer <tt>()</tt></a></li>
+ <li><a href="#ObjectMethod <strong>attach</strong> ()"> ObjectMethod attach <tt>()</tt></a></li>
+ <li><a href="#ObjectMethod <strong>templates</strong> ()"> ObjectMethod templates <tt>()</tt></a></li>
+ <li><a href="#ObjectMethod <strong>i18n</strong> ()"> ObjectMethod i18n <tt>()</tt></a></li>
+ <li><a href="#ObjectMethod <strong>search</strong> ()"> ObjectMethod search <tt>()</tt></a></li>
+ <li><a href="#ObjectMethod <strong>security</strong> ()"> ObjectMethod security <tt>()</tt></a></li>
+ <li><a href="#ObjectMethod <strong>net</strong> ()"> ObjectMethod net <tt>()</tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
<li><a href="#ObjectMethod <strong>writeLog</strong> ($action"> ObjectMethod writeLog <tt>($action,$webTopic,$extra,$user)</tt></a></li>
<li><a href="#ObjectMethod <strong>writeWarning</strong> ($te"> ObjectMethod writeWarning <tt>($text)</tt></a></li>
<li><a href="#ObjectMethod <strong>writeDebug</strong> ($text"> ObjectMethod writeDebug <tt>($text)</tt></a></li>
<li><a href="#StaticMethod *apply_PatternToInc"> StaticMethod applyPatternToIncludedText <tt>($text,$pattern) -> $text</tt></a></li>
<li><a href="#ObjectMethod <strong>inlineAlert</strong> ($tem"> ObjectMethod inlineAlert <tt>($template,$def,...) -> $string</tt></a></li>
<li><a href="#StaticMethod <strong>parseSections</strong> ($t"> StaticMethod parseSections <tt>($text) -> ($string,$sectionlistref)</tt></a></li>
- <li><a href="#ObjectMethod *expand_VariablesOn"> ObjectMethod expandVariablesOnTopicCreation <tt>($text,$user) -> $text</tt></a></li>
+ <li><a href="#ObjectMethod *expand_VariablesOn"> ObjectMethod expandVariablesOnTopicCreation <tt>($text,$user,$web,$topic) -> $text</tt></a></li>
<li><a href="#StaticMethod <strong>entityEncode</strong> ($te"> StaticMethod entityEncode <tt>($text,$extras) -> $encodedText</tt></a></li>
<li><a href="#StaticMethod <strong>entityDecode</strong> ($en"> StaticMethod entityDecode <tt>($encodedText) -> $text</tt></a></li>
+ <li><a href="#StaticMethod *url_EncodeAttachme"> StaticMethod urlEncodeAttachment <tt>($text)</tt></a></li>
<li><a href="#StaticMethod <strong>urlEncode</strong> ($strin"> StaticMethod urlEncode <tt>($string) -> encodedstring</tt></a></li>
<li><a href="#StaticMethod <strong>urlDecode</strong> ($strin"> StaticMethod urlDecode <tt>($string) -> decodedstring</tt></a></li>
<li><a href="#StaticMethod <strong>isTrue</strong> ($value,$d"> StaticMethod isTrue <tt>($value,$default) -> $boolean</tt></a></li>
<li><a href="#StaticMethod *space_OutWikiWord*"> StaticMethod spaceOutWikiWord <tt>($word,$sep) -> $string</tt></a></li>
+ <li><a href="#ObjectMethod <strong>expand_AllTags</strong> (\"> ObjectMethod expandAllTags <tt>(\$text,$topic,$web,$meta)</tt></a></li>
<li><a href="#ObjectMethod <strong>enterContext</strong> ($id"> ObjectMethod enterContext <tt>($id,$val)</tt></a></li>
<li><a href="#ObjectMethod <strong>leaveContext</strong> ($id"> ObjectMethod leaveContext <tt>($id)</tt></a></li>
<li><a href="#ObjectMethod <strong>inContext</strong> ($id)"> ObjectMethod inContext <tt>($id)</tt></a></li>
<li><a href="#StaticMethod *register_TagHandle"> StaticMethod registerTagHandler <tt>($tag,$fnref)</tt></a></li>
<li><a href="#StaticMethod *registerRESTHandle"> StaticMethod registerRESTHandler <tt>($subject,$verb,\&fn)</tt></a></li>
<li><a href="#StaticMethod <strong>restDispatch</strong> ($su"> StaticMethod restDispatch <tt>($subject,$verb)=>\&fn</tt></a></li>
- <li><a href="#ObjectMethod *handle_CommonTags*"> ObjectMethod handleCommonTags <tt>($text,$web,$topic) -> $text</tt></a></li>
+ <li><a href="#ObjectMethod *handle_CommonTags*"> ObjectMethod handleCommonTags <tt>($text,$web,$topic,$meta) -> $text</tt></a></li>
<li><a href="#ObjectMethod <strong>add_ToHEAD</strong> ($id,$"> ObjectMethod addToHEAD <tt>($id,$html)</tt></a></li>
<li><a href="#StaticMethod <strong>initialize</strong> ($path"> StaticMethod initialize <tt>($pathInfo,$remoteUser,$topic,$url,$query) -> ($topicName,$webName,$scriptUrlPath,$userName,$dataDir)</tt></a></li>
<li><a href="#StaticMethod <strong>readFile</strong> ($filena"> StaticMethod readFile <tt>($filename) -> $text</tt></a></li>
## <a name="StaticMethod <strong>get_TWikiLibDir</strong> ("></a> [[StaticMethod]] **getTWikiLibDir** `() -> $path`
-STATIC method.
-
Returns the full path of the directory containing TWiki.pm
-## <a name="ObjectMethod <strong>_UTF82SiteCharSet*"></a> [[ObjectMethod]] \*UTF82SiteCharSet `($utf8) -> $ascii`
+## <a name="StaticMethod <strong>_UTF82SiteCharSet*"></a> [[StaticMethod]] \*UTF82SiteCharSet `($utf8) -> $ascii`
Auto-detect UTF-8 vs. site charset in string, and convert UTF-8 into site charset.
This method removes noautolink and nop tags before outputting the page unless $contentType is text/plain.
-## <a name="ObjectMethod <strong>write_PageHeader*"></a><a name="ObjectMethod *write_PageHeader</strong> "></a> [[ObjectMethod]] **writePageHeader** `($query,$pageType,$contentType,$contentLength)`
+## <a name="ObjectMethod <strong>generateHTTPHeader"></a> [[ObjectMethod]] \*generateHTTPHeaders `($query,$pageType,$contentType,$contentLength) -> $header`
All parameters are optional.
Implements the post-Dec2001 release plugin API, which requires the writeHeaderHandler in plugin to return a string of HTTP headers, CR/LF delimited. Filters any illegal headers. Plugin headers will override core settings.
-## <a name="ObjectMethod <strong>redirect</strong> ($url,$p"></a> [[ObjectMethod]] **redirect** `($url,$passthrough)`
+Does **not** add a `Content-length` header.
+
+## <a name="StaticMethod <strong>is_RedirectSafe</strong> ("></a> [[StaticMethod]] **isRedirectSafe** `($redirect)=>$ok`
+
+tests if the $redirect is an external URL, returning false if [[AllowRedirectUrl]] is denied
+
+## <a name="ObjectMethod <strong>redirect</strong> ($url,$p"></a> [[ObjectMethod]] **redirect** `($url,$passthrough,$action_redirectto)`
+
+- $url - url or twikitopic to redirect to
+- $passthrough - (optional) parameter to **\*FILLMEIN\***
+- $action\_redirectto - (optional) redirect to where ?redirectto= points to (if it's valid)
Redirects the request to `$url`, **unless**
Thus a redirect is only generated when in a CGI context.
-Normally this method will ignore parameters to the current query. If $passthrough is set, then it will pass all parameters that were passed to the current query on to the redirect target. If the request\_method was GET, then all parameters can be passed in the URL. If the request\_method was POST then it caches the form data and passes over a cache reference in the redirect GET.
+Normally this method will ignore parameters to the current query. Sometimes, for example when redirecting to a login page during authentication (and then again from the login page to the original requested URL), you want to make sure all parameters are passed on, and for this $passthrough should be set to true. In this case it will pass all parameters that were passed to the current query on to the redirect target. If the request\_method for the current query was GET, then all parameters will be passed by encoding them in the URL (after ?). If the request\_method was POST, then there is a risk the URL would be too big for the receiver, so it caches the form data and passes over a cache reference in the redirect GET.
-Passthrough is only meaningful if the redirect target is on the same server.
+NOTE: Passthrough is only meaningful if the redirect target is on the same server.
## <a name="ObjectMethod <strong>cacheQuery</strong> () - $"></a> [[ObjectMethod]] **cacheQuery** `() -> $queryString`
STATIC Check for a valid web name. If $system is true, then system web names are considered valid (names starting with \_) otherwise only user web names are valid
+If $TWiki::cfg\{EnableHierarchicalWebs\} is off, it will also return false when a nested web name is passed to it.
+
## <a name="ObjectMethod <strong>read_OnlyMirrorWeb"></a> [[ObjectMethod]] \*readOnlyMirrorWeb `($theWeb) -> ($mirrorSiteName,$mirrorViewURL,$mirrorLink,$mirrorNote)`
If this is a mirrored web, return information about the mirror. The info is returned in a quadruple:
Maps from a filename (or just the extension) to the name of the file that contains the image for that file type.
-## <a name="ObjectMethod <strong>get_OopsUrl</strong> ($tem"></a> [[ObjectMethod]] **getOopsUrl** `($template,@options) -> $absoluteOopsURL`
-
-Composes a URL for an "oops" error page. The @options consists of a list of key => value pairs. The following keys are used:
-
-- `-web` - web name
-- `-topic` - topic name
-- `-def` - optional template def within the main template file
-- `-params` - a single parameter, or a reference to an array of parameters These are passed in the URL as '&param1=' etc.
-
-Do _not_ include the "oops" part in front of the template name.
-
-Alternatively you can pass a reference to an [[OopsException]] in place of the template. All other parameters will be ignored.
-
-The returned URL ends up looking something like this: "http://host/twiki/bin/oops/$web/$topic?template=$template&param1=$scriptParams[0]..."
-
-Note: if \{keep\} is true in the params, then they will also be pushed into the current query.
-
## <a name="ObjectMethod <strong>normalize_WebTopic"></a> [[ObjectMethod]] \*normalizeWebTopicName `($theWeb,$theTopic) -> ($theWeb,$theTopic)`
Normalize a Web.TopicName
Constructs a new TWiki object. Parameters are taken from the query object.
-- `$loginName` is the username of the user you want to be logged-in if none is available from a session or browser. Used mainly for side scripts and debugging.
+- `$loginName` is the login username (**not** the wikiname) of the user you want to be logged-in if none is available from a session or browser. Used mainly for side scripts and debugging.
- `$query` the CGI query (may be undef, in which case an empty query is used)
- `\%initialContext` - reference to a hash containing context name=value pairs to be pre-installed in the context hash
-## <a name="ObjectMethod <strong>finish*"></a><a name="ObjectMethod *finish</strong> "></a> [[ObjectMethod]] **finish** ``
+## <a name="ObjectMethod <strong>renderer</strong> ()"></a> [[ObjectMethod]] **renderer** `()`
+
+Get a reference to the renderer object. Done lazily because not everyone needs the renderer.
+
+## <a name="ObjectMethod <strong>attach</strong> ()"></a> [[ObjectMethod]] **attach** `()`
+
+Get a reference to the attach object. Done lazily because not everyone needs the attach.
+
+## <a name="ObjectMethod <strong>templates</strong> ()"></a> [[ObjectMethod]] **templates** `()`
+
+Get a reference to the templates object. Done lazily because not everyone needs the templates.
+
+## <a name="ObjectMethod <strong>i18n</strong> ()"></a> [[ObjectMethod]] **i18n** `()`
-Complete processing after the client's HTTP request has been responded to. Right now this does two things:
+Get a reference to the i18n object. Done lazily because not everyone needs the i18ner.
-1. calling TWiki::Client to flushing the user's session (if any) to disk,
-2. breaking circular references to allow garbage collection in persistent environments
+## <a name="ObjectMethod <strong>search</strong> ()"></a> [[ObjectMethod]] **search** `()`
+
+Get a reference to the search object. Done lazily because not everyone needs the searcher.
+
+## <a name="ObjectMethod <strong>security</strong> ()"></a> [[ObjectMethod]] **security** `()`
+
+Get a reference to the security object. Done lazily because not everyone needs the security.
+
+## <a name="ObjectMethod <strong>net</strong> ()"></a> [[ObjectMethod]] **net** `()`
+
+Get a reference to the net object. Done lazily because not everyone needs the net.
+
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
+
+Break circular references.
## <a name="ObjectMethod <strong>writeLog</strong> ($action"></a> [[ObjectMethod]] **writeLog** `($action,$webTopic,$extra,$user)`
- `$action` - what happened, e.g. view, save, rename
- `$wbTopic` - what it happened to
- `$extra` - extra info, such as minor flag
-- `$user` - user who did the saving (user object or string user name)
+- `$user` - user who did the saving (user id)
Write the log for an event to the logfile
See test/unit/Fn\_SECTION.pm for detailed testcases that round out the spec.
-## <a name="ObjectMethod <strong>expand_VariablesOn"></a> [[ObjectMethod]] \*expandVariablesOnTopicCreation `($text,$user) -> $text`
+## <a name="ObjectMethod <strong>expand_VariablesOn"></a> [[ObjectMethod]] \*expandVariablesOnTopicCreation `($text,$user,$web,$topic) -> $text`
- `$text` - text to expand
-- `$user` - reference to user object. This is the user expanded in e.g. %USERNAME. Optional, defaults to logged-in user.
+- `$user` - This is the user expanded in e.g. %USERNAME. Optional, defaults to logged-in user.
Expand limited set of variables during topic creation. These are variables expected in templates that must be statically expanded in new content.
+- `$web` - name of web
+- `$topic` - name of topic
+
# SMELL: no plugin handler
## <a name="StaticMethod <strong>entityEncode</strong> ($te"></a> [[StaticMethod]] **entityEncode** `($text,$extras) -> $encodedText`
Decodes all numeric entities (e.g. &#123;). _Does not_ decode named entities such as &amp; (use HTML::Entities for that)
+## <a name="StaticMethod <strong>url_EncodeAttachme"></a> [[StaticMethod]] \*urlEncodeAttachment `($text)`
+
+For attachments, URL-encode specially to 'freeze' any characters >127 in the site charset (e.g. ISO-8859-1 or KOI8-R), by doing URL encoding into native charset ($siteCharset) - used when generating attachment URLs, to enable the web server to serve attachments, including images, directly.
+
+This encoding is required to handle the cases of:
+
+- browsers that generate UTF-8 URLs automatically from site charset URLs - now quite common - web servers that directly serve attachments, using the site charset for filenames, and cannot convert UTF-8 URLs into site charset filenames
+
+The aim is to prevent the browser from converting a site charset URL in the web page to a UTF-8 URL, which is the default. Hence we 'freeze' the URL into the site character set through URL encoding.
+
+In two cases, no URL encoding is needed: For EBCDIC mainframes, we assume that site charset URLs will be translated (outbound and inbound) by the web server to/from an EBCDIC character set. For sites running in UTF-8, there's no need for TWiki to do anything since all URLs and attachment filenames are already in UTF-8.
+
## <a name="StaticMethod <strong>urlEncode</strong> ($strin"></a> [[StaticMethod]] **urlEncode** `($string) -> encodedstring`
Encode by converting characters that are illegal in URLs to their %NN equivalents. This method is used for encoding strings that must be embedded _verbatim_ in URLs; it cannot be applied to URLs themselves, as it escapes reserved characters such as = and ?.
RFC 1738, Dec. '94:
- >
- ...Only alphanumerics [0-9a-zA-Z], the special
- characters $-_.+!*'(), and reserved characters used for their
- reserved purposes may be used unencoded within a URL.
+ ...Only alphanumerics [0-9a-zA-Z], the special
+ characters $-_.+!*'(), and reserved characters used for their
+ reserved purposes may be used unencoded within a URL.
Reserved characters are $&+,/:;=?@ - these are _also_ encoded by this method.
-SMELL: For non-ISO-8859-1 $TWiki::cfg\{Site\}\{CharSet\}, need to convert to UTF-8 before URL encoding. This encoding only supports 8-bit character codes.
+This URL-encoding handles all character encodings including ISO-8859-\*, KOI8-R, EUC-\* and UTF-8.
+
+This may not handle EBCDIC properly, as it generates an EBCDIC URL-encoded URL, but mainframe web servers seem to translate this outbound before it hits browser - see CGI::Util::escape for another approach.
## <a name="StaticMethod <strong>urlDecode</strong> ($strin"></a> [[StaticMethod]] **urlDecode** `($string) -> decodedstring`
Spaces out a wiki word by inserting a string (default: one space) between each word component. With parameter $sep any string may be used as separator between the word components; if $sep is undefined it defaults to a space.
+## <a name="ObjectMethod <strong>expand_AllTags</strong> (\"></a> [[ObjectMethod]] **expandAllTags** `(\$text,$topic,$web,$meta)`
+
+Expands variables by replacing the variables with their values. Some example variables: %TOPIC%, %SCRIPTURL%, %WIKINAME%, etc. $web and $incs are passed in for recursive include expansion. They can safely be undef. The rules for tag expansion are:
+
+1. Tags are expanded left to right, in the order they are encountered.
+2. Tags are recursively expanded as soon as they are encountered - the algorithm is inherently single-pass
+3. A tag is not "encountered" until the matching \}% has been seen, by which time all tags in parameters will have been expanded
+4. Tag expansions that create new tags recursively are limited to a set number of hierarchical levels of expansion
+
## <a name="ObjectMethod <strong>enterContext</strong> ($id"></a> [[ObjectMethod]] **enterContext** `($id,$val)`
Add the context id $id into the set of active contexts. The $val can be anything you like, but should always evaluate to boolean TRUE.
**Since:** TWiki::Plugins::VERSION 1.1
-## <a name="ObjectMethod <strong>handle_CommonTags*"></a> [[ObjectMethod]] \*handleCommonTags `($text,$web,$topic) -> $text`
+## <a name="ObjectMethod <strong>handle_CommonTags*"></a> [[ObjectMethod]] \*handleCommonTags `($text,$web,$topic,$meta) -> $text`
Processes %VARIABLE%, and %TOC% syntax; also includes 'commonTagsHandler' plugin hook.
Returns the text of the topic, after file inclusion, variable substitution, table-of-contents generation, and any plugin changes from commonTagsHandler.
+$meta may be undef when, for example, expanding templates, or one-off strings at a time when meta isn't available.
+
## <a name="ObjectMethod <strong>add_ToHEAD</strong> ($id,$"></a> [[ObjectMethod]] **addToHEAD** `($id,$html)`
Add `$html` to the HEAD tag of the page currently being generated.
2nd paragraph
</pre></td>
- <td> 1st paragraph <p> 2nd paragraph </p>
+ <td>
+ <p> 1st paragraph </p>
+ <p> 2nd paragraph </p>
</td>
</tr>
<tr valign="top">
---+++!! Not in TOC
</pre></td>
<td>
+ <p>
+ </p>
<h2>Sushi</h2>
<h3>Maguro</h3>
<h3>Not in TOC</h3>
<td><pre>
*Bold*
</pre></td>
- <td><strong>Bold</strong></td>
+ <td>
+ <p><strong>Bold</strong></p>
+ </td>
</tr>
<tr valign="top">
<td><strong>Italic Text:</strong> %BR% Words get shown in <em>italic</em> by enclosing them in <code>_</code> underscores. </td>
<td><pre>
_Italic_
</pre></td>
- <td><em>Italic</em></td>
+ <td>
+ <p><em>Italic</em></p>
+ </td>
</tr>
<tr valign="top">
<td><strong>Bold Italic:</strong> %BR% Words get shown in <strong><em>bold italic</em></strong> by enclosing them in <code>__</code> double-underscores. </td>
<td><pre>
__Bold italic__
</pre></td>
- <td><strong><em>Bold italic</em></strong></td>
+ <td>
+ <p><strong><em>Bold italic</em></strong></p>
+ </td>
</tr>
<tr valign="top">
<td><strong>Fixed Font:</strong> %BR% Words get shown in <code>fixed font</code> by enclosing them in <code>=</code> equal signs. </td>
<td><pre>
=Fixed font=
</pre></td>
- <td><code>Fixed font</code><p>
+ <td>
+ <p><code>Fixed font</code></p>
+ <p>
</p>
</td>
</tr>
<td><pre>
==Bold fixed==
</pre></td>
- <td><code><b>Bold fixed</b></code></td>
+ <td>
+ <p><code><b>Bold fixed</b></code></p>
+ </td>
</tr>
<tr valign="top">
<td> %T% You can follow the closing bold, italic, or other (<code>* _ __ = ==</code>) indicator with normal punctuation, such as commas and full stops. <p> %X% Make sure there is no space between the text and the indicators. </p>
_This works_,
_this does not _
</pre></td>
- <td><em>This works</em>,%BR% _this does not _ </td>
+ <td>
+ <p><em>This works</em>,%BR% _this does not _ </p>
+ </td>
</tr>
<tr valign="top">
- <td><strong>Verbatim (Literal) Text:</strong> %BR% Surround code excerpts and other formatted text with <code><verbatim></code> and <code></verbatim></code> tags.%BR% %T% <code>verbatim</code> tags disable HTML code. Use <code><pre></code> and <code></pre></code> tags instead if you want the HTML code within the tags to be interpreted.%BR% <strong><em>%X% NOTE:</em></strong> Preferences variables (* Set NAME = value) are set within verbatim tags. </td>
+ <td><strong>Verbatim Text:</strong> %BR% Surround code excerpts and other formatted text with <code><verbatim></code> and <code></verbatim></code> tags.%BR% %T% <code>verbatim</code> tags disable HTML code. Use <code><pre></code> and <code></pre></code> tags instead if you want the HTML code within the tags to be interpreted.%BR% <strong><em>%X% NOTE:</em></strong> Preferences variables (* Set NAME = value) are set within verbatim tags. </td>
<td><pre>
<verbatim>
class CatAnimal {
-------
</pre></td>
<td>
+ <p>
+ </p>
<hr />
</td>
</tr>
* last bullet
</pre></td>
<td>
+ <p>
+ </p>
<ul>
<li> level 1 <ul>
<li> level 2 </li>
i. Fondue
</pre></td>
<td>
+ <p>
+ </p>
<ol>
<li> Sushi </li>
<li> Dim Sum </li>
</td>
</tr>
<tr valign="top">
- <td><strong>Definition List:</strong> %BR% Three spaces, a dollar sign, the term, a colon, a space, followed by the definition. </td>
+ <td><strong>Definition List:</strong> %BR% Three spaces, a dollar sign, the term, a colon, a space, followed by the definition. <p> Deprecated syntax: Three spaces, the term with no spaces, a colon, a space, followed by the definition. </p>
+ </td>
<td><pre>
$ Sushi: Japan
$ Dim Sum: S.F.
</pre></td>
<td>
+ <p>
+ </p>
<dl>
<dt> Sushi </dt>
<dd> Japan </dd>
<li><code>|^|</code> cell with caret indicating follow-up row of multi-span rows </li>
<li> You can split rows over multiple lines by putting a backslash <code>'\'</code> at the end of each line </li>
<li> Contents of table cells wrap automatically as determined by the browser </li>
- <li> Use <code>&#124;</code> or <code>%VBAR%</code> to add <code>|</code> characters in tables. </li>
- </ul> %T% The [[TWiki/TablePlugin]] provides the <code>|^|</code> multiple-span row functionality and additional rendering features </td>
+ <li> Use <code>%VBAR%</code> or <code>&#124;</code> to add <code>|</code> characters in tables. </li>
+ <li> Use <code>%CARET%</code> or <code>&#94;</code> to add <code>^</code> characters in tables. </li>
+ </ul> %T% The %SYSTEMWEB%.TablePlugin provides the <code>|^|</code> multiple-span row functionality and additional rendering features </td>
<td><pre>
| *L* | *C* | *R* |
| A2 | B2 | C2 |
| A9 | B9 | C9 |
</pre></td>
<td>
+ <p>
+ </p>
<table border="1" cellpadding="0" cellspacing="0" style="border-width: 1px">
<tr>
<th bgcolor="#6b7f93" maxcols="0" style=""><a href="http://localhost?sortcol=0;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">L</font></a></th>
</td>
</tr>
<tr valign="top">
- <td><strong>WikiWord Links:</strong> %BR% CapitalizedWordsStuckTogether (or [[Main/WikiWords]]) will produce a link automatically if preceded by whitespace or parenthesis. %BR% %T% If you want to link to a topic in a different web write <code>Otherweb.TopicName</code>. %BR% %H% 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. <p> It's generally a good idea to use the [[Main/TWikiVariables]] %TWIKIWEB% and %MAINWEB% instead of TWiki and Main. </p>
+ <td><strong>WikiWord Links:</strong> %BR% CapitalizedWordsStuckTogether (or [[Main/WikiWords]]) will produce a link automatically if preceded by whitespace or parenthesis. %BR% %T% If you want to link to a topic in a different web write <code>Otherweb.TopicName</code>. %BR% To link to a topic in a subweb write <code>Otherweb.Subweb.TopicName</code>.%BR% %H% 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. %BR% %X% Dots <code>'.'</code> are used to separate webs and subwebs from topic names and therefore cannot be used in topic names. <p> It's generally a good idea to use the [[Main/TWikiVariables]] %SYSTEMWEB% and %USERSWEB% instead of TWiki and Main. </p>
</td>
<td><pre>
WebStatistics
Sandbox.WebNotify
Sandbox.WebHome
+
+Sandbox.Subweb.TopicName
</pre></td>
- <td>[[Main/WebStatistics]]<p>[[Sandbox/WebNotify]]</p>
+ <td>
+ <p>[[Main/WebStatistics]]</p>
+ <p>[[Sandbox/WebNotify]]</p>
<p>[[Sandbox/WebHome]]</p>
+ <p><a href="#MyAnchor" title="simulated link">TopicName</a></p>
</td>
</tr>
<tr valign="top">
- <td><strong>Anchors:</strong> %BR% You can define a reference inside a TWiki topic (called an anchor name) and link to that. To <strong><em>define</em></strong> an anchor write <code>#AnchorName</code> at the beginning of a line. The anchor name must be a [[Main/WikiWord]]. To <strong><em>link to</em></strong> an anchor name use the <code>[[MyTopic#MyAnchor]]</code> syntax. You can omit the topic name if you want to link within the same topic. </td>
+ <td><strong>Anchors:</strong> %BR% You can define a reference inside a TWiki topic (called an anchor name) and link to that. To <strong><em>define</em></strong> an anchor write <code>#AnchorName</code> at the beginning of a line. The anchor name must be a [[Main/WikiWord]] of no more than 32 characters. To <strong><em>link to</em></strong> an anchor name use the <code>[[MyTopic#MyAnchor]]</code> syntax. You can omit the topic name if you want to link within the same topic. </td>
<td><pre>
[[WikiWord#NotThere]]
#MyAnchor To here
</pre></td>
- <td>[[Main/WikiWord#NotThere]]<p>[[Main/WebHome#MyAnchor]]</p>
+ <td>
+ <p>[[Main/WikiWord#NotThere]]</p>
+ <p>[[Main/WebHome#MyAnchor]]</p>
<p><a name="MyAnchor"></a> To here </p>
</td>
</tr>
<td><pre>
[[wiki syntax]]
-[[Main.TWiki users]]
+[[Main.TWiki groups]]
escaped:
![[wiki syntax]]
</pre></td>
- <td>[[Main/WikiSyntax]]<p>[[Main/TWikiUsers]]</p>
+ <td>
+ <p>[[Main/WikiSyntax]]</p>
+ <p>[[USERSWEB/TWikiGroups]]</p>
<p> escaped: [[wiki syntax]] </p>
</td>
</tr>
[[http://gnu.org][GNU]]
</pre></td>
- <td>[[Main/WikiSyntax]]<p><a href="http://gnu.org" target="_top">GNU</a></p>
+ <td>
+ <p>[[Main/WikiSyntax]]</p>
+ <p><a href="http://gnu.org" target="_top">GNU</a></p>
</td>
</tr>
<tr valign="top">
<td><strong>Disable Links:</strong> %BR% You can disable automatic linking of [[Main/WikiWords]] by surrounding text with <code><noautolink></code> and <code></noautolink></code> tags.%BR% %H% It is possible to turn off all auto-linking with a NOAUTOLINK preferences setting. </td>
<td><pre>
<noautolink>
- RedHat &
- SuSE
+ RedHat & SuSE
</noautolink>
</pre></td>
- <td> RedHat & SuSE </td>
+ <td>
+ <p> RedHat & SuSE </p>
+ </td>
</tr>
<tr valign="top">
<td><strong>Mailto Links:</strong> %BR% 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 <code>[[mailto:user@domain][descriptive text]]</code>. </td>
[[mailto:?subject=\
Hi][Hi]]
</pre></td>
- <td><a href="mailto:a@b.com">a@b.com</a><p><a href="mailto:a@b.com">Mail</a></p>
+ <td>
+ <p><a href="mailto:a@b.com">a@b.com</a></p>
+ <p><a href="mailto:a@b.com">Mail</a></p>
<p><a href="mailto:?subject=Hi">Hi</a></p>
</td>
</tr>
+ <tr>
+ <td><strong>Literal content:</strong> %BR% TWiki generates HTML code from TWiki shorthand. <strong>Experts</strong> surround anything that must be output literally in the HTML code, without the application of TWiki shorthand rules, with <code><literal>..</literal></code> tags. %X% any HTML within literal tags <strong>must</strong> be well formed i.e. all tags must be properly closed before the end of the literal block. %I% TWiki Variables are expanded within literal blocks. </td>
+ <td><pre>
+<literal>
+| Not | A | Table |
+<literal>
+</pre></td>
+ <td> | Not | A | Table | </td>
+ </tr>
+ <tr>
+ <td><strong>Protected content:</strong> %BR% <strong>Experts</strong> protect text from mangling by WYSIWYG editors using <code><sticky>..</sticky></code> 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. </td>
+ <td><code><sticky></code> <pre>
+<div>
+This div is required
+</div>
+</pre> <code><sticky></code></td>
+ <td><sticky><div> This div is required </div></sticky></td>
+ </tr>
</table>
Object representing a single form definition.
+Form definitions are mainly used to control rendering of a form for editing, though there is some application login there that handles transferring values between edits and saves.
+
+A form definition consists of a TWiki::Form object, which has a list of field definitions. Each field definition is an object of a type derived from TWiki::Form::FieldDefinition. These objects are responsible for the actual syntax and semantics of the field type. Form definitions are parsed from TWiki tables, and the types are mapped by name to a class declared in TWiki::Form::\* - for example, the `text` type is mapped to `TWiki::Form::Text` and the `checkbox` type to `TWiki::Form::Checkbox`.
+
+The `TWiki::Form::FieldDefinition` class declares default behaviours for types that accept a single value in their definitions. The `TWiki::Form::ListFieldDefinition` extends this for types that have lists of possible values.
+
<div>
<ul>
<li><a href="#Package =TWiki::Form="> Package TWiki::Form</a><ul>
<li><a href="#ClassMethod <strong>new</strong> ($session,$web"> ClassMethod new <tt>($session,$web,$form,$def)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
+ <li><a href="#StaticMethod *field_Title2FieldN"> StaticMethod fieldTitle2FieldName <tt>($title) -> $name</tt></a></li>
<li><a href="#ObjectMethod <strong>render_ForEdit</strong> ($"> ObjectMethod renderForEdit <tt>($web,$topic,$meta) -> $html</tt></a></li>
- <li><a href="#ObjectMethod *render_FieldForEdi"> ObjectMethod renderFieldForEdit <tt>($fieldDef,$web,$topic,$value) -> $html</tt></a></li>
<li><a href="#ObjectMethod <strong>renderHidden</strong> ($me"> ObjectMethod renderHidden <tt>($meta) -> $html</tt></a></li>
- <li><a href="#ObjectMethod <strong>cgiName</strong> ($field)"> ObjectMethod cgiName <tt>($field) -> $string</tt></a></li>
<li><a href="#ObjectMethod *get_FieldValuesFro"> ObjectMethod getFieldValuesFromQuery <tt>($query,$metaObject) -> ($seen,\@missing)</tt></a></li>
<li><a href="#ObjectMethod *is_TextMergeable*"> ObjectMethod isTextMergeable <tt>($name) -> $boolean</tt></a></li>
- <li><a href="#ObjectMethod <strong>getField</strong> ($name)"> ObjectMethod getField <tt>($name) -> \%row</tt></a></li>
+ <li><a href="#ObjectMethod <strong>getField</strong> ($name)"> ObjectMethod getField <tt>($name) -> $fieldDefinition</tt></a></li>
<li><a href="#ObjectMethod <strong>getFields</strong> () -> \"> ObjectMethod getFields <tt>() -> \@fields</tt></a></li>
- <li><a href="#StaticMethod *render_ForDisplay*"> StaticMethod renderForDisplay <tt>($templates,$meta)</tt></a></li>
</ul>
</li>
</ul>
## <a name="ClassMethod <strong>new</strong> ($session,$web"></a> [[ClassMethod]] **new** `($session,$web,$form,$def)`
+Looks up a form in the session object or, if it hasn't been read yet, reads it frm the form definition topic on disc.
+
- $web - default web to recover form from, if $form doesn't specify a web
- `$form` - topic name to read form definition from
- `$def` - optional. a reference to a list of field definitions. if present, these definitions will be used, rather than those in `$form`.
May throw TWiki::OopsException
-## <a name="ObjectMethod <strong>render_ForEdit</strong> ($"></a> [[ObjectMethod]] **renderForEdit** `($web,$topic,$meta) -> $html`
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
-- `$web` the web of the topic being rendered
-- `$topic` the topic being rendered
-- `$meta` the meta data for the form
+Break circular references.
-Render the form fields for entry during an edit session, using data values from $meta
+## <a name="StaticMethod <strong>field_Title2FieldN"></a> [[StaticMethod]] \*fieldTitle2FieldName `($title) -> $name`
+
+Chop out all except A-Za-z0-9\_. from a field name to create a valid "name" for storing in meta-data
-## <a name="ObjectMethod <strong>render_FieldForEdi"></a> [[ObjectMethod]] \*renderFieldForEdit `($fieldDef,$web,$topic,$value) -> $html`
+## <a name="ObjectMethod <strong>render_ForEdit</strong> ($"></a> [[ObjectMethod]] **renderForEdit** `($web,$topic,$meta) -> $html`
-- `$fieldDef` the field being rendered
- `$web` the web of the topic being rendered
- `$topic` the topic being rendered
-- `$value` the current value of the field
-
-Render a single form field for entry during an edit session, using data values from $meta. Plugins can provide a handler that extends the set of supported types
+- `$meta` the meta data for the form
-SMELL: this should be a method on a field class
+Render the form fields for entry during an edit session, using data values from $meta
## <a name="ObjectMethod <strong>renderHidden</strong> ($me"></a> [[ObjectMethod]] **renderHidden** `($meta) -> $html`
Render form fields found in the meta as hidden inputs, so they pass through edits untouched.
-## <a name="ObjectMethod <strong>cgiName</strong> ($field)"></a><a name="ObjectMethod <strong>cgiName</strong> ($field) "></a> [[ObjectMethod]] **cgiName** `($field) -> $string`
-
-Generate the 'name' of the CGI parameter used to represent a field.
-
## <a name="ObjectMethod <strong>get_FieldValuesFro"></a> [[ObjectMethod]] \*getFieldValuesFromQuery `($query,$metaObject) -> ($seen,\@missing)`
Extract new values for form fields from a query.
If the form does not define the field, it is assumed to be mergeable.
-## <a name="ObjectMethod <strong>getField</strong> ($name)"></a><a name="ObjectMethod <strong>getField</strong> ($name) "></a> [[ObjectMethod]] **getField** `($name) -> \%row`
+## <a name="ObjectMethod <strong>getField</strong> ($name)"></a><a name="ObjectMethod <strong>getField</strong> ($name) "></a> [[ObjectMethod]] **getField** `($name) -> $fieldDefinition`
- `$name` - name of a form field (value of the `name` attribute)
-Returns the field, or undef if the form does not define the field.
+Returns a `TWiki::Form::FieldDefinition`, or undef if the form does not define the field.
## <a name="ObjectMethod <strong>getFields</strong> () - \@"></a> [[ObjectMethod]] **getFields** `() -> \@fields`
Return a list containing references to field name/value pairs. Each entry in the list has a \{name\} field and a \{value\} field. It may have other fields as well, which caller should ignore. The returned list should be treated as **read only** (must not be written to).
-
-## <a name="StaticMethod <strong>render_ForDisplay*"></a> [[StaticMethod]] \*renderForDisplay `($templates,$meta)`
-
-- `$templates` ref to templates singleton
-- `$meta` - meta object containing the form to be rendered
-
-Static because we want to be able to do this without a form definition.
-
-SMELL: Why? Is reading the form topic such a big burden?
--- /dev/null
+# <a name="Package <code>TWiki::Form::_FieldDefi"></a> Package =TWiki::Form::FieldDefinition
+
+Base class of all field definition classes.
+
+Type-specific classes are derived from this class to define specific per-type behaviours. This class also provides default behaviours for when a specific type cannot be loaded.
+
+<div>
+ <ul>
+ <li><a href="#Package =TWiki::Form::_FieldDefi"> Package TWiki::Form::FieldDefinition</a><ul>
+ <li><a href="#ClassMethod <strong>new</strong> (%...)"> ClassMethod new <tt>(%...)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
+ <li><a href="#isEditable() -> $boolean"> isEditable() -> $boolean</a></li>
+ <li><a href="#is_MultiValued() -> $boolean"> isMultiValued() -> $boolean</a></li>
+ <li><a href="#is_TextMergeable() -> $boolean"> isTextMergeable() -> $boolean</a></li>
+ <li><a href="#isMandatory() -> $boolean"> isMandatory() -> $boolean</a></li>
+ <li><a href="#render_ForEdit( $web, $topic, $v"> renderForEdit( $web, $topic, $value ) -> ($col0html, $col1html)</a></li>
+ <li><a href="#cssClasses(@classes) -> $classes"> cssClasses(@classes) -> $classes</a></li>
+ <li><a href="#get_DefaultValue() -> $value"> getDefaultValue() -> $value</a></li>
+ <li><a href="#renderHidden($meta) -> $html"> renderHidden($meta) -> $html</a></li>
+ <li><a href="#populate_MetaDataFromQuery( $que"> populateMetaDataFromQuery( $query, $meta, $old ) -> ($bValid, $bPresent)</a></li>
+ <li><a href="#ObjectMethod *render_ForDisplay*"> ObjectMethod renderForDisplay <tt>($format,$attrs) -> $html</tt></a></li>
+ </ul>
+ </li>
+ </ul>
+</div>
+
+## <a name="ClassMethod <strong>new</strong> (%...)"></a> [[ClassMethod]] **new** `(%...)`
+
+Construct a new [[FieldDefinition]]. Parameters are passed in a hash. See Form.pm for how it is called. Subclasses should pass @\_ on to this class.
+
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
+
+Break circular references.
+
+## <a name="isEditable() - $boolean"></a> isEditable() -> $boolean
+
+Is the field type editable? Labels aren't, for example. Subclasses may need to redefine this.
+
+## <a name="is_MultiValued() - $boolean"></a> isMultiValued() -> $boolean
+
+Is the field type multi-valued (i.e. does it store multiple values)? Subclasses may need to redefine this.
+
+## <a name="is_TextMergeable() - $boolean"></a> isTextMergeable() -> $boolean
+
+Is this field type mergeable using a conventional text merge?
+
+## <a name="isMandatory() - $boolean"></a> isMandatory() -> $boolean
+
+Is this field mandatory (required)?
+
+## <a name="render_ForEdit( $web, $topic, $v"></a> renderForEdit( $web, $topic, $value ) -> ($col0html, $col1html)
+
+`$web` - the web containing the topic being edited `$topic` - the topic being edited Render the field for editing. Returns two chunks of HTML; the `$col0html` is appended to the HTML for the first column in the form table, and the `$col1html` is used as the content of the second column.
+
+## <a name="cssClasses(@classes) - $classes"></a> cssClasses(@classes) -> $classes
+
+Construct a list of the CSS classes for the form field. Adds additional class specifiers related to the attributes of the field e.g mandatory. Pass it a list of the other classnames you want on the field.
+
+## <a name="get_DefaultValue() - $value"></a> getDefaultValue() -> $value
+
+Try and get a sensible default value for the field from the values stored in the form definition. The result should be a value string.
+
+Some subclasses may not support the definition of defaults in the form definition. In that case this method should return `undef`.
+
+## <a name="renderHidden($meta) - $html"></a> renderHidden($meta) -> $html
+
+Render the form in `$meta` as a set of hidden fields.
+
+## <a name="populate_MetaDataFromQuery( $que"></a> populateMetaDataFromQuery( $query, $meta, $old ) -> ($bValid, $bPresent)
+
+Given a CGI `$query`, a `$meta` object, and an array of `$old` field entries, then populate the $meta with a row for this field definition, taking the content from the query if it's there, otherwise from $old or failing that, from the default defined for the type. Refuses to update mandatory fields that have an empty value.
+
+Return $bValid true if the value in $meta was updated (either from the query or from a default in the form. Return $bPresent true if a value was present in the query (even it was undef)
+
+## <a name="ObjectMethod <strong>render_ForDisplay*"></a> [[ObjectMethod]] \*renderForDisplay `($format,$attrs) -> $html`
+
+Render the field for display, under the control of $attrs.
+
+The following vars in $format are expanded: $title - title of the form field $value - expanded to the **protected** value of the form field
+
+The value is protected by TWiki::Render::protectFormFieldValue.
--- /dev/null
+# <a name="Package <code>TWiki::Form::_ListField"></a> Package =TWiki::Form::ListFieldDefinition
+
+Form field definitions that accept lists of values in the field definition. This is different to being multi-valued, which means the field type can **store** multiple values.
+
+<div>
+ <ul>
+ <li><a href="#Package =TWiki::Form::_ListField"> Package TWiki::Form::ListFieldDefinition</a><ul>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
+ </ul>
+ </li>
+ </ul>
+</div>
+
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
+
+Break circular references.
--- /dev/null
+# <a name="Package <code>="></a> Package =
+
+<div>
+ <ul>
+ <li><a href="#Package =="> Package ==</a><ul>
+ <li><a href="#get_DefaultValue() -> $value"> getDefaultValue() -> $value</a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
+ </ul>
+ </li>
+ </ul>
+</div>
+
+## <a name="get_DefaultValue() - $value"></a> getDefaultValue() -> $value
+
+The default for a select is always the empty string, as there is no way in TWiki form definitions to indicate selected values. This defers the decision on a value to the browser.
+
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
+
+Break circular references.
+# <a name="TWiki Forms"></a> TWiki Forms
+
+_Add structure to content with forms attached to twiki topics. TWiki forms (with form fields) and formatted search are the base for building database applications._
+
<div>
<ul>
<li><a href="#TWiki Forms"> TWiki Forms</a><ul>
</ul>
</div>
-# <a name="TWiki Forms"></a> TWiki Forms
-
-_Add structure to content with forms attached to twiki topics. TWiki forms (with form fields) and formatted search are the base for building database applications._
-
## <a name="Overview"></a> Overview
-By adding form-based input to freeform content, you can structure topics with unlimited, easily searchable categories. A form is enabled for a web and can be added to a topic. The form data is shown in tabular format when the topic is viewed, and can be changed in edit mode using edit fields, radio buttons, check boxes and list boxes. Many different form types can be defined in a web, though a topic can only have only form attached to it at a time.
+By adding form-based input to freeform content, you can structure topics with unlimited, easily searchable categories. A form is enabled for a web and can be added to a topic. The form data is shown in tabular format when the topic is viewed, and can be changed in edit mode using edit fields, radio buttons, check boxes and list boxes. Many different form types can be defined in a web, though a topic can only have one form attached to it at a time.
Typical steps to build an application based on TWiki forms:
> </tr>
> </table>
-Field values can also be obtained as the result of a [[FormattedSearch]]. For example,
+Field values can also be set using the result of expanding other TWiki variables. For example,
-> `%SEARCH{"Office$" scope="topic" web="%MAINWEB%" nonoise="on" type="regex" format="$web.$topic" separator=", " }%`
+> `%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.
+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.
<a name="EnablingForms"></a>
</form>
- **_%T% Tip:_** For TWiki applications you can [[automatically generate unique topicnames|Main/TWikiTemplates#AutomaticallyGeneratedTopicname]].
-- **_%X% Note:_** Initial values will not be submitted to the form of a new topic if you only use the formtemplate parameter.
+- **_%X% Note:_** Initial values will **not** be set in the form of a new topic if you _only_ use the formtemplate parameter.
## <a name="Changing a form"></a> Changing a form
- <code>**Type**</code> `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.
- <code>**Type**</code> `checkbox+buttons` will add **Set** and **Clear** buttons to the basic `checkbox` type.
- <code>**Type**</code> `radio` is like `checkbox` except that radio buttons are mutually exclusive; only one can be selected.
-- <code>**Type**</code> `label` specifies read-only label text, The `Value` field should contian the text of the label.
+- <code>**Type**</code> `label` specifies read-only label text. The `Value` field should contain the text of the label.
- <code>**Type**</code> `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.
- There are two modifiers that can be applied to the `select` type:
- `select+multi` turns multiselect on for the select, to allow Shift+Click and Ctrl+Click to select (or deselect) multiple items.
- The field value will be used to initialize a field when a form is created, unless specific values are given by the topic template or query parameters. The first item in the list for a select or radio type is the default item. For `label`, `text`, and `textarea` fields the value may also contain commas. `checkbox` fields cannot be initialized through the form template.
- Leading and trailing spaces are _not_ significant.
-- Field values can also be generated through a [[FormattedSearch]], which must yield a suitable table as the result.
-- Variables in the initial values of a form definition get expanded when form values are initialized from the form definition. The escape words `$quot` ("), `$percnt` (%), `$dollar` ($), `$n` (newline), and `$nop` can be used to prevent expansion.
+- Field values can also be generated through a %SYSTEMWEB%.FormattedSearch, which must yield a suitable table as the result.
+- Variables in the initial values of a form definition get expanded when the form definition is loaded.
+ - If you want to use a `|` character in the initial values field, you have to precede it with a backslash, thus: `\|`.
+ - You can use `<nop>` to prevent TWiki variables from being expanded.
+ - The [[FormatTokens]] can be used to prevent expansion of other characters.
**General Notes:**
> parameter it is easy to display the value of a classification field next to the topic link:
>
> | *Topic* | *Classification* |
-> %SEARCH{"%MAINWEB%.UserName" scope="text" nosearch="on" nototal="on" order="modified" reverse="on"
+> %SEARCH{"%USERSWEB%.UserName" scope="text" nosearch="on" nototal="on" order="modified" reverse="on"
> format="|<b>[[$web.$topic][$topic]]</b> |<nop>$formfield(TopicClassification) |" web="Sandbox"}%
Searching forms this way is obviously pretty inefficient, but it's easy to do. If you want better performance, take a look at some of the structured wiki extensions that support higher performance searching e.g. TWiki:Plugins.DBCachePlugin.
_Official list of stable TWiki functions for Plugin developers_
-This module defines official functions that [[Plugins|TWiki/TWikiPlugins]] can use to interact with the TWiki engine and content.
+This module defines official functions that [[Plugins|SYSTEMWEB/TWikiPlugins]] can use to interact with the TWiki engine and content.
Refer to [[EmptyPlugin]] and lib/TWiki/Plugins/EmptyPlugin.pm for a template Plugin and documentation on how to write a Plugin.
Deprecated functions will still work in older code, though they should _not_ be called in new Plugins and should be replaced in older Plugins as soon as possible.
-The version of the TWiki::Func module is defined by the VERSION number of the TWiki::Plugins module, currently 1.11. This can be shown by the `%PLUGINVERSION%` variable. The 'Since' field in the function documentation refers to the VERSION number and the date that the function was addded.
+The version of the TWiki::Func module is defined by the VERSION number of the TWiki::Plugins module, currently 1.11. This can be shown by the `%PLUGINVERSION%` TWiki variable, and accessed in code using `$TWiki::Plugins::VERSION`. The 'Since' field in the function documentation refers to `$TWiki::Plugins::VERSION`.
-**_Note:_** Beware! These methods should only ever be called from the context of a TWiki Plugin. They require a Plugins SESSION context to be established before they are called, and will not work if simply called from another TWiki module. For example,
+Notes on use of `$TWiki::Plugins::VERSION` (from 1.2 forwards):
- use TWiki;
- print TWiki::Func::getSkin(),"\n";
+- If the **major** version (e.g. `1.`) is the same then any plugin coded to use any **earlier** revision of the `1.` API will still work. No function has been removed from the interface, nor has any API published in that version changed in such a way as to **require** plugins to be recoded.
+- If the **minor** version (e.g. 1.1) is incremented there may be changes in the API that may help improve the coding of some plugins - for example, new interfaces giving access to previously hidden core functions. In addition, **deprecation** of functions in the interface trigger a minor version increment. Note that deprecated functions are not _removed_, they are merely frozen, and plugin authors are recommended to stop using them.
+- Any additional digits in the version number relate to minor changes, such as the addition of parameters to the existing functions, or addition of utility functions that are unlikely to require significant changes to existing plugins.
+- `TWiki::Plugins::VERSION` also applies to the plugin handlers. The handlers are documented in the EmptyPlugin, and that module indicates what version of `TWiki::Plugins::VERSION` it relates to.
-will fail with `Can't call method "getSkin" on an undefined value at TWiki/Func.pm line 83`.
-
-If you want to call the methods outside the context of a plugin, you can create a Plugins SESSION object. For example, the script:
-
- use TWiki:
- $TWiki::Plugins::SESSION = new TWiki();
- print TWiki::Func::getSkin(),"\n";
-
-will work happily.
+A full history of the changes to this API can be found at the end of this topic.
<div>
<ul>
<li><a href="#get_UrlHost( ) -> $host"> getUrlHost( ) -> $host</a></li>
<li><a href="#get_ScriptUrl( $web, $topic, $sc"> getScriptUrl( $web, $topic, $script, ... ) -> $url</a></li>
<li><a href="#get_ViewUrl( $web, $topic ) -> $"> getViewUrl( $web, $topic ) -> $url</a></li>
- <li><a href="#get_OopsUrl( $web, $topic, $temp"> getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -> $url</a></li>
<li><a href="#get_PubUrlPath( ) -> $path"> getPubUrlPath( ) -> $path</a></li>
+ <li><a href="#get_ExternalResource( $url ) ->"> getExternalResource( $url ) -> $response</a></li>
<li><a href="#get_CgiQuery( ) -> $query"> getCgiQuery( ) -> $query</a></li>
+ <li><a href="#get_SessionKeys() -> @keys"> getSessionKeys() -> @keys</a></li>
<li><a href="#get_SessionValue( $key ) -> $val"> getSessionValue( $key ) -> $value</a></li>
<li><a href="#set_SessionValue( $key, $value )"> setSessionValue( $key, $value ) -> $boolean</a></li>
<li><a href="#clear_SessionValue( $key ) -> $b"> clearSessionValue( $key ) -> $boolean</a></li>
<li><a href="#getContext() -> \%hash"> getContext() -> \%hash</a></li>
+ <li><a href="#push_TopicContext($web, $topic)"> pushTopicContext($web, $topic)</a></li>
+ <li><a href="#pop_TopicContext()"> popTopicContext()</a></li>
</ul>
</li>
<li><a href="#Preferences"> Preferences</a><ul>
<li><a href="#get_PluginPreferencesValue( $key"> getPluginPreferencesValue( $key ) -> $value</a></li>
<li><a href="#get_PreferencesFlag( $key, $web"> getPreferencesFlag( $key, $web ) -> $value</a></li>
<li><a href="#get_PluginPreferencesFlag( $key"> getPluginPreferencesFlag( $key ) -> $boolean</a></li>
+ <li><a href="#set_PreferencesValue($name, $val"> setPreferencesValue($name, $val)</a></li>
<li><a href="#get_WikiToolName( ) -> $name"> getWikiToolName( ) -> $name</a></li>
<li><a href="#get_MainWebname( ) -> $name"> getMainWebname( ) -> $name</a></li>
<li><a href="#get_TwikiWebname( ) -> $name"> getTwikiWebname( ) -> $name</a></li>
</li>
<li><a href="#User Handling and Access Control"> User Handling and Access Control</a><ul>
<li><a href="#get_DefaultUserName( ) -> $login"> getDefaultUserName( ) -> $loginName</a></li>
- <li><a href="#get_WikiName( ) -> $wikiName"> getWikiName( ) -> $wikiName</a></li>
- <li><a href="#get_WikiUserName( ) -> $wikiName"> getWikiUserName( ) -> $wikiName</a></li>
+ <li><a href="#get_CanonicalUserID( $user ) ->"> getCanonicalUserID( $user ) -> $cUID</a></li>
+ <li><a href="#get_WikiName( $user ) -> $wikiNa"> getWikiName( $user ) -> $wikiName</a></li>
+ <li><a href="#get_WikiUserName( $user ) -> $wi"> getWikiUserName( $user ) -> $wikiName</a></li>
<li><a href="#wiki_ToUserName( $wikiName ) ->"> wikiToUserName( $wikiName ) -> $loginName</a></li>
<li><a href="#user_ToWikiName( $loginName, $do"> userToWikiName( $loginName, $dontAddWeb ) -> $wikiName</a></li>
+ <li><a href="#email_ToWikiNames( $email, $dont"> emailToWikiNames( $email, $dontAddWeb ) -> @wikiNames</a></li>
+ <li><a href="#wiki_NameToEmails( $wikiname ) -"> wikiNameToEmails( $wikiname ) -> @emails</a></li>
<li><a href="#isGuest( ) -> $boolean"> isGuest( ) -> $boolean</a></li>
- <li><a href="#permissionsSet( $web ) -> $boole"> permissionsSet( $web ) -> $boolean</a></li>
+ <li><a href="#is_AnAdmin( $login ) -> $boolean"> isAnAdmin( $login ) -> $boolean</a></li>
+ <li><a href="#is_GroupMember( $group, $login )"> isGroupMember( $group, $login ) -> $boolean</a></li>
+ <li><a href="#eachUser() -> $iterator"> eachUser() -> $iterator</a></li>
+ <li><a href="#eachMembership($wikiname) -> $it"> eachMembership($wikiname) -> $iterator</a></li>
+ <li><a href="#eachGroup() -> $iterator"> eachGroup() -> $iterator</a></li>
+ <li><a href="#isGroup( $group ) -> $boolean"> isGroup( $group ) -> $boolean</a></li>
+ <li><a href="#each_GroupMember($group) -> $ite"> eachGroupMember($group) -> $iterator</a></li>
<li><a href="#check_AccessPermission( $type, $"> checkAccessPermission( $type, $wikiName, $text, $topic, $web, $meta ) -> $boolean</a></li>
</ul>
</li>
<li><a href="#webExists( $web ) -> $boolean"> webExists( $web ) -> $boolean</a></li>
<li><a href="#createWeb( $newWeb, $baseWeb, $o"> createWeb( $newWeb, $baseWeb, $opts )</a></li>
<li><a href="#moveWeb( $oldName, $newName )"> moveWeb( $oldName, $newName )</a></li>
+ <li><a href="#each_ChangeSince($web, $time) ->"> eachChangeSince($web, $time) -> $iterator</a></li>
<li><a href="#get_TopicList( $web ) -> @topics"> getTopicList( $web ) -> @topics</a></li>
<li><a href="#topicExists( $web, $topic ) -> $"> topicExists( $web, $topic ) -> $boolean</a></li>
<li><a href="#check_TopicEditLock( $web, $topi"> checkTopicEditLock( $web, $topic, $script ) -> ( $oopsUrl, $loginName, $unlockTime )</a></li>
<li><a href="#writeHeader( $query, $contentLen"> writeHeader( $query, $contentLength )</a></li>
<li><a href="#redirect_CgiQuery( $query, $url,"> redirectCgiQuery( $query, $url, $passthru )</a></li>
<li><a href="#add_ToHEAD( $id, $header )"> addToHEAD( $id, $header )</a></li>
- <li><a href="#expand_CommonVariables( $text, $"> expandCommonVariables( $text, $topic, $web ) -> $text</a></li>
+ <li><a href="#expand_CommonVariables( $text, $"> expandCommonVariables( $text, $topic, $web, $meta ) -> $text</a></li>
<li><a href="#renderText( $text, $web ) -> $te"> renderText( $text, $web ) -> $text</a></li>
<li><a href="#internalLink( $pre, $web, $topic"> internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) -> $text</a></li>
</ul>
<li><a href="#Special handlers"> Special handlers</a><ul>
<li><a href="#register_TagHandler( $var, \fn,"> registerTagHandler( $var, \&fn, $syntax )</a></li>
<li><a href="#registerRESTHandler( $alias, \fn"> registerRESTHandler( $alias, \&fn, )</a></li>
+ <li><a href="#decode_FormatTokens($str) -> $un"> decodeFormatTokens($str) -> $unencodedString</a></li>
</ul>
</li>
<li><a href="#Searching"> Searching</a><ul>
<li><a href="#General Utilities"> General Utilities</a><ul>
<li><a href="#get_RegularExpression( $name ) -"> getRegularExpression( $name ) -> $expr</a></li>
<li><a href="#normalize_WebTopicName($web, $to"> normalizeWebTopicName($web, $topic) -> ($web, $topic)</a></li>
+ </ul>
+ </li>
+ <li><a href="#StaticMethod *sanitize_Attachmen"> StaticMethod sanitizeAttachmentName <tt>($fname) -> ($fileName,$origName)</tt></a><ul>
+ <li><a href="#space_OutWikiWord( $word, $sep )"> spaceOutWikiWord( $word, $sep ) -> $text</a></li>
<li><a href="#writeWarning( $text )"> writeWarning( $text )</a></li>
<li><a href="#writeDebug( $text )"> writeDebug( $text )</a></li>
<li><a href="#formatTime( $time, $format, $tim"> formatTime( $time, $format, $timezone ) -> $text</a></li>
+ <li><a href="#isTrue( $value, $default ) -> $b"> isTrue( $value, $default ) -> $boolean</a></li>
<li><a href="#is_ValidWikiWord ( $text ) -> $b"> isValidWikiWord ( $text ) -> $boolean</a></li>
<li><a href="#extractParameters($attr ) -> %pa"> extractParameters($attr ) -> %params</a></li>
<li><a href="#extract_NameValuePair( $attr, $n"> extractNameValuePair( $attr, $name ) -> $value</a></li>
</li>
<li><a href="#Deprecated functions"> Deprecated functions</a><ul>
<li><a href="#get_ScriptUrlPath( ) -> $path"> getScriptUrlPath( ) -> $path</a></li>
+ <li><a href="#get_OopsUrl( $web, $topic, $temp"> getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -> $url</a></li>
+ <li><a href="#permissionsSet( $web ) -> $boole"> permissionsSet( $web ) -> $boolean</a></li>
<li><a href="#get_PublicWebList( ) -> @webs"> getPublicWebList( ) -> @webs</a></li>
<li><a href="#format_GmTime( $time, $format )"> formatGmTime( $time, $format ) -> $text</a></li>
<li><a href="#get_DataDir( ) -> $dir"> getDataDir( ) -> $dir</a></li>
- `$web` - Web name, e.g. `'Main'`
- `$topic` - Topic name, e.g. `'WebNotify'`
- `$script` - Script name, e.g. `'view'`
-- `...` - an arbitrary number of name,value parameter pairs that will be url-encoded and added to the url. The special parameter name '#' is reserved for specifying an anchor. e.g. `getScriptUrl('x','y','view','#'=>'XXX',a=>1,b=>2)` will give `.../view/x/y?a=1&b=2#XXX`
+- `...` - an arbitrary number of name=>value parameter pairs that will be url-encoded and added to the url. The special parameter name '#' is reserved for specifying an anchor. e.g. `getScriptUrl('x','y','view','#'=>'XXX',a=>1,b=>2)` will give `.../view/x/y?a=1&b=2#XXX`
Return: `$url` URL, e.g. `"http://example.com:80/cgi-bin/view.pl/Main/WebNotify"`
**Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
-### <a name="get_OopsUrl( $web, $topic, $temp"></a> getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -> $url
+### <a name="get_PubUrlPath( ) - $path"></a> getPubUrlPath( ) -> $path
-Compose fully qualified 'oops' dialog URL
+Get pub URL path
-- `$web` - Web name, e.g. `'Main'`. The current web is taken if empty
-- `$topic` - Topic name, e.g. `'WebNotify'`
-- `$template` - Oops template name, e.g. `'oopsmistake'`. The 'oops' is optional; 'mistake' will translate to 'oopsmistake'.
-- `$param1` ... `$param4` - Parameter values for %PARAM1% ... %PARAMn% variables in template, optional
+Return: `$path` URL path of pub directory, e.g. `"/pub"`
-Return: `$url` URL, e.g. `"http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked¶m1=joe"`
+**Since:** TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
-This might be used like this:
+### <a name="get_ExternalResource( $url ) - $"></a> getExternalResource( $url ) -> $response
- my $url = TWiki::Func::getOopsUrl($web, $topic, 'oopsmistake', 'I made a boo-boo');
- TWiki::Func::redirectCgiQuery( undef, $url );
- return 0;
+Get whatever is at the other end of a URL (using an HTTP GET request). Will only work for encrypted protocols such as `https` if the `LWP` CPAN module is installed.
-**Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
+Note that the `$url` may have an optional user and password, as specified by the relevant RFC. Any proxy set in `configure` is honoured.
-Since TWiki::Plugins::VERSION 1.1, the recommended approach is to throw an [[oops exception|Main/TWikiOopsExceptionDotPm]].
+The `$response` is an object that is known to implement the following subset of the methods of `LWP::Response`. It may in fact be an `LWP::Response` object, but it may also not be if `LWP` is not available, so callers may only assume the following subset of methods is available:
- use Error qw( :try );
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <td><code>code()</code></td>
+ </tr>
+ <tr>
+ <td><code>message()</code></td>
+ </tr>
+ <tr>
+ <td><code>header($field)</code></td>
+ </tr>
+ <tr>
+ <td><code>content()</code></td>
+ </tr>
+ <tr>
+ <td><code>is_error()</code></td>
+ </tr>
+ <tr>
+ <td><code>is_redirect()</code></td>
+ </tr>
+</table>
- throw TWiki::OopsException($web, $topic, undef, 0, [ 'I made a boo-boo' ]);
+Note that if LWP is **not** available, this function:
-and let TWiki handle the cleanup.
+1. can only really be trusted for HTTP/1.0 urls. If HTTP/1.1 or another protocol is required, you are **strongly** recommended to `require LWP`.
+2. Will not parse multipart content
-### <a name="get_PubUrlPath( ) - $path"></a> getPubUrlPath( ) -> $path
+In the event of the server returning an error, then `is_error()` will return true, `code()` will return a valid HTTP status code as specified in RFC 2616 and RFC 2518, and `message()` will return the message that was received from the server. In the event of a client-side error (e.g. an unparseable URL) then `is_error()` will return true and `message()` will return an explanatory message. `code()` will return 400 (BAD REQUEST).
-Get pub URL path
+Note: Callers can easily check the availability of other HTTP::Response methods as follows:
-Return: `$path` URL path of pub directory, e.g. `"/pub"`
+ my $response = TWiki::Func::getExternalResource($url);
+ if (!$response->is_error() && $response->isa('HTTP::Response')) {
+ ... other methods of HTTP::Response may be called
+ } else {
+ ... only the methods listed above may be called
+ }
-**Since:** TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
+**Since:** TWiki::Plugins::VERSION 1.2
### <a name="get_CgiQuery( ) - $query"></a> getCgiQuery( ) -> $query
**Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
+### <a name="get_SessionKeys() - @keys"></a> getSessionKeys() -> @keys
+
+Get a list of all the names of session variables. The list is unsorted.
+
+Session keys are stored and retrieved using `setSessionValue` and `getSessionValue`.
+
+**Since:** TWiki::Plugins::VERSION 1.2
+
### <a name="get_SessionValue( $key ) - $valu"></a> getSessionValue( $key ) -> $value
Get a session value from the client session module
Get a hash of context identifiers representing the currently active context.
-The context is a set of identifiers that are set during specific phases of TWiki processing. For example, each of the standard scripts in the 'bin' directory each has a context identifier - the view script has 'view', the edit script has 'edit' etc. So you can easily tell what 'type' of script your Plugin is being called within. The core context identifiers are listed in the [[TWikiTemplates]] topic. Please be careful not to overwrite any of these identifiers!
+The context is a set of identifiers that are set during specific phases of TWiki processing. For example, each of the standard scripts in the 'bin' directory each has a context identifier - the view script has 'view', the edit script has 'edit' etc. So you can easily tell what 'type' of script your Plugin is being called within. The core context identifiers are listed in the %SYSTEMWEB%.TWikiTemplates topic. Please be careful not to overwrite any of these identifiers!
Context identifiers can be used to communicate between Plugins, and between Plugins and templates. For example, in [[FirstPlugin]].pm, you might write:
**Since:** TWiki::Plugins::VERSION 1.1
+### <a name="push_TopicContext($web, $topic)"></a> pushTopicContext($web, $topic)
+
+- `$web` - new web
+- `$topic` - new topic
+
+Change the TWiki context so it behaves as if it was processing `$web.$topic` from now on. All the preferences will be reset to those of the new topic. Note that if the new topic is not readable by the logged in user due to access control considerations, there will **not** be an exception. It is the duty of the caller to check access permissions before changing the topic.
+
+It is the duty of the caller to restore the original context by calling `popTopicContext`.
+
+Note that this call does **not** re-initialise plugins, so if you have used global variables to remember the web and topic in `initPlugin`, then those values will be unchanged.
+
+**Since:** TWiki::Plugins::VERSION 1.2
+
+### <a name="pop_TopicContext()"></a> popTopicContext()
+
+Returns the TWiki context to the state it was in before the `pushTopicContext` was called.
+
+**Since:** TWiki::Plugins::VERSION 1.2
+
## <a name="Preferences"></a> Preferences
### <a name="get_PreferencesValue( $key, $web"></a> getPreferencesValue( $key, $web ) -> $value
**NOTE:** As of TWiki4.1, if `$NO_PREFS_IN_TOPIC` is enabled in the plugin, then preferences set in the plugin topic will be ignored.
+### <a name="set_PreferencesValue($name, $val"></a> setPreferencesValue($name, $val)
+
+Set the preferences value so that future calls to getPreferencesValue will return this value, and `%$name%` will expand to the preference when used in future variable expansions.
+
+The preference only persists for the rest of this request. Finalised preferences cannot be redefined using this function.
+
+Returns 1 if the preference was defined, and 0 otherwise.
+
### <a name="get_WikiToolName( ) - $name"></a> getWikiToolName( ) -> $name
Get toolname as defined in TWiki.cfg
**Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
-### <a name="get_WikiName( ) - $wikiName"></a> getWikiName( ) -> $wikiName
+### <a name="get_CanonicalUserID( $user ) - $"></a> getCanonicalUserID( $user ) -> $cUID
+
+Return the cUID of the specified user. A cUID is a unique identifier which is assigned by TWiki for each user. BEWARE: While the default [[TWikiUserMapping]] uses a cUID that looks like a user's [[LoginName]], some characters are modified to make them compatible with rcs. Additionally, other usermappings will use other conventions - the [[JoomlauserMapping]] for example, has cUIDs like 'JoomlaeUserMapping\_1234'.
+
+If $user is undefined Get the cUID of logged in user, and will generally be 'BaseUserMapping\_666'
+
+- $user can be a cUID, login, wikiname or web.wikiname
+
+Return: `$cUID` an internal unique and transportable escaped identifier for registered users (they can be autogenerated for an authenticated but unregistered user)
+
+**Since:** TWiki::Plugins::VERSION 1.2
-Get Wiki name of logged in user
+### <a name="get_WikiName( $user ) - $wikiNam"></a> getWikiName( $user ) -> $wikiName
+
+return the [[WikiName]] of the specified user if $user is undefined Get Wiki name of logged in user
+
+- $user can be a cUID, login, wikiname or web.wikiname
Return: `$wikiName` Wiki Name, e.g. `'JohnDoe'`
**Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
-### <a name="get_WikiUserName( ) - $wikiName"></a> getWikiUserName( ) -> $wikiName
+### <a name="get_WikiUserName( $user ) - $wik"></a> getWikiUserName( $user ) -> $wikiName
+
+return the userWeb.WikiName of the specified user if $user is undefined Get Wiki name of logged in user
-Get Wiki name of logged in user with web prefix
+- $user can be a cUID, login, wikiname or web.wikiname
Return: `$wikiName` Wiki Name, e.g. `"Main.JohnDoe"`
### <a name="wiki_ToUserName( $wikiName ) - $"></a> wikiToUserName( $wikiName ) -> $loginName
-Translate a Wiki name to a login name based on [[Main.TWikiUsers|Main/TWikiUsers]] topic
+Translate a Wiki name (or login name or cUID, if it can) to a login name.
- `$wikiName` - Wiki name, e.g. `'Main.JohnDoe'` or `'JohnDoe'`
-Return: `$loginName` Login name of user, e.g. `'jdoe'`
+Return: `$loginName` Login name of user, e.g. `'jdoe'`, or undef if not matched.
+
+Note that it is possible for several login names to map to the same wikiname. This function will only return the **first** login name that maps to the wikiname.
+
+returns undef if the [[WikiName]] is not found.
**Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
### <a name="user_ToWikiName( $loginName, $do"></a> userToWikiName( $loginName, $dontAddWeb ) -> $wikiName
-Translate a login name to a Wiki name based on [[Main.TWikiUsers|Main/TWikiUsers]] topic
+Translate a login name to a Wiki name
- `$loginName` - Login name, e.g. `'jdoe'`
- `$dontAddWeb` - Do not add web prefix if `"1"`
Return: `$wikiName` Wiki name of user, e.g. `'Main.JohnDoe'` or `'JohnDoe'`
+userToWikiName will always return a name, if the user does not exist in the mapping, the $loginName parameter is returned. (backward compatibility)
+
**Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
+### <a name="email_ToWikiNames( $email, $dont"></a> emailToWikiNames( $email, $dontAddWeb ) -> @wikiNames
+
+- `$email` - email address to look up
+- `$dontAddWeb` - Do not add web prefix if `"1"`
+
+Find the wikinames of all users who have the given email address as their registered address. Since several users could register with the same email address, this returns a list of wikinames rather than a single wikiname.
+
+**Since:** TWiki::Plugins::VERSION 1.2
+
+### <a name="wiki_NameToEmails( $wikiname ) -"></a> wikiNameToEmails( $wikiname ) -> @emails
+
+- `$wikiname` - wikiname of user to look up
+
+Returns the registered email addresses of the named user. If $wikiname is undef, returns the registered email addresses for the logged-in user.
+
+**Since:** TWiki::Plugins::VERSION 1.2
+
### <a name="isGuest( ) - $boolean"></a> isGuest( ) -> $boolean
Test if logged in user is a guest ([[TWikiGuest]])
**Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
-### <a name="permissionsSet( $web ) - $boolea"></a> permissionsSet( $web ) -> $boolean
+### <a name="is_AnAdmin( $login ) - $boolean"></a> isAnAdmin( $login ) -> $boolean
-Test if any access restrictions are set for this web, ignoring settings on individual pages
+Find out if the user is an admin or not. If the user is not given, the currently logged-in user is assumed.
-- `$web` - Web name, required, e.g. `'Sandbox'`
+- $login can be either a login, or a CUID
-**Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
+**Since:** TWiki::Plugins::VERSION 1.2
+
+### <a name="is_GroupMember( $group, $login )"></a> isGroupMember( $group, $login ) -> $boolean
+
+Find out if $login is in the named group. e.g.
+
+ if( TWiki::Func::isGroupMember( "HesperionXXGroup", "jordi" )) {
+ ...
+ }
+
+If `$user` is `undef`, it defaults to the currently logged-in user.
+
+- $login can be a login name, or a cUID, or [[WikiName]]
+
+**Since:** TWiki::Plugins::VERSION 1.2
+
+### <a name="eachUser() - $iterator"></a> eachUser() -> $iterator
+
+Get an iterator over the list of all the registered users **not** including groups. The iterator will return each wiki name in turn (e.g. 'FredBloggs').
+
+Use it as follows:
+
+ my $iterator = TWiki::Func::eachUser();
+ while ($it->hasNext()) {
+ my $user = $it->next();
+ # $user is a wikiname
+ }
+
+**WARNING** on large sites, this could be a long list!
+
+**Since:** TWiki::Plugins::VERSION 1.2
+
+### <a name="eachMembership($wikiname) - $ite"></a> eachMembership($wikiname) -> $iterator
+
+Get an iterator over the names of all groups that the user is a member of. If `$wikiname` is `undef`, defaults to the currently logged-in user.
+
+**Since:** TWiki::Plugins::VERSION 1.2
+
+### <a name="eachGroup() - $iterator"></a> eachGroup() -> $iterator
+
+Get an iterator over all groups.
+
+Use it as follows:
+
+ my $iterator = TWiki::Func::eachGroup();
+ while ($it->hasNext()) {
+ my $group = $it->next();
+ # $group is a group name e.g. TWikiAdminGroup
+ }
+
+**WARNING** on large sites, this could be a long list!
+
+**Since:** TWiki::Plugins::VERSION 1.2
+
+### <a name="isGroup( $group ) - $boolean"></a> isGroup( $group ) -> $boolean
+
+Checks if `$group` is the name of a group known to TWiki.
+
+### <a name="each_GroupMember($group) - $iter"></a> eachGroupMember($group) -> $iterator
+
+Get an iterator over all the members of the named group. Returns undef if $group is not a valid group.
+
+Use it as follows:
+
+ my $iterator = TWiki::Func::eachGroupMember('RadioheadGroup');
+ while ($it->hasNext()) {
+ my $user = $it->next();
+ # $user is a wiki name e.g. 'TomYorke', 'PhilSelway'
+ }
+
+**WARNING** on large sites, this could be a long list!
+
+**Since:** TWiki::Plugins::VERSION 1.2
### <a name="check_AccessPermission( $type, $"></a> checkAccessPermission( $type, $wikiName, $text, $topic, $web, $meta ) -> $boolean
-Check access permission for a topic based on the [[TWiki.TWikiAccessControl|TWiki/TWikiAccessControl]] rules
+Check access permission for a topic based on the [[%SYSTEMWEB%.TWikiAccessControl|SYSTEMWEB/TWikiAccessControl]] rules
- `$type` - Access type, required, e.g. `'VIEW'`, `'CHANGE'`.
- `$wikiName` - [[WikiName]] of remote user, required, e.g. `"PeterThoeny"`. If `$wikiName` is '', 0 or `undef` then access is **always permitted**.
**Since:** TWiki::Plugins::VERSION 1.1
+### <a name="each_ChangeSince($web, $time) -"></a><a name="each_ChangeSince($web, $time) - "></a> eachChangeSince($web, $time) -> $iterator
+
+Get an iterator over the list of all the changes in the given web between `$time` and now. $time is a time in seconds since 1st Jan 1970, and is not guaranteed to return any changes that occurred before (now - \{Store\}\{RememberChangesFor\}). \{Store\}\{RememberChangesFor\}) is a setting in `configure`. Changes are returned in **most-recent-first** order.
+
+Use it as follows:
+
+ my $iterator = TWiki::Func::eachChangeSince(
+ $web, time() - 7 * 24 * 60 * 60); # the last 7 days
+ while ($it->hasNext()) {
+ my $change = $it->next();
+ # $change is a perl hash that contains the following fields:
+ # topic => topic name
+ # user => wikiname - wikiname of user who made the change
+ # time => time of the change
+ # revision => revision number *after* the change
+ # more => more info about the change (e.g. 'minor')
+ }
+
### <a name="get_TopicList( $web ) - @topics"></a> getTopicList( $web ) -> @topics
Get list of all topics in a web
- `$web` - Web name, optional, e.g. `'Main'`.
- `$topic` - Topic name, required, e.g. `'TokyoOffice'`, or `"Main.TokyoOffice"`
-$web and $topic are parsed as described in the documentation for `normalizeWebTopicName`.
+$web and $topic are parsed as described in the documentation for `normalizeWebTopicName`. Specifically, the %USERSWEB% is used if $web is not specified and $topic has no web specifier. To get an expected behaviour it is recommened to specify the current web for $web; don't leave it empty.
**Since:** TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
- `$web` Web name, e.g. `"Main"`, or empty
- `$topic` Topic name, e.g. `"MyTopic"`, or `"Main.MyTopic"`
-- `$lock` 1 to lease the topic, 0 to clear the lease=
+- `$lock` 1 to lease the topic, 0 to clear an existing lease
Takes out a "lease" on the topic. The lease doesn't prevent anyone from editing and changing the topic, but it does redirect them to a warning screen, so this provides some protection. The `edit` script always takes out a lease.
</tr>
</table>
-NOTE: if you are trying to get revision info for a topic, use `$meta->getRevisionInfo` instead if you can - it is significantly more efficient, and returns a user object that contains other user information.
-
-NOTE: prior versions of TWiki may under some circumstances have returned the login name of the user rather than the wiki name; the code documentation was totally unclear, and we have been unable to establish the intent. However the wikiname is obviously more useful, so that is what is returned.
+NOTE: if you are trying to get revision info for a topic, use `$meta->getRevisionInfo` instead if you can - it is significantly more efficient.
**Since:** TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
Return: `$text` Topic text with embedded meta data; an oops URL for calling redirectCgiQuery() is returned in case of an error
-This method is more efficient than `readTopic`, but returns meta-data embedded in the text. Plugins authors must be very careful to avoid damaging meta-data. You are recommended to use readTopic instead, which is a lot safer..
+This method is more efficient than `readTopic`, but returns meta-data embedded in the text. Plugins authors must be very careful to avoid damaging meta-data. You are recommended to use readTopic instead, which is a lot safer.
**Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
### <a name="readTemplate( $name, $skin ) - $"></a> readTemplate( $name, $skin ) -> $text
-Read a template or skin. Embedded [[template directives|TWiki/TWikiTemplates]] get expanded
+Read a template or skin. Embedded [[template directives|SYSTEMWEB/TWikiTemplates]] get expanded
- `$name` - Template name, e.g. `'view'`
- `$skin` - Comma-separated list of skin names, optional, e.g. `'print'`
Prints a basic content-type HTML header for text/html to standard out
-- `$query` - CGI query object. If not given, the default CGI query will be used. In most cases you should _not_ pass this parameter.
-- `$contentLength` - Length of content
+- `$query` - CGI query object. If not given, the default CGI query will be used (optional, in most cases you should _not_ pass this parameter)
+- `$contentLength` - Length of content (optional, in most cases you should _not_ pass this parameter)
Return: none
Print output to STDOUT that will cause a 302 redirect to a new URL. Nothing more should be printed to STDOUT after this method has been called.
-The `$passthru` parameter allows you to pass the parameters that were passed to the current query on to the target URL, as long as it is another URL on the same TWiki installation. If `$passthru` is set to a true value, then TWiki will save the current URL parameters, and then try to restore them on the other side of the redirect. Parameters are stored on the server in a cache file (see `{PassthroughDir} in =configure`).
+The `$passthru` parameter allows you to pass the parameters that were passed to the current query on to the target URL, as long as it is another URL on the same TWiki installation. If `$passthru` is set to a true value, then TWiki will save the current URL parameters, and then try to restore them on the other side of the redirect. Parameters are stored on the server in a cache file.
Note that if `$passthru` is set, then any parameters in `$url` will be lost when the old parameters are restored. if you want to change any parameter values, you will need to do that in the current CGI query before redirecting e.g.
TWiki::Func::addToHEAD('PATTERN_STYLE','<link id="twikiLayoutCss" rel="stylesheet" type="text/css" href="%PUBURL%/TWiki/PatternSkin/layout.css" media="all" />')
-### <a name="expand_CommonVariables( $text, $"></a> expandCommonVariables( $text, $topic, $web ) -> $text
+### <a name="expand_CommonVariables( $text, $"></a> expandCommonVariables( $text, $topic, $web, $meta ) -> $text
Expand all common `%VARIABLES%`
- `$text` - Text with variables to expand, e.g. `'Current user is %WIKIUSER%'`
- `$topic` - Current topic name, e.g. `'WebNotify'`
- `$web` - Web name, optional, e.g. `'Main'`. The current web is taken if missing
+- `$meta` - topic meta-data to use while expanding (Since TWiki::Plugins::VERSION 1.2)
Return: `$text` Expanded text, e.g. `'Current user is TWikiGuest'`
### <a name="renderText( $text, $web ) - $tex"></a> renderText( $text, $web ) -> $text
-Render text from TWiki markup into XHTML as defined in [[TWiki.TextFormattingRules|TWiki/TextFormattingRules]]
+Render text from TWiki markup into XHTML as defined in [[%SYSTEMWEB%.TextFormattingRules|SYSTEMWEB/TextFormattingRules]]
- `$text` - Text to render, e.g. `'*bold* text and =fixed font='`
- `$web` - Web name, optional, e.g. `'Main'`. The current web is taken if missing
(ie, with the name of the function instead of the alias) will not work.
+### <a name="decode_FormatTokens($str) - $une"></a> decodeFormatTokens($str) -> $unencodedString
+
+TWiki has an informal standard set of tokens used in `format` parameters that are used to block evaluation of paramater strings. For example, if you were to write
+
+`%MYTAG{format="%WURBLE%"}%`
+
+then %WURBLE would be expanded **before** %MYTAG is evaluated. To avoid this TWiki uses escapes in the format string. For example:
+
+`%MYTAG{format="$percntWURBLE$percnt"}%`
+
+This lets you enter arbitrary strings into parameters without worrying that TWiki will expand them before your plugin gets a chance to deal with them properly. Once you have processed your tag, you will want to expand these tokens to their proper value. That's what this function does.
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th bgcolor="#99CCCC"><strong> Escape: </strong></th>
+ <th bgcolor="#99CCCC"><strong> Expands To: </strong></th>
+ </tr>
+ <tr>
+ <td><code>$n</code> or <code>$n()</code></td>
+ <td> New line. Use <code>$n()</code> if followed by alphanumeric character, e.g. write <code>Foo$n()Bar</code> instead of <code>Foo$nBar</code></td>
+ </tr>
+ <tr>
+ <td><code>$nop</code> or <code>$nop()</code></td>
+ <td> Is a "no operation". </td>
+ </tr>
+ <tr>
+ <td><code>$quot</code></td>
+ <td> Double quote (<code>"</code>) </td>
+ </tr>
+ <tr>
+ <td><code>$percnt</code></td>
+ <td> Percent sign (<code>%</code>) </td>
+ </tr>
+ <tr>
+ <td><code>$dollar</code></td>
+ <td> Dollar sign (<code>$</code>) </td>
+ </tr>
+</table>
+
+Note thath $quot, $percnt and $dollar all work \*even if they are followed by alphanumeric characters\*. You have been warned!
+
+**Since:** TWiki::Plugins::VERSION 1.2
+
## <a name="Searching"></a> Searching
### <a name="search_InWebContent($searchStrin"></a> searchInWebContent($searchString, $web, \\@topics, \\%options ) -> \\%map
Note that hierarchical web names ([[SubWeb]]) are only available if hierarchical webs are enabled in `configure`.
-The symbols %USERSWEB%, %SYSTEMWEB%, %DOCWEB%, %MAINWEB% and %TWIKIWEB% can be used in the input to represent the web names set in $cfg\{UsersWebName\} and $cfg\{SystemWebName\}. For example:
+The symbols %USERSWEB%, %SYSTEMWEB% and %DOCWEB% can be used in the input to represent the web names set in $cfg\{UsersWebName\} and $cfg\{SystemWebName\}. For example:
<table border="1" cellpadding="0" cellspacing="0">
<tr>
</tr>
</table>
+## <a name="StaticMethod <strong>sanitize_Attachmen"></a> [[StaticMethod]] \*sanitizeAttachmentName `($fname) -> ($fileName,$origName)`
+
+Given a file namer, sanitise it according to the rules for transforming attachment names. Returns the sanitised name together with the basename before sanitisation.
+
+Sanitation includes filtering illegal characters and mapping client file names to legal server names.
+
+**Since:** TWiki::Plugins::VERSION 1.2
+
+### <a name="space_OutWikiWord( $word, $sep )"></a> spaceOutWikiWord( $word, $sep ) -> $text
+
+Spaces out a wiki word by inserting a string (default: one space) between each word component. With parameter $sep any string may be used as separator between the word components; if $sep is undefined it defaults to a space.
+
+**Since:** TWiki::Plugins::VERSION 1.2
+
### <a name="writeWarning( $text )"></a> writeWarning( $text )
Log Warning that may require admin intervention to data/warning.txt
**Since:** TWiki::Plugins::VERSION 1.020 (26 Feb 2004)
+### <a name="isTrue( $value, $default ) - $bo"></a> isTrue( $value, $default ) -> $boolean
+
+Returns 1 if `$value` is true, and 0 otherwise. "true" means set to something with a Perl true value, with the special cases that "off", "false" and "no" (case insensitive) are forced to false. Leading and trailing spaces in `$value` are ignored.
+
+If the value is undef, then `$default` is returned. If `$default` is not specified it is taken as 0.
+
+**Since:** $TWiki::Plugins::VERSION 1.2
+
### <a name="is_ValidWikiWord ( $text ) - $bo"></a> isValidWikiWord ( $text ) -> $boolean
Check for a valid [[WikiWord]] or [[WikiName]]
**Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
+### <a name="get_OopsUrl( $web, $topic, $temp"></a> getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -> $url
+
+Compose fully qualified 'oops' dialog URL
+
+- `$web` - Web name, e.g. `'Main'`. The current web is taken if empty
+- `$topic` - Topic name, e.g. `'WebNotify'`
+- `$template` - Oops template name, e.g. `'oopsmistake'`. The 'oops' is optional; 'mistake' will translate to 'oopsmistake'.
+- `$param1` ... `$param4` - Parameter values for %PARAM1% ... %PARAMn% variables in template, optional
+
+Return: `$url` URL, e.g. `"http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked¶m1=joe"`
+
+**DEPRECATED** since 1.1, the recommended approach is to throw an [[oops exception|Main/TWikiOopsExceptionDotPm]].
+
+ use Error qw( :try );
+
+ throw TWiki::OopsException(
+ 'toestuckerror',
+ web => $web,
+ topic => $topic,
+ params => [ 'I got my toe stuck' ]);
+
+(this example will use the `oopstoestuckerror` template.)
+
+If this is not possible (e.g. in a REST handler that does not trap the exception) then you can use `getScriptUrl` instead:
+
+ my $url = TWiki::Func::getScriptUrl($web, $topic, 'oops',
+ template => 'oopstoestuckerror',
+ param1 => 'I got my toe stuck');
+ TWiki::Func::redirectCgiQuery( undef, $url );
+ return 0;
+
+**Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
+
+### <a name="permissionsSet( $web ) - $boolea"></a> permissionsSet( $web ) -> $boolean
+
+Test if any access restrictions are set for this web, ignoring settings on individual pages
+
+- `$web` - Web name, required, e.g. `'Sandbox'`
+
+**Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
+
+**DEPRECATED** since 1.2 - use `getPreferencesValue` instead to determine what permissions are set on the web, for example:
+
+ foreach my $type qw( ALLOW DENY ) {
+ foreach my $action qw( CHANGE VIEW ) {
+ my $pref = $type . 'WEB' . $action;
+ my $val = getPreferencesValue( $pref, $web ) || '';
+ if( $val =~ /\S/ ) {
+ print "$pref is set to $val on $web\n";
+ }
+ }
+ }
+
### <a name="get_PublicWebList( ) - @webs"></a> getPublicWebList( ) -> @webs
**DEPRECATED** since 1.1 - use `getListOfWebs` instead.
</tr>
<tr>
<td> Preferences: </td>
- <td> The site-wide, single <em>web</em> and single user-level preferences settings. The settings are stored in [[Main/TWikiPreferences]], [[Main/WebPreferences]] and [[Main/TWikiUsers]] home pages. [[Main/TWikiVariables#PreferencesVariables]]</td>
+ <td> The site-wide, single <em>web</em> and single user-level preferences settings. The settings are stored in [[Main/TWikiPreferences]], [[Main/WebPreferences]] and %USERSWEB%.TWikiUsers home pages. [[Main/TWikiVariables#PreferencesVariables]]</td>
</tr>
<tr>
<td> Site: </td>
+# <a name="Appendix A: TWiki Development Ti"></a> Appendix A: TWiki Development Time-line
+
<div>
<ul>
- <li><a href="#Appendix A: TWiki Development Ti"> Appendix A: TWiki Development Timeline</a><ul>
+ <li><a href="#Appendix A: TWiki Development Ti"> Appendix A: TWiki Development Time-line</a><ul>
+ <li><a href="#TWiki Release 4.2 (Freetown), 22"> TWiki Release 4.2 (Freetown), 22 Jan 2008</a></li>
<li><a href="#TWiki Release 4.1 (Edinburgh), 1"> TWiki Release 4.1 (Edinburgh), 16 Jan 2007</a></li>
<li><a href="#TWiki Release 4.0.0 (Dakar), 01"> TWiki Release 4.0.0 (Dakar), 01 Feb 2006</a></li>
<li><a href="#01-Sep-2004 Release (Cairo)"> 01-Sep-2004 Release (Cairo)</a></li>
</ul>
</div>
-# <a name="Appendix A: TWiki Development Ti"></a> Appendix A: TWiki Development Timeline
+<a name="FreetownRelease"></a>
+
+## <a name="TWiki Release 4.2 (Freetown), 22"></a> TWiki Release 4.2 (Freetown), 22 Jan 2008
+
+**_New Features and Enhancements of TWiki Release 4.2_**
+
+- **Easier Installation and Upgrade**
+ - New Internal Admin Login feature
+ - The Main.TWikiUsers topic is no longer distributed as a default topic in Main web
+ - A new directory `working` which per default is located in the TWiki root which contains registration\_approvals, tmp, and work\_areas
+ - Configure can now authenticate when connecting to local plugins repository.
+
+- **Usability Enhancements**
+ - New WYSIWYG editor based on TinyMCE replaces the Kupu based editor
+ - New "Restore topic" feature has been added to the _More Topic Actions_ menu to easily restore an older version of a topic
+
+- **Application Platform Enhancements**
+ - Enhancements to IF: allows, ingroup, istopic, and isweb
+
+- **Search Enhancements**
+ - New `query` search mode supports SQL-style queries over form fields and other meta-data
+
+- **Skins and Templates Enhancements**
+ - The PatternSkin which is the default skin for TWiki has got a face lift
+ - The default templates have been heavily refactored to make it easier to create skins reusing the default skin.
+
+- **Miscellaneous Feature Enhancements**
+ - Many new functions in the API for plugin developers
+ - Table of Content (TOC) feature enhanced
+ - re-architected Pluggable user mapping (between login name and WikiName) to integrate with alternative authentication and Management schemes
+ - Topic based User management has been extracted into a separately update-able package (TWikiUsersContrib)
+
+- **Enhancements of Pre-installed Plugins**
+ - [[CommentPlugin]]: New `templatetopic` parameter to point to custom comment template topic
+ - [[EditTablePlugin]]: Move and delete rows
+ - [[MailerContrib]]: Allow Exclusion Of Webs
+ - [[SpreadSheetPlugin]]: 6 new math formulas; formula to format time diff
+
+- **Bug Fixes**
+ - More than 300 bugs fixes since 4.1.2
+
+<a name="FreetownHallOfFame"></a> **_Hall of Fame of TWiki Release 4.2_**
+
+Many people have been involved in creating TWiki 4.2. Special thanks go to the most active contributors in the following areas:
+
+- Release management led by TWiki:Main.KennethLavrsen, ably assisted by TWiki:Main.SvenDowideit
+- Design and development driven by TWiki:Main.CrawfordCurrie, TWiki:Main.ArthurClemens, and TWiki:Main.SvenDowideit
+- Testing driven by TWiki:Main.KennethLavrsen
+
+Many thanks also to the contributors in the following areas:
+
+- **Sponsor and facilitator:** TWiki:Main.PeterThoeny
+- **Testing and bug fixing:** TWiki:Main.KennethLavrsen, TWiki:Main.CrawfordCurrie, TWiki:Main.ArthurClemens, TWiki:Main.SvenDowideit, TWiki:Main.SteffenPoulsen, TWiki:Main.MichaelDaum, TWiki:Main.PeterThoeny, TWiki:Main.RichardDonkin
+- **Spec and code:** TWiki:Main.CrawfordCurrie (2323), TWiki:Main.ArthurClemens (566), TWiki:Main.SvenDowideit (507), TWiki:Main.PeterThoeny (83), TWiki:Main.KennethLavrsen (73), TWiki:Main.SteffenPoulsen (72), TWiki:Main.AntonioTerceiro (63) - ( 3857 changes by 20 authors )
+- **Templates and skins:** TWiki:Main.ArthurClemens (587), TWiki:Main.CrawfordCurrie (130), TWiki:Main.AndreUlrich (73), TWiki:Main.SvenDowideit (44) - ( 869 changes by 12 authors )
+- **Documentation:** TWiki:Main.ArthurClemens (460), TWiki:Main.CrawfordCurrie (377), TWiki:Main.PeterThoeny (233), TWiki:Main.AndreUlrich (157), TWiki:Main.SvenDowideit (118), TWiki:Main.KennethLavrsen (68) - ( 1450 changes by 14 authors )
+- **Release package builds:** TWiki:Main.SvenDowideit
+- **Usability:** TWiki:Main.CarloSchulz, TWiki:Main.ArthurClemens
+- **Translations:** Coordinated by TWiki:Main.AntonioTerceiro
+ - Bulgarian: TWiki:Main.KrassimirBerov
+ - Danish: TWiki:Main.SteffenPoulsen
+ - Dutch: TWiki:Main.ArthurClemens
+ - Finnish: TWiki:Main.HeikkiToivonen
+ - French: TWiki:Main.BenVoui
+ - German: TWiki:Main.OliverKrueger, TWiki:Main.AndreUlrich
+ - Italian: TWiki:Main.MassimoMancini
+ - Portuguese: TWiki:Main.CarlinhosCecconi
+ - Simplified Chinese: TWiki:Main.CheDong
+ - Swedish: TWiki:Main.ErikAman
+ - Traditional Chinese: TWiki:Main.CheDong
+ - Ukrainian: TWiki:Main.SerhijDubyk
+- **Marketing:** TWiki:Main.RodBeckstrom, TWiki:Main.PeterThoeny, TWiki:Main.MichaelCorbett, TWiki:Main.KoenMartens
+- **Public relations:** TWiki:Main.PeterThoeny, TWiki:Main.MichaelCorbett
+- **Meetups:** TWiki:Main.AmirShobeiri
+- **TWiki.org wiki champions:** TWiki:Main.PeterThoeny, TWiki:Main.ArthurClemens, TWiki:Main.CrawfordCurrie, TWiki:Main.KennethLavrsen, TWiki:Main.SvenDowideit, TWiki:Main.MichaelDaum, TWiki:Main.CarloSchulz, TWiki:Main.StephaneLenclud, TWiki:Main.RichardDonkin, TWiki:Main.KoenMartens
+- **Customer support:** TWiki:Main.PeterThoeny, TWiki:Main.ArthurClemens, TWiki:Main.CrawfordCurrie, TWiki:Main.SvenDowideit, TWiki:Main.HaraldJoerg
+- **System administration:** TWiki:Main.SvenDowideit, TWiki:Main.PeterThoeny, TWiki:Main.CrawfordCurrie
+
+If you find an omission please fix it at TWiki:TWiki.TWikiHistory. For the full list of contributors see [[TWikiContributor]].
+
+**_Note:_** Order of contributors under "Spec and code", "Templates and skins" and "Documentation" is based on number of SVN file changes for core and default extensions from March 2007 (svn rev:13046) to Jan 2008 (svn rev:16210). (Details at TWikibug:TWiki420SvnLog). Order of contributors under "Testing and bug fixing" is based on Bugs web statistics from 2007-03 to 2007-12. Order of contributors under "TWiki.org wiki champions" and "Customer support" is based on TWiki.org web statistics from 2007-02 to 2007-12.
+
+See more details on the TWiki 4.2 release at [[TWikiReleaseNotes04x02]].
<a name="EdinburghRelease"></a>
<ul>
<li><a href="#Package =TWiki::_I18N="> Package TWiki::I18N</a><ul>
<li><a href="#ClassMethod *available_languages"> ClassMethod available_languages <tt></tt></a></li>
- <li><a href="#ClassMethod <strong>get</strong> ($session)"> ClassMethod get <tt>($session)</tt></a></li>
+ <li><a href="#ClassMethod <strong>new</strong> ($session)"> ClassMethod new <tt>($session)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
<li><a href="#ObjectMethod <strong>maketext</strong> ($text)"> ObjectMethod maketext <tt>($text) -> $translation</tt></a></li>
<li><a href="#ObjectMethod <strong>language</strong> () -> $l"> ObjectMethod language <tt>() -> $language_tag</tt></a></li>
<li><a href="#ObjectMethod *enabled_languages*"> ObjectMethod enabled_languages <tt>() -> %languages</tt></a></li>
**_Note_**: the languages available to users are determined in the `configure` interface.
-## <a name="ClassMethod <strong>get</strong> ($session)"></a> [[ClassMethod]] **get** `($session)`
+## <a name="ClassMethod <strong>new</strong> ($session)"></a> [[ClassMethod]] **new** `($session)`
-Constructor. Gets the language object corresponding to the current user's language.
+Constructor. Gets the language object corresponding to the current users language. If $session is not a TWiki object reference, just calls Local::Maketext::new (the superclass constructor)
+
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
+
+Break circular references.
## <a name="ObjectMethod <strong>maketext</strong> ($text)"></a><a name="ObjectMethod <strong>maketext</strong> ($text) "></a> [[ObjectMethod]] **maketext** `($text) -> $translation`
--- /dev/null
+# <a name="Package <code>TWiki::If::Node="></a> Package =TWiki::If::Node
+
+Node class for the result of an If statement parse
+
+<div>
+ <ul>
+ <li><a href="#Package =TWiki::If::Node="> Package TWiki::If::Node</a></li>
+ </ul>
+</div>
--- /dev/null
+# <a name="Package <code>TWiki::If::Parser="></a> Package =TWiki::If::Parser
+
+Support for the conditions in %IF\{\} statements.
+
+<div>
+ <ul>
+ <li><a href="#Package =TWiki::If::Parser="> Package TWiki::If::Parser</a></li>
+ </ul>
+</div>
--- /dev/null
+# <a name="Package <code>TWiki::Infix::Error="></a> Package =TWiki::Infix::Error
+
+Class of errors used with TWiki::Infix::Parser
+
+<div>
+ <ul>
+ <li><a href="#Package =TWiki::Infix::Error="> Package TWiki::Infix::Error</a></li>
+ </ul>
+</div>
--- /dev/null
+# <a name="Package <code>TWiki::Infix::Node="></a> Package =TWiki::Infix::Node
+
+Base class for node types generated by Infix::Parser. You don't **have** to use it, but it may be useful.
+
+<div>
+ <ul>
+ <li><a href="#Package =TWiki::Infix::Node="> Package TWiki::Infix::Node</a><ul>
+ <li><a href="#ClassMethod <strong>newNode</strong> ($o,@p) ->"> ClassMethod newNode <tt>($o,@p) -> \$if</tt></a></li>
+ <li><a href="#ClassMethod <strong>newLeaf</strong> ($val,$typ"> ClassMethod newLeaf <tt>($val,$type) -> \$if</tt></a></li>
+ <li><a href="#ObjectMethod <strong>evaluate</strong> (...) ->"> ObjectMethod evaluate <tt>(...) -> $result</tt></a></li>
+ </ul>
+ </li>
+ </ul>
+</div>
+
+## <a name="ClassMethod <strong>newNode</strong> ($o,@p) -"></a><a name="ClassMethod <strong>newNode</strong> ($o,@p) - "></a> [[ClassMethod]] **newNode** `($o,@p) -> \$if`
+
+Construct a new parse node (contract with Infix::Parser)
+
+## <a name="ClassMethod <strong>newLeaf</strong> ($val,$typ"></a> [[ClassMethod]] **newLeaf** `($val,$type) -> \$if`
+
+Construct a new terminal node (contract with Infix::Parser)
+
+## <a name="ObjectMethod <strong>evaluate</strong> (...) -"></a><a name="ObjectMethod <strong>evaluate</strong> (...) - "></a> [[ObjectMethod]] **evaluate** `(...) -> $result`
+
+Execute the parse node. The parameter array is passed on, by reference, to the evaluation functions.
--- /dev/null
+# <a name="Package <code>TWiki::Infix::Parser="></a> Package =TWiki::Infix::Parser
+
+A simple stack-based parser that parses infix expressions with nonary, unary and binary operators specified using an operator table.
+
+Escapes are supported in strings, using backslash.
+
+<div>
+ <ul>
+ <li><a href="#Package =TWiki::Infix::Parser="> Package TWiki::Infix::Parser</a><ul>
+ <li><a href="#new($client_class, \%options) ->"> new($client_class, \%options) -> parser object</a></li>
+ <li><a href="#ObjectMethod <strong>addOperator</strong> (%ope"> ObjectMethod addOperator <tt>(%oper)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>parse</strong> ($string) -"> ObjectMethod parse <tt>($string) -> $parseTree</tt></a></li>
+ </ul>
+ </li>
+ </ul>
+</div>
+
+## <a name="new($client_class, \%options) -"></a><a name="new($client_class, \%options) - "></a> new($client\_class, \\%options) -> parser object
+
+Creates a new infix parser. Operators must be added for it to be useful.
+
+The tokeniser matches tokens in the following order: operators, quotes (" and '), numbers, words, brackets. If you have any overlaps (e.g. an operator '<' and a bracket operator '<<') then the first choice will match.
+
+`$client_class` needs to be the _name_ of a _package_ that supports the following two functions:
+
+- `newLeaf($val, $type)` - create a terminal. $type will be:
+ 1. if the terminal matched the `words` specification (see below).
+ 2. if it is a number matched the `numbers` specification (see below)
+ 3. if it is a quoted string
+- =newNode($op, @params) - create a new operator node. @params is a variable-length list of parameters, left to right. $op is a reference to the operator hash in the \\@opers list.
+
+These functions should throw Error::Simple in the event of errors. TWiki::Infix::Node is such a class, ripe for subclassing.
+
+The remaining parameters are named, and specify options that affect the behaviour of the parser:
+
+1. `words=>qr//` - should be an RE specifying legal words (unquoted terminals that are not operators i.e. names and numbers). By default this is `\w+`. It's ok if operator names match this RE; operators always have precedence over atoms.
+2. `numbers=>qr//` - should be an RE specifying legal numbers (unquoted terminals that are not operators or words). By default this is `qr/[+-]?(?:\d+\.\d+|\d+\.|\.\d+|\d+)(?:[eE][+-]?\d+)?/`, which matches integers and floating-point numbers. Number matching always takes precedence over word matching (i.e. "1xy" will be parsed as a number followed by a word. A typical usage of this option is when you only want to recognise integers, in which case you would set this to `numbers => qr/\d+/`.
+
+## <a name="ObjectMethod <strong>addOperator</strong> (%ope"></a> [[ObjectMethod]] **addOperator** `(%oper)`
+
+Add an operator to the parser.
+
+`%oper` is a hash, containing the following fields:
+
+- `name` - operator string
+- `prec` - operator precedence, positive non-zero integer. Larger number => higher precedence.
+- `arity` - set to 1 if this operator is unary, 2 for binary. Arity 0 is legal, should you ever need it.
+- `close` - used with bracket operators. `name` should be the open bracket string, and `close` the close bracket. The existance of `close` marks this as a bracket operator.
+- `casematters=` - indicates that the parser should check case in the operator name (i.e. treat 'AND' and 'and' as different). By default operators are case insensitive. **Note** that operator names must be caselessly unique i.e. you can't define 'AND' and 'and' as different operators in the same parser. Does not affect the interpretation of non-operator terminals (names).
+
+Other fields in the hash can be used for other purposes; the parse tree generated by this parser will point to the hashes passed to this function.
+
+Field names in the hash starting with `InfixParser_` are reserved for use by the parser.
+
+## <a name="ObjectMethod <strong>parse</strong> ($string) -"></a> [[ObjectMethod]] **parse** `($string) -> $parseTree`
+
+Parses `$string`, calling `newLeaf` and `newNode` in the client class as necessary to create a parse tree. Returns the result of calling `newNode` on the root of the parse.
+
+Throws TWiki::Infix::Error in the event of parse errors.
-# <a name="TWiki Installation Guide"></a><a name=" TWiki Installation Guide"></a> TWiki Installation Guide
+# <a name="TWiki Installation Guide"></a> TWiki Installation Guide
-**The following is installation instructions for the TWiki 4.1 production release on an Apache web server on Linux.** Visit TWiki:TWiki.InstallingTWiki for the latest updates to this guide and supplemental information for installing or upgrading TWiki, including notes on installing TWiki on different platforms, environments and web hosting sites.
+**The following is installation instructions for the TWiki 4.2 production release on an Apache web server on Linux.** Visit TWiki:TWiki.InstallingTWiki for the latest updates to this guide and supplemental information for installing or upgrading TWiki, including notes on installing TWiki on different platforms, environments and web hosting sites.
-If you are upgrading from a previous version of TWiki, you probably want to read [[TWikiUpgradeGuide]] instead (both this document and the TWikiUpgradeGuide are also available in the root of the distribution as HTML files)
+If you are upgrading from a previous version of TWiki, you probably want to read `TWikiUpgradeGuide` instead.
+
+Both this document and the TWikiUpgradeGuide are also available in the root of the distribution as HTML files. For this reason links to pages inside your own TWiki are written like `TWiki.WebHome` and not like live web links.
<div>
<ul>
- <li><a href="#Preparing to install TWiki"> Preparing to install TWiki</a></li>
- <li><a href="#Basic Installation"> Basic Installation</a></li>
- <li><a href="#Important Server Security Settin"> Important Server Security Settings</a></li>
- <li><a href="#Next Steps"> Next Steps</a></li>
- <li><a href="#Enable Authentication of Users"> Enable Authentication of Users</a></li>
- <li><a href="#Set TWiki Preferences"> Set TWiki Preferences</a></li>
- <li><a href="#Enable Email Notification"> Enable Email Notification</a></li>
- <li><a href="#Enable _WebStatistics"> Enable WebStatistics</a></li>
- <li><a href="#Automate removal of expired sess"> Automate removal of expired sessions and lease files</a></li>
- <li><a href="#Enable Localisation"> Enable Localisation</a></li>
- <li><a href="#Tailor New Users Home Topic"> Tailor New Users Home Topic</a></li>
- <li><a href="#Install Plugins"> Install Plugins</a></li>
- <li><a href="#Customize your TWiki!"> Customize your TWiki!</a></li>
- <li><a href="#Troubleshooting"> Troubleshooting</a></li>
- <li><a href="#Appendixes"> Appendixes</a></li>
- <li><a href="#TWiki System Requirements"> TWiki System Requirements</a><ul>
- <li><a href="#Server Requirements"> Server Requirements</a></li>
- <li><a href="#Required CPAN Modules"> Required CPAN Modules</a></li>
- <li><a href="#Optional CPAN Modules"> Optional CPAN Modules</a></li>
- <li><a href="#Client Requirements"> Client Requirements</a></li>
- <li><a href="#Important note about TWiki Plugi"> Important note about TWiki Plugins</a></li>
+ <li><a href="#TWiki Installation Guide"> TWiki Installation Guide</a><ul>
+ <li><a href="#Preparing to install TWiki"> Preparing to install TWiki</a></li>
+ <li><a href="#Basic Installation"> Basic Installation</a></li>
+ <li><a href="#Important Server Security Settin"> Important Server Security Settings</a></li>
+ <li><a href="#Next Steps"> Next Steps</a></li>
+ <li><a href="#Enable Authentication of Users"> Enable Authentication of Users</a></li>
+ <li><a href="#Define the Administrator User(s)"> Define the Administrator User(s)</a></li>
+ <li><a href="#Set TWiki Preferences"> Set TWiki Preferences</a></li>
+ <li><a href="#Enable Email Notification"> Enable Email Notification</a></li>
+ <li><a href="#Enable _WebStatistics"> Enable WebStatistics</a></li>
+ <li><a href="#Automate removal of expired sess"> Automate removal of expired sessions and lease files</a></li>
+ <li><a href="#Enable Localisation"> Enable Localisation</a></li>
+ <li><a href="#Tailor New Users Home Topic"> Tailor New Users Home Topic</a></li>
+ <li><a href="#Install Plugins"> Install Plugins</a></li>
+ <li><a href="#Customize Your TWiki!"> Customize Your TWiki!</a></li>
+ <li><a href="#Customization of Special Pages"> Customization of Special Pages</a></li>
+ <li><a href="#WYSIWYG vs Raw Edit"> WYSIWYG vs Raw Edit</a></li>
+ <li><a href="#Copyright, License and Classific"> Copyright, License and Classification Statements</a></li>
+ <li><a href="#Troubleshooting"> Troubleshooting</a></li>
+ <li><a href="#Appendices"> Appendices</a></li>
+ <li><a href="#TWiki System Requirements"> TWiki System Requirements</a><ul>
+ <li><a href="#Server Requirements"> Server Requirements</a></li>
+ <li><a href="#Required CPAN Modules"> Required CPAN Modules</a></li>
+ <li><a href="#Optional CPAN Modules"> Optional CPAN Modules</a></li>
+ <li><a href="#Client Requirements"> Client Requirements</a></li>
+ <li><a href="#Important note about TWiki Plugi"> Important note about TWiki Plugins</a></li>
+ </ul>
+ </li>
+ <li><a href="#Notes on Installing TWiki on Non"> Notes on Installing TWiki on Non-Root Account</a></li>
+ <li><a href="#Installing Manually Without Conf"> Installing Manually Without Configure</a></li>
</ul>
</li>
- <li><a href="#Notes on Installing TWiki on Non"> Notes on Installing TWiki on Non-Root Account</a></li>
- <li><a href="#Installing Manually Without Conf"> Installing Manually Without Configure</a></li>
</ul>
</div>
## <a name="Preparing to install TWiki"></a> Preparing to install TWiki
-Before attempting to install TWiki, you are encouraged to review the TWiki:TWiki.AdminSkillsAssumptions. This guide assumes the person installing TWiki has, at a minimum, basic knowledge of server administration and cgi script management on the system on which TWiki is to be installed. While it is possible to install TWiki with FTP access alone (for example, on a hosted site), it is tricky and may require additional support from your hosting service (for example, in setting file ownership).
+Before attempting to install TWiki, you are encouraged to review the TWiki:TWiki.AdminSkillsAssumptions. This guide assumes the person installing TWiki has, at a minimum, basic knowledge of server administration on the system on which TWiki is to be installed. While it is possible to install TWiki with FTP access alone (for example, on a hosted site), it is tricky and may require additional support from your hosting service (for example, in setting file ownership and installing missing perl CPAN libraries).
-To help setup a correct Apache configuration, you can use the automatic TWiki:TWiki.ApacheConfigGenerator which generates the contents for an Apache config file for TWiki based on your inputs.
+To help setup a correct Apache configuration, you are very much encouraged to use the automatic tool TWiki:TWiki.ApacheConfigGenerator which generates the contents for an Apache config file for TWiki based on your inputs.
While this installation guide specifically describes installation on an Apache web server on Linux, TWiki should be fine with any web server and OS that meet the system requirements (see below). For additional notes on installing TWiki on other systems, see TWiki:TWiki.InstallingTWiki#OtherPlatforms.
-If you are installing TWiki without Unix/Linux root (administrator) privileges (for example, on a hosted domain), see "Notes on Installing TWiki on Non-Root Account" below for supplemental instructions to the basic steps presented below.
+If you are installing TWiki without Unix/Linux root (administrator) priviledges (for example, on a hosted domain), see "Notes on Installing TWiki on Non-Root Account" below for supplemental instructions to the basic steps presented below.
+
+If you are upgrading from an earlier major version of TWiki such as Cairo (TWiki 3) you will need the information found in TWiki:TWiki.TWikiUpgradeGuide. There is also a static HTML `TWikiUpgradeGuide.html` included in the root of your TWiki distribution.
-If you are upgrading from an earlier major version of TWiki such a Cairo (TWiki 3) you will need the information found in TWiki:TWiki.TWikiUpgradeGuide which includes a description of both an automated and a manual procedure. The manual procedure is probably the safest to follow but takes more time. The upgrade guide describes essential steps needed to avoid problems with locked topics.
+Upgrading from a recent TWiki4 release is much simpler. Upgraders from earlier TWiki4 versions can follow the steps described in TWiki:TWiki.UpgradingTWiki04x00PatchReleases to ensure a safe upgrade without accidently overwriting customizations.
-Upgrading from a recent TWiki4 release is much simpler. Upgraders from earlier TWiki4 versions can with advantage follow the steps described in TWiki:TWiki.UpgradingTWiki04x00PatchReleases to ensure a safe upgrade without accidently overwriting customizations.
+One of the more difficult tasks is installation of addition CPAN libraries. See TWiki:TWiki.HowToInstallCpanModules for detailed information on how to install CPAN libraries.
If you need help, ask a question in the TWiki:Support web or on TWiki:Codev.TWikiIRC (irc.freenode.net, channel #twiki)
1. **Download** the TWiki distribution from <http://TWiki.org/download.html>.
2. **Make a directory** for the installation and **unpack the distribution** in it. In the rest of this document we assume this directory is called `twiki`.
-3. **Make sure** the user that runs CGI scripts on your system can read and write all files in the distribution. <br /> Detailed instructions on file permissions are beyond the scope of this guide, and the best and safest set of file and directory permissions depend on the actual server environment. For Unix/Linux see TWiki:TWiki.SettingFileAccessRightsLinuxUnix which contains scripts to setup the right file and directory access rights.<br /> The general rules for access rights are:
- - During installation and configuration, the CGI user needs to be able to read and write _everything_ in the distribution.
- - Once installation and configuration is complete, the CGI user needs write access to everything under the `data` and `pub` directories and to `twiki/lib/LocalSite.cfg`. _Everything else_ should be read-only.
- - Everybody else should be denied access to everything, always.
-4. **Make sure** Perl 5 and the Perl CGI library are installed on your system.<br /> The default location of Perl is `/usr/bin/perl`. **If it's somewhere else**, change the path to Perl in the first line of each script in the `twiki/bin` directory.<br /> %H% Some systems require a special extension on perl scripts (e.g. `.cgi` or `.pl`). If necessary, rename all files in `twiki/bin` (i.e. rename `view` to `view.pl` etc). If you do this, make sure you set the `ScriptSuffix` option in `configure` (Step 6).
-5. **Create the file** `twiki/bin/LocalLib.cfg`.<br /> There is a template for this file in `twiki/bin/LocalLib.cfg.txt`.<br /> The file `twiki/bin/LocalLib.cfg.txt` must contain a setting for `$twikiLibPath`, which must point to the absolute file path of your `twiki/lib` e.g. `/home/httpd/twiki/lib`.<br /> %H% If you need to install additional [CPAN](http://cpan.perl.org/) modules, but can't update the main Perl installation files on the server, you can set `$CPANBASE` to point to your personal [CPAN](http://cpan.perl.org/) install. Don't forget that the webserver user has to be able to read those files as well.
-6. **Configure the webserver** so you can execute the `bin/configure` script from your browser. But limit the access to either localhost, an IP address or a specific user using basic Apache authentication. You should never leave the `configure` script open to the public. See TWiki:TWiki.ApacheConfigGenerator which contains a tool that can generate a safe and working config file for TWiki on Apache.
- - If you are unsure about how to do this on your system, see TWiki:TWiki.InstallingTWiki#OtherPlatforms for links to information about various server setups. There is an example Apache `httpd.conf` file in `twiki_httpd_conf.txt` at the root of the package. This file also contains advice on securing your installation. There's also a script called `tools/rewriteshebang.pl` to help you in fixing up the shebang lines in your CGI scripts.
-7. **Run the `configure` script** from your browser (i.e. enter `http://yourdomain/twiki/bin/configure` into your browser address bar) and resolve any errors or warnings it tells you about.<br /> %X% When you run `configure` for the first time, you can only edit the section `General Path Settings`. Save these settings, and then return to `configure` to continue configuration.<br /> When you return to configure you now need to setup _Mail and Proxies_. Especially the `{WebMasterEmail}`, and `{SMTP}{MAILHOST}` must be defined to enable TWiki to 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}`.
+ - **Note!** that TWiki does not allow spaces in the directory names. Especially on Windows make sure to use a directory path without spaces.
+3. **Setup access file and directory rights** to enable the webserver user (the user Apache runs the CGI scripts as) to read and write inside the twiki directory.
+ - **Warning!** Do not just just run a `chmod -R 770 twiki`. The access rules have different meaning for files and directories. This is the most common mistake installers make.
+ - The distribution tgz has the file and directory access rights setup to work with a reasonable security level that will work for all types of installations including shared hosting.
+ - The ownership of the twiki directory tree is normally set to the user that unpacked the tgz and will have to be changed to the webserver user using the command `chown -R user:group /path/to/twiki`. The webserver username varies from Distributions. Examples for some major distributions:
+ - RedHat, Fedora, CentOS, Gentoo, Mandriva : `chown -R apache:apache /path/to/twiki`
+ - debian/Ubuntu/Kubunto : `chown -R www-data:www-data /path/to/twiki`
+ - Suse : `chown -R wwwrun:www /path/to/twiki`
+ - If you mistakenly change the access rights in a way that makes TWiki stop working, simply run the script found at TWiki:TWiki.SettingFileAccessRightsLinuxUnix to set the access right of the entire TWiki tree back to the distributed defaults.
+ - It is possible to define tighter access rules than the ones given by default after the installation is complete. But how tight they should be depends on your distribution and local needs. Typically you may want to limit all access from world if the webserver machine has login access for other users than root and the web server administrator. For a dedicated web server made just for running TWiki with limited login access the default access rights have a good safety level.
+4. **Check the Perl installation**. Ensure that Perl 5 and the Perl CGI library are installed on your system.
+ - The default location of Perl is `/usr/bin/perl`. **If it's somewhere else**, change the path to Perl in the first line of each script in the `twiki/bin` directory.
+ - Some systems require a special extension on perl scripts (e.g. `.cgi` or `.pl`). This is normally only needed under Windows and only where perl scripts are only recognized by file extension. Linux and Unix users should normally never need to do this. If necessary, rename all files in `twiki/bin` (i.e. rename `view` to `view.pl` etc). If you do this, make sure you set the `ScriptSuffix` option in `configure` (Step 6).
+5. **Create the file LocalLib.cfg** located as `twiki/bin/LocalLib.cfg`
+ - There is a template for this file in `twiki/bin/LocalLib.cfg.txt`. Simply copy [[LocalLib]].cfg.txt to [[LocalLib]].cfg. Make sure the ownership and access rights of the copy are the same as [[LocalLib]].cfg.txt
+ - The file `twiki/bin/LocalLib.cfg` must contain a setting for `$twikiLibPath`, which must point to the absolute file path of your `twiki/lib` e.g. `/var/www/twiki/lib`.<br />
+ - If you need to install additional [CPAN](http://cpan.perl.org/) modules, but can't update the main Perl installation files on the server, you can set `$CPANBASE` to point to your personal [CPAN](http://cpan.perl.org/) install. Don't forget that the webserver user has to be able to read those files as well.
+6. **Choose best configuration method** for your webserver. There are two ways to configure Apache: config file included from httpd.conf or .htaccess files
+ - Apache config file: The recommended method is using a config file. With a config file you can put the entire TWiki configuration in ONE file (typically named `twiki.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 using a config file requires that you can restart Apache which again means that you need root or sudo access to stop and start Apache. The TWiki 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 twiki.conf file from inside the desired virtual host config in your Apache configuration.
+ - .htaccess file: This should only be used when you cannot use a config file. Performance is slowed down because Apache has to look through _all_ directories in search for possible .htaccess files each time someone views a page in TWiki. Normally this is the only way to control Apache in a shared host environment where you have no root or sudo priviledges.
+7. **Configure the webserver**
+ - Unless you are an Apache expert setting up the webserver can be quite difficult. But TWiki has three resources that make setting up Apache easier.
+ - The best and easiest way is to use webpage TWiki:TWiki.ApacheConfigGenerator which contains a tool that can generate a safe and working config file for TWiki on Apache.
+ - In the root of the twiki installation you find an example config file `twiki_httpd_conf.txt`
+ - In the root of the twiki installation and in the `twiki/bin` directory you find example `.htaccess` files you can copy and modify. The files contains help text explaining how to set them up. In `twiki/bin` you find `.htaccess.txt` which can be copied to `.htaccess` and defined access to the CGI scripts. In the root of TWiki you find `pub-htaccess.txt` which you can copy to `pub/.htaccess`, `subdir-htaccess.txt` which you can copy to all directories as `.htaccess` except bin and pub, and you find `root-htaccess.txt` which you can copy to `.htaccess` in the twiki root directory. But again only use .htaccess files if you do not have root priviledges.
+ - If you are unsure about how to do this on your system, see TWiki:TWiki.InstallingTWiki#OtherPlatforms for links to information about various server setups.
+ - **Note!** When you use config files you need to restart Apache each time you change a setting to make the new setting active.
+8. **Protect the configure script**
+ - You should never leave the `configure` script open to the public. Limit access to the `twiki/bin/configure` script to either localhost, an IP address or a specific user using basic Apache authentication. The TWiki:TWiki.ApacheConfigGenerator lets you setup who has access to the configure script. Also the example twiki-httpd-conf.txt and bin/.htaccess.txt files includes the needed setting to protect the configure script.
+ - If you limit the access to a particular user then you need to setup a .htpasswd file that contains the user name and password that Apache will authenticate against. Per default both TWiki:TWiki.ApacheConfigGenerator and the example config files and .htaccess files uses `twiki/data/.htpasswd` but this file does not exist until you have TWiki running and have registered the first user. You therefore have two options. Either limit the access to localhost or an IP address, or make a .htpasswd file. To make a .htpasswd file change directory to `twiki/data` and issue the command `htpasswd -c .htpasswd username` and enter your password when asked. The username must match the `Require user username` directive in the Apache config file or .htaccess file. Do not use a username you will later use to register in TWiki because TWiki will then claim that you are already registered.
+9. **Run the `configure` script** from your browser (enter `http://yourdomain/twiki/bin/configure` into your browser address bar)
+ - Resolve any errors or warnings it tells you about.
+ - **Note!** When you run `configure` for the first time, you can only edit the section `General Path Settings`. Save these settings, and then return to `configure` to continue configuration.
+ - If your webserver can be accessed by more than one domain name make sure to add the additional alternative URLs to `{PermittedRedirectHostUrls}`
+ - When you return to configure you now need to setup _Mail and Proxies_. Especially the `{WebMasterEmail}`, and `{SMTP}{MAILHOST}` must be defined to enable TWiki to 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 mailing or want to enable it later you can uncheck `{EnableEmail}`.
You now have a basic, unauthenticated installation running. At this point you can just point your Web browser at `http://yourdomain.com/twiki/bin/view` and start TWiki-ing away!
Before you continue any further there are some basic and very important security settings you have to make sure are set correctly.
-- You should protect the configure script from general access. The configure script the tool is designed for use by administrators only and should be restricted to invocation by them only, by using the basic Apache authentication. Because of this there has not been put much effort into hardening the script. The configure script cannot save any settings once the password has been saved the first time, but the script could still be vulnerable to specially crafted field values and the script reveals many details about the webserver that you should not display in public.
-- You absolutely must turn off any kind of PHP, Perl, Python, Server Side Includes etc in the `pub` directory. TWiki has some builtin protection which renames files with dangerous filenames by appending .txt to the filename. But this is a secondary security measure. The essential action that you must take is to turn off any possible execution of any of the attached files.<br /> Most Linux distributions have a default Apache installation which has PHP and server side include (SSI) enabled. The `twiki_httpd_conf.txt` file provided in the root of the twiki directory is an example of an Apache config file which you would normally include from httpd.conf. In many distributions this happens automatically if the file is copied to a specific directory (Example RedHat/Fedora/Centos: /etc/httpd/conf.d) and has suffix `.conf`. This example file shows how to protect the `pub` directory from executing both PHP scripts and server side includes.<br /> If you do not have access to the apache config files you can normally control control access by placing a file called `.htaccess` in the directory you want to protect. The `pub-htaccess.txt` file provided in the root of the twiki directory is an example of an Apache `.htaccess` file which protects against execusion of PHP and SSI scripts.
-- Make sure that you deny access to all other twiki directories than the `bin` and `pub` directories. When you have access to the Apache config files the `twiki_httpd_conf.txt` file mentioned above also contains protection of these directories.<br /> For those that do not have access to the Apache config files a sample `subdir-htaccess.txt` file can be copied as `.htaccess` to the data, lib, locale, templates and tools directories.
+- As already described above you should protect the configure script from general access. The configure script is designed for use by administrators only and should be restricted to invocation by them only, by using the basic Apache authentication. Because of this there has not been put much effort into hardening the script. The configure script cannot save any settings once the password has been saved the first time, but the script could still be vulnerable to specially crafted field values and the script reveals many details about the webserver that you should not display in public.
+- You absolutely must turn off any kind of PHP, Perl, Python, Server Side Includes etc in the `pub` directory. TWiki has some built-in protection which renames files with dangerous filenames by appending .txt to the filename. But this is a secondary security measure. The essential action that you must take is to turn off any possible execution of any of the attached files.<br /> Most Linux distributions have a default Apache installation which has PHP and server side include (SSI) enabled.
+- Make sure that you deny access to all other twiki directories than the `bin` and `pub` directories. When you have access to the Apache config files the `twiki_httpd_conf.txt` file mentioned above also contains protection of these directories.<br /> For those that do not have access to the Apache config files a sample `subdir-htaccess.txt` file can be copied as `.htaccess` to the data, lib, locale, templates, tools and working directories.
-The TWIki:TWiki.ApacheConfigGenerator will help you address all 3 security elements.
+The TWiki:TWiki.ApacheConfigGenerator as well as the example `twiki_httpd_conf.txt` and example `htaccess.txt` files include the needed settings that protect against all 3 security elements.
## <a name="Next Steps"></a> Next Steps
-Once you have TWiki installed and running, you might consider the following optional steps for setting up and customizing your TWiki site. Many of the references below refer to topics within your TWiki installation. For example, `TWiki.TWikiSkins` refers to the `TWikiSkins` topic in your TWiki web. If not available locally, you can find these topics in the on-line reference copy of [[TWiki Release 4.1|TWiki:TWiki04x01/WebHome]].
+Once you have TWiki installed and running, you might consider the following optional steps for setting up and customizing your TWiki site. Many of the references below refer to topics within your TWiki installation. For example, `TWiki.TWikiSkins` refers to the `TWikiSkins` topic in your TWiki web. Easy way to jump directly to view the pages is to open your own TWiki in your browser and write `TWiki.TWikiSkins` in the Jump test box to the right in the top bar and hit Enter. You can find these topics in the on-line reference copy at the official TWiki website: [[TWiki Release 4.2|TWiki:TWiki04x02/WebHome]]
<a name="AuthenticationOfUsers"></a>
3. Save your `configure` settings.
4. Register yourself using the `TWiki.TWikiRegistration` topic.<br /> %H% Check that the password manager recognizes the new user. Check that a new line with the username and encrypted password is added to the `data/.htpasswd` file. If not, you probably got a path wrong, or the permissions may not allow the webserver user to write to that file.
2. Edit a topic (by clicking on the `Edit` link at beginning or end of topic) to check if authentication works.
-3. Edit the `Main/TWikiAdminGroup` topic to include users with system administrator status. Additional instructions are provided in that topic.<br /> %X% This is a very important step, as users in this group can access all topics, independent of TWiki access controls.
-4. Clear admin notes: Some pages are meant to be customized after choice of authentication - check and update these topics (remove notice): `Main.TWikiAdminGroup`, `TWiki.ChangePassword`, `TWiki.ResetPassword`, and `TWiki.ChangeEmailAddress`.
You are strongly encouraged to read `TWiki.TWikiUserAuthentication`, TWiki:TWiki.TWikiUserAuthenticationSupplement, and TWiki:TWiki.SecuringTWikiSite for further information about managing users and security of your TWiki site.
+**Note!** The other `LoginManager` option `TWiki::Client::ApacheLogin` uses a basic Apache type authentication where the browser itself prompts you for username and password. Most will find the TemplateLogin looking nicer. But ApacheLogin is required when you use Apache authentication methods like mod\_ldap where all authentication is handled by an Apache module and not by the TWiki perl code. When you use ApacheLogin the apache configuration must be set up to require authentication of the some but not all the scripts in the bin directory. This section in the Apache config (or .htaccess) controls this
+
+ <FilesMatch "(attach|edit|manage|rename|save|upload|mail|logon|rest|.*auth).*">
+ require valid-user
+ </FilesMatch>
+
+The TWiki:TWiki.ApacheConfigGenerator includes this section when you choose _ApacheLogin_. In the example `twiki_httpd_conf.txt` and `bin/.htaccess.txt` files this section is commented out with #. Uncomment the section when you use _ApacheLogin_. It is important that this section is commented out or removed when you use _TemplateLogin_.
+
+<a name="DefineAdminUser"></a>
+
+## <a name="Define the Administrator User(s)"></a> Define the Administrator User(s)
+
+Administrators have read and write access to any topic in TWiki, irrespectively of TWiki access controls. When you install TWiki one of the first things you will want to do is define yourself as an administrator. You become an administrator simply by adding yourself to the `TWikiAdminGroup`. It is the [[WikiName]] and not the login name you add to the group. Editing the `Main.TWikiAdminGroup` topic requires that you are an administrator. So to add the first administrator you need to login using the internal TWiki admin user login and the password you defined in configure.
+
+- Navigate to the `Main.TWikiAdminGroup` topic
+- Follow carefully the steps `Main.TWikiAdminGroup` of how to become an admin
+- Note that if you use _ApacheLogin_ you have to be registered and logged in before you use the _internal admin login_
+
<a name="SetPreferences"></a>
## <a name="Set TWiki Preferences"></a> Set TWiki Preferences
Preferences for customizing many aspects of TWiki are set simply by editing a special topic with TWiki.
-- Edit `TWiki.TWikiPreferences`. Read through it and set any additional settings you think you might need. (You can click the 'Edit' button near the top to edit the settings in place).
-- %T% Alternately, you can copy any settings or variables that you want to customize from `TWiki.TWikiPreferences` and paste them into `Main.TWikiPreferences`. This will protect your local customizations from being overwritten in later upgrades. See notes at top of `TWiki.TWikiPreferences` for more information.
+- `TWiki.TWikiPreferences`. Read through it and identify any additional settings or changes you think you might need. You can edit the settings in `TWiki.TWikiPreferences` but these will be overwritten when you later upgrade to a newer TWiki version. Instead copy any settings or variables that you want to customize from `TWiki.TWikiPreferences` and paste them into `Main.TWikiPreferences`. When you later upgrade TWiki simply avoid overwriting the `data/Main/TWikiPreferences.txt` file and all your settings will be kept. Settings in `Main.TWikiPreferences` overrides settings in both `TWiki.TWikiPreferences` and any settings defined in Plugin topics. See notes at top of `TWiki.TWikiPreferences` for more information.
## <a name="Enable Email Notification"></a> Enable Email Notification
Each TWiki web has an automatic email notification service that sends you an email with links to all of the topics modified since the last alert. To enable this service:
1. Confirm the Mail and Proxies settings in the Configure interface.
-2. Setup a cron job (or equivalent) to call the `bin/mailnotify` script as described in the `TWiki.MailerContrib` topic.
+2. Setup a cron job (or equivalent) to call the `tools/mailnotify` script as described in the `TWiki.MailerContrib` topic.
## <a name="Enable _WebStatistics"></a> Enable WebStatistics
## <a name="Automate removal of expired sess"></a> Automate removal of expired sessions and lease files
-Per default TWiki cleans out expired session and lease files each time any topic is viewed. This however cost performance. It is an advantage to define a negative value in `configure` for \{Sessions\}\{ExpireAfter\} and install let cron run the `tools/tick_twiki.pl` script. Read The topic [[TWikiScripts#tick_twiki_pl]] for details how to do this.
+Per default TWiki cleans out expired session and lease files each time any topic is viewed. This however cost performance. It is an advantage to define a negative value in `configure` for \{Sessions\}\{ExpireAfter\} and install let cron run the `tools/tick_twiki.pl` script. Read The topic `TWikiScripts#tick_twiki_pl` for details how to do this.
## <a name="Enable Localisation"></a> Enable Localisation
-TWiki now supports displaying of national (non-ascii) characters and presentation of basic interface elements in different languages. To enable these features, see the `Localisation` section of `configure`. For more information about these features, see [TWiki:TWiki.InternationalizationSupplement](http://twiki.org/cgi-bin/view/TWiki.InternationalizationSupplement 'TWiki.InternationalizationSupplement' on TWiki.org).
+TWiki now supports displaying of national (non-ascii) characters and presentation of basic interface elements in different languages. To enable these features, see the `Localisation` section of `configure`. For more information about these features, see TWiki:TWiki.InternationalizationSupplement.
+
+<a name="TailorUsersTopic"></a>
## <a name="Tailor New Users Home Topic"></a> Tailor New Users Home Topic
-When a new users registers on your TWiki a home topic is created for him based on the `TWiki/NewUserTemplate` template topic. This can be tailored. It contains additional resources you can use to:
+When a new users registers on your TWiki, a home topic is created for them based on the `TWiki.NewUserTemplate` topic (and its `TWiki.UserForm`). It contains additional resources you can use to:
- Localise the user topic.
-- Add a default ALLOWTOPICCHANGE so only the user can edit his own home topic. We do not encourage this for Intranet sites as it sends a wrong signal to new users, but it can be necessary on a public TWiki to avoid that the user topics get spammed.
+- Add a default ALLOWTOPICCHANGE so only the user can edit their own home topic. We do not encourage this for Intranet sites as it sends a wrong signal to new users, but it can be necessary on a public TWiki to prevent spam.
+- Add and remove fields defined in the `TWiki.UserForm`
+
+If you choose to tailor anything you are strongly adviced to copy `NewUserTemplate` and `UserForm` to the Main web and tailor the Main web copies. TWiki will look for the `NewUserTemplate` in the Main web first and if it does not exist it uses the default from the TWiki web. By creating a `Main.NewUserTemplate` and its `Main.UserForm` you will not loose your tailorings next time you upgrade TWiki.
+
+If you added or removed fields from the user form you may also need to tailor `TWiki.TWikiRegistration`.
## <a name="Install Plugins"></a> Install Plugins
Some plugins require that you define their settings in `configure`. You fill find these under the _Extensions_ section of configure.
-## <a name="Customize your TWiki!"></a> Customize your TWiki!
+## <a name="Customize Your TWiki!"></a> Customize Your TWiki!
+
+The real power of TWiki lies in it's flexibility to be customized to meet your needs. You can with small means change the looks of the default skin (called PatternSkin) by reading the `TWiki.PatternSkinCustomization`
+
+At the official TWiki website you can find more resources. A good place to start for exploring what's possible is [TWiki:TWiki.TWikiAdminCookBook](http://twiki.org/cgi-bin/view/TWiki/TWikiAdminCookBook 'TWiki/TWikiAdminCookBook' on TWiki.org) which offers tips and tricks for customizing your TWiki site. Many of these are appropriate to implement immediately after installing TWiki and before adding content so now's a good time to look at these.
+
+## <a name="Customization of Special Pages"></a> Customization of Special Pages
-The real power of TWiki lies in it's flexibility to be customized to meet your needs. A good place to start for exploring what's possible is [TWiki:TWiki.TWikiAdminCookBook](http://twiki.org/cgi-bin/view/TWiki/TWikiAdminCookBook 'TWiki/TWikiAdminCookBook' on TWiki.org) which offers tips and tricks for customizing your TWiki site. Many of these are appropriate to implement immediately after installing TWiki and before adding content so now's a good time to look at these. If you would like to customize the look of your TWiki, see [TWiki:TWiki.TWikiSkinsSupplement](http://twiki.org/cgi-bin/view/TWiki.TWikiSkinsSupplement 'TWiki.TWikiSkinsSupplement' on TWiki.org).
+Some pages are meant to be customized after choice of authentication. If you do not use the internal TWiki password manager the topics that contains the features for changing and resetting passwords and changing the email address should be changed to a note describing how to perform these tasks in your organization. The topics are:
+
+- `TWiki.ChangePassword`
+- `TWiki.ResetPassword`
+- `TWiki.ChangeEmailAddress`
+
+## <a name="WYSIWYG vs Raw Edit"></a> WYSIWYG vs Raw Edit
+
+From TWiki release 4.2.0 the WYSIWYG editor has been replaced by a much better and more powerful editor and it was decided that WYSIWYG would be the default edit mode. An Edit Raw link is available for those that have a need or preference for this mode.
+
+However you may prefer to have the same user interface as in TWiki 4.1 where _Edit_ was the raw text editor and you had a WYSIWYG button. You can modify the templates that define the buttons by following the description on TWiki:Codev.TWikiRawEditDefault04x02.
+
+## <a name="Copyright, License and Classific"></a> Copyright, License and Classification Statements
+
+In the bottom of each topic you will find a default copyright messages saying "Copyright &© by the contributing authors. All material on this collaboration platform is the property of the contributing authors." It is a setting WEBCOPYRIGHT that defines this. This is often not adequate.
+
+- If your TWiki is used in a commercial application without public access you should replace this by your normal copyright notice. You should also consider adding classifications (e.g. For Internal Use Only) so people do not have to add this manually to every new topic.
+- If your TWiki is public with public access you need to decide which copyright and license the contributions should be covered by. For open source type applications licenses such as [the GNU Free Documentation License](http://www.gnu.org/licenses/fdl.html), [FreeBSD Documentation License](http://www.freebsd.org/copyright/freebsd-doc-license.html), and [Creative Commons license](http://creativecommons.org/licenses/) are possible licenses to consider. Remember that once people have started contributing it is difficult and not correct to change or impose licenses on existing contributions.
+
+You change the copy right statement globally by taking these steps.
+
+- Copy the setting WEBCOPYRIGHT from `TWiki.TWikiPreferences` to `Main.TWikiPreferences` and alter the copied text to your need.
+- You can create a unique message for each web by adding the WEBCOPYRIGHT setting to `WebPreferences` in each web. E.g. adding a confidencial classification to a very restricted web.
+- The WEBCOPYRIGHT in `TWiki.WebPreferences` covers the documentation that comes with TWiki and is covered by the original TWiki Copyright and GPL License. You will normally leave this unchanged.
## <a name="Troubleshooting"></a> Troubleshooting
- For Windows, check the [TWiki:Codev.WindowsInstallCookbook](http://twiki.org/cgi-bin/view/Codev/WindowsInstallCookbook 'Codev/WindowsInstallCookbook' on TWiki.org).
- For MacOS X, check TWiki:Codev.TWikiOnMacOSX.
-It is also advisable to review TWiki:Codev.KnownIssuesOfTWiki04x01.
+It is also advisable to review TWiki:Codev.KnownIssuesOfTWiki04x02.
If you need help, ask a question in the TWiki:Support web or on TWiki:Codev/TWikiIRC (irc.freenode.net, channel #twiki)
-## <a name="Appendixes"></a> Appendixes
+## <a name="Appendices"></a> Appendices
<a name="SystemRequirements"></a>
### <a name="Required CPAN Modules"></a> Required CPAN Modules
+Most of the CPAN libraries listesd below are part of a standard Perl installation so you most likely have them all!
+
+See [TWiki:TWiki.HowToInstallCpanModules](http://twiki.org/cgi-bin/view/TWiki/HowToInstallCpanModules 'TWiki/HowToInstallCpanModules' on TWiki.org) for detailed information on how to install CPAN libraries
+
The following Perl [CPAN](http://cpan.perl.org/) modules are used by TWiki:
<table border="1" cellpadding="0" cellspacing="0">
<td> >=3.05 </td>
</tr>
<tr>
- <td>[[Main/FileHandle]]</td>
+ <td> FileHandle </td>
<td> >=2.01 </td>
</tr>
<tr>
The following Perl modules may be used by TWiki:
+See [TWiki:TWiki.HowToInstallCpanModules](http://twiki.org/cgi-bin/view/TWiki/HowToInstallCpanModules 'TWiki/HowToInstallCpanModules' on TWiki.org) for detailed information on how to install CPAN libraries
+
<table border="1" cellpadding="0" cellspacing="0">
<tr>
<th bgcolor="#99CCCC"><strong> Module </strong></th>
> <td> dir secure from public access </td>
> <td><code>/home/smith/twiki/tools</code></td>
> </tr>
+> <tr>
+> <td><code>twiki/working</code></td>
+> <td> Temporary and internal files </td>
+> <td> dir secure from public access </td>
+> <td><code>/home/smith/twiki/working</code></td>
+> </tr>
> </table>
- **Step 3:** Files in the pub directory must be readable as a url. This means that directory permissions should be set to `755` (or `775` ) and file permissions should be set to `644` (or `664`). If you can run a `chmod` command, you can accomplish this in two quick steps by running these commands from the root direct:
This topic contains javascript files that are included by TWiki templates, and may be used by skin templates and in topics.
-**_Related Topics:_** [[TWikiTemplates]], [[TWikiSkins]], [[PatternJavascripts]]
+**_Related Topics:_** [[TWikiTemplates]], [[TWikiSkins]]
-- Set ALLOWTOPICCHANGE = [[TWikiAdminGroup]]
+- Set ALLOWTOPICCHANGE = %USERSWEB%.TWikiAdminGroup
--- /dev/null
+# <a name="Package <code>TWiki::_LineIterator="></a> Package =TWiki::LineIterator
+
+Iterator over the lines in a file
+
+<div>
+ <ul>
+ <li><a href="#Package =TWiki::_LineIterator="> Package TWiki::LineIterator</a><ul>
+ <li><a href="#new( $file )"> new( $file )</a></li>
+ <li><a href="#hasNext() -> $boolean"> hasNext() -> $boolean</a></li>
+ <li><a href="#next() -> $data"> next() -> $data</a></li>
+ </ul>
+ </li>
+ </ul>
+</div>
+
+## <a name="new( $file )"></a> new( $file )
+
+Create a new iterator over the given file. if the file cannot be opened, then there will be no elements in the iterator.
+
+## <a name="hasNext() - $boolean"></a> hasNext() -> $boolean
+
+Returns false when the iterator is exhausted.
+
+ my $it = new TWiki::ListIterator(\@list);
+ while ($it->hasNext()) {
+ ...
+
+## <a name="next() - $data"></a> next() -> $data
+
+Return the next line in the file.
+
+The iterator object can be customised to pre- and post-process entries from the list before returning them. This is done by setting two fields in the iterator object:
+
+- `{filter}` can be defined to be a sub that filters each entry. The entry will be ignored (next() will not return it) if the filter returns false.
+- `{process}` can be defined to be a sub to process each entry before it is returned by next. The value returned from next is the value returned by the process function.
+
+For example,
+
+ my $it = new TWiki::LineIterator("/etc/passwd");
+ $it->{filter} = sub { $_[0] =~ /^.*?:/; return $1; };
+ $it->{process} = sub { return "User $_[0]"; };
+ while ($it->hasNext()) {
+ my $x = $it->next();
+ print "$x\n";
+ }
--- /dev/null
+# <a name="Package <code>TWiki::_ListIterator="></a> Package =TWiki::ListIterator
+
+Iterator over a list
+
+<div>
+ <ul>
+ <li><a href="#Package =TWiki::_ListIterator="> Package TWiki::ListIterator</a><ul>
+ <li><a href="#new(\@list)"> new(\@list)</a></li>
+ <li><a href="#hasNext() -> $boolean"> hasNext() -> $boolean</a></li>
+ <li><a href="#next() -> $data"> next() -> $data</a></li>
+ </ul>
+ </li>
+ </ul>
+</div>
+
+## <a name="new(\@list)"></a> new(\\@list)
+
+Create a new iterator over the given list. Designed primarily for operations over fully defined lists of object references. The list is not damaged in any way.
+
+## <a name="hasNext() - $boolean"></a> hasNext() -> $boolean
+
+Returns false when the iterator is exhausted.
+
+ my $it = new TWiki::ListIterator(\@list);
+ while ($it->hasNext()) {
+ ...
+
+## <a name="next() - $data"></a> next() -> $data
+
+Return the next entry in the list.
+
+The iterator object can be customised to pre- and post-process entries from the list before returning them. This is done by setting two fields in the iterator object:
+
+- `{filter}` can be defined to be a sub that filters each entry. The entry will be ignored (next() will not return it) if the filter returns false.
+- `{process}` can be defined to be a sub to process each entry before it is returned by next. The value returned from next is the value returned by the process function.
+
+For example,
+
+ my @list = ( 1, 2, 3 );
+
+ my $it = new TWiki::ListIterator(\@list);
+ $it->{filter} = sub { return $_[0] != 2 };
+ $it->{process} = sub { return $_[0] + 1 };
+ while ($it->hasNext()) {
+ my $x = $it->next();
+ print "$x, ";
+ }
+
+will print
+
+ 2, 4
--- /dev/null
+# <a name="Package <code>TWiki::_LoginManager::"></a><a name="Package =TWiki::_LoginManager::_"></a> Package =TWiki::LoginManager::ApacheLogin
+
+This is login manager that you can specify in the security setup section of [configure](http://www.dementia.org/twiki/configure). It instructs TWiki to cooperate with your web server (typically Apache) to require authentication information (username & password) from users. It requires that you configure your web server to demand authentication for scripts named "login" and anything ending in "auth". The latter should be symlinks to existing scripts; e.g., `viewauth -> view`, `editauth -> edit`, and so on.
+
+See also [[TWikiUserAuthentication]].
+
+Subclass of TWiki::LoginManager; see that class for documentation of the methods of this class.
+
+<div>
+ <ul>
+ <li><a href="#Package =TWiki::_LoginManager::"> Package TWiki::LoginManager::ApacheLogin</a><ul>
+ <li><a href="#ClassMethod <strong>new</strong> ($session)"> ClassMethod new <tt>($session)</tt></a></li>
+ <li><a href="#ObjectMethod *forceAuthenticatio"> ObjectMethod forceAuthentication <tt>() -> boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>loginUrl</strong> () -> $l"> ObjectMethod loginUrl <tt>() -> $loginUrl</tt></a></li>
+ <li><a href="#ObjectMethod <strong>login</strong> ($query,$tw"> ObjectMethod login <tt>($query,$twiki)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>getUser</strong> () -> $au"> ObjectMethod getUser <tt>() -> $authUser</tt></a></li>
+ </ul>
+ </li>
+ </ul>
+</div>
+
+## <a name="ClassMethod <strong>new</strong> ($session)"></a> [[ClassMethod]] **new** `($session)`
+
+Construct the [[ApacheLogin]] object
+
+## <a name="ObjectMethod <strong>forceAuthenticatio"></a> [[ObjectMethod]] \*forceAuthentication `() -> boolean`
+
+method called when authentication is required - redirects to (...|view)auth Triggered on auth fail
+
+## <a name="ObjectMethod <strong>loginUrl</strong> () - $lo"></a> [[ObjectMethod]] **loginUrl** `() -> $loginUrl`
+
+TODO: why is this not used internally? When is it called, and why Content of a login link
+
+## <a name="ObjectMethod <strong>login</strong> ($query,$tw"></a> [[ObjectMethod]] **login** `($query,$twiki)`
+
+this allows the login and logon cgi-scripts to use the same code. all a logon does, is re-direct to viewauth, and apache then figures out if it needs to challenge the user
+
+## <a name="ObjectMethod <strong>getUser</strong> () - $aut"></a> [[ObjectMethod]] **getUser** `() -> $authUser`
+
+returns the userLogin if stored in the apache CGI query (ie session)
--- /dev/null
+# <a name="Package <code>TWiki::_LoginManager="></a> Package =TWiki::LoginManager
+
+The package is also a Factory for login managers and also the base class for all login managers.
+
+On it's own, an object of this class is used when you specify 'none' in the security setup section of [configure](http://www.dementia.org/twiki/configure). When it is used, logins are not supported. If you want to authenticate users then you should consider [[TemplateLogin]] or [[ApacheLogin]], which are subclasses of this class.
+
+If you are building a new login manager, then you should write a new subclass of this class, implementing the methods marked as **VIRTUAL**. There are already examples in the `lib/TWiki/LoginManager` directory.
+
+The class has extensive tracing, which is enabled by $TWiki::cfg\{Trace\}\{LoginManager.pm\}. The tracing is done in such a way as to let the perl optimiser optimise out the trace function as a no-op if tracing is disabled.
+
+Here's an overview of how it works:
+
+Early in TWiki::new, the login manager is created. The creation of the login manager does two things:
+
+1. If sessions are in use, it loads CGI::Session but doesn't initialise the session yet.
+2. Creates the login manager object
+
+Slightly later in TWiki::new, loginManager->loadSession is called.
+
+1. Calls loginManager->getUser to get the username **before** the session is created
+ - TWiki::LoginManager::ApacheLogin looks at REMOTE\_USER (only for authenticated scripts)
+ - TWiki::LoginManager::TemplateLogin just returns undef
+2. reads the TWIKISID cookie to get the SID (or the TWIKISID parameters in the CGI query if cookies aren't available, or [[IP2SID]] mapping if that's enabled).
+3. Creates the CGI::Session object, and the session is thereby read.
+4. If the username still isn't known, reads it from the cookie. Thus TWiki::LoginManager::ApacheLogin overrides the cookie using REMOTE\_USER, and TWiki::LoginManager::TemplateLogin **always** uses the session.
+
+Later again in TWiki::new, plugins are given a chance to **override** the username found from the loginManager.
+
+The last step in TWiki::new is to find the user, using whatever user mapping manager is in place.
+
+## <a name="ObjectData <code>twiki="></a> [[ObjectData]] =twiki
+
+The TWiki object this login manager is attached to.
+
+<div>
+ <ul>
+ <li><a href="#Package =TWiki::_LoginManager="> Package TWiki::LoginManager</a><ul>
+ <li><a href="#ObjectData =twiki="> ObjectData twiki</a></li>
+ <li><a href="#StaticMethod *make_LoginManager*"> StaticMethod makeLoginManager <tt>($twiki) -> $TWiki::LoginManager</tt></a></li>
+ <li><a href="#ClassMethod <strong>new</strong> ($session,$imp"> ClassMethod new <tt>($session,$impl)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
+ <li><a href="#ClassMethod <strong>_real_trace</strong> ($sess"> ClassMethod _real_trace <tt>($session,$impl)</tt></a></li>
+ <li><a href="#ClassMethod <strong>_IP2SID</strong> ($session,"> ClassMethod _IP2SID <tt>($session,$impl)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>loadSession</strong> ($def"> ObjectMethod loadSession <tt>($defaultUser) -> $login</tt></a></li>
+ <li><a href="#ObjectMethod <strong>checkAccess</strong> ()"> ObjectMethod checkAccess <tt>()</tt></a></li>
+ <li><a href="#ObjectMethod <strong>complete</strong> ()"> ObjectMethod complete <tt>()</tt></a></li>
+ <li><a href="#StaticMethod *expire_DeadSession"> StaticMethod expireDeadSessions <tt>()</tt></a></li>
+ <li><a href="#ObjectMethod <strong>user_LoggedIn</strong> ($l"> ObjectMethod userLoggedIn <tt>($login,$wikiname)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>_my_ScriptURLRE</strong> ("> ObjectMethod _myScriptURLRE <tt>($thisl)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>_rewriteURL</strong> ($thi"> ObjectMethod _rewriteURL <tt>($thisl)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>_rewriteFORM</strong> ($th"> ObjectMethod _rewriteFORM <tt>($thisl)</tt></a></li>
+ <li><a href="#ObjectMethod *end_RenderingHandl"> ObjectMethod endRenderingHandler <tt>()</tt></a></li>
+ <li><a href="#ObjectMethod <strong>_pushCookie</strong> ($thi"> ObjectMethod _pushCookie <tt>($thisl)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>addCookie</strong> ($c)"> ObjectMethod addCookie <tt>($c)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>modifyHeader</strong> (\%h"> ObjectMethod modifyHeader <tt>(\%header)</tt></a></li>
+ <li><a href="#ObjectMethod *redirect_CgiQuery*"> ObjectMethod redirectCgiQuery <tt>($url)</tt></a></li>
+ <li><a href="#ObjectMethod *get_SessionValues*"> ObjectMethod getSessionValues <tt>() -> \%values</tt></a></li>
+ <li><a href="#ObjectMethod *get_SessionValue*"> ObjectMethod getSessionValue <tt>($name) -> $value</tt></a></li>
+ <li><a href="#ObjectMethod *set_SessionValue*"> ObjectMethod setSessionValue <tt>($name,$value)</tt></a></li>
+ <li><a href="#ObjectMethod *clear_SessionValue"> ObjectMethod clearSessionValue <tt>($name) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod *forceAuthenticatio"> ObjectMethod forceAuthentication <tt>() -> boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>loginUrl</strong> (...) ->"> ObjectMethod loginUrl <tt>(...) -> $url</tt></a></li>
+ <li><a href="#ObjectMethod <strong>getUser</strong> ()"> ObjectMethod getUser <tt>()</tt></a></li>
+ <li><a href="#ObjectMethod <strong>_LOGIN</strong> ($thisl)"> ObjectMethod _LOGIN <tt>($thisl)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>_LOGOUTURL</strong> ($this"> ObjectMethod _LOGOUTURL <tt>($thisl)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>_LOGOUT</strong> ($thisl)"> ObjectMethod _LOGOUT <tt>($thisl)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>_AUTHENTICATED</strong> ($"> ObjectMethod _AUTHENTICATED <tt>($thisl)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>_CANLOGIN</strong> ($thisl"> ObjectMethod _CANLOGIN <tt>($thisl)</tt></a></li>
+ <li><a href="#ObjectMethod *_SESSION_VARIABLE*"> ObjectMethod _SESSION_VARIABLE <tt>($thisl)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>_LOGINURL</strong> ($thisl"> ObjectMethod _LOGINURL <tt>($thisl)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>_dispLogon</strong> ($this"> ObjectMethod _dispLogon <tt>($thisl)</tt></a></li>
+ <li><a href="#PrivateMethod _skinSelect ()"> PrivateMethod _skinSelect ()</a></li>
+ </ul>
+ </li>
+ </ul>
+</div>
+
+## <a name="StaticMethod <strong>make_LoginManager*"></a> [[StaticMethod]] \*makeLoginManager `($twiki) -> $TWiki::LoginManager`
+
+Factory method, used to generate a new TWiki::LoginManager object for the given session.
+
+## <a name="ClassMethod <strong>new</strong> ($session,$imp"></a> [[ClassMethod]] **new** `($session,$impl)`
+
+Construct the user management object
+
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
+
+Break circular references.
+
+## <a name="ClassMethod <strong>_real_trace</strong> ($sess"></a> [[ClassMethod]] **\_real\_trace** `($session,$impl)`
+
+Construct the user management object
+
+## <a name="ClassMethod <strong>_IP2SID</strong> ($session,"></a> [[ClassMethod]] **\_IP2SID** `($session,$impl)`
+
+read/write IP to SID map, return SID
+
+## <a name="ObjectMethod <strong>loadSession</strong> ($def"></a> [[ObjectMethod]] **loadSession** `($defaultUser) -> $login`
+
+Get the client session data, using the cookie and/or the request URL. Set up appropriate session variables in the twiki object and return the login name.
+
+$defaultUser is a username to use if one is not available from other sources. The username passed when you create a TWiki instance is passed in here.
+
+## <a name="ObjectMethod <strong>checkAccess</strong> ()"></a> [[ObjectMethod]] **checkAccess** `()`
+
+Check if the script being run in this session is authorised for execution. If not, throw an access control exception.
+
+## <a name="ObjectMethod <strong>complete</strong> ()"></a> [[ObjectMethod]] **complete** `()`
+
+Complete processing after the client's HTTP request has been responded to. Flush the user's session (if any) to disk.
+
+## <a name="StaticMethod <strong>expire_DeadSession"></a> [[StaticMethod]] \*expireDeadSessions `()`
+
+Delete sessions and passthrough files that are sitting around but are really expired. This **assumes** that the sessions are stored as files.
+
+This is a static method, but requires TWiki::cfg. It is designed to be run from a session or from a cron job.
+
+## <a name="ObjectMethod <strong>user_LoggedIn</strong> ($l"></a> [[ObjectMethod]] **userLoggedIn** `($login,$wikiname)`
+
+Called when the user is known. It's invoked from TWiki::UI::Register::finish for instance,
+
+1. when the user follows the link in their verification email message
+2. or when the session store is read
+3. when the user authenticates (via templatelogin / sudo)
+
+- `$login` - string login name
+- `$wikiname` - string wikiname
+
+## <a name="ObjectMethod <strong>_my_ScriptURLRE</strong> ("></a> [[ObjectMethod]] **\_myScriptURLRE** `($thisl)`
+
+## <a name="ObjectMethod <strong>_rewriteURL</strong> ($thi"></a> [[ObjectMethod]] **\_rewriteURL** `($thisl)`
+
+## <a name="ObjectMethod <strong>_rewriteFORM</strong> ($th"></a> [[ObjectMethod]] **\_rewriteFORM** `($thisl)`
+
+## <a name="ObjectMethod <strong>end_RenderingHandl"></a> [[ObjectMethod]] \*endRenderingHandler `()`
+
+This handler is called by getRenderedVersion just before the plugins postRenderingHandler. So it is passed all HTML text just before it is printed.
+
+**DEPRECATED** Use postRenderingHandler instead.
+
+## <a name="ObjectMethod <strong>_pushCookie</strong> ($thi"></a> [[ObjectMethod]] **\_pushCookie** `($thisl)`
+
+## <a name="ObjectMethod <strong>addCookie</strong> ($c)"></a> [[ObjectMethod]] **addCookie** `($c)`
+
+Add a cookie to the list of cookies for this session.
+
+- `$c` - a CGI::Cookie
+
+## <a name="ObjectMethod <strong>modifyHeader</strong> (\%h"></a> [[ObjectMethod]] **modifyHeader** `(\%header)`
+
+Modify a HTTP header
+
+- `\%header` - header entries
+
+## <a name="ObjectMethod <strong>redirect_CgiQuery*"></a> [[ObjectMethod]] \*redirectCgiQuery `($url)`
+
+Generate an HTTP redirect on STDOUT, if you can. Return 1 if you did.
+
+- `$url` - target of the redirection.
+
+## <a name="ObjectMethod <strong>get_SessionValues*"></a> [[ObjectMethod]] \*getSessionValues `() -> \%values`
+
+Get a name->value hash of all the defined session variables
+
+## <a name="ObjectMethod <strong>get_SessionValue*"></a><a name="ObjectMethod *get_SessionValue</strong> "></a> [[ObjectMethod]] **getSessionValue** `($name) -> $value`
+
+Get the value of a session variable.
+
+## <a name="ObjectMethod <strong>set_SessionValue*"></a><a name="ObjectMethod *set_SessionValue</strong> "></a> [[ObjectMethod]] **setSessionValue** `($name,$value)`
+
+Set the value of a session variable. We do not allow setting of AUTHUSER.
+
+## <a name="ObjectMethod <strong>clear_SessionValue"></a> [[ObjectMethod]] \*clearSessionValue `($name) -> $boolean`
+
+Clear the value of a session variable. We do not allow setting of AUTHUSER.
+
+## <a name="ObjectMethod <strong>forceAuthenticatio"></a> [[ObjectMethod]] \*forceAuthentication `() -> boolean`
+
+**VIRTUAL METHOD** implemented by subclasses
+
+Triggered by an access control violation, this method tests to see if the current session is authenticated or not. If not, it does whatever is needed so that the user can log in, and returns 1.
+
+If the user has an existing authenticated session, the function simply drops though and returns 0.
+
+## <a name="ObjectMethod <strong>loginUrl</strong> (...) -"></a><a name="ObjectMethod <strong>loginUrl</strong> (...) - "></a> [[ObjectMethod]] **loginUrl** `(...) -> $url`
+
+**VIRTUAL METHOD** implemented by subclasses
+
+Return a full URL suitable for logging in.
+
+- `...` - url parameters to be added to the URL, in the format required by TWiki::getScriptUrl()
+
+## <a name="ObjectMethod <strong>getUser</strong> ()"></a> [[ObjectMethod]] **getUser** `()`
+
+**VIRTUAL METHOD** implemented by subclasses
+
+If there is some other means of getting a username - for example, Apache has remote\_user() - then return it. Otherwise, return undef and the username stored in the session will be used.
+
+## <a name="ObjectMethod <strong>_LOGIN</strong> ($thisl)"></a> [[ObjectMethod]] **\_LOGIN** `($thisl)`
+
+## <a name="ObjectMethod <strong>_LOGOUTURL</strong> ($this"></a> [[ObjectMethod]] **\_LOGOUTURL** `($thisl)`
+
+## <a name="ObjectMethod <strong>_LOGOUT</strong> ($thisl)"></a> [[ObjectMethod]] **\_LOGOUT** `($thisl)`
+
+## <a name="ObjectMethod <strong>_AUTHENTICATED</strong> ($"></a> [[ObjectMethod]] **\_AUTHENTICATED** `($thisl)`
+
+## <a name="ObjectMethod <strong>_CANLOGIN</strong> ($thisl"></a> [[ObjectMethod]] **\_CANLOGIN** `($thisl)`
+
+## <a name="ObjectMethod <strong>_SESSION_VARIABLE*"></a> [[ObjectMethod]] \*\_SESSION\_VARIABLE `($thisl)`
+
+## <a name="ObjectMethod <strong>_LOGINURL</strong> ($thisl"></a> [[ObjectMethod]] **\_LOGINURL** `($thisl)`
+
+## <a name="ObjectMethod <strong>_dispLogon</strong> ($this"></a> [[ObjectMethod]] **\_dispLogon** `($thisl)`
+
+## <a name="PrivateMethod _skinSelect ()"></a> [[PrivateMethod]] \_skinSelect ()
+
+Internal use only TODO: what does it do?
--- /dev/null
+# <a name="Package <code>TWiki::_LoginManager::"></a><a name="Package =TWiki::_LoginManager::_"></a> Package =TWiki::LoginManager::TemplateLogin
+
+This is a login manager that you can specify in the security setup section of [configure](http://www.dementia.org/twiki/configure). It provides users with a template-based form to enter usernames and passwords, and works with the [[PasswordManager]] that you specify to verify those passwords.
+
+Subclass of TWiki::LoginManager; see that class for documentation of the methods of this class.
+
+<div>
+ <ul>
+ <li><a href="#Package =TWiki::_LoginManager::"> Package TWiki::LoginManager::TemplateLogin</a><ul>
+ <li><a href="#ClassMethod <strong>new</strong> ($session,$imp"> ClassMethod new <tt>($session,$impl)</tt></a></li>
+ <li><a href="#ObjectMethod *forceAuthenticatio"> ObjectMethod forceAuthentication <tt>() -> boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>loginUrl</strong> () -> $l"> ObjectMethod loginUrl <tt>() -> $loginUrl</tt></a></li>
+ <li><a href="#ObjectMethod <strong>login</strong> ($query,$tw"> ObjectMethod login <tt>($query,$twiki)</tt></a></li>
+ </ul>
+ </li>
+ </ul>
+</div>
+
+## <a name="ClassMethod <strong>new</strong> ($session,$imp"></a> [[ClassMethod]] **new** `($session,$impl)`
+
+Construct the [[TemplateLogin]] object
+
+## <a name="ObjectMethod <strong>forceAuthenticatio"></a> [[ObjectMethod]] \*forceAuthentication `() -> boolean`
+
+method called when authentication is required - redirects to (...|view)auth Triggered on auth fail
+
+## <a name="ObjectMethod <strong>loginUrl</strong> () - $lo"></a> [[ObjectMethod]] **loginUrl** `() -> $loginUrl`
+
+TODO: why is this not used internally? When is it called, and why Content of a login link
+
+## <a name="ObjectMethod <strong>login</strong> ($query,$tw"></a> [[ObjectMethod]] **login** `($query,$twiki)`
+
+If a login name and password have been passed in the query, it validates these and if authentic, redirects to the original script. If there is no username in the query or the username/password is invalid (validate returns non-zero) then it prompts again.
+
+If a flag to remember the login has been passed in the query, then the corresponding session variable will be set. This will result in the login cookie being preserved across browser sessions.
+
+The password handler is expected to return a perl true value if the password is valid. This return value is stored in a session variable called VALIDATION. This is so that password handlers can return extra information about the user, such as a list of TWiki groups stored in a separate database, that can then be displayed by referring to %SESSION\_VARIABLE\{"VALIDATION"\}%
# <a name="TWiki Logos"></a> TWiki Logos
-The official TWiki logo is a big "T" in a speech bubble convenying "working together", and has a "collaborate with TWiki" tag line.
+The official TWiki logo is a big "T" in a speech bubble conveying "working together", and has a "collaborate with TWiki" tag line.
## <a name="TWiki.org Logo Artwork"></a> TWiki.org Logo Artwork
<p><code>T-logo-124x35-t.gif</code>: <br /><img alt="T-logo, transparent bg, 124x35" src="http://www.dementia.org/twiki//view/T-logo-124x35-t.gif" /></p>
<p><code>T-logo-88x31-t.gif</code>: <br /><img alt="T-logo, transparent bg, 88x31" src="http://www.dementia.org/twiki//view/T-logo-88x31-t.gif" /></p>
<p><code>T-logo-80x15.gif</code>: <br /><img alt="T-logo, 80x15" src="http://www.dementia.org/twiki//view/T-logo-80x15.gif" /></p>
+ <p><code>T-badge-88x31.gif</code>: <br /><img alt="T-badge, 88x31" src="http://www.dementia.org/twiki//view/T-badge-88x31.gif" /></p>
<p>
</p>
</td>
If you use the official TWiki.org artwork on your own site you can link back to TWiki.org. Use this HTML (with any logo file on this page):
-`<a href="http://twiki.org/"><img src="%PUBURL%/%TWIKIWEB%/TWikiLogos/T-logo-140x40-t.gif" alt="This site is powered by the TWiki collaboration platform" title="This site is powered by the TWiki collaboration platform" border="0" /></a>`
+`<a href="http://twiki.org/"><img src="%PUBURL%/%SYSTEMWEB%/TWikiLogos/T-logo-140x40-t.gif" alt="This site is powered by the TWiki collaboration platform" title="This site is powered by the TWiki collaboration platform" border="0" /></a>`
If you create your own TWiki skin you are encouraged to add the small 80x31 pixel TWiki logo at the bottom of your skin:
-`<a href="http://twiki.org/"><img src="%PUBURL%/%TWIKIWEB%/TWikiLogos/T-logo-80x15.gif" alt="This site is powered by the TWiki collaboration platform" width="80" height="15" title="This site is powered by the TWiki collaboration platform" border="0" /></a>`
+`<a href="http://twiki.org/"><img src="%PUBURL%/%SYSTEMWEB%/TWikiLogos/T-logo-80x15.gif" alt="This site is powered by the TWiki collaboration platform" width="80" height="15" title="This site is powered by the TWiki collaboration platform" border="0" /></a>`
## <a name="Right to use Trademarked Artwork"></a> Right to use Trademarked Artwork
## <a name="Background and Feedback"></a> Background and Feedback
The logo was created by TWiki:Main.PeterThoeny and TWiki:Main.ArthurClemens in September 2005, based on a lot of feedback from the TWiki community. See history and provide feedback at TWiki:Codev.TWikiLogoDevelopment.
+
+-- **_Contributors:_** TWiki:Main.ArthurClemens, TWiki:Main.PeterThoeny - 02 Oct 2005
+<a name="TWikiMetaData"></a>
+
+# <a name="TWiki Meta Data"></a> TWiki Meta Data
+
+_Additional topic data, program-generated or from [[TWikiForms]], is stored embedded in the topic text using `META:` tags_
+
<div>
<ul>
<li><a href="#TWiki Meta Data"> TWiki Meta Data</a><ul>
</li>
<li><a href="#Viewing Meta Data in Page Source"> Viewing Meta Data in Page Source</a></li>
<li><a href="#Rendering Meta Data"> Rendering Meta Data</a></li>
- <li><a href="#Known Issues"> Known Issues</a></li>
</ul>
</li>
</ul>
</div>
-<a name="TWikiMetaData"></a>
-
-# <a name="TWiki Meta Data"></a> TWiki Meta Data
+## <a name="Overview"></a> Overview
-_Additional topic data, program-generated or from [[TWikiForms]], is stored in `META` variable name/value pairs_
+By default, TWiki stores topics in files on disk, in a really simple and obvious directory structure. The big advantage of this approach is that it makes it really easy to manipulate topics from outside TWiki, and is also very safe; there are no complex binary indexes to maintain, and moving a topic from one TWiki to another is as simple as copying a couple of text files.
-## <a name="Overview"></a> Overview
+To keep eveything together in one place, TWiki uses a simple method for embedding additional data (program-generated or from [[TWikiForms]]) in topics. It does this using `META:` tags.
-[[TWikiMetaData]] uses `META` variables to store topic data that's separate from the main free-form content. This includes program-generated info like [[FileAttachment]] and topic movement data, and user-defined [[TWikiForms]] info. Use `META` variables to format and display Meta Data.
+`META:` data includes program-generated info like [[FileAttachment]] and topic movement data, and user-defined [[TWikiForms]] info.
## <a name="Meta Data Syntax"></a> Meta Data Syntax
- Each meta variable is on one line.
-- `\n` (new line) is represented in values by `%_N_` and `"` (double-quotes) by `%_Q_%`.
+- Values in meta-data are URL encoded so that characters such as \\n can be stored.
> **Example of Format**
>
**_Note:_** SEARCH can also be used to render meta data, see examples in [[FormattedSearch]] and [[SearchPatternCookbook]].
-## <a name="Known Issues"></a> Known Issues
-
-At present, there is no Meta Data support for Plugins. However, the format is readily extendable and the `Meta.pm` code that supports the format needs only minor alteration.
-
**_Related Topics:_** [[DeveloperDocumentationCategory]], [[UserDocumentationCategory]]
-
--- **_Contributors:_** TWiki:Main.JohnTalintyre, TWiki:Main.MikeMannix, TWiki:Main.PeterThoeny, TWiki:Main.CrawfordCurrie
# <a name="Package <code>TWiki::Meta="></a> Package =TWiki::Meta
-Meta-data handling.
+All TWiki topics have **data** (text) and **meta-data** (information about the topic). Meta-data includes information such as file attachments, form fields, topic parentage etc. When TWiki loads a topic from the store, it represents the meta-data in the topic using an object of this class.
A meta-data object is a hash of different types of meta-data (keyed on the type, such as 'FIELD' and 'TOPICINFO').
Each entry in the hash is an array, where each entry in the array contains another hash of the key=value pairs, corresponding to a single meta-datum.
-If there may be multiple entries of the same top-level type (i.e. for FIELD and FILEATTACHMENT) then the array hash multiple entries. These types are referred to as "keyed" types. The array entries are keyed with the attribute 'name' which must be in each entry in the array.
+If there may be multiple entries of the same top-level type (i.e. for FIELD and FILEATTACHMENT) then the array has multiple entries. These types are referred to as "keyed" types. The array entries are keyed with the attribute 'name' which must be in each entry in the array.
For unkeyed types, the array has only one entry.
-The module knows nothing about how meta-data is stored. That is entirely the responsibility of the Store module.
+Pictorially,
-Meta-data objects are created by the Store engine when topics are read. They are populated using the `put` method.
+- TOPICINFO
+ - author => '...'
+ - date => '...'
+ - ...
+- FILEATTACHMENT
+ - [0] -> \{ name => '...' ... \}
+ - [1] -> \{ name => '...' ... \}
+- FIELD
+ - [0] -> \{ name => '...' ... \}
+ - [1] -> \{ name => '...' ... \}
+
+As well as the meta-data, the object also stores the web name, topic name and remaining text after meta-data extraction.
<div>
<ul>
<li><a href="#Package =TWiki::Meta="> Package TWiki::Meta</a><ul>
- <li><a href="#ClassMethod <strong>new</strong> ($session,$web"> ClassMethod new <tt>($session,$web,$topic)</tt></a></li>
- <li><a href="#ClassMethod <strong>web</strong> ()"> ClassMethod web <tt>()</tt></a></li>
- <li><a href="#ClassMethod <strong>topic</strong> ()"> ClassMethod topic <tt>()</tt></a></li>
+ <li><a href="#ClassMethod <strong>new</strong> ($session,$web"> ClassMethod new <tt>($session,$web,$topic,$text)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
+ <li><a href="#ObjectMethod <strong>session</strong> ()"> ObjectMethod session <tt>()</tt></a></li>
+ <li><a href="#ObjectMethod <strong>web</strong> ()"> ObjectMethod web <tt>()</tt></a></li>
+ <li><a href="#ObjectMethod <strong>topic</strong> ()"> ObjectMethod topic <tt>()</tt></a></li>
+ <li><a href="#ObjectMethod <strong>text</strong> ([$text]) ->"> ObjectMethod text <tt>([$text]) -> $text</tt></a></li>
<li><a href="#ObjectMethod <strong>put</strong> ($type,\%args"> ObjectMethod put <tt>($type,\%args)</tt></a></li>
<li><a href="#ObjectMethod <strong>putKeyed</strong> ($type,\"> ObjectMethod putKeyed <tt>($type,\%args)</tt></a></li>
<li><a href="#ObjectMethod *putAll*"> ObjectMethod putAll <tt></tt></a></li>
<li><a href="#ObjectMethod <strong>get</strong> ($type,$key)"> ObjectMethod get <tt>($type,$key) -> \%hash</tt></a></li>
<li><a href="#ObjectMethod <strong>find</strong> ($type) -> @"> ObjectMethod find <tt>($type) -> @values</tt></a></li>
- <li><a href="#StaticMethod *index_ByKey*"> StaticMethod indexByKey <tt></tt></a></li>
<li><a href="#ObjectMethod <strong>remove</strong> ($type,$ke"> ObjectMethod remove <tt>($type,$key)</tt></a></li>
<li><a href="#ObjectMethod <strong>copyFrom</strong> ($otherM"> ObjectMethod copyFrom <tt>($otherMeta,$type,$nameFilter)</tt></a></li>
<li><a href="#ObjectMethod <strong>count</strong> ($type) ->"> ObjectMethod count <tt>($type) -> $integer</tt></a></li>
<li><a href="#ObjectMethod *for_EachSelectedVa"> ObjectMethod forEachSelectedValue <tt>($types,$keys,\&fn,\%options)</tt></a></li>
<li><a href="#ObjectMethod <strong>getParent</strong> () -> $"> ObjectMethod getParent <tt>() -> $parent</tt></a></li>
<li><a href="#ObjectMethod <strong>get_FormName</strong> () -"> ObjectMethod getFormName <tt>() -> $formname</tt></a></li>
+ <li><a href="#ObjectMethod *render_FormForDisp"> ObjectMethod renderFormForDisplay <tt>() -> $html</tt></a></li>
+ <li><a href="#ObjectMethod *render_FormFieldFo"> ObjectMethod renderFormFieldForDisplay <tt>($name,$format,$attrs) -> $text</tt></a></li>
+ <li><a href="#ObjectMethod *get_EmbeddedStoreF"> ObjectMethod getEmbeddedStoreForm <tt>() -> $text</tt></a></li>
+ <li><a href="#ObjectMethod <strong>get_MetaFor</strong> () ->"> ObjectMethod getMetaFor <tt>() -> $meta</tt></a></li>
</ul>
</li>
</ul>
</div>
-## <a name="ClassMethod <strong>new</strong> ($session,$web"></a> [[ClassMethod]] **new** `($session,$web,$topic)`
+## <a name="ClassMethod <strong>new</strong> ($session,$web"></a> [[ClassMethod]] **new** `($session,$web,$topic,$text)`
+
+- `$session` - a TWiki object (e.g. =$TWiki::Plugins::SESSION)
+- `$web`, `$topic` - the topic that the metadata relates to
+
+Construct a new, empty object to contain meta-data for the given topic.
+
+- $text - optional raw text to convert to meta-data form
+
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
+
+Break circular references.
+
+## <a name="ObjectMethod <strong>session</strong> ()"></a> [[ObjectMethod]] **session** `()`
-Construct a new, empty Meta collection.
+Get the session
-## <a name="ClassMethod <strong>web</strong> ()"></a> [[ClassMethod]] **web** `()`
+## <a name="ObjectMethod <strong>web</strong> ()"></a> [[ObjectMethod]] **web** `()`
Get the web name
-## <a name="ClassMethod <strong>topic</strong> ()"></a> [[ClassMethod]] **topic** `()`
+## <a name="ObjectMethod <strong>topic</strong> ()"></a> [[ObjectMethod]] **topic** `()`
Get the topic name
+## <a name="ObjectMethod <strong>text</strong> ([$text]) -"></a><a name="ObjectMethod <strong>text</strong> ([$text]) - "></a> [[ObjectMethod]] **text** `([$text]) -> $text`
+
+Get/set the topic body text. If $text is undef, gets the value, if it is defined, sets the value to that and returns the new text.
+
## <a name="ObjectMethod <strong>put</strong> ($type,\%args"></a> [[ObjectMethod]] **put** `($type,\%args)`
-Put a hash of key=value pairs into the given type set in this meta.
+Put a hash of key=value pairs into the given type set in this meta. This will **not** replace another value with the same name (for that see `putKeyed`)
+
+For example,
-See the main comment for this package to understand how meta-data is represented.
+ $meta->put( 'FIELD', { name => 'MaxAge', title => 'Max Age', value =>'103' } );
## <a name="ObjectMethod <strong>putKeyed</strong> ($type,\"></a> [[ObjectMethod]] **putKeyed** `($type,\%args)`
-Put a hash of key=value pairs into the given type set in this meta. The entries are keyed by 'name'.
+Put a hash of key=value pairs into the given type set in this meta, replacing any existing value with the same key.
-See the main comment for this package to understand how meta-data is represented.
+For example,
+
+ $meta->putKeyed( 'FIELD', { name => 'MaxAge', title => 'Max Age', value =>'103' } );
## <a name="ObjectMethod <strong>putAll*"></a><a name="ObjectMethod *putAll</strong> "></a> [[ObjectMethod]] **putAll** ``
-Replaces all the items of a given key with a new array This is the logical inverse of the find method
+Replaces all the items of a given key with a new array.
+
+For example,
+
+ $meta->putAll( 'FIELD',
+ { name => 'MinAge', title => 'Min Age', value =>'50' },
+ { name => 'MaxAge', title => 'Max Age', value =>'103' },
+ { name => 'HairColour', title => 'Hair Colour', value =>'white' }
+ );
## <a name="ObjectMethod <strong>get</strong> ($type,$key)"></a><a name="ObjectMethod <strong>get</strong> ($type,$key) "></a> [[ObjectMethod]] **get** `($type,$key) -> \%hash`
-Find the value of a meta-datum in the map. If the type is keyed, the $key parameter is required to say _which_ entry you want. Otherwise it can be undef.
+Find the value of a meta-datum in the map. If the type is keyed (idenitifed by a `name`), the `$key` parameter is required to say _which_ entry you want. Otherwise you will just get the first value.
-WARNING SMELL If key is undef but the type is keyed you get the FIRST entry If you want all the keys of a given type use the 'find' method.
+If you want all the keys of a given type use the 'find' method.
The result is a reference to the hash for the item.
-## <a name="ObjectMethod <strong>find</strong> ($type) - @v"></a> [[ObjectMethod]] **find** `($type) -> @values`
-
-Get all meta data for a specific type Returns the array stored for the type. This will be zero length if there are no entries.
+For example,
-## <a name="StaticMethod <strong>index_ByKey*"></a><a name="StaticMethod *index_ByKey</strong> "></a> [[StaticMethod]] **indexByKey** ``
+ my $ma = $meta->get( 'FIELD', 'MinAge' );
+ my $topicinfo = $meta->get( 'TOPICINFO' ); # get the TOPICINFO hash
-See tests/unit/MetaTests.pm for an example
+## <a name="ObjectMethod <strong>find</strong> ($type) - @v"></a> [[ObjectMethod]] **find** `($type) -> @values`
-The result is a hash the same as the array provided by find but keyed by the keyName. NB. results are indeterminate if the key you choose is not unique in the find.
+Get all meta data for a specific type. Returns the array stored for the type. This will be zero length if there are no entries.
-Flattens a keyed hash structure, taking only the values. Returns a hash.
+For example,
-See tests/unit/MetaTests.pm for an example
+ my $attachments = $meta->find( 'FILEATTACHMENT' );
## <a name="ObjectMethod <strong>remove</strong> ($type,$ke"></a> [[ObjectMethod]] **remove** `($type,$key)`
If $type is undef, will copy ALL TYPES.
-If $nameFilter is defined (an RE), it will copy only data where \{name\} matches $nameFilter.
+If $nameFilter is defined (a perl refular expression), it will copy only data where `{name}` matches $nameFilter.
-SMELL: This is a shallow copy
+Does **not** copy web, topic or text.
## <a name="ObjectMethod <strong>count</strong> ($type) - $"></a> [[ObjectMethod]] **count** `($type) -> $integer`
-Return the number of entries of the given type that are in this meta set
+Return the number of entries of the given type
## <a name="ObjectMethod <strong>get_RevisionInfo*"></a><a name="ObjectMethod *get_RevisionInfo</strong> "></a> [[ObjectMethod]] **getRevisionInfo** `($fromrev) -> ($date,$author,$rev,$comment)`
## <a name="ObjectMethod <strong>stringify</strong> ($types"></a> [[ObjectMethod]] **stringify** `($types) -> $string`
-Return a string version of the meta object. Uses \\n to separate lines. If $types is specified, return only types specified by that RE.
+Return a string version of the meta object. Uses \\n to separate lines. If `$types` is specified, return only types that match it. Types should be a perl regular expression.
## <a name="ObjectMethod <strong>for_EachSelectedVa"></a> [[ObjectMethod]] \*forEachSelectedValue `($types,$keys,\&fn,\%options)`
## <a name="ObjectMethod <strong>get_FormName</strong> () -"></a> [[ObjectMethod]] **getFormName** `() -> $formname`
Returns the name of the FORM, or '' if none.
+
+## <a name="ObjectMethod <strong>render_FormForDisp"></a> [[ObjectMethod]] \*renderFormForDisplay `() -> $html`
+
+Render the form contained in the meta for display.
+
+## <a name="ObjectMethod <strong>render_FormFieldFo"></a> [[ObjectMethod]] \*renderFormFieldForDisplay `($name,$format,$attrs) -> $text`
+
+Render a single formfield, using the $format. See TWiki::Form::FormField::renderForDisplay for a description of how the value is rendered.
+
+## <a name="ObjectMethod <strong>get_EmbeddedStoreF"></a> [[ObjectMethod]] \*getEmbeddedStoreForm `() -> $text`
+
+Generate the embedded store form of the topic. The embedded store form has meta-data values embedded using %META: lines. The text stored in the meta is taken as the topic text.
+
+## <a name="ObjectMethod <strong>get_MetaFor</strong> () -"></a><a name="ObjectMethod <strong>get_MetaFor</strong> () - "></a> [[ObjectMethod]] **getMetaFor** `() -> $meta`
+
+This method will load (or otherwise fetch) the meta-data for a named web/topic. The request might be satisfied by a read from the store, or it might be satisfied from a cache. The caller doesn't care.
+
+This is an object method rather than a static method because it depends on the implementation of Meta - it might be this base class, or it might be a caching subclass, for example.
<div>
<ul>
<li><a href="#Package =TWiki::Net="> Package TWiki::Net</a><ul>
- <li><a href="#ObjectMethod <strong>getUrl</strong> ($protocol"> ObjectMethod getUrl <tt>($protocol,$host,$port,$url,$user,$pass) -> $text</tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a><ul>
+ <li><a href="#get_ExternalResource( $url ) ->"> getExternalResource( $url ) -> $response</a></li>
+ </ul>
+ </li>
<li><a href="#set_MailHandler( \fn )"> setMailHandler( \&fn )</a></li>
<li><a href="#ObjectMethod <strong>sendEmail</strong> ($text,"> ObjectMethod sendEmail <tt>($text,$retries) -> $error</tt></a></li>
</ul>
</ul>
</div>
-## <a name="ObjectMethod <strong>getUrl</strong> ($protocol"></a> [[ObjectMethod]] **getUrl** `($protocol,$host,$port,$url,$user,$pass) -> $text`
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
-Get the text at the other end of a URL
+Break circular references.
+
+### <a name="get_ExternalResource( $url ) - $"></a> getExternalResource( $url ) -> $response
+
+Get whatever is at the other end of a URL (using an HTTP GET request). Will only work for encrypted protocols such as `https` if the `LWP` CPAN module is installed.
+
+Note that the `$url` may have an optional user and password, as specified by the relevant RFC. Any proxy set in `configure` is honoured.
+
+The `$response` is an object that is known to implement the following subset of the methods of `LWP::Response`. It may in fact be an `LWP::Response` object, but it may also not be if `LWP` is not available, so callers may only assume the following subset of methods is available:
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <td><code>code()</code></td>
+ </tr>
+ <tr>
+ <td><code>message()</code></td>
+ </tr>
+ <tr>
+ <td><code>header($field)</code></td>
+ </tr>
+ <tr>
+ <td><code>content()</code></td>
+ </tr>
+ <tr>
+ <td><code>is_error()</code></td>
+ </tr>
+ <tr>
+ <td><code>is_redirect()</code></td>
+ </tr>
+</table>
+
+Note that if LWP is **not** available, this function:
+
+1. can only really be trusted for HTTP/1.0 urls. If HTTP/1.1 or another protocol is required, you are **strongly** recommended to `require LWP`.
+2. Will not parse multipart content
+
+In the event of the server returning an error, then `is_error()` will return true, `code()` will return a valid HTTP status code as specified in RFC 2616 and RFC 2518, and `message()` will return the message that was received from the server. In the event of a client-side error (e.g. an unparseable URL) then `is_error()` will return true and `message()` will return an explanatory message. `code()` will return 400 (BAD REQUEST).
+
+Note: Callers can easily check the availability of other HTTP::Response methods as follows:
+
+ my $response = TWiki::Func::getExternalResource($url);
+ if (!$response->is_error() && $response->isa('HTTP::Response')) {
+ ... other methods of HTTP::Response may be called
+ } else {
+ ... only the methods listed above may be called
+ }
## <a name="set_MailHandler( \fn )"></a> setMailHandler( \\&fn )
--- /dev/null
+# <a name="Package <code>TWiki::Net::HTTPRespons"></a> Package =TWiki::Net::HTTPResponse
+
+Fakeup of HTTP::Response for use when LWP is not available. Only implements a small subset of the HTTP::Response methods:
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <td><code>code()</code></td>
+ </tr>
+ <tr>
+ <td><code>message()</code></td>
+ </tr>
+ <tr>
+ <td><code>header($field)</code></td>
+ </tr>
+ <tr>
+ <td><code>content()</code></td>
+ </tr>
+ <tr>
+ <td><code>is_error()</code></td>
+ </tr>
+ <tr>
+ <td><code>is_redirect()</code></td>
+ </tr>
+</table>
+
+See the documentation of HTTP::Response for information about the methods.
+
+<div>
+ <ul>
+ <li><a href="#Package =TWiki::Net::HTTPRespons"> Package TWiki::Net::HTTPResponse</a></li>
+ </ul>
+</div>
# <a name="Package <code>TWiki::_OopsException="></a> Package =TWiki::OopsException
-**extends** `Error`
+Exception used to raise a request to redirect to an Oops URL.
-Exception used to raise a request to redirect to an Oops URL. An [[OopsException]] thrown anywhere in the code will redirect the browser to a url based on the `oops` script. `oops` requires a `template` parameter, that is the name of a template file from the `templates` directory. This file will be expanded and the parameter values passed to the exception instantiated. The result will be shown in the browser.
+An [[OopsException]] thrown anywhere in the code will redirect the browser to a url based on the `oops` script. `oops` requires the name of an oops template file from the `templates` directory. This file will be expanded and the parameter values passed to the exception instantiated. The result will be shown in the browser.
-<div>
- <ul>
- <li><a href="#Package =TWiki::_OopsException="> Package TWiki::OopsException</a><ul>
- <li><a href="#ClassMethod <strong>new</strong> ($template,..."> ClassMethod new <tt>($template,...)</tt></a></li>
- <li><a href="#ObjectMethod <strong>stringify</strong> ([$sess"> ObjectMethod stringify <tt>([$session]) -> $string</tt></a></li>
- </ul>
- </li>
- </ul>
-</div>
+Plugins may throw TWiki::OopsException. For example:
-## <a name="ClassMethod <strong>new</strong> ($template,..."></a> [[ClassMethod]] **new** `($template,...)`
+ use Error;
-- `template` is the name of an oops template
+ ...
-The remaining parameters are interpreted as key-value pairs. The following keys are used:
+ throw TWiki::OopsException( 'bathplugin',
+ def => 'toestuck',
+ web => $web,
+ topic => $topic,
+ params => [ 'bigtoe', 'hot tap' ] );
-- `web` will be used as the web for the oops
-- `topic` will be used as the topic for the oops
-- `def` - is the (optional) name of a TMPL:DEF within the template
-- `keep` - if set, the exception handler should try it's damndest to retain parameter values from the query.
-- `params` is a reference to an array of parameters. These will be substituted for %PARAM1%, %PARAM2% ... %PARAMn% in the template.
+ %TOC%
-## <a name="ObjectMethod <strong>stringify</strong> ([$sess"></a> [[ObjectMethod]] **stringify** `([$session]) -> $string`
+ ---++ ClassMethod *new* <tt>($template,...)</tt>
+ * =template= is the name of an oops template. e.g. 'bathplugin' refers to =templates/oopsbathplugin.tmpl=
+ The remaining parameters are interpreted as key-value pairs. The following keys are used:
+ * =web= will be used as the web for the oops
+ * =topic= will be used as the topic for the oops
+ * =def= - is the (optional) name of a TMPL:DEF within the template
+ * =keep= - if set, the exception handler should try its damnedest to retain parameter values from the query.
+ * =params= is a reference to an array of parameters. These will be substituted for !%PARAM1%, !%PARAM2% ... !%PARAMn% in the template.
-Generates a string representation for the object. if a session is passed in, and the excpetion specifies a def, then that def is expanded. This is to allow internal expansion of oops exceptions for example when performing bulk operations.
+ For an example of how to use the =def= parameter, see the =oopsattention=
+ template.
+
+ NOTE: parameter values are automatically and unconditionally entity-encoded
+
+ ---++ ObjectMethod *stringify* <tt>([$session]) -> $string</tt>
+
+ Generates a string representation for the object. if a session is passed in,
+ and the exception specifies a def, then that def is expanded. This is to allow
+ internal expansion of oops exceptions for example when performing bulk
+ operations, and also for debugging.
+
+ ---++ ObjectMethod *redirect* <tt>($twiki)</tt>
+
+ Generate a redirect to an 'oops' script for this exception.
+
+ If the 'keep' parameter is set in the
+ exception, it saves parameter values into the query as well. This is needed
+ if the query string might get lost during a passthrough, due to a POST
+ being redirected to a GET.
<ul>
<li><a href="#Package =="> Package ==</a><ul>
<li><a href="#ClassMethod <strong>new</strong> ($session,$nam"> ClassMethod new <tt>($session,$name,$module)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
</ul>
</li>
</ul>
- `$session` - TWiki object
- `$name` - name of the plugin e.g. [[MyPlugin]]
- `$module` - (options) name of the plugin class. Default is TWiki::Plugins::$name
+
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
+
+Break circular references.
+# <a name="TWiki Plugins"></a> TWiki Plugins
+
+_Add functionality to TWiki with readily available Plugins; create Plugins based on APIs_
+
<div>
<ul>
<li><a href="#TWiki Plugins"> TWiki Plugins</a><ul>
<li><a href="#Available Core Functions"> Available Core Functions</a></li>
<li><a href="#Predefined Hooks"> Predefined Hooks</a></li>
<li><a href="#Hints on Writing Fast Plugins"> Hints on Writing Fast Plugins</a></li>
- <li><a href="#Plugin Version Detection"> Plugin Version Detection</a></li>
+ <li><a href="#Version Detection"> Version Detection</a></li>
<li><a href="#Security"> Security</a></li>
</ul>
</li>
<li><a href="#Creating Plugins"> Creating Plugins</a><ul>
<li><a href="#Anatomy of a Plugin"> Anatomy of a Plugin</a></li>
<li><a href="#Creating the Perl Module"> Creating the Perl Module </a></li>
- <li><a href="#Measuring and Improving the Plug"> Measuring and Improving the Plugin Performance</a></li>
<li><a href="#Writing the Documentation Topic"> Writing the Documentation Topic</a></li>
<li><a href="#Packaging for Distribution"> Packaging for Distribution</a></li>
+ <li><a href="#Measuring and Improving the Plug"> Measuring and Improving the Plugin Performance</a></li>
<li><a href="#Publishing for Public Use"> Publishing for Public Use</a></li>
</ul>
</li>
<li><a href="#Web Accessible Data"> Web Accessible Data</a></li>
</ul>
</li>
+ <li><a href="#Integrating with configure"> Integrating with <code>configure</code></a><ul>
+ <li><a href="#Structure of a Config.spec file"> Structure of a <code>Config.spec</code> file</a></li>
+ </ul>
+ </li>
<li><a href="#Maintaining Plugins"> Maintaining Plugins</a><ul>
<li><a href="#Discussions and Feedback on Plug"> Discussions and Feedback on Plugins</a></li>
<li><a href="#Maintaining Compatibility with E"> Maintaining Compatibility with Earlier TWiki Versions</a></li>
</ul>
</div>
-# <a name="TWiki Plugins"></a> TWiki Plugins
-
-_Add functionality to TWiki with readily available Plugins; create Plugins based on APIs_
-
## <a name="Overview"></a> Overview
You can add Plugins to extend TWiki functionality, without altering the core code. A plug-in approach lets you:
### <a name="On-Site Pretesting"></a> On-Site Pretesting
-The recommended approach to testing new Plugins before making them public is to create a second local TWiki installation, and test the Plugin there. You can allow selected users access to the test area. Once you are satisifed that it won't compromise your main installation, you can install it there as well.
+The recommended approach to testing new Plugins before making them public is to create a second local TWiki installation, and test the Plugin there. You can allow selected users access to the test area. Once you are satisfied that it won't compromise your main installation, you can install it there as well.
[[InstalledPlugins]] shows which Plugins are: 1) installed, 2) loading properly, and 3) what TWiki:Codev.PluginHandlers they invoke. Any failures are shown in the Errors section. The <code>[[%FAILEDPLUGINS%|Main/VarFAILEDPLUGINS]]</code> variable can be used to debug failures. You may also want to check your webserver error log and the various TWiki log files.
### <a name="Some Notes on Plugin Performance"></a> Some Notes on Plugin Performance
-The performance of the system depends to some extent on the number of Plugins installed and on the Plugin implementation. Some Plugins impose no measurable performance decrease, some do. For example, a Plugin might use many Perl libraries that need to be initialized with each page view (unless you run mod\_perl). You can only really tell the performance impact by installing the Plugin and by measuring the performance with and without the new Plugin. Use the TWiki:Plugins.PluginBenchmarkAddOn, or test manually with the Apache `ab` utility. Example on Unix:%BR% `time wget -qO /dev/null http://www.dementia.org/twiki/view/TWiki/AbcPlugin`
+The performance of the system depends to some extent on the number of Plugins installed and on the Plugin implementation. Some Plugins impose no measurable performance decrease, some do. For example, a Plugin might use many Perl libraries that need to be initialized with each page view (unless you run mod\_perl). You can only really tell the performance impact by installing the Plugin and by measuring the performance with and without the new Plugin. Use the TWiki:Plugins.PluginBenchmarkAddOn, or test manually with the Apache `ab` utility. Example on Unix:%BR% `time wget -qO /dev/null http://www.dementia.org/twiki/view/%SYSTEMWEB%/AbcPlugin`
%T% If you need to install an "expensive" Plugin, but you only need its functionality only in a subset of your data, you can disable it elsewhere by defining the %DISABLEDPLUGINS% TWiki variable.
-Define `DISABLEDPLUGINS` to be a comma-separated list of names of plugins to disable. Define it in Main.TWikiPreferences 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,
+Define `DISABLEDPLUGINS` to be a comma-separated list of names of plugins to disable. Define it in %USERSWEB%.TWikiPreferences 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
### <a name="Plugin Evaluation Order"></a> Plugin Evaluation Order
-By default, TWiki executes Plugins in alphabetical order on Plugin name. It is possible to change the order, for example to evaluate database variables before the speadsheet CALCs. This can be done with `{PluginsOrder}` in the Plugins section of [configure](http://www.dementia.org/twiki/configure).
+By default, TWiki executes Plugins in alphabetical order on Plugin name. It is possible to change the order, for example to evaluate database variables before the spreadsheet CALCs. This can be done with `{PluginsOrder}` in the Plugins section of [configure](http://www.dementia.org/twiki/configure).
### <a name="Plugin-Specific Settings"></a> Plugin-Specific Settings
Plugin status variables let you list all active Plugins wherever needed.
+This site is running TWiki version **TWiki-4.1.2, Sat, 03 Mar 2007, build 13046**, Plugin API version **1\.11**
+
+<a name="ActivatedPlugins"></a>
+
#### <a name="=%ACTIVATEDPLUGINS%="></a> `%ACTIVATEDPLUGINS%`
On this TWiki site, the enabled Plugins are: [[SpreadSheetPlugin]], [[CommentPlugin]], [[EditTablePlugin]], [[InterwikiPlugin]], [[PreferencesPlugin]], [[SlideShowPlugin]], [[SmiliesPlugin]], [[TablePlugin]], [[TwistyPlugin]].
- [[TablePlugin]] <span>(1.020, 12339)</span>:
- [[TwistyPlugin]] <span>(1.2.0, $Rev: 12154$)</span>:
+<a name="FailedPlugins"></a>
+
#### <a name="=%FAILEDPLUGINS%="></a> `%FAILEDPLUGINS%`
<table border="1">
### <a name="Hints on Writing Fast Plugins"></a> Hints on Writing Fast Plugins
- Delay initialization as late as possible. For example, if your Plugin is a simple syntax processor, you might delay loading extra Perl modules until you actually see the syntax in the text.
-- For example, use an `eval` block like this:%BR% `eval { require IPC::Run }` %BR% `return "<font color=\"red\">SamplePlugin: Can't load required modules ($@)</font>" if $@;`
-- You can use a flag to avoid running the initialization twice
-- The TWiki:Plugins.PluginBenchmarkAddOn comes in handy to measure and fine-tune the performance of your Plugin
+ - For example, use an `eval` block like this:%BR% `eval { require IPC::Run }` %BR% `return "<font color=\"red\">SamplePlugin: Can't load required modules ($@)</font>" if $@;`
+- Keep the main plugin package as small as possible; create other packages that are loaded if and only if they are used. For example, create sub-packages of BathPlugin in `lib/TWiki/Plugins/BathPlugin/`.
+- Avoid using preferences in the plugin topic; set `$NO_PREFS_IN_TOPIC` if you possibly can, as that will stop TWiki from reading the plugin topic for every page. Use [[Config.spec|Main/WebHome#ConfigSpec]] instead.
+- Use registered tag handlers
+- [[Measure the performance|Main/WebHome#MeasurePerformance]] to see the difference
-### <a name="Plugin Version Detection"></a> Plugin Version Detection
+### <a name="Version Detection"></a> Version Detection
-To eliminate the incompatibility problems bound to arise from active open Plugin development, a Plugin versioning system is provided for automatic compatibility checking.
+To eliminate the incompatibility problems that are bound to arise from active open Plugin development, a Plugin versioning system is provided for automatic compatibility checking.
-- All modules require a `$VERSION='0.000'` variable, beginning at `1.000`.
+- All plugin packages require a `$VERSION` variable. This should be an integer, or a subversion version id.
-- The `initPlugin` handler should check all dependencies and return TRUE if the initialization is OK or FALSE if something went wrong.
- - The Plugin initialization code does not register a Plugin that returns FALSE (or that has no `initPlugin` handler).
+- The `initPlugin` handler should check all dependencies and return 1 if the initialization is OK or 0 if something went wrong.
+ - The Plugin initialization code does not register a Plugin that returns 0 (or that has no `initPlugin` handler).
- `$TWiki::Plugins::VERSION` in the `TWiki::Plugins` module contains the TWiki Plugin API version, currently **1\.11**.
- You can also use the <code>[[%PLUGINVERSION{}%|Main/VarPLUGINVERSION]]</code> variable to query the Plugin API version or the version of installed Plugins.
### <a name="Anatomy of a Plugin"></a> Anatomy of a Plugin
-A basic TWiki Plugin consists of two elements:
+A (very) basic TWiki Plugin consists of two files:
-- a Perl module, ex: `MyFirstPlugin.pm`
-- a documentation topic, ex: `MyFirstPlugin.txt`
+- a Perl module, e.g. `MyFirstPlugin.pm`
+- a documentation topic, e.g. `MyFirstPlugin.txt`
-The Perl module can be a block of code that connects with TWiki alone, or it can include other elements, like other Perl modules (including other Plugins), graphics, TWiki templates, external applications (ex: a Java applet), or just about anything else it can call. In particular, files that should be web-accessible (graphics, Java applets ...) are best placed as attachments of the `MyFirstPlugin` topic. Other needed Perl code is best placed in a `lib/TWiki/Plugins/MyFirstPlugin/` directory.
+The Perl module can be a block of code that talks to with TWiki alone, or it can include other elements, like other Perl modules (including other Plugins), graphics, TWiki templates, external applications (ex: a Java applet), or just about anything else it can call. In particular, files that should be web-accessible (graphics, Java applets ...) are best placed as attachments of the `MyFirstPlugin` topic. Other needed Perl code is best placed in a `lib/TWiki/Plugins/MyFirstPlugin/` directory.
The Plugin API handles the details of connecting your Perl module with main TWiki code. When you're familiar with the [[Plugin API|Main/WebHome#PluginAPI]], you're ready to develop Plugins.
+_The TWiki::Plugins.BuildContrib module provides a lot of support for plugins development, including a plugin creator, automatic publishing support, and automatic installation script writer. If you plan on writing more than one plugin, you probably need it_.
+
### <a name="Creating the Perl Module"></a> Creating the Perl Module
Copy file `lib/TWiki/Plugins/EmptyPlugin.pm` to `<name>Plugin.pm`. The `EmptyPlugin.pm` module contains mostly empty functions, so it does nothing, but it's ready to be used. Customize it. Refer to the [[Plugin API|Main/WebHome#PluginAPI]] specs for more information.
use TWiki::Plugins::MyFirstPlugin::Attrs;
$var = MyFirstPlugin::Attrs->new();
-<a name="MeasurePerformance"></a>
-
-### <a name="Measuring and Improving the Plug"></a> Measuring and Improving the Plugin Performance
-
-A high quality Plugin performs well. You can use the TWiki:Plugins.PluginBenchmarkAddOn to measure your TWiki:Plugins.PluginBenchmarks. The data is needed as part of the Documentation Topic.
-
-See also [[Hints on Writing Fast Plugins|Main/WebHome#FastPluginHints]].
-
<a name="CreatePluginTopic"></a>
### <a name="Writing the Documentation Topic"></a> Writing the Documentation Topic
-The Plugin documentation topic contains usage instructions and version details. It serves the Plugin files as [[FileAttachments]] for downloading. (The doc topic is also included _in_ the [[distribution package|Main/WebHome#CreatePluginPackage]].) To create a documentation topic:
+The Plugin documentation topic contains usage instructions and version details. It serves the Plugin files as %SYSTEMWEB%.FileAttachments for downloading. (The doc topic is also included _in_ the [[distribution package|Main/WebHome#CreatePluginPackage]].) To create a documentation topic:
1. **Copy** the Plugin topic template from TWiki.org. To copy the text, go to TWiki:Plugins/PluginPackage and:
- enter the Plugin name in the "How to Create a Plugin" section
- click Create
- select all in the Edit box & copy
- Cancel the edit
- - go back to your site to the TWiki web
+ - go back to your site to the %SYSTEMWEB% web
- In the [[GoBox]] enter your Plugin name, for example `MyFirstPlugin`, press enter and create the new topic
- paste & save new Plugin topic on your site
2. **Customize** your Plugin topic.
>
> **Plugin Settings:** <_Description and settings for custom Plugin %VARIABLES%, and those required by TWiki._>"
>
-> - **Plugins Preferences** <_If user settings are needed, explain... Entering values works exactly like [[TWikiPreferences]] and [[WebPreferences]]: six (6) spaces and then:_>"
+> - **Plugins Preferences** <_If user settings are needed, explain... Entering values works exactly like %SYSTEMWEB%.TWikiPreferences and [[WebPreferences]]: six (6) spaces and then:_>"
> - **Set <_EXAMPLE = value added_>**
>
> **Plugin Installation Instructions:** <_Step-by-step set-up guide, user help, whatever it takes to install and run, goes here._>"
- `data/TWiki/MyFirstPlugin.txt`
- `pub/TWiki/MyFirstPlugin/uparrow.gif`
+<a name="MeasurePerformance"></a>
+
+### <a name="Measuring and Improving the Plug"></a> Measuring and Improving the Plugin Performance
+
+A high quality Plugin performs well. You can use the TWiki:Plugins.PluginBenchmarkAddOn to measure your TWiki:Plugins.PluginBenchmarks. The data is needed as part of the Documentation Topic.
+
+See also [[Hints on Writing Fast Plugins|Main/WebHome#FastPluginHints]].
+
<a name="PublishPlugin"></a>
### <a name="Publishing for Public Use"></a> Publishing for Public Use
### <a name="Plugin Internal Data"></a> Plugin Internal Data
-You can create a Plugin "work area" using the `TWiki::Func::getWorkArea()` function, which gives you a persistant 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, `TWiki::Func::storeFile()` and `TWiki::Func::readFile()` are provided to persistently store and retrieve simple data in this area.
+You can create a Plugin "work area" using the `TWiki::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, `TWiki::Func::storeFile()` and `TWiki::Func::readFile()` are provided to persistently store and retrieve simple data in this area.
### <a name="Web Accessible Data"></a> Web Accessible Data
Recommendation for file name:
-- Prefix the filename with an underscore (the leading underscore avoids a nameclash with files attached to the same topic)
+- Prefix the filename with an underscore (the leading underscore avoids a name clash with files attached to the same topic)
- Identify where the attachment originated from, typically by including the Plugin name in the file name
- Use only alphanumeric characters, underscores, dashes and periods to avoid platform dependency issues and URL issues
- Example: `_FooBarPlugin_img123.gif`
- Use only alphanumeric characters, underscores, dashes and periods to avoid platform dependency issues and URL issues
- Example: `_Main_roundedge-ul.gif`
+<a name="ConfigSpec"></a>
+
+## <a name="Integrating with configure"></a> Integrating with `configure`
+
+Some TWiki extensions have setup requirements that are best integrated into `configure` rather than trying to use TWiki preferences variables. These extensions use `Config.spec` files to publish their configuration requirements.
+
+`Config.spec` files are read during TWiki 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/TWiki/Plugins/BathPlugin/Config.spec`.
+
+### <a name="Structure of a Config.spec file"></a> Structure of a `Config.spec` file
+
+The `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
+ $TWiki::cfg{BathPlugin}{PlugType} = 'Plastic';
+
+ # **NUMBER**
+ # Enter the chain length in cm
+ $TWiki::cfg{BathPlugin}{ChainLength} = '30';
+
+ # **BOOLEAN EXPERT**
+ # Turn this option off to disable the water temperature alarm
+ $TWiki::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 `$TWiki::cfg{BathPlugin}{PlugType}`, `$TWiki::cfg{BathPlugin}{ChainLength}`, and `$TWiki::cfg{BathPlugin}{TempSensorEnabled}` for use in your plugin. For example,
+
+ if( $TWiki::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:
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <td> BOOLEAN </td>
+ <td> A true/false value, represented as a checkbox </td>
+ </tr>
+ <tr>
+ <td> COMMAND <em>length</em></td>
+ <td> A shell command </td>
+ </tr>
+ <tr>
+ <td> LANGUAGE </td>
+ <td> A language (selected from <code>{LocalesDir}</code></td>
+ </tr>
+ <tr>
+ <td> NUMBER </td>
+ <td> A number </td>
+ </tr>
+ <tr>
+ <td> OCTAL </td>
+ <td> An octal number </td>
+ </tr>
+ <tr>
+ <td> PASSWORD <em>length</em></td>
+ <td> A password (input is hidden) </td>
+ </tr>
+ <tr>
+ <td> PATH <em>length</em></td>
+ <td> A file path </td>
+ </tr>
+ <tr>
+ <td> PERL </td>
+ <td> A perl structure, consisting of arrays and hashes </td>
+ </tr>
+ <tr>
+ <td> REGEX <em>length</em></td>
+ <td> A perl regular expression </td>
+ </tr>
+ <tr>
+ <td> SELECT <em>choices</em></td>
+ <td> Pick one of a range of choices </td>
+ </tr>
+ <tr>
+ <td> SELECTCLASS <em>root</em></td>
+ <td> Select a perl package (class) </td>
+ </tr>
+ <tr>
+ <td> STRING <em>length</em></td>
+ <td> A string </td>
+ </tr>
+ <tr>
+ <td> URL <em>length</em></td>
+ <td> A url </td>
+ </tr>
+ <tr>
+ <td> URLPATH <em>length</em></td>
+ <td> A relative URL path </td>
+ </tr>
+</table>
+
+All types can be followed by a comma-separated list of _attributes_.
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <td> EXPERT </td>
+ <td> means this an expert option </td>
+ </tr>
+ <tr>
+ <td> M </td>
+ <td> means the setting is mandatory (may not be empty) </td>
+ </tr>
+ <tr>
+ <td> H </td>
+ <td> means the option is not visible in <code>configure</code></td>
+ </tr>
+</table>
+
+See `lib/TWiki.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.
+
<a name="MaintainPlugins"></a>
## <a name="Maintaining Plugins"></a> Maintaining Plugins
The Plugin interface ([[TWikiFuncDotPm]] functions and handlers) evolve over time. TWiki 4.0 introduced new API functions to address the needs of Plugin authors. It also deprecated some functions. Some Plugins written for earlier TWiki releases using unofficial TWiki internal functions no longer work on the TWiki 4.0 codebase. All this means that some Plugins need to be updated to work on the TWiki 4.0 codebase.
-Organizations typically do not upgrade to the latest TWiki for many months. However, many administrators still would like to install the latest versions of a Plugin on their older TWiki installation. This need is fullfilled if Plugins are maintained in a compatible manner.
+Organizations typically do not upgrade to the latest TWiki for many months. However, many administrators still would like to install the latest versions of a Plugin on their older TWiki installation. This need is fulfilled if Plugins are maintained in a compatible manner.
**_%T% Tip:_** Plugins can be written to be compatible with older and newer TWiki releases. This can be done also for Plugins using unofficial TWiki internal functions of an earlier release that no longer work on the latest TWiki codebase. TWiki:TWiki.TWikiPluginsSupplement#MaintainPlugins has more.
If the currently-running TWiki version is 1.1 _or later_, then the _handler will not be called_ and _the warning will not be issued_. TWiki with versions of `TWiki::Plugins` before 1.1 will still call the handler as required.
**_Related Topics:_** [[DeveloperDocumentationCategory]], [[AdminDocumentationCategory]], TWiki:TWiki.TWikiPluginsSupplement
-
--- **_Contributors:_** TWiki:Main.PeterThoeny, TWiki:Main.AndreaSterbini, TWiki:MainMikeMannix, TWiki:CrawfordCurrie
<li><a href="#PUBLIC constant $VERSION"> PUBLIC constant $VERSION</a></li>
<li><a href="#PUBLIC $SESSION"> PUBLIC $SESSION</a></li>
<li><a href="#ClassMethod <strong>new</strong> ($session)"> ClassMethod new <tt>($session)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
<li><a href="#ObjectMethod <strong>load</strong> ($allDisable"> ObjectMethod load <tt>($allDisabled) -> $loginName</tt></a></li>
<li><a href="#ObjectMethod <strong>settings</strong> ()"> ObjectMethod settings <tt>()</tt></a></li>
<li><a href="#ObjectMethod <strong>enable</strong> ()"> ObjectMethod enable <tt>()</tt></a></li>
<li><a href="#ObjectMethod *after_AttachmentSa"> ObjectMethod afterAttachmentSaveHandler <tt>($attachmentAttrHash,$topic,$web,$error)</tt></a></li>
<li><a href="#ObjectMethod *write_HeaderHandle"> ObjectMethod writeHeaderHandler <tt>() -> $headers</tt></a></li>
<li><a href="#ObjectMethod *modify_HeaderHandl"> ObjectMethod modifyHeaderHandler <tt>(\@headers,$query)</tt></a></li>
+ <li><a href="#ObjectMethod *complete_PageHandl"> ObjectMethod completePageHandler <tt>($text,$pageType,$contentType)</tt></a></li>
<li><a href="#ObjectMethod *redirect_CgiQueryH"> ObjectMethod redirectCgiQueryHandler <tt>() -> $result</tt></a></li>
<li><a href="#ObjectMethod *render_FormFieldFo"> ObjectMethod renderFormFieldForEditHandler <tt>($name,$type,$size,$value,$attributes,$possibleValues) -> $html</tt></a></li>
<li><a href="#ObjectMethod *render_WikiWordHan"> ObjectMethod renderWikiWordHandler <tt>() -> $result</tt></a></li>
Construct new singleton plugins collection object. The object is a container for a list of plugins and the handlers registered by the plugins. The plugins and the handlers are carefully ordered.
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
+
+Break circular references.
+
## <a name="ObjectMethod <strong>load</strong> ($allDisable"></a> [[ObjectMethod]] **load** `($allDisabled) -> $loginName`
Find all active plugins, and invoke the early initialisation. Has to be done _after_ prefs are read.
## <a name="ObjectMethod <strong>addListener</strong> ($com"></a> [[ObjectMethod]] **addListener** `($command,$handler)`
-- =$command\* - name of the event
+- `$command` - name of the event
- `$handler` - the handler object.
Add a listener to the end of the list of registered listeners for this event. The listener must implement `invoke($command,...)`, which will be triggered when the event is to be processed.
<pre class='slobadob'>
XYZ
</pre>
- the map will contain:
- <pre>
+
+the map will contain:
+
$removed->{'pre1'}{text}: XYZ
$removed->{'pre1'}{params}: class="slobadob"
- </pre>
Iterating over blocks for a single tag is easy. For example, to prepend a line number to every line of a pre block you might use this code:
-foreach my $placeholder ( keys %$map ) \{ if( $placeholder =~ /^pre/i ) \{ my $n = 1; $map->\{$placeholder\}\{text\} =~ s/^/$n++/gem; \} \}
+ foreach my $placeholder ( keys %$map ) {
+ if( $placeholder =~ /^pre/i ) {
+ my $n = 1;
+ $map->{$placeholder}{text} =~ s/^/$n++/gem;
+ }
+ }
## <a name="ObjectMethod <strong>post_RenderingHand"></a> [[ObjectMethod]] \*postRenderingHandler `(\$text)`
This code provides Plugins with the opportunity to alter an uploaded attachment between the upload and save-to-store processes. It is invoked as per other Plugins.
- `$attrHashRef` - Hash reference of attachment attributes (keys are indicated below)
-- `$topic` - | Topic name
-- `$web` - | Web name
+- `$topic` - Topic name
+- `$web` - Web name
Keys in $attrHashRef:
deal with an uploaded attachment between the upload and save-to-store processes. It is invoked as per other plugins.
- `$attrHashRef` - Hash reference of attachment attributes (keys are indicated below)
-- `$topic` - | Topic name
-- `$web` - | Web name
-- `$error` - | Error string of save action, empty if OK
+- `$topic` - Topic name
+- `$web` - Web name
+- `$error` - Error string of save action, empty if OK
Keys in $attrHashRef:
## <a name="ObjectMethod <strong>write_HeaderHandle"></a> [[ObjectMethod]] \*writeHeaderHandler `() -> $headers`
-Called by TWiki::writePageHeader. **DEPRECATED** do not use!
-
**DEPRECATED** Use modifyHeaderHandler instead. it is a lot more flexible, and allows you to modify existing headers as well as add new ones. It also works correctly when multiple plugins want to modify headers.
## <a name="ObjectMethod <strong>modify_HeaderHandl"></a> [[ObjectMethod]] \*modifyHeaderHandler `(\@headers,$query)`
+## <a name="ObjectMethod <strong>complete_PageHandl"></a> [[ObjectMethod]] \*completePageHandler `($text,$pageType,$contentType)`
+
## <a name="ObjectMethod <strong>redirect_CgiQueryH"></a> [[ObjectMethod]] \*redirectCgiQueryHandler `() -> $result`
Called by TWiki::redirect
-<form action="http://www.dementia.org/twiki/viewauth/Main/WebHome" enctype="multipart/form-data" method="post" name="editpreferences">
- <p>
- </p>
- <h1><a name="%WIKITOOLNAME% Site-Level Prefer"></a><a name=" %WIKITOOLNAME% Site-Level Prefe"></a> %WIKITOOLNAME% Site-Level Preferences </h1>
- <p> This topic defines <strong><em>site-level</em></strong> settings that apply to all users and webs on this [[Main/TWikiSite]]. </p>
- <p><strong><em>%X% Note:</em></strong> This topic should be regarded as read-only, so that upgrades can safely overwrite it without risk to your customizations. </p>
- <p> Preference settings local to your site should be set in [[Main/TWikiPreferences]] (this topic is pointed to by {LocalSitePreferences}, which is set by the admin in the <a href="http://www.dementia.org/twiki/configure" target="_top">configure</a> interface). Settings in [[Main/TWikiPreferences]] will override settings in this topic, and should be used for defining custom settings and variables. </p>
- <p>[[Main/TWikiVariables#PreferencesVariables]] on how to set Preferences Variables. </p>
- <p>
- </p><input name="prefsaction" type="submit" value="Edit" /> <em>(Click for form-based editing of existing preferences.)</em><div>
- <ul>
- <li><a href="#Default Web Preferences"> Default Web Preferences</a></li>
- <li><a href="#Default User Settings"> Default User Settings</a></li>
- <li><a href="#TWiki Platform Settings"> TWiki Platform Settings</a><ul>
- <li><a href="#Search Settings"> Search Settings</a></li>
- <li><a href="#E-mail Settings"> E-mail Settings</a></li>
- <li><a href="#HTTP-EQUIV Settings"> HTTP-EQUIV Settings</a></li>
- </ul>
- </li>
- <li><a href="#Skin Settings"> Skin Settings</a><ul>
- <li><a href="#PatternSkin"> PatternSkin</a></li>
- <li><a href="#Skin icons"> Skin icons</a></li>
- <li><a href="#Legacy support"> Legacy support</a></li>
- </ul>
- </li>
- <li><a href="#Plugins Settings"> Plugins Settings</a></li>
- <li><a href="#Rendering Shortcuts Settings"> Rendering Shortcuts Settings</a></li>
- <li><a href="#Miscellaneous Settings"> Miscellaneous Settings</a></li>
- <li><a href="#Access Control Settings"> Access Control Settings</a></li>
- <li><a href="#Creating New Preference Variable"> Creating New Preference Variables</a></li>
- <li><a href="#Related Topics"> Related Topics</a></li>
- </ul>
- </div>
- <p><a name="DefaultWebPreferences"></a></p>
- <h2><a name="Default Web Preferences"></a> Default Web Preferences </h2>
- <p> %X% <strong>NOTE:</strong> These are just defaults; don't change them here. Instead, add them to the WebPreferences topic in each web </p>
- <p>
- </p>
- <ul>
- <li> List of selected topics in a web (used in menus) <ul>
- <li> Set WEBTOPICLIST = [[Main/WebChanges]] | [[Main/WebIndex]] | [[Main/WebSearch]] | Go <input name="topic" size="16" type="text" /></li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <ul>
- <li> Web-specific background color: (is overwritten by web preferences) <ul>
- <li> Set WEBBGCOLOR = #FFD8AA </li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <ul>
- <li><a href="http://en.wikipedia.org/wiki/Favicon" target="_top">favicon</a>: Attach a <code>favicon.ico</code> to a web's [[Main/WebPreferences]] or add a <code>FAVICON</code> setting to [[Main/WebPreferences]]<ul>
- <li> Set FAVICON = <a href="http://www.dementia.org/twiki//view/Main/WebPreferences/favicon.ico" target="_top">http://www.dementia.org/twiki//view/Main/WebPreferences/favicon.ico</a></li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <ul>
- <li> Image, URL and alternate tooltip text of web's logo. <ul>
- <li> Set WEBLOGOIMG = %WIKILOGOIMG% </li>
- <li> Set WEBLOGOURL = %WIKILOGOURL% </li>
- <li> Set WEBLOGOALT = %WIKILOGOALT% </li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <ul>
- <li> List this web in the [[TWiki/SiteMap]]: <ul>
- <li> If yes, set SITEMAPLIST to <code>on</code>, do not set NOSEARCHALL, and add the "what" and "use to..." description for the site map. Make sure to list only links that include the name of the web, e.g. %WEB%.Topic links. </li>
- <li> Set SITEMAPLIST = on </li>
- <li> Set SITEMAPWHAT = Describe what this web does. </li>
- <li> Set SITEMAPUSETO = ...to do something. </li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <ul>
- <li> Copyright notice: <ul>
- <li> Set WEBCOPYRIGHT = <span> <a href="http://twiki.org/"><img alt="This site is powered by the TWiki collaboration platform" border="0" height="15" src="http://www.dementia.org/twiki//view/TWiki/TWikiLogos/T-logo-80x15.gif" title="This site is powered by the TWiki collaboration platform" width="80" /></a></span>Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors. <br /> Ideas, requests, problems regarding %WIKITOOLNAME%? <a href="mailto:?subject=%WIKITOOLNAME% Feedback on Main.WebHome">Send feedback</a></li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <ul>
- <li> Simplified Copyright notice for the [[Main/WebRss]] feed (don't use any special characters, html tags, entities, wiki markup or [[Main/WikiWords]]) <ul>
- <li> Set WEBRSSCOPYRIGHT = Copyright 2010 by contributing authors </li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <ul>
- <li> Exclude web from a <code>web="all"</code> search: (Set to <code>on</code> for hidden webs; is overwritten by web preferences) <strong><em>Note</em></strong> it is much better to use [[Main/TWikiAccessControls]] in individual webs to control who can and can't view the contents of a web. NOSEARCHALL is retained for compatibility, but you should avoid using it. <ul>
- <li> Set NOSEARCHALL = </li>
- </ul>
- </li>
- <li> Prevent automatic linking of [[TWiki/WikiWords]] and acronyms (if set to <code>on</code>); link WikiWords (if empty); can be overwritten by web preferences: <ul>
- <li> Set NOAUTOLINK = </li>
- <li><strong><em>Note:</em></strong> Use the <code>[[...][...]]</code> syntax to link topics in case you disabled WikiWord linking. The <code><noautolink> ... </noautolink></code> syntax can be used to prevents links within a block of text. </li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <ul>
- <li> Warn if <code>%INCLUDE{}%</code> of topic fails: Fail silently if empty or <code>off</code>. Output warning message (defined in templates/oopsalerts.tmpl) if set to <code>on</code>. Otherwise output specific text (use <code>$topic</code> for topic). You can override this in web preferences, or by using a <code>warn="..."</code> parameter with <code>%INCLUDE{}%</code> : <ul>
- <li> Set INCLUDEWARNING = on </li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <h2><a name="Default User Settings"></a> Default User Settings </h2>
- <p> %X% <strong>NOTE:</strong> They are typically redefined in topics of individual [[Main/TWikiUsers]]</p>
- <p>
- </p>
- <ul>
- <li> Show tool-tip topic info on mouse-over of [[Main/WikiWord]] links. Setting can be on, off, or customized. An empty setting or off setting disables the tool-tips (for better performance). The setting can contain $summary to show the topic summary, $date for the last change date, $rev for the revision, $username for the login name of the last editor, $wikiname for the WikiName, $wikiusername for Main.WikiName, $topic for the topic name, and $web for the web name <ul>
- <li> Set LINKTOOLTIPINFO = off </li>
- <li> #Set LINKTOOLTIPINFO = $username - $date - $rev: $summary </li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <ul>
- <li> Some skins have two editors available; the default editor, and a second editor which is usually a WYSIWYG editor (the second editor is used by hitting the WYSIWYG link in <code>pattern</code> or <code>classic</code> skins). If COMPOSER is not set, the second editor will work the same as the <em>default</em> editor. If the WysiwygPlugin is installed and it is set to 'kupu' (the default), then the <strong>Kupu</strong> WYSIWYG editor will be enabled. You can change the setting to use any editor that is enabled by setting the <code>cover</code> parameter on the edit URL. <ul>
- <li> Set COMPOSER = kupu </li>
- <li> Enable content checks before editing </li>
- <li> Set WYSWIYGPLUGIN_WYSIWYGSKIN = kupu </li>
- <li> Disable WYSIWYG on pages that contain complex TML. On pages that have complex TML, WYSIWYG will fall back to the default text editor. </li>
- <li> Set WYSIWYG_EXCLUDE = calls </li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <ul>
- <li> Horizontal size of text edit box: (can be overwritten by user preferences) <ul>
- <li> Set EDITBOXWIDTH = 70 </li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <ul>
- <li> Vertical size of text edit box: (can be overwritten by user preferences) <ul>
- <li> Set EDITBOXHEIGHT = 22 </li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <ul>
- <li> Style of text edit box. Set to <code>width: 99%</code> for full window width (default; this will overwrite the EDITBOXWIDTH setting), or <code>width: auto</code> to disable. This setting works for IE and some other recent browsers. (can be overwritten by user preferences) <ul>
- <li> Set EDITBOXSTYLE = width: 99% </li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <ul>
- <li> Default state of the <strong><em>Force New Revision</em></strong> ([[Main/ForceNewRevision]]) check box in preview. Check box is initially checked if <code>Set FORCENEWREVISIONCHECKBOX = checked="checked"</code>, or unchecked if empty: (can be overwritten by user preferences) <ul>
- <li> Set FORCENEWREVISIONCHECKBOX = </li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <ul>
- <li> Default state of the <strong><em>Minor Changes, Don't Notify</em></strong> ([[Main/DontNotify]]) check box in preview. Check box is initially checked if <code>Set DONTNOTIFYCHECKBOX = checked="checked"</code>, or unchecked if empty: (can be overwritten by user preferences) <ul>
- <li> Set DONTNOTIFYCHECKBOX = </li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <ul>
- <li> Default state of the <strong><em>link</em></strong> check box in the attach file page. Checkbox is initially checked if <code>Set ATTACHLINKBOX = checked="checked"</code>, or unchecked if empty (<code>Set ATTACHLINKBOX =</code>). If checked, a link is created to the attached file at the end of the topic: (can be overwritten by user preferences) <ul>
- <li> Set ATTACHLINKBOX = </li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <ul>
- <li> Format of file link when the <strong><em>link</em></strong> check box is checked: (can be overwritten by user preferences) <ul>
- <li> %H% <strong>NOTE:</strong> Keyword <code><b>$name</b></code> gets expanded to filename; <code><b>$comment</b></code> to comment; <code><b>\t</b></code> to tab (3 spaces for bullets). </li>
- </ul>
- </li>
- </ul><pre>
- * Set ATTACHEDFILELINKFORMAT = \n * [[%ATTACHURL%/$name][$name]]: $comment
-</pre><p>
- </p>
- <ul>
- <li> Format of images when the <strong><em>link</em></strong> check box is checked: (can be overwritten by user preferences) <ul>
- <li> %H% <strong>NOTE:</strong> Keyword <code><b>$name</b></code> gets expanded to filename; <code><b>$comment</b></code> to comment; <code><b>$size</b></code> to <code><b>width="..." height="..."</b></code> attribute of <code><b>img</b></code> tag; <code><b>\t</b></code> to tab and <code><b>\n</b></code> to linefeed (3 spaces for bullets). </li>
- </ul>
- </li>
- </ul><pre>
- * Set ATTACHEDIMAGEFORMAT = \n * $comment: <br />\n <img src="%ATTACHURLPATH%/$name" alt="$name" $size />
-</pre><p>
- </p>
- <h2><a name="TWiki Platform Settings"></a> TWiki Platform Settings </h2>
- <p>
- </p>
- <ul>
- <li> TWiki site name: <ul>
- <li> Set WIKITOOLNAME = TWiki </li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <ul>
- <li> Image, URL and alternate tooltip text of the logo <strong>for this installation</strong>: you should change these settings for your site, or they can be overwridden in WebPreferences for individual webs by defining these variables there. <ul>
- <li> Set WIKILOGOIMG = <img alt="T-logo-140x40-t.gif" src="http://www.dementia.org/twiki//view/TWiki/TWikiLogos/T-logo-140x40-t.gif" /></li>
- <li> Set WIKILOGOURL = <a href="http://TWiki.org/" target="_top">http://TWiki.org/</a></li>
- <li> Set WIKILOGOALT = Powered by %WIKITOOLNAME% </li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <ul>
- <li> Home page of this site <ul>
- <li> Set WIKIHOMEURL = <a href="http://www.dementia.org/twiki/view" target="_top">http://www.dementia.org/twiki/view</a></li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <ul>
- <li> List of %WIKITOOLNAME% webs - on the first line of the upper toolbar (to add a new web, see [[Main/ManagingWebs]] and [[TWiki/SiteMap]]): <ul>
- <li> Set WIKIWEBLIST = [[Main/WebHome]] | [[TWiki/WebHome]] | [[Sandbox/WebHome]]</li>
- <li> %T% <strong>NOTE:</strong> To automatically list all non-hidden webs in alphabetical order, use the <code>%WEBLIST{}%</code> variable instead: <br />
- </li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <p>
- </p>
- <ul>
- <li> Maximum size of [[TWiki/FileAttachments]] in KB, 0 for no limit: <ul>
- <li> Set ATTACHFILESIZELIMIT = 10000 </li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <ul>
- <li> Broadcast message for skins supporting a %BROADCASTMESSAGE% at the top of the page: (IMPORTANT: Set to empty message if not used; #Comment out unused messages) <ul>
- <li> Set BROADCASTMESSAGE = </li>
- <li> #Set BROADCASTMESSAGE = <table border="0" cellpadding="3" cellspacing="0" width="100%">
- <tr>
- <td bgcolor="yellow"><font color="red"><strong>NOTE:</strong></font> Edit and Attach will be disabled today between 05:00 PM and 06:00 PM PDT (00:00 to 01:00 GMT) for a scheduled %WIKITOOLNAME% maintenance. </td>
- </tr>
- </table>
- </li>
- <li> If you use [[Main/PatternSkin]]: </li>
- <li> #Set BROADCASTMESSAGE = <div><strong>NOTE:</strong> Edit and Attach will be disabled today between 05:00 PM and 06:00 PM PDT (00:00 to 01:00 GMT) for a scheduled %WIKITOOLNAME% maintenance.</div>
- </li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <ul>
- <li> Users or groups allowed to [[TWiki/ManagingWebs]]: (ex: [[Main/TWikiAdminGroup]]) </li>
- <li><strong>This has been disabled for the TWiki-4.0.0 release due to a potential security hole - you must be in the [[Main/TWikiAdminGroup]] to create a web</strong><ul>
- <li> Set ALLOWWEBMANAGE = [[Main/TWikiAdminGroup]]</li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <h3><a name="Search Settings"></a> Search Settings </h3>
- <p>
- </p>
- <ul>
- <li> Default type for search, one of: keyword (for search engine like syntax), regex (for [[Main/RegularExpression]] search), or literal (for verbatim search) <ul>
- <li> Set SEARCHDEFAULTTTYPE = keyword </li>
- </ul>
- </li>
- <li> Default for <code>%SEARCH{}%</code> variable, one of: keyword, regex, or literal <ul>
- <li> Set SEARCHVARDEFAULTTYPE = literal </li>
- </ul>
- </li>
- <li> Stop words, e.g., common words and characters to exclude from a keyword search: <ul>
- <li> Set SEARCHSTOPWORDS = a, all, am, an, and, any, as, at, b, be, by, c, d, e, for, from, g, h, how, i, i'm, i.e., in, is, isn't, it, it's, its, j, k, l, m, n, o, of, on, or, p, q, r, s, t, that, that's, the, this, to, u, v, w, was, wasn't, what, what's, when, where, who, who's, will, with, x, y, z </li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <h3><a name="E-mail Settings"></a> E-mail Settings </h3>
- <p>
- </p>
- <ul>
- <li> 'Mail this topic' mailto: link - can be included in topics, templates or skins <ul>
- <li> Set MAILTHISTOPIC = <a href="mailto:?subject=WebHome&body=%TOPICURL%">%MAILTHISTOPICTEXT%</a></li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
- <ul>
- <li> 'Mail this topic' link text <ul>
- <li> Set MAILTHISTOPICTEXT = Send a link to this page </li>
- </ul>
- </li>
- </ul>
- <p>
- </p>
+# <a name="%WIKITOOLNAME% Site-Level Prefer"></a><a name=" %WIKITOOLNAME% Site-Level Prefe"></a> %WIKITOOLNAME% Site-Level Preferences
+
+This topic defines **_site-level_** settings that apply to all users and webs on this [[TWikiSite]].
+
+**_%X% Note:_** This topic should be regarded as read-only, so that upgrades can safely overwrite it without risk to your customizations.
+
+Preference settings local to your site should be set in [[Main.TWikiPreferences|Main/TWikiPreferences]] (this topic is pointed to by \{LocalSitePreferences\}, which is set by the admin in the [configure](http://www.dementia.org/twiki/configure) interface). Settings in [[Main.TWikiPreferences|Main/TWikiPreferences]] will override settings in this topic, and should be used for defining custom settings and variables.
+
+[[Read more|Main/TWikiVariables#PreferencesVariables]] on how to set Preferences Variables.
+
+<div>
<ul>
- <li> URL for current topic <ul>
- <li> Set TOPICURL = [[%WEB%/WebHome]]</li>
+ <li><a href="#Default Web Preferences"> Default Web Preferences</a></li>
+ <li><a href="#Default User Settings"> Default User Settings</a></li>
+ <li><a href="#TWiki Platform Settings"> TWiki Platform Settings</a><ul>
+ <li><a href="#Search Settings"> Search Settings</a></li>
+ <li><a href="#E-mail Settings"> E-mail Settings</a></li>
+ <li><a href="#HTTP-EQUIV Settings"> HTTP-EQUIV Settings</a></li>
</ul>
</li>
- </ul>
- <p>
- </p>
- <p>
- </p>
- <h3><a name="HTTP-EQUIV Settings"></a> HTTP-EQUIV Settings </h3>
- <p>
- </p>
- <ul>
- <li> %T% <strong>NOTE:</strong> Changing cache behaviour with these settings should not be necessary and may cause cache-related problems (e.g. TWiki:Codev.BackFromPreviewLosesText or TWiki:Codev.RefreshEditPage). These settings do not affect proxy caches. </li>
- <li><strong>NOTE:</strong> The current values of these preferences are not displayed in view mode (values are <code><link></code>-tags). </li>
- </ul>
- <p>
- </p>
- <ul>
- <li><code><b>http-equiv</b></code> meta tags for <code><b>view</b></code>, <code><b>rdiff</b></code>, <code><b>attach</b></code>, <code><b>search*</b></code> scripts: <ul>
- <li> #Set HTTP_EQUIV_ON_VIEW = </li>
- <li> Set HTTP_EQUIV_ON_VIEW = </li>
+ <li><a href="#Skin Settings"> Skin Settings</a><ul>
+ <li><a href="#PatternSkin"> PatternSkin</a></li>
+ <li><a href="#Skin icons"> Skin icons</a></li>
+ <li><a href="#Legacy support"> Legacy support</a></li>
</ul>
</li>
+ <li><a href="#Plugins Settings"> Plugins Settings</a></li>
+ <li><a href="#Rendering Shortcuts Settings"> Rendering Shortcuts Settings</a></li>
+ <li><a href="#Miscellaneous Settings"> Miscellaneous Settings</a></li>
+ <li><a href="#Access Control Settings"> Access Control Settings</a></li>
+ <li><a href="#Creating New Preference Variable"> Creating New Preference Variables</a></li>
+ <li><a href="#Related Topics"> Related Topics</a></li>
</ul>
-</form>
+</div>
+
+<a name="DefaultWebPreferences"></a>
+
+## <a name="Default Web Preferences"></a> Default Web Preferences
+
+%X% **NOTE:** These are just defaults; don't change them here. Instead, add them to the WebPreferences topic in each web
+
+- List of selected topics in a web (used in menus)
+ - Set WEBTOPICLIST = [[Changes|Main/WebChanges]] | [[Index|Main/WebIndex]] | [[Search|Main/WebSearch]] | Go <input name="topic" size="16" type="text" />
+
+- Web-specific background color: (is overwritten by web preferences)
+ - Set WEBBGCOLOR = #FFD8AA
+
+- [favicon](http://en.wikipedia.org/wiki/Favicon): Attach a `favicon.ico` to a web's [[WebPreferences]] or add a `FAVICON` setting to [[WebPreferences]]
+ - Set FAVICON = <http://www.dementia.org/twiki//view/Main/WebPreferences/favicon.ico>
+
+- Image, URL and alternate tooltip text of web's logo.
+ - Set WEBLOGOIMG = %WIKILOGOIMG%
+ - Set WEBLOGOURL = %WIKILOGOURL%
+ - Set WEBLOGOALT = %WIKILOGOALT%
+
+- List this web in the %SYSTEMWEB%.SiteMap:
+ - If yes, set SITEMAPLIST to `on`, do not set NOSEARCHALL, and add the "what" and "use to..." description for the site map. Make sure to list only links that include the name of the web, e.g. %WEB%.Topic links.
+ - Set SITEMAPLIST = on
+ - Set SITEMAPWHAT = Describe what this web does.
+ - Set SITEMAPUSETO = ...to do something.
+
+- Copyright notice:
+ - Set WEBCOPYRIGHT = <span> [<img src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiLogos/T-badge-88x31.gif" width="88" height="31" alt="This site is powered by the TWiki collaboration platform" title="This site is powered by the TWiki collaboration platform" />](http://twiki.org/)</span>Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors. <br /> Ideas, requests, problems regarding %WIKITOOLNAME%? [Send feedback](mailto:?subject=%WIKITOOLNAME%%20Feedback%20on%20Main.WebHome)
+
+- Simplified Copyright notice for the [[WebRss]] feed (don't use any special characters, html tags, entities, wiki markup or [[WikiWords]])
+ - Set WEBRSSCOPYRIGHT = Copyright 2010 by contributing authors
+
+- Exclude web from a `web="all"` search: (Set to `on` for hidden webs; is overwritten by web preferences) **_Note_** it is much better to use [[TWikiAccessControls]] in individual webs to control who can and can't view the contents of a web. NOSEARCHALL is retained for compatibility, but you should avoid using it.
+ - Set NOSEARCHALL =
+- Prevent automatic linking of [[WikiWords]] and acronyms (if set to `on`); link WikiWords (if empty); can be overwritten by web preferences:
+ - Set NOAUTOLINK =
+ - **_Note:_** Use the `[[...][...]]` syntax to link topics in case you disabled WikiWord linking. The `<noautolink> ... </noautolink>` syntax can be used to prevents links within a block of text.
+- If you use non WikiWords for topic names (for example "Expenses" or "Mighty1") and if you use bracket notation to link to those topics, it is useful to **turn of all warnings** (like: "WARNING: This topic name is not recommended because it will not be linked automatically") and checkboxes ("Allow non WikiWord for the new topic name"). Can be overwritten by web preferences. Set to `on` to activate:
+ - Set HIDE\_NON\_WIKI\_WORD\_WARNINGS =
+
+- Warn if `%INCLUDE{}%` of topic fails: Fail silently if empty or `off`. Output warning message (defined in templates/oopsalerts.tmpl) if set to `on`. Otherwise output specific text (use `$topic` for topic). You can override this in web preferences, or by using a `warn="..."` parameter with `%INCLUDE{}%` :
+ - Set INCLUDEWARNING = on
+
+- Generated Table of Contents (TOC) settings
+ - The first header level to appear in the TOC:
+ - Set TOC\_MIN\_DEPTH =
+ - If not set: `1`
+ - Possible values: `1` to `6`
+ - The last header level to appear in the TOC:
+ - Set TOC\_MAX\_DEPTH =
+ - If not set: `6`
+ - Possible values: `1` to `6`
+ - Can be overridden by `depth` parameter of [[variable TOC|SYSTEMWEB/VarTOC2]]
+ - The default TOC title:
+ - Set TOC\_TITLE =
+ - If not set: nothing
+ - Possible values: any string, for example `On this page:`
+ - Can be overridden by `title` parameter of [[variable TOC|SYSTEMWEB/VarTOC2]]
+ - Do not show a TOC if the topic it contains is included in another topic:
+ - Set TOC\_HIDE\_IF\_INCLUDED =
+ - If not set: included TOC is shown
+ - Possible values: `on` or nothing
+
+## <a name="Default User Settings"></a> Default User Settings
+
+%X% **NOTE:** They are typically redefined in topics of individual %USERSWEB%.TWikiUsers
+
+- Show tool-tip topic info on mouse-over of [[WikiWord]] links. Setting can be on, off, or customized. An empty setting or off setting disables the tool-tips (for better performance). The setting can contain $summary to show the topic summary, $date for the last change date, $rev for the revision, $username for the login name of the last editor, $wikiname for the WikiName, $wikiusername for %USERSWEB%.WikiName, $topic for the topic name, and $web for the web name
+ - Set LINKTOOLTIPINFO = off
+ - #Set LINKTOOLTIPINFO = $username - $date - $rev: $summary
+
+- Horizontal size of text edit box: (can be overwritten by user preferences)
+ - Set EDITBOXWIDTH = 70
+
+- Vertical size of text edit box: (can be overwritten by user preferences)
+ - Set EDITBOXHEIGHT = 22
+
+- Style of text edit box. Set to `width: 99%` for full window width (default; this will overwrite the EDITBOXWIDTH setting), or `width: auto` to disable. This setting works for IE and some other recent browsers. (can be overwritten by user preferences)
+ - Set EDITBOXSTYLE = width:99%
+
+- Default state of the **_Force New Revision_** ([[ForceNewRevision]]) check box in preview. Check box is initially checked if `Set FORCENEWREVISIONCHECKBOX = checked="checked"`, or unchecked if empty: (can be overwritten by user preferences)
+ - Set FORCENEWREVISIONCHECKBOX =
+
+- Default state of the **_Minor Changes, Don't Notify_** ([[DontNotify]]) check box in preview. Check box is initially checked if `Set DONTNOTIFYCHECKBOX = checked="checked"`, or unchecked if empty: (can be overwritten by user preferences)
+ - Set DONTNOTIFYCHECKBOX =
+
+- Default state of the **_link_** check box in the attach file page. Checkbox is initially checked if `Set ATTACHLINKBOX = checked="checked"`, or unchecked if empty (`Set ATTACHLINKBOX =`). If checked, a link is created to the attached file at the end of the topic: (can be overwritten by user preferences)
+ - Set ATTACHLINKBOX =
+
+- Format of file link when the **_link_** check box is checked: (can be overwritten by user preferences)
+ - %H% **NOTE:** Keyword <code>**$name**</code> gets expanded to filename; <code>**$comment**</code> to comment; <code>**\\t**</code> to tab (3 spaces for bullets).
+
+ * Set ATTACHEDFILELINKFORMAT = \n * [[%ATTACHURL%/$name][$name]]: $comment
+
+- Format of images when the **_link_** check box is checked: (can be overwritten by user preferences)
+ - %H% **NOTE:** Keyword <code>**$name**</code> gets expanded to filename; <code>**$comment**</code> to comment; <code>**$size**</code> to <code>**width="..." height="..."**</code> attribute of <code>**img**</code> tag; <code>**\\t**</code> to tab and <code>**\\n**</code> to linefeed (3 spaces for bullets).
+
+ * Set ATTACHEDIMAGEFORMAT = \n * $comment: <br />\n <img src="%ATTACHURLPATH%/$name" alt="$name" $size />
+
+## <a name="TWiki Platform Settings"></a> TWiki Platform Settings
+
+- TWiki site name:
+ - Set WIKITOOLNAME = TWiki
+
+- Image, URL and alternate tooltip text of the logo **for this installation**: you should change these settings for your site, or they can be overwridden in WebPreferences for individual webs by defining these variables there.
+ - Set WIKILOGOIMG = 
+ - Set WIKILOGOURL = <http://TWiki.org/>
+ - Set WIKILOGOALT = Powered by %WIKITOOLNAME%
+
+- Home page of this site
+ - Set WIKIHOMEURL = <http://www.dementia.org/twiki/view>
+
+- List of %WIKITOOLNAME% webs - on the first line of the upper toolbar (to add a new web, see [[ManagingWebs]] and %SYSTEMWEB%.SiteMap):
+ - Set WIKIWEBLIST = [[%USERSWEB%|USERSWEB/WebHome]] | [[%SYSTEMWEB%|SYSTEMWEB/WebHome]] | [[Sandbox|Sandbox/WebHome]]
+ - %T% **NOTE:** To automatically list all non-hidden webs in alphabetical order, use the `%WEBLIST{}%` variable instead: <br />
+
+- Maximum size of %SYSTEMWEB%.FileAttachments in KB, 0 for no limit:
+ - Set ATTACHFILESIZELIMIT = 10000
+
+- Broadcast message for skins supporting a %BROADCASTMESSAGE% at the top of the page: (IMPORTANT: Set to empty message if not used; #Comment out unused messages)
+ - Set BROADCASTMESSAGE =
+ - #Set BROADCASTMESSAGE = **NOTE:** Edit and Attach will be disabled today between 05:00 PM and 06:00 PM PDT (00:00 to 01:00 GMT) for a scheduled %WIKITOOLNAME% maintenance.
+
+- Users or groups allowed to [[create new top-level webs|SYSTEMWEB/ManagingWebs]]: (ex: %USERSWEB%.WebCreatorsGroup). If set to nothing, only administrators will be able to do this.
+ - Set ALLOWROOTCHANGE = %USERSWEB%.TWikiAdminGroup
+
+### <a name="Search Settings"></a> Search Settings
+
+- Default type for search, one of: keyword (for search engine like syntax), regex (for [[RegularExpression]] search), or literal (for verbatim search)
+ - Set SEARCHDEFAULTTTYPE = keyword
+- Default for `%SEARCH{}%` variable, one of: keyword, regex, or literal
+ - Set SEARCHVARDEFAULTTYPE = literal
+- Stop words, e.g., common words and characters to exclude from a keyword search:
+ - Set SEARCHSTOPWORDS = a, all, am, an, and, any, as, at, b, be, by, c, d, e, for, from, g, h, how, i, i'm, i.e., in, is, isn't, it, it's, its, j, k, l, m, n, o, of, on, or, p, q, r, s, t, that, that's, the, this, to, u, v, w, was, wasn't, what, what's, when, where, who, who's, will, with, x, y, z
+
+### <a name="E-mail Settings"></a> E-mail Settings
+
+- 'Mail this topic' mailto: link - can be included in topics, templates or skins
+ - Set MAILTHISTOPIC = [%MAILTHISTOPICTEXT%](mailto:?subject=WebHome&body=%TOPICURL%)
+
+- 'Mail this topic' link text
+ - Set MAILTHISTOPICTEXT = Send a link to this page
+
+- URL for current topic
+ - Set TOPICURL = [[http://www.dementia.org/twiki/view/%WEB%/WebHome|%WEB%/WebHome]]
+
+### <a name="HTTP-EQUIV Settings"></a> HTTP-EQUIV Settings
+
+- %T% **NOTE:** Changing cache behaviour with these settings should not be necessary and may cause cache-related problems (e.g. TWiki:Codev.BackFromPreviewLosesText or TWiki:Codev.RefreshEditPage). These settings do not affect proxy caches.
+- **NOTE:** The current values of these preferences are not displayed in view mode (values are `<link>`-tags).
+
+- <code>**http-equiv**</code> meta tags for <code>**view**</code>, <code>**rdiff**</code>, <code>**attach**</code>, <code>**search\***</code> scripts:
+ - #Set HTTP\_EQUIV\_ON\_VIEW =
+ - Set HTTP\_EQUIV\_ON\_VIEW =
- <code>**http-equiv**</code> meta tags for <code>**edit**</code> script:
- Set HTTP\_EQUIV\_ON\_EDIT =
### <a name="PatternSkin"></a> [[PatternSkin]]
- Default TWiki styles
- - Set TWIKILAYOUTURL = <http://www.dementia.org/twiki//view/TWiki/PatternSkin/layout.css>
- - Set TWIKISTYLEURL = <http://www.dementia.org/twiki//view/TWiki/PatternSkin/style.css>
- - Set TWIKICOLORSURL = <http://www.dementia.org/twiki//view/TWiki/PatternSkin/colors.css>
+ - Set TWIKILAYOUTURL = <http://www.dementia.org/twiki//view/%SYSTEMWEB%/PatternSkin/layout.css>
+ - Set TWIKISTYLEURL = <http://www.dementia.org/twiki//view/%SYSTEMWEB%/PatternSkin/style.css>
+ - Set TWIKICOLORSURL = <http://www.dementia.org/twiki//view/%SYSTEMWEB%/PatternSkin/colors.css>
- Custom overriding styles (enabled pr. default but empty, to prevent browsers from fetching %USERLAYOUTURL%-style URLs)
- Set USERLAYOUTURL =
- Set USERCOLORSURL =
- **PatternSkin header settings**
- - Set WEBHEADERART = 
- - Set WEBHEADERBGCOLOR = #ffffff
+ - Set WEBHEADERART = 
+ - #Set WEBHEADERBGCOLOR = #faf8f0
### <a name="Skin icons"></a> Skin icons
- Topic containing the icon graphics library. Icons can easily be rendered with `%ICON{name}%`.
- - Set ICONTOPIC = [[TWikiDocGraphics]]
+ - Set ICONTOPIC = %SYSTEMWEB%.TWikiDocGraphics
### <a name="Legacy support"></a> Legacy support
- Support for legacy "EDITTOPIC", used to be hard-coded, now replaced by TMPL:P conditional instantiation
- - Set EDITURL = <http://www.dementia.org/twiki/edit/%WEB%/%TOPIC%?t=1277827363>
+ - Set EDITURL = <http://www.dementia.org/twiki/edit/%WEB%/%TOPIC%?t=1277827703>
- Set EDITTOPIC = [Edit](%EDITURL% Edit Topic - deprecated usage - please see release notes)
## <a name="Plugins Settings"></a> Plugins Settings
## <a name="Rendering Shortcuts Settings"></a> Rendering Shortcuts Settings
-- Line break:
+- Line break: Note that the setting has an intentional trailing space
- Set BR = <br />
- Bullet sign:
- Vertical bar / pipe symbol:
- Set VBAR = |
+- Vertical caret symbol:
+ - Set CARET = ^
+
- Line break and bullet with different levels of indentation:
- Set BB = <br />•
- Set BB2 = <br /> •
## <a name="Miscellaneous Settings"></a> Miscellaneous Settings
-- Format of a [[NewWikiWord]] link: %BR%
+- Format of a [[NewWikiWord]] link:
+- Note that `$text` is the topic link text, `$topic` is the name of the new topic, and `$web` is the name of the web for the new topic. Values for the 3 are taken from the link syntax `[[$web.$topic][$text]]`. For normal plain WikiWord links `$text` and `$topic` are the same. The value of `$web` is the current web unless the link is in the format `$web.$topic`.
- default setting:
- Set NEWLINKFORMAT = <span>$text[?](http://www.dementia.org/twiki/edit/$web/$topic?topicparent=%WEB%.%TOPIC% Create this topic)</span>
- alternative setting:
- #Set NEWLINKFORMAT = [$text](http://www.dementia.org/twiki/edit/$web/$topic?topicparent=%WEB%.%TOPIC% Create this topic)
-- [[PreviewBackground]] image:
- - Set PREVIEWBGIMAGE = 
+- %SYSTEMWEB%.PreviewBackground image:
+ - Set PREVIEWBGIMAGE = 
+
+- User-friendly synonyms for system webs
+ - Set DOCWEB = %SYSTEMWEB%
-- User-friendly synonyms for MAINWEB and TWIKIWEB
- - Set USERSWEB = Main
- - Set SYSTEMWEB = TWiki
- - Set DOCWEB = TWiki
+- show extra help for ApacheLogin users for [[TWikiAdminUser]] login
+ - Set ADMINLOGIN = [internal admin login](http://www.dementia.org/twiki/login?sudo=sudo;origurl=http://www.dementia.org/twiki/view/Main/WebHome) (use the username suggested and the password set in configure).
## <a name="Access Control Settings"></a> Access Control Settings
-- Users or groups allowed to change or rename this %TOPIC% topic:
- - Set ALLOWTOPICCHANGE = [[TWikiAdminGroup]]
-- By default, only admins can create webs in the root
- - Set ALLOWROOTCHANGE = [[TWikiAdminGroup]]
+- No-one (except admins) should change this topic
+ - Set ALLOWTOPICCHANGE = %USERSWEB%.TWikiAdminGroup
+ - Set ALLOWTOPICRENAME = %USERSWEB%.TWikiAdminGroup
## <a name="Creating New Preference Variable"></a> Creating New Preference Variables
- A preference is defined in a [[TWikiShorthand]] bullet item: <code>**[3 spaces] \* [space] Set NAME = value**</code><br /> Example (as a nested bullet item, indented 6 spaces):
- Set WEBBGCOLOR = #FFFFC0
-- Preferences are used as [[TWikiVariables]] by enclosing the name in percent signs: <code>**%**</code>. Example:
+- Preferences are used as %SYSTEMWEB%.TWikiVariables by enclosing the name in percent signs: <code>**%**</code>. Example:
- When you write variable <code>**%WEBBGCOLOR%**</code>, it gets expanded to `%WEBBGCOLOR%` .
- %X% The sequential order of the preference settings is significant. Define preferences that use other preferences FIRST. For example, set <code>**WEBCOPYRIGHT**</code> before <code>**WIKIWEBMASTER**</code> since the copyright notice uses the TWiki administrator e-mail address.
-- %X% In order to protect your custom variables from being overwritten when upgrading the [[TWiki.%TOPIC%|TWiki/TOPIC]] topic, it is recommended that custom variables are defined in [[Main.%TOPIC%|Main/TOPIC]].
+- %X% In order to protect your custom variables from being overwritten when upgrading the [[%SYSTEMWEB%.%TOPIC%|SYSTEMWEB/TOPIC]] topic, it is recommended that custom variables are defined in [[%USERSWEB%.%TOPIC%|USERSWEB/TOPIC]].
## <a name="Related Topics"></a> Related Topics
- [[WebPreferences]] has preferences of the %WEB% web.
-- [[TWikiUsers]] has a list of user topics. User topics can have optional user preferences.
-- [[TWikiVariables]] has a list of common `%VARIABLES%`.
-- [[TWikiAccessControl]] explains how to restrict access by users or groups.
+- User topics in %USERSWEB% can have optional user preferences.
+- %SYSTEMWEB%.TWikiVariables has a list of common `%VARIABLES%`.
+- %SYSTEMWEB%.TWikiAccessControl explains how to restrict access by users or groups.
- TWiki:Plugins.PreferencesPlugin makes editing preferences a snap.
**_Note_**: Can't edit? [[View raw topic|%WEB%/%TOPIC%?raw=on]]
<td> S </td>
</tr>
<tr>
- <td> NEWTOPICBGCOLOR </td>
- <td> text </td>
- <td> 20 </td>
- <td> #FFFFCE </td>
- <td> HTML Color </td>
- <td> S </td>
- </tr>
- <tr>
- <td> NEWTOPICFONTCOLOR </td>
- <td> text </td>
- <td> 20 </td>
- <td> #0000FF </td>
- <td> HTML Color </td>
- <td> S </td>
- </tr>
- <tr>
<td> WEBCOPYRIGHT </td>
<td> textarea </td>
<td> </td>
<td> PREVIEWBGIMAGE </td>
<td> text </td>
<td> 30 </td>
- <td><img alt="preview2bg.gif" src="http://www.dementia.org/twiki//view/TWiki/PreviewBackground/preview2bg.gif" /></td>
+ <td><img alt="preview2bg.gif" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/PreviewBackground/preview2bg.gif" /></td>
<td> Image URL </td>
<td> S </td>
</tr>
<td> WIKILOGOIMG </td>
<td> text </td>
<td> 30 </td>
- <td><img alt="horzTWiki.gif" src="http://www.dementia.org/twiki//view/TWiki/TWikiLogos/horzTWiki.gif" /></td>
+ <td><img alt="horzTWiki.gif" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiLogos/horzTWiki.gif" /></td>
<td> URL of a logo image </td>
<td> S </td>
</tr>
<td> WIKIWEBLIST </td>
<td> textarea </td>
<td> </td>
- <td>[[Main/WebHome]]</td>
- <td align="center">[[TWiki/WebHome]]</td>
+ <td>[[USERSWEB/WebHome]]</td>
+ <td align="center">[[SYSTEMWEB/WebHome]]</td>
<td align="right">[[Sandbox/WebHome]]</td>
<td> </td>
<td> S </td>
<td> TWIKILAYOUTURL </td>
<td> text </td>
<td> 30 </td>
- <td><a href="http://www.dementia.org/twiki//view/TWiki/PatternSkin/layout.css" target="_top">http://www.dementia.org/twiki//view/TWiki/PatternSkin/layout.css</a></td>
+ <td><a href="http://www.dementia.org/twiki//view/%SYSTEMWEB%/PatternSkin/layout.css" target="_top">http://www.dementia.org/twiki//view/%SYSTEMWEB%/PatternSkin/layout.css</a></td>
<td> URL of a CSS </td>
<td> S </td>
</tr>
<td> TWIKISTYLEURL </td>
<td> text </td>
<td> 30 </td>
- <td><a href="http://www.dementia.org/twiki//view/TWiki/PatternSkin/style.css" target="_top">http://www.dementia.org/twiki//view/TWiki/PatternSkin/style.css</a></td>
+ <td><a href="http://www.dementia.org/twiki//view/%SYSTEMWEB%/PatternSkin/style.css" target="_top">http://www.dementia.org/twiki//view/%SYSTEMWEB%/PatternSkin/style.css</a></td>
<td> URL of a CSS </td>
<td> S </td>
</tr>
<ul>
<li><a href="#Package =TWiki::Prefs="> Package TWiki::Prefs</a><ul>
<li><a href="#ClassMethod <strong>new</strong> ($session[,$ca"> ClassMethod new <tt>($session[,$cache])</tt></a></li>
- <li><a href="#ObjectMethod *finish*"> ObjectMethod finish <tt></tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
<li><a href="#ObjectMethod <strong>pushPreferences</strong> ("> ObjectMethod pushPreferences <tt>($web,$topic,$type)</tt></a></li>
<li><a href="#ObjectMethod *push_WebPreference"> ObjectMethod pushWebPreferences <tt>($web)</tt></a></li>
<li><a href="#ObjectMethod *push_GlobalPrefere"> ObjectMethod pushGlobalPreferences <tt>()</tt></a></li>
<li><a href="#ObjectMethod *push_PreferencesVa"> ObjectMethod pushPreferencesValues <tt>($type,\%values)</tt></a></li>
<li><a href="#ObjectMethod <strong>mark</strong> ()"> ObjectMethod mark <tt>()</tt></a></li>
- <li><a href="#ObjectMethod <strong>resetTo</strong> ($mark)"> ObjectMethod resetTo <tt>($mark)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>restore</strong> ($mark)"> ObjectMethod restore <tt>($mark)</tt></a></li>
<li><a href="#ObjectMethod *get_PreferencesVal"> ObjectMethod getPreferencesValue <tt>($key) -> $value</tt></a></li>
<li><a href="#ObjectMethod <strong>isFinalised</strong> ($key"> ObjectMethod isFinalised <tt>($key)</tt></a></li>
<li><a href="#ObjectMethod *get_TopicPreferenc"> ObjectMethod getTopicPreferencesValue <tt>($key,$web,$topic) -> $value</tt></a></li>
<li><a href="#get_TextPreferencesValue( $key,"> getTextPreferencesValue( $key, $text, $meta, $web, $topic ) -> $value</a></li>
- <li><a href="#ObjectMethod *get_WebPreferences"> ObjectMethod getWebPreferencesValue <tt>($key,$web) -> $value</tt></a></li>
+ <li><a href="#ObjectMethod *get_WebPreferences"> ObjectMethod getWebPreferencesValue <tt>($key,$web) -> $value</tt></a><ul>
+ <li><a href="#set_PreferencesValue($name, $val"> setPreferencesValue($name, $val)</a></li>
+ </ul>
+ </li>
<li><a href="#ObjectMethod stringify() -> $tex">ObjectMethod stringify() -> $text</a></li>
</ul>
</li>
Creates a new Prefs object. If $cache is defined, it will be pushed onto the stack.
-## <a name="ObjectMethod <strong>finish*"></a><a name="ObjectMethod *finish</strong> "></a> [[ObjectMethod]] **finish** ``
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
-Complete processing after the client's HTTP request has been responded to.
-
-1. breaking circular references to allow garbage collection in persistent environments
+Break circular references.
## <a name="ObjectMethod <strong>pushPreferences</strong> ("></a> [[ObjectMethod]] **pushPreferences** `($web,$topic,$type)`
Return a marker representing the current top of the preferences stack. Used to remember the stack when new web and topic preferences are pushed during a topic include.
-## <a name="ObjectMethod <strong>resetTo</strong> ($mark)"></a> [[ObjectMethod]] **resetTo** `($mark)`
+## <a name="ObjectMethod <strong>restore</strong> ($mark)"></a> [[ObjectMethod]] **restore** `($mark)`
Resets the preferences stack to the given mark, to recover after a topic include.
Intended for use in protections mechanisms, where the order doesn't match the prefs stack.
+### <a name="set_PreferencesValue($name, $val"></a> setPreferencesValue($name, $val)
+
+Set a preferences value. The preference is set in the context at the top of the preference stack, whatever the current state may be.
+
+The preference is not serialised.
+
## <a name="ObjectMethod stringify() - $text"></a> [[ObjectMethod]] stringify() -> $text
Generate a TML-formatted version of the current preferences
<ul>
<li><a href="#Package =TWiki::Prefs::_PrefsCac"> Package TWiki::Prefs::PrefsCache</a><ul>
<li><a href="#ClassMethod <strong>new</strong> ($prefs,$paren"> ClassMethod new <tt>($prefs,$parent,$type,$web,$topic,$prefix)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
<li><a href="#ObjectMethod <strong>finalise</strong> ($parent"> ObjectMethod finalise <tt>($parent)</tt></a></li>
<li><a href="#ObjectMethod *load_PrefsFromTopi"> ObjectMethod loadPrefsFromTopic <tt>($web,$topic,$keyPrefix)</tt></a></li>
<li><a href="#ObjectMethod *load_PrefsFromText"> ObjectMethod loadPrefsFromText <tt>($text,$meta,$web,$topic)</tt></a></li>
- <li><a href="#ObjectMethod <strong>insert</strong> ($type,$ke"> ObjectMethod insert <tt>($type,$key,$val)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>insert</strong> ($type,$ke"> ObjectMethod insert <tt>($type,$key,$val) -> $boolean</tt></a></li>
<li><a href="#ObjectMethod <strong>stringify</strong> ($html,"> ObjectMethod stringify <tt>($html,\%shown) -> $text</tt></a></li>
</ul>
</li>
If the specified topic is not found, returns an empty object.
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
+
+Break circular references.
+
## <a name="ObjectMethod <strong>finalise</strong> ($parent"></a> [[ObjectMethod]] **finalise** `($parent)`
Finalise preferences in this cache, by freezing any preferences listed in FINALPREFERENCES at their current value.
Loads preferences from text and optional metadata. All settings loaded are prefixed with the key prefix (default ''). If `$meta` is defined, then metadata will be taken from that object. Otherwise, `$text` will be parsed to extract meta-data.
-## <a name="ObjectMethod <strong>insert</strong> ($type,$ke"></a> [[ObjectMethod]] **insert** `($type,$key,$val)`
+## <a name="ObjectMethod <strong>insert</strong> ($type,$ke"></a> [[ObjectMethod]] **insert** `($type,$key,$val) -> $boolean`
Adds a key-value pair of the given type to the object. Type is Set or Local. Callback used for the Prefs::Parser object, or can be used to add arbitrary new entries to a prefs cache.
Note that attempts to redefine final preferences will be ignored.
+Returns 1 if the preference was defined, 0 otherwise.
+
## <a name="ObjectMethod <strong>stringify</strong> ($html,"></a> [[ObjectMethod]] **stringify** `($html,\%shown) -> $text`
Generate an (HTML if $html) representation of the content of this cache.
--- /dev/null
+# <a name="Package <code>TWiki::Query::_HoistREs"></a> Package =TWiki::Query::HoistREs
+
+Static functions to extract regular expressions from queries. The REs can be used in caching stores that use the TWiki standard inline meta-data representation to pre-filter topic lists for more efficient query matching.
+
+See `Store/RcsFile.pm` for an example of usage.
+
+<div>
+ <ul>
+ <li><a href="#Package =TWiki::Query::_HoistREs"> Package TWiki::Query::HoistREs</a><ul>
+ <li><a href="#ObjectMethod <strong>hoist</strong> ($query) ->"> ObjectMethod hoist <tt>($query) -> @res</tt></a></li>
+ </ul>
+ </li>
+ </ul>
+</div>
+
+## <a name="ObjectMethod <strong>hoist</strong> ($query) -"></a><a name="ObjectMethod <strong>hoist</strong> ($query) - "></a> [[ObjectMethod]] **hoist** `($query) -> @res`
+
+Extract useful filter REs from the given query. The list returned is a list of filter expressions that can be used with a cache search to refine the list of topics. The full query should still be applied to topics that remain after the filter match has been applied; this is purely an optimisation.
--- /dev/null
+# <a name="Package <code>TWiki::Query="></a> Package =TWiki::Query
+
+A Query object is a representation of a query over the TWiki database.
+
+Fields are given by name, and values by strings or numbers. Strings should always be surrounded by 'single-quotes'. Numbers can be signed integers or decimals. Single quotes in values may be escaped using backslash (\\).
+
+See [[QuerySearch]] for details of the query language. At the time of writing only a subset of the entire query language is supported, for use in searching.
+
+A query object implements the `evaluate` method as its general contract with the rest of the world. This method does a "hard work" evaluation of the parser tree. Of course, smarter Store implementations should be able to do it better....
+
+<div>
+ <ul>
+ <li><a href="#Package =TWiki::Query="> Package TWiki::Query</a><ul>
+ <li><a href="#PUBLIC $aliases"> PUBLIC $aliases</a></li>
+ <li><a href="#PUBLIC %is_ArrayType"> PUBLIC %isArrayType</a></li>
+ </ul>
+ </li>
+ </ul>
+</div>
+
+## <a name="PUBLIC $aliases"></a> PUBLIC $aliases
+
+A hash mapping short aliases for META: entry names. For example, this hash maps 'form' to 'META:FORM'. Published so extensions can extend the range of supported types.
+
+## <a name="PUBLIC %is_ArrayType"></a> PUBLIC %isArrayType
+
+Maps META: entry type names to true if the type is an array type (such as FIELD, ATTACHMENT or PREFERENCE). Published so extensions can extend the range or supported types. The type name should be given without the leading 'META:'
--- /dev/null
+# <a name="Package <code>TWiki::Query::Parser="></a> Package =TWiki::Query::Parser
+
+Parser for queries
+
+<div>
+ <ul>
+ <li><a href="#Package =TWiki::Query::Parser="> Package TWiki::Query::Parser</a></li>
+ </ul>
+</div>
# <a name="Registration"></a> Registration
-**To edit pages on this [[TWikiSite]], you must have a registered user name and password.**
+**This TWiki does _not_ support new User Registration**
%H% **Note:** Registered users can [[change|TWiki/ChangePassword]] and [[reset|TWiki/ResetPassword]] their passwords.
</tr>
<tr>
<td align="right"> First Name: </td>
- <td><input name="Twk1FirstName" onblur="this.form.Twk1WikiName.value=capitalise(this.value)+capitalise(this.form.Twk1LastName.value)" size="40" type="text" value="" /> <code><font color="red">**</font></code></td>
+ <td><input %noregistration%="%NOREGISTRATION%" name="Twk1FirstName" onblur="this.form.Twk1WikiName.value=capitalise(this.value)+capitalise(this.form.Twk1LastName.value)" size="40" type="text" value="" /> <code><font color="red">**</font></code></td>
</tr>
<tr>
<td align="right"> Last Name: </td>
- <td><input name="Twk1LastName" onblur="this.form.Twk1WikiName.value=capitalise(this.form.Twk1FirstName.value)+capitalise(this.value)" size="40" type="text" value="" /> <code><font color="red">**</font></code></td>
+ <td><input %noregistration%="%NOREGISTRATION%" name="Twk1LastName" onblur="this.form.Twk1WikiName.value=capitalise(this.form.Twk1FirstName.value)+capitalise(this.value)" size="40" type="text" value="" /> <code><font color="red">**</font></code></td>
</tr>
<tr>
<td align="right"> (identifies you to others) [[Main/WikiName]]: </td>
- <td><input name="Twk1WikiName" onblur="" size="40" type="text" value="" /> <code><font color="red">**</font></code></td>
+ <td><input %noregistration%="%NOREGISTRATION%" name="Twk1WikiName" onblur="" size="40" type="text" value="" /> <code><font color="red">**</font></code></td>
</tr>
<tr>
<td>
</tr>
<tr>
<td align="right"> E-mail address: </td>
- <td><input name="Twk1Email" size="40" type="text" value="" /> <code><font color="red">**</font></code></td>
+ <td><input %noregistration%="%NOREGISTRATION%" name="Twk1Email" size="40" type="text" value="" /> <code><font color="red">**</font></code></td>
</tr>
<tr>
<td> %BESPOKE_PASSWORD% </td>
</tr>
<tr>
<td align="right"> Organisation name: </td>
- <td><input name="Twk0OrganisationName" size="40" type="text" value="" /></td>
+ <td><input %noregistration%="%NOREGISTRATION%" name="Twk0OrganisationName" size="40" type="text" value="" /></td>
</tr>
<tr>
<td align="right"> Organisation URL: </td>
- <td><input name="Twk0OrganisationURL" onblur="if(this.value=='http://') { this.value='' }" onfocus="if(this.value=='') { this.value='http://' }" size="40" type="text" /></td>
+ <td><input %noregistration%="%NOREGISTRATION%" name="Twk0OrganisationURL" onblur="if(this.value=='http://') { this.value='' }" onfocus="if(this.value=='') { this.value='http://' }" size="40" type="text" /></td>
</tr>
<tr>
<td align="right"> Country: </td>
- <td><select name="Twk1Country" size="1"><option selected value="">Select...</option>
+ <td><select %noregistration%="%NOREGISTRATION%" name="Twk1Country" size="1"><option selected value="">Select...</option>
<option>USA</option>
<option>Albania</option>
<option>Algeria</option>
<tr>
<td align="right" valign="top"> Comments:<br /> (optional) </td>
<td>
- <textarea cols="38" name="Twk0Comment" rows="4" wrap="virtual">
+ <textarea %noregistration%="%NOREGISTRATION%" cols="38" name="Twk0Comment" rows="4" wrap="virtual">
</textarea>
</td>
</tr>
<li> Add your name to the list of users in the [[Main/TWikiUsers]] topic in the Main web. </li>
<li> Send you a confirmation of your registration by e-mail. </li>
</ul> Once registered you can login using your %LOGIN_METHOD_IN_THIS_SITE% and password. </div>
- <div><input name="rx" type="hidden" value="%BLACKLISTPLUGIN{ action="magic" }%" /> <input name="topic" type="hidden" value="%TOPIC%" /> <input name="action" type="hidden" value="register" /> <input type="submit" value=" Submit " /></div>
+ <div><input name="rx" type="hidden" value="%BLACKLISTPLUGIN{ action="magic" }%" /> <input name="topic" type="hidden" value="%TOPIC%" /> <input name="action" type="hidden" value="register" /> <input %noregistration%="%NOREGISTRATION%" type="submit" value=" Submit " /></div>
</div>
</form>
<li><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> If you have any questions about registration, send an e-mail to <a href="mailto:?subject=%TOPIC% Question"></a>. </li>
</ul>
</div>
-
-<table bgcolor="yellow">
- <tr>
- <td><strong><em>Note to administrator:</em></strong> The form fields can be customized to the needs of your organization. See also [[Main/TWikiUserAuthentication]]. In case you are registering users through other means, replace this topic with a note describing how to get registered in TWiki. In any case, remove this note. </td>
- </tr>
-</table>
- #Set ALLOWWEBVIEW =
- _etc_
-%RED%Note:%ENDCOLOR% For security reasons, the [[Trash|Trash/WebHome]] web is shipped with `ALLOWWEBVIEW` set to [[TWikiAdminGroup]].
+%RED%Note:%ENDCOLOR% For security reasons, the [[Trash|Trash/WebHome]] web is shipped with `ALLOWWEBVIEW` set to empty (so it is only viewable by admins).
#### <a name="Site Permissions Overview"></a> Site Permissions Overview
-# <a name="TWiki Release 4.1.2 (Edinburgh),"></a><a name=" TWiki Release 4.1.2 (Edinburgh)"></a> TWiki Release 4.1.2 (Edinburgh), 15:45:54 03 March 2007
+# <a name="TWiki Release 4.1.2 (Edinburgh),"></a><a name=" TWiki Release 4.1.2 (Edinburgh)"></a> TWiki Release 4.1.2 (Edinburgh), 04:18:52 22 January 2008
+
+_Note: This is the release note for the previous major release version 4.1.X. This note and the [[TWikiReleaseNotes04x00]] are included with 4.2.X because they contain valuable information for people upgrading from earlier versions. Both for the admin and the users. See [[TWikiReleaseNotes04x02]] for the 4.2.X release notes_
<div>
<ul>
- Users of mod\_perl should notice a new experimental feature that speeds up searching by a large factor. The feature is described in the [NativeSearch](http://twiki.org/cgi-bin/view/Codev/NativeSearch) topic at the TWiki website. In configure look for the \{RCS\}\{SearchAlgorithm\} setting. Normal mode is Forking. The new mode for mod\_perl is Native and is a C program which needs to be compiled with a C-compiler like gcc, and this new mode works faster than forking on mod\_perl. If you do not run mod\_perl stick to the default Forking.
- /tmp/twiki directory which was introduced with 4.1.1 is now auto created also with older versions of the CGI::Session library. This is important for distributions that cleans out /tmp when rebooting.
- Configure has gotten much better at installing extensions such as plugins.
-- Configure is now more friendly to a new administator. Configure now only shows the important "General Path Settings" until you have saved and created the [[LocalSite]].cfg file. This prevents a number of false errors from being wrongly fixed by a first time installer.
+- Configure is now more friendly to a new administator. Configure now only shows the important "General Path Settings" until you have saved and created the `LocalSite.cfg` file. This prevents a number of false errors from being wrongly fixed by a first time installer.
- The documented bahavior of "\* Set ALLOWTOPICCHANGE = (nothing)" does not match the code. Documentation has been updated to match actual behavior in 4.1.2. See also deprecation notice below. You should review your use of access rights settings in topics.
## <a name="Deprecation Notices"></a> Deprecation Notices
## <a name="TWiki 4.1.2 Patch Release Detail"></a> TWiki 4.1.2 Patch Release Details
-The 4.1.2 release was built from SVN <http://svn.twiki.org/svn/twiki/Patch04x01> revision 13046 (15:45:54 03 March 2007).
+The 4.1.2 release was built from SVN <http://svn.twiki.org/svn/twiki/Patch04x01> revision 16278 (22 Jan 2008) (04:18:52 22 January 2008).
TWiki 4.1.1 Fixes
--- /dev/null
+# <a name="TWiki Release 4.2.0 (Freetown),"></a><a name=" TWiki Release 4.2.0 (Freetown),"></a> TWiki Release 4.2.0 (Freetown), 04:18:52 22 January 2008
+
+<div>
+ <ul>
+ <li><a href="#Introduction"> Introduction</a></li>
+ <li><a href="#Pre-installed Extensions"> Pre-installed Extensions</a></li>
+ <li><a href="#New Features Highlights"> New Features Highlights</a></li>
+ <li><a href="#Important Changes since 4.1.2"> Important Changes since 4.1.2</a><ul>
+ <li><a href="#New WYSIWYG Editor"> New WYSIWYG Editor</a></li>
+ <li><a href="#NEWTOPICLINKSYMBOL removed"> NEWTOPICLINKSYMBOL removed</a></li>
+ <li><a href="#!_UserForm and _NewUserTemplate"> UserForm and NewUserTemplate Customization</a></li>
+ <li><a href="#!_TWikiUsers no longer distribut"> TWikiUsers no longer distributed</a></li>
+ <li><a href="#New <code>working</code> directory"> New working directory</a></li>
+ <li><a href="#New Internal Admin Login"> New Internal Admin Login</a></li>
+ <li><a href="#Rearchitected User Mapping syste"> Rearchitected User Mapping system (a transperant change for end users)</a></li>
+ </ul>
+ </li>
+ <li><a href="#API Enhancements (Func)"> API Enhancements (Func)</a></li>
+ <li><a href="#Deprecation Notices"> Deprecation Notices</a></li>
+ <li><a href="#TWiki 4.2.0 Minor Release - Deta"> TWiki 4.2.0 Minor Release - Details</a></li>
+ <li><a href="#Fixes"> Fixes</a></li>
+ <li><a href="#Enhancements"> Enhancements</a></li>
+ </ul>
+</div>
+
+## <a name="Introduction"></a> Introduction
+
+TWiki Release 4.2.0 is a minor release. TWiki releases are either major (major new features and changes in architecture), minor (enhancements and bug fixes), or patch releases (bug fixes only) which can be installed as upgrades on production installations.
+
+TWiki Release 4.2.0 introduces some good enhancements and quite many bug fixes since 4.1.2.
+
+The development team has done everything to maintain full compatibility with topics generated in TWiki-4.0 and there are no changes to the topic format when using normal TWikiUserMapping
+
+## <a name="Pre-installed Extensions"></a> Pre-installed Extensions
+
+TWiki 4.2.0 is shipped with
+
+- **Plugins:** CommentPlugin, EditTablePlugin, EmptyPlugin, InterwikiPlugin, PreferencesPlugin, RenderListPlugin, SlideShowPlugin, SmiliesPlugin, SpreadSheetPlugin, TablePlugin, TinyMCEPlugin, TwistyPlugin, WysiwygPlugin
+- **Contribs:** BehaviourContrib, JSCalendarContrib, MailerContrib, TipsContrib, TWikiUserMappingContrib, TwistyContrib
+- **Skins:** ClassicSkin, PatternSkin
+
+## <a name="New Features Highlights"></a> New Features Highlights
+
+- **Easier Installation and Upgrade**
+ - New Internal Admin Login feature. See below.
+ - The Main.TWikiUsers topic is no longer distributed as a default topic in Main. See below.
+ - A new directory `working` which per default is located in the twiki root which contains registration\_approvals, tmp, and work\_areas. See below
+ - ResetPassword, ChangePassword, ChangeEmailAddress, and TWikiRegistration no longer contains yellow text that you have to remove.
+ - Configure can now authenticate when connecting to local plugins repository.
+
+- **Usability Enhancements**
+ - New WYSIWYG editor based on TinyMCE replaces the Kupu based editor. See below.
+ - New "Restore topic" feature has been added to the _More Topic Actions_ menu. You can now much more easily restore an older version of a topic including the values a topic form.
+ - Attachment comments no longer has a limit to the length of the text.
+ - The viewfile script now accepts similar simple URL path as used to access a topic. E.g. `http://example.com/twiki/bin/viewfile/TWiki/TWikiDocGraphics/addon.gif` means the same as `http://example.com/twiki/bin/viewfile/TWiki/TWikiDocGraphics?filename=addon.gif`. This make it simpler to use command line tools like `wget` in Linux to download attachments.
+
+- **Application Platform Enhancements**
+ - Enhancements to IF: allows, ingroup, istopic, and isweb
+
+- **Search Enhancements**
+ - New `query` search mode supports SQL-style queries over form fields and other meta-data.
+
+- **Skins and Templates Enhancements**
+ - The PatternSkin which is the default skin for TWiki has got a face lift.
+ - The template have been heavily refactored. This will break some tailorings and home made skins but it was needed to make it easier to make skins in the future.
+
+- **Miscellaneous Feature Enhancements**
+ - Many new functions in the API for plugin developers.
+ - Table of Content (TOC) feature enhanced
+ - User Mapping (mapping between login name and WikiName) code has been extended to allow pluggable modules to integrate with all sorts of alternative authentication and Management schemes. For normal cases you use the default TWikiUserMapping which is using the Main.TWikiUsers topic to map between login and WikiName. A new BaseUserMapping is provided for TWikis where you only have guests and an administrator. In this case you use the login and password given in configure to login as an admin.
+
+## <a name="Important Changes since 4.1.2"></a> Important Changes since 4.1.2
+
+### <a name="New WYSIWYG Editor"></a> New WYSIWYG Editor
+
+TWiki now ships with a new WYSIWYG editor based on TinyMCE replaces the Kupu based editor.%BR% TinyMCE is not a perfect Wysiwyg editor but it is magnitudes better than the Kupu editor
+
+The WysiwygPlugin that drives the engine behind both TinyMCE has additionally been heavily improved so that less TWiki Applications are negatively affected by editing WYSIWYG
+
+When TinyMCEPlugin is enabled the Edit button per default becomes WYSIWYG editing mode. A new Raw Edit link has been added to enable application developers to edit the good old way
+
+The WYSIWYG button is removed when using TinyMCE instead of Kupu.
+
+### <a name="NEWTOPICLINKSYMBOL removed"></a> NEWTOPICLINKSYMBOL removed
+
+The NEWTOPICLINKSYMBOL preference which was deprecated in 4.1 has now been removed from the code. If you want to control the appearance of new links, you can use the more flexible NEWLINKFORMAT.
+
+### <a name="UserForm and _NewUserTemplate Cu"></a><a name="_UserForm and _NewUserTemplate C"></a> UserForm and NewUserTemplate Customization
+
+When a new user registers on TWiki his user topic is created based on the `NewUserTemplate` and `UserForm`.
+
+The `NewUserTemplate` was located in the TWiki web and the `UserForm` in the Main web. When upgrading TWiki these were some of the topics you had to take care not to overwrite.
+
+From 4.2.0 the `UserForm` and `NewUserTemplate` are distributed in the TWiki web. If you create the two in the Main web the Main web version will be used instead. So if you tailor the user topic format or the form then you should always copy the two files to the Main web and modify the ones in the Main web. When you later upgrade TWiki your tailored template and form will not be overwritten.
+
+### <a name="TWikiUsers no longer distributed"></a><a name="_TWikiUsers no longer distribute"></a> TWikiUsers no longer distributed
+
+The `Main.TWikiUsers` topic contains all the registered users. It is a topic you do not want to overwrite when you upgrade TWiki.
+
+From 4.2.0 this file is no longer included in the TWiki distribution. When you register the first time TWiki creates the `Main.TWikiUsers` topic in the Main web if it does not exist already. This means that you can now upgrade TWiki without risk of overwriting the important `TWikiUsers` topic.
+
+- For new installers this makes no difference at all
+- For upgraders this is one less problem to worry about as your important Main.TWikiUsers topic now no longer gets overwritten when upgrading.
+
+### <a name="New <code>working</code> directory"></a> New `working` directory
+
+A new directory `working` which per default is located in the twiki root, has been introduced which contains:
+
+- registration\_approvals - with 4.2.0 it is moved to here from the data directory)
+- tmp - so we now avoid having to fight with special access rights and /tmp directory that gets cleaned out when booting.
+- work\_areas - with 4.2.0 it is moved to here from the pub directory. Configure automatically moved the directory when you upgrade.
+
+Note: Remember to restrict access to this new directory when you upgrade.
+
+### <a name="New Internal Admin Login"></a> New Internal Admin Login
+
+TWiki 4.2 introduces a new _Internal Admin Login_ feature which uses "admin" (configurable) as username and the password from configure to become temporary administrator. When you do a new installation you need to use this feature as Main.TWikiAdminGroup is now access restricted by default to avoid security attacks during the hours an installation may take. From configure there is a link to the TWikiAdminGroup topic and on TWikiAdminGroup the step by step instructions are written in a yellow box.
+
+### <a name="Rearchitected User Mapping syste"></a> Rearchitected User Mapping system (a transperant change for end users)
+
+The User Mapping system has been further rearchitected to reduce its dependance on the traditional TWiki User topic based management and mapping implementation. TWiki is now capable of dealing with login names that are not 7bit ascii (by transforming those logins into a 'cUID' that can be used by rcs). TWiki::Users now uses `TWikiIterators` opening the way for much larger user sets.
+
+## <a name="API Enhancements (Func)"></a> API Enhancements (Func)
+
+- $TWiki::Plugins::VERSION is now 1.2
+- Added `decodeFormatTokens($str) -> $unencodedString`
+- Added `eachChangeSince($web, $time) -> $iterator`
+- Added `eachGroup() -> $iterator`
+- Added `eachGroupMember($group) -> $iterator`
+- Added `eachMembership($wikiname) -> $iterator`
+- Added `eachUser() -> $iterator`
+- Added `emailToWikiNames( $email, $dontAddWeb ) -> @wikiNames`
+- Added `meta` parameter to `expandCommonVariables( $text, $topic, $web, $meta ) -> $text`
+- Added `getCanonicalUserID( $user ) -> $cUID`
+- Added `getExternalResource( $url ) -> $response`
+- Added `getSessionKeys() -> @keys`
+- Added `user` parameter to `getWikiName( $user ) -> $wikiName`
+- Added `user` parameter to `getWikiUserName($user ) -> $wikiName`
+- Added `isAnAdmin( $login ) -> $boolean`
+- Added `isGroup( $group ) -> $boolean`
+- Added `isGroupMember( $group, $login ) -> $boolean`
+- Added `isTrue( $value, $default ) -> $boolean`
+- Added `popTopicContext()`
+- Added `pushTopicContext($web, $topic)`
+- Added `setPreferencesValue($name, $val)`
+- Added `sanitizeAttachmentName($fname) -> ($fileName, $origName)`
+- Added `spaceOutWikiWord( $word, $sep ) -> $text`
+- Added `wikiNameToEmails( $wikiname ) -> @emails`
+- Deprecated getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -> $url
+- Deprecated permissionsSet( $web ) -> $boolean
+
+## <a name="Deprecation Notices"></a> Deprecation Notices
+
+The %MAINWEB% and %TWIKIWEB% variables have been deprecated. For compatibility reasons they are unlikely to ever be removed completely, but you should use the %USERSWEB% and %SYSTEMWEB% variables instead.
+
+In Func getOopsUrl and permissionsSet have been declared deprecated. There is no plan to remove them yet.
+
+## <a name="TWiki 4.2.0 Minor Release - Deta"></a> TWiki 4.2.0 Minor Release - Details
+
+The 4.2.0 release was built from SVN <http://svn.twiki.org/svn/twiki/branches/TWikiRelease04x02> revision 16278 (22 Jan 2008).
+
+## <a name="Fixes"></a> Fixes
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <td>[[BUGS/Item5252]]</td>
+ <td> RenderListPlugin produces warnings with list with no level 1 bullets </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item5246]]</td>
+ <td> When using SERVERTIME with $week in template TWIki fails on missing CPAN lib dependency </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item5245]]</td>
+ <td> adding missing docs for NEWLINKFORMAT - introduced in 2006 </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item5226]]</td>
+ <td> TWikiUserMapping speed re-enhancements </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item5210]]</td>
+ <td> EDITTABLE with a simple text input in which the user has put %BR% gets trunkated at the first BR </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item5123]]</td>
+ <td> missing fetchUsers method in Password.pm </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item5121]]</td>
+ <td> Performance: Copy hash </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item5046]]</td>
+ <td> error link mailto </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item5040]]</td>
+ <td> Auto attach has hardcoded the string 'UnknownUser' for the attachment meta user attr </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item5038]]</td>
+ <td> TablePlugin prepends 'table' to id parameter </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item5031]]</td>
+ <td> "Here" link in merge_notice in templates/messages.tmpl </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item5029]]</td>
+ <td> Template.pm prints incomplete and confusing error message </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item5019]]</td>
+ <td> if you get a lease conflict when using EditTablePlugin, the oops conflict output link is unusable </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item5009]]</td>
+ <td> TWISTY <code>link</code> parameter doesn't support (local) variables (set in topic and used with %) properly </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item5008]]</td>
+ <td> If you register someone you are magically logged in as them </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item5004]]</td>
+ <td> AutoAttach created META that will break topic rendering </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4991]]</td>
+ <td> TwistyPlugin: add behaviour earlier to head than twisty js </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4989]]</td>
+ <td> wrong expansion of deprecated URL tag </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4986]]</td>
+ <td> select+multi+values broken in various respects </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4973]]</td>
+ <td> default skin appears to have javascript in it </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4972]]</td>
+ <td> session files should only be created for web based sessions. </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4971]]</td>
+ <td> taint error when registering and verify is off </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4944]]</td>
+ <td> EditTablePlugin data corruption under mod_perl </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4941]]</td>
+ <td> ChangePassword form does not detect failure when .htpasswd is read-only </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4939]]</td>
+ <td> Pass topicparent when creating a new topic </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4928]]</td>
+ <td> lets use HTTP error codes in rest cgi, rather than rather less useful die's </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4921]]</td>
+ <td> rest cgi is not testing the URL correctly </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4918]]</td>
+ <td> checkpoint-save ignores EDIT_TEMPATE </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4900]]</td>
+ <td> 0 is not recognized as valid input in a mandatory form field </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4898]]</td>
+ <td> tmp and working dir security needs work (docco and code </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4879]]</td>
+ <td> configure not honoring $TWiki::cfg{ScriptUrlPath} </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4856]]</td>
+ <td> EditTablePlugin: make buttons customizable and translatable </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4854]]</td>
+ <td> EditTablePlugin: undefined textarea size gives error in log </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4848]]</td>
+ <td> TWiki:Plugins.EditTablePlugin textarea bug! </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4846]]</td>
+ <td> Installation process SNAFU if you don't set a configure PW </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4819]]</td>
+ <td> viewauth redirect loops to death when Main and TWiki webs both are view denied for TWikiGuest </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4816]]</td>
+ <td> EditPreferences of Main.TWikiPreferences broken </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4807]]</td>
+ <td> swap twikistyle and defaultstyle definitions </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4797]]</td>
+ <td> Online installer not resolving dependencies </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4794]]</td>
+ <td> Wrong link to FileAttachment </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4793]]</td>
+ <td> Login screen has error messages the wrong order </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4774]]</td>
+ <td> When using a field type select+multi in a form used in a template topic, the field doesn't remember the selection </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4765]]</td>
+ <td> Reading static HTML's for upgrade/install is difficult without internet connection/behind firewall </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4761]]</td>
+ <td> Remove inline scripts from pattern skin </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4756]]</td>
+ <td> raw=all does not show all meta when VIEW_TEMPLATE is defined. </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4753]]</td>
+ <td> /bin/twiki is experimental stuff that should not be in distribution </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4752]]</td>
+ <td> Terrifying text appears below plugins list during new extensions install via configure </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4736]]</td>
+ <td> add expires header for css js etc </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4727]]</td>
+ <td> nested web creation is broken (it should prevent the user from creating them if its disabled...) </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4724]]</td>
+ <td><code>afterEditHandler</code> is never called on "Quiet Save" </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4722]]</td>
+ <td> Unused EXPERT options are always shown </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4718]]</td>
+ <td> Improve the installation doc for how to setup apache config for configure </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4713]]</td>
+ <td> Repackage native search as a conrib, remove from 4.2 </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4702]]</td>
+ <td> Lighter top bar background image </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4694]]</td>
+ <td> Standard user topics of TWikiUserMapping are referenced, but not defined </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4692]]</td>
+ <td> Forking search algorithm throws error if topic is nonexistent </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4680]]</td>
+ <td> Print view seems weird in both pattern skin and default skin </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4677]]</td>
+ <td> Search results now have empty line (= html P) between search header and results list </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4676]]</td>
+ <td> Update color scheme to match new neutral table borders </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4675]]</td>
+ <td> Add completePageHandler for plugins </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4671]]</td>
+ <td> default skin is a bit broken </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4670]]</td>
+ <td> close browser advice non-sensical when not using apache login </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4667]]</td>
+ <td> Adding CGI::Session with distribution and enable Template login by default. </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4664]]</td>
+ <td> Web rename renames content as well </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4661]]</td>
+ <td> renaming a topic destroys full qualified topic names </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4659]]</td>
+ <td> Change the strategy of protecting again html attach spam to not harm Wysiwyg editor </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4658]]</td>
+ <td> remove use of undefined variable un utf8 code </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4605]]</td>
+ <td> User shown as Unknown User (Login ID) when author is not in TWikiUsers. Bad feature </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4590]]</td>
+ <td> Rename "Checkpoint" to "Save and Continue" </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4585]]</td>
+ <td> configure generates apache errors </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4576]]</td>
+ <td> Improve how emailing is enabled and disabled in TWiki especially for registration </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4569]]</td>
+ <td> WebSearchAdvanced does not show selected state for default radion button "both" </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4539]]</td>
+ <td> Rename css class TWikiFooterNote to twikiFooterNote </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4510]]</td>
+ <td> Remove inline scripts </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4509]]</td>
+ <td> Prevent [ and ] in topic names when renaming topics </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4508]]</td>
+ <td> ResetPassword, ChangePassword, ChangeEmailAddress, TWikiRegistration needs to be hacked after each upgrade </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4505]]</td>
+ <td> User registration states incorrect user name </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4493]]</td>
+ <td> Inline rdiff between rev 0 and rev 1 is empty </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4487]]</td>
+ <td> As described in TWiki.TWikiScripts auth protect rest </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4476]]</td>
+ <td> Missing error message when registration mail fails to be sent </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4459]]</td>
+ <td> TemplateLogin messages not translated </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4458]]</td>
+ <td> Topic newsletter notifications in MailerContrib fail </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4453]]</td>
+ <td> A Set embedded in a list has problems </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4449]]</td>
+ <td> No (simple) way to create a Set </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4448]]</td>
+ <td> InterwikiPlugin: Change ISBN rule </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4440]]</td>
+ <td> reading the FORMFIELDs of another topic imposes its access rights </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4439]]</td>
+ <td> %INCLUDE breaks enumeration/tables when included topic has file attachments </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4435]]</td>
+ <td> Paragraphs not correctly handled </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4434]]</td>
+ <td> Patch for improper replacing of "0" with "" (empty string) in URLPARAM default value </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4432]]</td>
+ <td align="right"> causes an internal server error </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4426]]</td>
+ <td> HTMl embedded in lists breaks the translator </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4425]]</td>
+ <td> Empty bullets get a <code><br /></code> tag. </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4403]]</td>
+ <td> Error saving topic message not shown as code because of trailing space </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4402]]</td>
+ <td> Access check based on getWikiUserName (fails) vs. getWikiName (succeeds) </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4399]]</td>
+ <td> Add a note about adding a doc license to footer when installing TWiki </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4397]]</td>
+ <td> Authenticating through REST does not work in MAIN </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4383]]</td>
+ <td> {Register}{NeedVerification} shoud not be an expert setting and disabled by default </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4380]]</td>
+ <td><code>mailnotify</code> fails due to TWIki::Merge failing </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4378]]</td>
+ <td> default skin, and thus the classic skin, contains javascript </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4372]]</td>
+ <td> Custom META fields that don't have the <em>name</em> key are ignored by TWiki::Store </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4355]]</td>
+ <td> bulkregistration is unforgiving on TWikiTable format </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4349]]</td>
+ <td> TablePlugin generates invalid html attribute <code>maxcols</code></td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4347]]</td>
+ <td> Empty field values in searches are returned as strings containing "$value" </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4335]]</td>
+ <td> TablePlugin: TWikiTables in TWikiLists generate invalid html </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4333]]</td>
+ <td> OopsException allows anything from a URL to pass through to the generated HTML incl scripts </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4332]]</td>
+ <td> No error message for duplicate_activation </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4319]]</td>
+ <td> {SafeEnvPath} screws up windows </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4308]]</td>
+ <td> getListOfWebs() and webExists() disagree </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4300]]</td>
+ <td> TablePlugin overrides skin css AGAIN </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4284]]</td>
+ <td> Support topic permissions checking </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4280]]</td>
+ <td> Move hide-if-no-javascript functionality from TwistyPlugin to default templates </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4271]]</td>
+ <td> Update TwistyPlugin with TWiki 4 javascript files </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4269]]</td>
+ <td> Update TwistyContrib with TWiki 4 javascript files </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4260]]</td>
+ <td> Add MAKETEXT to all default templates </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4258]]</td>
+ <td> Get rid of default TH background color </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4257]]</td>
+ <td> Default templates and documentation topics assume pattern CSS classes </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4250]]</td>
+ <td> Pipe symbol (i.e. in SEARCH) breaks Form Definition Table </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4249]]</td>
+ <td> RegistrationApprovals is not a web </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4243]]</td>
+ <td> Malformed META embedded in text can crash TWiki </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4239]]</td>
+ <td> syntax error at /usr/lib/cgi-bin/TEST/lib/TWiki/ Users/ApacheHtpasswdUser.pm line 67, near "}" </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4236]]</td>
+ <td> Configure harmless errors confuse people when they have other unrelated errors. </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4229]]</td>
+ <td> Remove deprecated filename attribute from attach template </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4219]]</td>
+ <td> Add correct CSS class to select box </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4207]]</td>
+ <td> Usability: Warn if more than one {WebMasterEmail} e-mail address </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4204]]</td>
+ <td> Document how you become an admin user with new temporary admin login (sudo) </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4193]]</td>
+ <td> Show and hide WYSIWYG buttons based on COMPOSER setting </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4173]]</td>
+ <td> GROUPS variable kills server if there is a large group </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4166]]</td>
+ <td> TwistyPlugin: wrong use of plugin handlers </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4158]]</td>
+ <td> TWikiRegistration does not pass on multiple checkbox element values to UserForm. </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4157]]</td>
+ <td> tick_twiki.pl broken </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4156]]</td>
+ <td> Fixing twiki cgi for logging in </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4151]]</td>
+ <td> Javascript: twiki object overwritten </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4150]]</td>
+ <td> Add global setting to allow non-WikiWords </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4146]]</td>
+ <td> Documentation VarENCODE param typo </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4143]]</td>
+ <td> Remove max length on attachment comment </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4141]]</td>
+ <td> Topic templates are not documented </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4138]]</td>
+ <td> Doc bug in TWikiUpgradeGuide.html </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4128]]</td>
+ <td> Create default directive for non-view pages </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4126]]</td>
+ <td> WebSearch: Fix checkbox state based on url param web=all </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4088]]</td>
+ <td> Add css style to raw textarea </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4081]]</td>
+ <td> Broken Links to Topics and Subwebs </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4080]]</td>
+ <td> Downloading extension via configure sometimes end up in an "Invalid header block" message </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4071]]</td>
+ <td> Add dmg to mime.types </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4067]]</td>
+ <td> Hexadecimal character references do not work </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4063]]</td>
+ <td> Document how to reset a password with ApacheLogin </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4062]]</td>
+ <td> Reset password message doesn't make sense any more </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4060]]</td>
+ <td> template login Error message activated when there was no error </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4048]]</td>
+ <td> EditTablePlugin: Password shown in URL params after template login on direct sort urls (authenticated setups) </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4045]]</td>
+ <td> PatternSkin: More space in topic name fields and file field </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4043]]</td>
+ <td> attachments have bad user name display issues </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4042]]</td>
+ <td> Broken formfield "name" and "title" attributes </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4035]]</td>
+ <td> METASEARCH doc not complete. format option and probably more are missing in the doc </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4034]]</td>
+ <td> Topic rename: error in javascript so select all does not work </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4028]]</td>
+ <td> Authenticated twice; garbled CommentPlugin text </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4023]]</td>
+ <td> configure link for 'Expert mode' missing t= parameter to prevent caching </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4019]]</td>
+ <td> Remove preferences edit button from TWiki.TWikiPreferences </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4006]]</td>
+ <td> More options: do not show "View previous topic revision" when there is no previous version </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3991]]</td>
+ <td> Add <code>spaceOutWikiWord</code> to Func </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3989]]</td>
+ <td> Problematic Values for FINALPREFERENCES in Distribution </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3971]]</td>
+ <td> viewauth Redirect May Add Superfluous Slash </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3969]]</td>
+ <td> Emails may be 8bit, not 7bit </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3968]]</td>
+ <td> Base HREF is wrong when scripturls are changed </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3957]]</td>
+ <td> Mandatory fields will not accept 0 </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3955]]</td>
+ <td> RCS command-line settings should be EXPERT </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3949]]</td>
+ <td> Search 'Number of topics' does not show on first search on advanced regex searches </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3947]]</td>
+ <td> Better documentation on how to install CPAN libs (including a reference in the install doc) </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3940]]</td>
+ <td> PREFERENCE values not carried over to preview and then save </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3929]]</td>
+ <td> Make TOPICLIST topic parameter equivalent to other vars </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3921]]</td>
+ <td><code>renderWikiWordHandler</code> called at wrong place in Render.pm; change to support bracket notation </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3917]]</td>
+ <td> Add .changes API to Func </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3914]]</td>
+ <td> Some plugins cannot be downloaded using <code>configure</code></td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3911]]</td>
+ <td> default preview tmpl has major bug in release value="%REDIRECTTO" </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3909]]</td>
+ <td> Pattern skin template documentation update </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3902]]</td>
+ <td> Reset Password is broken in MAIN branch </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3900]]</td>
+ <td> New CARET preferences variable </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3897]]</td>
+ <td> Fix sanitizeAttachmentName </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3895]]</td>
+ <td> Structure the TWiki version number to make accessible from plugins (code included) </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3892]]</td>
+ <td> Do not automatically lock user homepages when this is not set in NewUserTemplate </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3890]]</td>
+ <td> EDITTABLE expands variables in table cells </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3889]]</td>
+ <td> $EXISTS() should default to topic in current web </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3885]]</td>
+ <td> Plugin installation doesn't work through some proxies </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3883]]</td>
+ <td> No rendering of TML after %BR% used in table cells and multiline bullets </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3879]]</td>
+ <td> Topic rename does not find URL references from topics in different web </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3876]]</td>
+ <td> Better documentation of <code>$FORMAT(PERCENT, ...)</code></td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3864]]</td>
+ <td><code>renderWikiWordHandler</code> is not documented </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3862]]</td>
+ <td> Parameter passed to preRenderingHandler incorrect </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3853]]</td>
+ <td> WEBLIST docco spelling error (selection=) </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3835]]</td>
+ <td> TWiki.TWikiSiteTools mentions geturl.pl, but does not point out the authentication problems with it </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3834]]</td>
+ <td> USERINFO{format="$groups"} always returns webDotWikiName identifiers </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3833]]</td>
+ <td> Cannot move attachment to topic with non-wikiword name </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3832]]</td>
+ <td>[[Main/BracketLinks]] are not updated during page renames </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3829]]</td>
+ <td> NativeSearch: give gentle warning when no parameters are passed to test.pl </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3822]]</td>
+ <td> Table rules for columns are invisible in Internet explorer </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3821]]</td>
+ <td> Document INCLUDE behaviour in TWikiAccessControl </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3813]]</td>
+ <td> Web reference gets inappropriately inserted into bracketed links inside verbatim tags. </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3812]]</td>
+ <td> Space in username not rejected when resetting password </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3806]]</td>
+ <td> add <code>true</code> and <code>false</code> to TWiki::isTrue </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3805]]</td>
+ <td> footerrows setting is ignored when adding rows </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3804]]</td>
+ <td> TemplateLogin.pm doesn't return the error from the underlying PasswordManager </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3803]]</td>
+ <td> %!USERINFO{format="$groups"}% crashes </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3796]]</td>
+ <td> Javascript: ensuring variables are local </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3790]]</td>
+ <td> Web statistic severely broken </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3787]]</td>
+ <td> TWiki.TWikiDocumentation jumps to top at double click </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3784]]</td>
+ <td> Rename across webs bugs </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3783]]</td>
+ <td> Pattern skin small template refactoring </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3780]]</td>
+ <td> Add Sanitize Attachment Name to TWiki::Func </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3779]]</td>
+ <td> Table with backslash breaks EditTablePlugin </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3778]]</td>
+ <td> Lock WebPreferences to person creating web </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3775]]</td>
+ <td> Commentplugin makes inappropriate line ending handling when targeting an anchor </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3772]]</td>
+ <td> TWiki::Func::getOopsUrl() doesn't support <code>def</code> parameter </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3771]]</td>
+ <td> Dutch translation files some special chars mangled </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3769]]</td>
+ <td> Can't create configuration subsection for plugins and contribs </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3765]]</td>
+ <td> configure docco for mail handler should say howto force twiki to use sendmail </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3760]]</td>
+ <td> With rename topic, topic texts are changed as well </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3759]]</td>
+ <td> MailerContrib not mailing groups </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3758]]</td>
+ <td> Remark "There is no size limit for uploaded files." is not relevant to users </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3756]]</td>
+ <td> TWikiRegistrationAgent produces wrongly formated entries </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3755]]</td>
+ <td> Need to document parameterized include </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3752]]</td>
+ <td> Doc fix to AdminSkillsAssumptions </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3748]]</td>
+ <td> EXTEND.pm fails to move directories across filesystems </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3743]]</td>
+ <td> Input bugs in SpreadSheetPlugin::Calc </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3742]]</td>
+ <td> Short description containing TML does not get rendered properly in PLUGINDESCRIPTIONS </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3738]]</td>
+ <td> Avoid "detailed instructions are beyond the scope of this document" </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3735]]</td>
+ <td> WYSIWYG broken for bolded WikiWords </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3727]]</td>
+ <td> Can't login; e-mail wiped out in .htpasswd entry </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3725]]</td>
+ <td> BulkRegister not functioning properly if password Manger is set to NONE </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3704]]</td>
+ <td> Incorrect number of topics indicated with multiple SEARCHes </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3703]]</td>
+ <td> in the size field of a form will crash the forms code </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3690]]</td>
+ <td> exec return an exit code of 1 for a perfectly valid grep </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3689]]</td>
+ <td> CommentPlugin location only works if it is above the %COMMENT... tag </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3688]]</td>
+ <td> Page loads unreasonable slow under IE with Twisty enabled (clone of 3582) </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3686]]</td>
+ <td> Make redirectto parameter work for rename </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3684]]</td>
+ <td> Over-complex CPAN installation instructions </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3673]]</td>
+ <td> Bad expression error in 'more' screen if parent is missing </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3668]]</td>
+ <td> Broken links in topic A if includes topic B in which InterWiki links are defined </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3653]]</td>
+ <td> Document standard extensions in release notes </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3652]]</td>
+ <td> I18N: Urls to file attachments that has umlauts only works in some browsers </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3646]]</td>
+ <td> Make edit form somewhat less spacious </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3641]]</td>
+ <td> Access key char invisible on hover </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3639]]</td>
+ <td> Extension installer in configure floods error_log when checking for installed plugins. </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3630]]</td>
+ <td> Topic URL parameter overwrites revision to which REVINFO variable refers </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3623]]</td>
+ <td> Can't delete attachment with pluses in file name </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3621]]</td>
+ <td> Improve visibility of attachment twisty </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3604]]</td>
+ <td> URL rendering cuts off first part of URL </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3594]]</td>
+ <td> Can't save template topic with mandatory form fields </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3592]]</td>
+ <td> Cleaning up Main.TWikiPreferences </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3583]]</td>
+ <td> 'configure' password gets saved as 'smtp' password (in plain text!) </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3581]]</td>
+ <td> Unwanted question mark link in bracket link text </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3580]]</td>
+ <td> redirectto implemented redundantly in several places </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3579]]</td>
+ <td> Usability: [Save] of preferences screen should support access key </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3578]]</td>
+ <td> Deprecate <code>permissionsSet</code> from Func </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3575]]</td>
+ <td> Usability: Use pub url instead of viewfile url in attachment table </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3570]]</td>
+ <td> Usability: Time consuming to create new topic </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3567]]</td>
+ <td> TablePlugin: css attributes priority of site/web preferences too agressive </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3486]]</td>
+ <td> Possible to create topics with unsupported characters </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3463]]</td>
+ <td> Document how to use .spec files for plugin setting in TWiki.TWikiPlugins </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3456]]</td>
+ <td> Doc is unclear that Space In Path Causes Error </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3438]]</td>
+ <td> UnprocessedBulkRegistrationLog is improperly formatted </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3375]]</td>
+ <td> Refactor object names for clarity </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3368]]</td>
+ <td> No existance check for topic used in <code>include</code></td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3367]]</td>
+ <td> EditTablePlugin ignores valid table syntax </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3362]]</td>
+ <td> Update doc topics that have forms </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3341]]</td>
+ <td> invalid Date: header in mailnotify </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3289]]</td>
+ <td> attach a filename with paraens and wikiwords </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3246]]</td>
+ <td> Fix save_error template </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3229]]</td>
+ <td> WysiwygPlugin alters things inside complex twiki vars so they break </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3158]]</td>
+ <td> Don't include anything when trying to include a non existing section </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3105]]</td>
+ <td> Usability: Misleading "Invalid Activation Code" error message </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3051]]</td>
+ <td> Wasted vertical space below edit box </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3038]]</td>
+ <td> NEWTOPICFGCOLOR and NEWTOPICBGCOLOR never used </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3009]]</td>
+ <td> Need clear definition of the impact of spaces on EditTable definition </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item2975]]</td>
+ <td> EditTablePlugin format fails for last item </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item2960]]</td>
+ <td> I18N: Using UTF8 in headers breaks header anchors </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item2915]]</td>
+ <td> Allow date format in form fields </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item2892]]</td>
+ <td> TWiki dies with SEARCH on topic that has form field named <code>*Foobar*</code></td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item2772]]</td>
+ <td> Mailto link should use %20 instead of for spaces </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item2690]]</td>
+ <td> EditTablePlugin: remove sort links from headers when editing the table </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item2632]]</td>
+ <td> Username vs WikiName is confusing in Configure </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item2615]]</td>
+ <td> Fully document exposed APIs </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item2520]]</td>
+ <td> WebExist uses WebPreferences as opposed to WebHome to determine the validity of a web </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item2354]]</td>
+ <td> FuncUsersContrib and MoreFuncContrib and FuncusersContrib should be merged into Func </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item2326]]</td>
+ <td> Remove the secret NEWTOPICLINKSYMBOL (was missing docs for <code>NEWTOPIC*</code> ) </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item2244]]</td>
+ <td> Documented METASEARCH parameter defaults are not the actual defaults </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item2221]]</td>
+ <td> .changes is hardcoded to 500 entries, affecting WebStatistics and MailerContrib </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item2108]]</td>
+ <td> Better installation doc for TWikiAdminGroup </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item2032]]</td>
+ <td> Some UTF8 characters in form values broken (CGI.pm interaction) </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item2005]]</td>
+ <td> Cannot change configure password without making other changes </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item1993]]</td>
+ <td> IE eats newlines </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item1985]]</td>
+ <td> Not possible to use CDATA in SEARCH output (prev: RSS feeds chokes on HTML entities in SEARCH results) </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item1965]]</td>
+ <td> ResetPassword usability </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item1870]]</td>
+ <td> Improvements to installation docs </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item1860]]</td>
+ <td> NewUserTemplate should be in Main </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item1852]]</td>
+ <td> Lease files are not deleted or renamed when you delete/rename topics with cancelled edit </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item1828]]</td>
+ <td> Rendering bug of headings when using MBCS as a heading string </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item1562]]</td>
+ <td> RcsFile::searchInWebContent doesn't check exit status of the grep command </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item1379]]</td>
+ <td> Table sorting confused when using variables. </td>
+ </tr>
+</table>
+
+## <a name="Enhancements"></a> Enhancements
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <td>[[BUGS/Item652]]</td>
+ <td><code>configure</code> plugins should be sorted case-insensitively </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4995]]</td>
+ <td> EditTablePlugin: Omit Edit button in print view </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4810]]</td>
+ <td> SpreadSheetPlugin: New FORMATTIMEDIFF() function </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4809]]</td>
+ <td> ConditionalBasedOnGroupMembership </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4709]]</td>
+ <td> Update small T-logo badge in bottom bar </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4599]]</td>
+ <td> Add timestamps to history revisions (rdiff) </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4568]]</td>
+ <td> Offer RSS feed on search results </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4548]]</td>
+ <td> Improve TOC display in TWiki documentation </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4547]]</td>
+ <td> Improve TWiki variables documentation </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4504]]</td>
+ <td> pop-ups need to pass extra url parameters </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4500]]</td>
+ <td> need a way to set preferences from TWiki::Func </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4473]]</td>
+ <td> check that we have a testable can_edit state </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4461]]</td>
+ <td> 'Changed' link should point to most recent changes, not the entire history </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4451]]</td>
+ <td> Add Bugs rule </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4351]]</td>
+ <td> Add a way to pass authentication information to an extra plugins repository </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4294]]</td>
+ <td> TablePlugin: put all css styling in head </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4279]]</td>
+ <td> TwistyContrib: support TwistyPlugin 1.4 </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4278]]</td>
+ <td> TwistyPlugin 1.4: remove ugly javascript init calls </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4275]]</td>
+ <td> Add Adobe Air to mimetypes </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4259]]</td>
+ <td> Simplify default templates more, and use CSS </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4241]]</td>
+ <td> CSS class <code>twikiUnvisited</code></td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4185]]</td>
+ <td> SlideShowPlugin: Add VarSLIDESHOWSTART and VarSLIDESHOWEND variable documentation </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4184]]</td>
+ <td> RenderListPlugin: Add VarRENDERLIST variable documentation </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4183]]</td>
+ <td> TablePlugin: Add VarTABLE variable documentation </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4182]]</td>
+ <td> EditTablePlugin: Add VarEDITTABLE variable documentation </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4181]]</td>
+ <td> CommentPlugin: Add VarCOMMENT variable documentation </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4180]]</td>
+ <td> SpreadSheetPlugin: Add VarCALC variable documentation </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4174]]</td>
+ <td> Add templatetopic url parameter to WebTopicCreator </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4153]]</td>
+ <td> Add control over TOC rendering </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4142]]</td>
+ <td> Template unification </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4140]]</td>
+ <td> Support standard escapes in IF statements </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4139]]</td>
+ <td> Configurable date format to enable 2007-05-25 format. </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4120]]</td>
+ <td> Main.TWikiUsers no longer in distribution but gets created from template if non existing </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4087]]</td>
+ <td> PatternSkin: visual update to form elements </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4075]]</td>
+ <td> Enhance MailerContrib To Allow Exclusion Of Webs </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4069]]</td>
+ <td> Normalise <code>viewfile</code> so it is able to use path syntax as well as the ?filename= syntax. </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4046]]</td>
+ <td> PatternSkin: Add RSS feed icon to WebLeftBar </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4044]]</td>
+ <td> Add RSS feed icon to TWikiDocGraphics </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item4041]]</td>
+ <td> Extend SEARCH to allow SQL-type queries over form fields </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3988]]</td>
+ <td> Japanese translation </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3854]]</td>
+ <td> show subwebs="" in WEBLIST relative to a web </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3841]]</td>
+ <td> Add expandStandardEscapes to TWiki::Func </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3801]]</td>
+ <td> Propose adding $admin attribute to USERINFO rather than appending "isAdmin()" to $group output </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3798]]</td>
+ <td> twikiNotification: CSS style for notifcations </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3774]]</td>
+ <td> Add getSessionKeys to Func </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3773]]</td>
+ <td> Handlers don't have access to the full topic </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3766]]</td>
+ <td> Enhance EditTablePlugin with DHTML; fix eating of newlines; graceful fallback calendar button; fix css styling </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3757]]</td>
+ <td> TWiki inserts html into text areas which have text in them </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3607]]</td>
+ <td> SEARCH summary should remove leading exclamation point </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3606]]</td>
+ <td> SpreadSheetPlugin doc work for 4.2 </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3552]]</td>
+ <td> Support interface to getting URLs in Func </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3530]]</td>
+ <td> Make scope="all" the default search in WebSearch </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3487]]</td>
+ <td> Need a way to tell if mod_perl is in use </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3321]]</td>
+ <td> Table column headers always centered </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3313]]</td>
+ <td> Make redirectto parameter work for upload </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3265]]</td>
+ <td> Existing attachments: change header from "Other attachments of" to "Attachments of" </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3250]]</td>
+ <td> Allow infinite expiry of cookies </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item3234]]</td>
+ <td> PatternSkin minor CSS changes for 4.2 </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item2123]]</td>
+ <td> Add new type=word search to search on word boundaries </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item1966]]</td>
+ <td> Poor/nonexistent revert-to-previous-version design </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item1772]]</td>
+ <td> Add a <code>?template=viewplain</code> template for plain view </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item1748]]</td>
+ <td> Attach help contains note for Internet Explorer 4 that can be removed now </td>
+ </tr>
+ <tr>
+ <td>[[BUGS/Item1582]]</td>
+ <td> configure needs a backlink to the TWiki/WebHome </td>
+ </tr>
+</table>
+
+**_Related Topic:_** [[TWikiHistory]]
<ul>
<li><a href="#Package =TWiki::Render="> Package TWiki::Render</a><ul>
<li><a href="#ClassMethod <strong>new</strong> ($session)"> ClassMethod new <tt>($session)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
<li><a href="#ObjectMethod <strong>renderParent</strong> ($we"> ObjectMethod renderParent <tt>($web,$topic,$meta,$params) -> $text</tt></a></li>
<li><a href="#ObjectMethod <strong>renderMoved</strong> ($web"> ObjectMethod renderMoved <tt>($web,$topic,$meta,$params) -> $text</tt></a></li>
- <li><a href="#ObjectMethod *render_FormField*"> ObjectMethod renderFormField <tt>($web,$topic,$meta,$params) -> $text</tt></a></li>
<li><a href="#ObjectMethod <strong>make_AnchorName</strong> ("> ObjectMethod makeAnchorName <tt>($anchorName,$compatibilityMode) -> $anchorName</tt></a></li>
- <li><a href="#ObjectMethod <strong>internalLink</strong> ($th"> ObjectMethod internalLink <tt>($theWeb,$theTopic,$theLinkText,$theAnchor,$doLink,$doKeepWeb) -> $html</tt></a></li>
+ <li><a href="#ObjectMethod <strong>internalLink</strong> ($th"> ObjectMethod internalLink <tt>($theWeb,$theTopic,$theLinkText,$theAnchor,$doLink,$doKeepWeb,$hasExplicitLinkLabel) -> $html</tt></a></li>
<li><a href="#ObjectMethod <strong>renderFORMFIELD</strong> ("> ObjectMethod renderFORMFIELD <tt>(%params,$topic,$web) -> $html</tt></a></li>
<li><a href="#ObjectMethod *get_RenderedVersio"> ObjectMethod getRenderedVersion <tt>($text,$theWeb,$theTopic) -> $html</tt></a></li>
<li><a href="#StaticMethod *verbatim_CallBack*"> StaticMethod verbatimCallBack <tt></tt></a></li>
<li><a href="#ObjectMethod <strong>_TML2PlainText</strong> ($"> ObjectMethod TML2PlainText <tt>($text,$web,$topic,$opts) -> $plainText</tt></a></li>
<li><a href="#ObjectMethod *protect_PlainText*"> ObjectMethod protectPlainText <tt>($text) -> $tml</tt></a></li>
<li><a href="#ObjectMethod *make_TopicSummary*"> ObjectMethod makeTopicSummary <tt>($theText,$theTopic,$theWeb,$theFlags) -> $tml</tt></a></li>
- <li><a href="#ObjectMethod *take_OutProtected*"> ObjectMethod takeOutProtected <tt>(\$text,$re,\%map) -> $text</tt></a></li>
- <li><a href="#ObjectMethod *put_BackProtected*"> ObjectMethod putBackProtected <tt>(\$text,\%map,$callback) -> $text</tt></a></li>
<li><a href="#ObjectMethod <strong>take_OutBlocks</strong> (\"> ObjectMethod takeOutBlocks <tt>(\$text,$tag,\%map) -> $text</tt></a></li>
<li><a href="#ObjectMethod <strong>put_BackBlocks</strong> (\"> ObjectMethod putBackBlocks <tt>(\$text,\%map,$tag,$newtag,$callBack) -> $text</tt></a></li>
<li><a href="#ObjectMethod *render_RevisionInf"> ObjectMethod renderRevisionInfo <tt>($web,$topic,$meta,$rev,$format) -> $string</tt></a></li>
<li><a href="#ObjectMethod *summariseChanges*"> ObjectMethod summariseChanges <tt>($user,$web,$topic,$orev,$nrev,$tml) -> $text</tt></a></li>
<li><a href="#ObjectMethod <strong>for_EachLine</strong> ($te"> ObjectMethod forEachLine <tt>($text,\&fn,\%options) -> $newText</tt></a></li>
+ <li><a href="#StaticMethod <strong>get_ReferenceRE</strong> ("> StaticMethod getReferenceRE <tt>($web,$topic,%options) -> $re</tt></a></li>
<li><a href="#StaticMethod *replace_TopicRefer"> StaticMethod replaceTopicReferences <tt>($text,\%options) -> $text</tt></a></li>
<li><a href="#StaticMethod *replace_WebReferen"> StaticMethod replaceWebReferences <tt>($text,\%options) -> $text</tt></a></li>
<li><a href="#ObjectMethod *replace_WebInterna"> ObjectMethod replaceWebInternalReferences <tt>(\$text,\%meta,$oldWeb,$oldTopic)</tt></a></li>
- <li><a href="#StaticMethod *render_FormFieldAr"> StaticMethod renderFormFieldArg <tt>($meta,$args) -> $text</tt></a></li>
<li><a href="#StaticMethod <strong>breakName</strong> ($text,"> StaticMethod breakName <tt>($text,$args) -> $text</tt></a></li>
+ <li><a href="#StaticMethod *protect_FormFieldV"> StaticMethod protectFormFieldValue <tt>($value,$attrs) -> $html</tt></a></li>
</ul>
</li>
</ul>
## <a name="ClassMethod <strong>new</strong> ($session)"></a> [[ClassMethod]] **new** `($session)`
-Creates a new renderer with initial state from preference values (NEWTOPICBGCOLOR, NEWTOPICFONTCOLOR NEWTOPICLINKSYMBOL LINKTOOLTIPINFO)
+Creates a new renderer
+
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
+
+Break circular references.
## <a name="ObjectMethod <strong>renderParent</strong> ($we"></a> [[ObjectMethod]] **renderParent** `($web,$topic,$meta,$params) -> $text`
Render moved meta-data
-## <a name="ObjectMethod <strong>render_FormField*"></a><a name="ObjectMethod *render_FormField</strong> "></a> [[ObjectMethod]] **renderFormField** `($web,$topic,$meta,$params) -> $text`
-
-Render meta-data for a single formfield
-
## <a name="ObjectMethod <strong>make_AnchorName</strong> ("></a> [[ObjectMethod]] **makeAnchorName** `($anchorName,$compatibilityMode) -> $anchorName`
-- `$anchorName` -
-- `$compatibilityMode` -
+- `$anchorName` - the unprocessed anchor name
+- `$compatibilityMode` - SMELL: compatibility with **what**?? Who knows. :-(
Build a valid HTML anchor name
-## <a name="ObjectMethod <strong>internalLink</strong> ($th"></a> [[ObjectMethod]] **internalLink** `($theWeb,$theTopic,$theLinkText,$theAnchor,$doLink,$doKeepWeb) -> $html`
+## <a name="ObjectMethod <strong>internalLink</strong> ($th"></a> [[ObjectMethod]] **internalLink** `($theWeb,$theTopic,$theLinkText,$theAnchor,$doLink,$doKeepWeb,$hasExplicitLinkLabel) -> $html`
Generate a link.
Note: Topic names may be spaced out. Spaced out names are converted to WikWords, for example, "spaced topic name" points to "SpacedTopicName".
- `$theWeb` - the web containing the topic
-- `$theTopic` - the topic to be lunk
+- `$theTopic` - the topic to be link
- `$theLinkText` - text to use for the link
- `$theAnchor` - the link anchor, if any
- `$doLinkToMissingPages` - boolean: false means suppress link for non-existing pages
- `$doKeepWeb` - boolean: true to keep web prefix (for non existing Web.TOPIC)
+- `$hasExplicitLinkLabel` - boolean: true in case of [[explicit link label|Main/TopicName]]
Called by \_handleWikiWord and \_handleSquareBracketedLink and by Func::internalLink
Makes a plain text summary of the given topic by simply trimming a bit off the top. Truncates to $TMTRUNC chars or, if a number is specified in $theFlags, to that length.
-## <a name="ObjectMethod <strong>take_OutProtected*"></a> [[ObjectMethod]] \*takeOutProtected `(\$text,$re,\%map) -> $text`
-
-- `$text` - Text to process
-- `$re` - Regular expression that matches tag expressions to remove
-- `\%map` - Reference to a hash to contain the removed blocks
-
-Return value: $text with blocks removed
-
-used to extract from $text comment type tags like <!DOCTYPE blah>
-
-WARNING: if you want to take out <!-- comments --> you _will_ need to re-write all the takeOuts to use a different placeholder
-
-## <a name="ObjectMethod <strong>put_BackProtected*"></a> [[ObjectMethod]] \*putBackProtected `(\$text,\%map,$callback) -> $text`
-
-Return value: $text with blocks added back
-
-- `\$text` - reference to text to process
-- `\%map` - map placeholders to blocks removed by takeOutBlocks
-- `$callback` - Reference to function to call on each block being inserted (optional)
-
-Reverses the actions of takeOutProtected.
-
## <a name="ObjectMethod <strong>take_OutBlocks</strong> (\"></a> [[ObjectMethod]] **takeOutBlocks** `(\$text,$tag,\%map) -> $text`
- `$text` - Text to process
And if you set $newtag to '', we replace the taken out block with the valuse itself
-- which i'm using to stop the rendering process, but then at the end put in the html directly (for tag. ---++ ObjectMethod \*renderRevisionInfo\* `($web,$topic,$meta,$rev,$format) -> $string` Obtain and render revision info for a topic. \* =$web= - the web of the topic \* =$topic= - the topic \* =$meta= if specified, get rev info from here. If not specified, or meta contains rev info for a different version than the one requested, will reload the topic \* =$rev= - the rev number, defaults to latest rev \* =$format= - the render format, defaults to =$rev - $time - $wikiusername= =$format= can contain the following keys for expansion: | =$web= | the web name | | =$topic= | the topic name | | =$rev= | the rev number | | =$comment= | the comment | | =$username= | the login of the saving user | | =$wikiname= | the wikiname of the saving user | | =$wikiusername= | the web.wikiname of the saving user | | =$date= | the date of the rev (no time) | | =$time= | the time of the rev | | =$min=, =$sec=, etc. | Same date format qualifiers as GMTIME | ---++ ObjectMethod \*summariseChanges\* `($user,$web,$topic,$orev,$nrev,$tml) -> $text` \* =$user= - user (null to ignore permissions) \* =$web= - web \* =$topic= - topic \* =$orev= - older rev \* =$nrev= - later rev \* =$tml= - if true will generate renderable TML (i.e. HTML with NOPs. if false will generate a summary suitable for use in plain text (mail, for example) Generate a (max 3 line) summary of the differences between the revs. If there is only one rev, a topic summary will be returned. If =$tml= is not set, all HTML will be removed. In non-tml, lines are truncated to 70 characters. Differences are shown using + and - to indicate added and removed text. ---++ ObjectMethod \*forEachLine\* `($text,\&fn,\%options) -> $newText` Iterate over each line, calling =\\&fn= on each. \\%options may contain: \* =pre= => true, will call fn for each line in pre blocks \* =verbatim= => true, will call fn for each line in verbatim blocks \* =noautolink= => true, will call fn for each line in =noautolink= blocks The spec of \\&fn is sub fn( \\$line, \\%options ) -> $newLine; the %options hash passed into this function is passed down to the sub, and the keys =in\_pre=, =in\_verbatim= and =in\_noautolink= are set boolean TRUE if the line is from one (or more) of those block types. The return result replaces $line in $newText. ---++ StaticMethod \*replaceTopicReferences\* `($text,\%options) -> $text` Callback designed for use with forEachLine, to replace topic references. \\%options contains: \* =oldWeb= => Web of reference to replace \* =oldTopic= => Topic of reference to replace \* =spacedTopic= => RE matching spaced out oldTopic \* =newWeb= => Web of new reference \* =newTopic= => Topic of new reference \* =inWeb= => the web which the text we are presently processing resides in \* =fullPaths= => optional, if set forces all links to full web.topic form For a usage example see TWiki::UI::Manage.pm ---++ StaticMethod \*replaceWebReferences\* `($text,\%options) -> $text` Callback designed for use with forEachLine, to replace web references. \\%options contains: \* =oldWeb= => Web of reference to replace \* =newWeb= => Web of new reference For a usage example see TWiki::UI::Manage.pm ---++ ObjectMethod \*replaceWebInternalReferences\* `(\$text,\%meta,$oldWeb,$oldTopic)` Change within-web wikiwords in $$text and $meta to full web.topic syntax. \\%options must include topics => list of topics that must have references to them changed to include the web specifier. ---++ StaticMethod \*renderFormFieldArg\* `($meta,$args) -> $text` Parse the arguments to a $formfield specification and extract the relevant formfield from the given meta data. \* =args= string containing name of form field In addition to the name of a field =args= can be appended with a commas followed by a string format (\\d+)([,\\s\*]\\.\\.\\.)?). This supports the formatted search function $formfield and is used to shorten the returned string or a hyphenated string. ---++ StaticMethod \*breakName\* `($text,$args) -> $text` \* =$text= - text to "break" \* =$args= - string of format (\\d+)([,\\s\*]\\.\\.\\.)?) Hyphenates $text every $1 characters, or if $2 is "..." then shortens to $1 characters and appends "..." (making the final string $1+3 characters long) \_Moved from Search.pm because it was obviously unhappy there, as it is a rendering function\_
+- which i'm using to stop the rendering process, but then at the end put in the html directly (for tag. ---++ ObjectMethod \*renderRevisionInfo\* `($web,$topic,$meta,$rev,$format) -> $string` Obtain and render revision info for a topic. \* =$web= - the web of the topic \* =$topic= - the topic \* =$meta= if specified, get rev info from here. If not specified, or meta contains rev info for a different version than the one requested, will reload the topic \* =$rev= - the rev number, defaults to latest rev \* =$format= - the render format, defaults to =$rev - $time - $wikiusername= =$format= can contain the following keys for expansion: | =$web= | the web name | | =$topic= | the topic name | | =$rev= | the rev number | | =$comment= | the comment | | =$username= | the login of the saving user | | =$wikiname= | the wikiname of the saving user | | =$wikiusername= | the web.wikiname of the saving user | | =$date= | the date of the rev (no time) | | =$time= | the time of the rev | | =$min=, =$sec=, etc. | Same date format qualifiers as GMTIME | ---++ ObjectMethod \*summariseChanges\* `($user,$web,$topic,$orev,$nrev,$tml) -> $text` \* =$user= - user (null to ignore permissions) \* =$web= - web \* =$topic= - topic \* =$orev= - older rev \* =$nrev= - later rev \* =$tml= - if true will generate renderable TML (i.e. HTML with NOPs. if false will generate a summary suitable for use in plain text (mail, for example) Generate a (max 3 line) summary of the differences between the revs. If there is only one rev, a topic summary will be returned. If =$tml= is not set, all HTML will be removed. In non-tml, lines are truncated to 70 characters. Differences are shown using + and - to indicate added and removed text. ---++ ObjectMethod \*forEachLine\* `($text,\&fn,\%options) -> $newText` Iterate over each line, calling =\\&fn= on each. \\%options may contain: \* =pre= => true, will call fn for each line in pre blocks \* =verbatim= => true, will call fn for each line in verbatim blocks \* =literal= => true, will call fn for each line in literal blocks \* =noautolink= => true, will call fn for each line in =noautolink= blocks The spec of \\&fn is =sub fn( $line, \\%options ) -> $newLine=. The %options hash passed into this function is passed down to the sub, and the keys =in\_literal=, =in\_pre=, =in\_verbatim= and =in\_noautolink= are set boolean TRUE if the line is from one (or more) of those block types. The return result replaces $line in $newText. ---++ StaticMethod \*getReferenceRE\* `($web,$topic,%options) -> $re` \* $web, $topic - specify the topic being referred to, or web if $topic is undef. \* %options - the following options are available \* =interweb= - if true, then fully web-qualified references are required. \* =grep= - if true, generate a GNU-grep compatible RE instead of the default Perl RE. \* =url= - if set, generates an expression that will match a TWiki URL that points to the web/topic, instead of the default which matches topic links in plain text. Generate a regular expression that can be used to match references to the specified web/topic. Note that the resultant RE will only match fully qualified (i.e. with web specifier) topic names and topic names that are wikiwords in text. Works for spaced-out wikiwords for topic names. The RE returned is designed to be used with =s///= ---++ StaticMethod \*replaceTopicReferences\* `($text,\%options) -> $text` Callback designed for use with forEachLine, to replace topic references. \\%options contains: \* =oldWeb= => Web of reference to replace \* =oldTopic= => Topic of reference to replace \* =newWeb= => Web of new reference \* =newTopic= => Topic of new reference \* =inWeb= => the web which the text we are presently processing resides in \* =fullPaths= => optional, if set forces all links to full web.topic form For a usage example see TWiki::UI::Manage.pm ---++ StaticMethod \*replaceWebReferences\* `($text,\%options) -> $text` Callback designed for use with forEachLine, to replace web references. \\%options contains: \* =oldWeb= => Web of reference to replace \* =newWeb= => Web of new reference For a usage example see TWiki::UI::Manage.pm ---++ ObjectMethod \*replaceWebInternalReferences\* `(\$text,\%meta,$oldWeb,$oldTopic)` Change within-web wikiwords in $$text and $meta to full web.topic syntax. \\%options must include topics => list of topics that must have references to them changed to include the web specifier. ---++ StaticMethod \*breakName\* `($text,$args) -> $text` \* =$text= - text to "break" \* =$args= - string of format (\\d+)([,\\s\*]\\.\\.\\.)?) Hyphenates $text every $1 characters, or if $2 is "..." then shortens to $1 characters and appends "..." (making the final string $1+3 characters long) \_Moved from Search.pm because it was obviously unhappy there, as it is a rendering function\_ ---++ StaticMethod \*protectFormFieldValue\* `($value,$attrs) -> $html` Given the value of a form field, and a set of attributes that control how to display that value, protect the value from further processing. The protected value is determined from the value of the field after: \* newlines are replaced with <br> or the value of $attrs->\{newline\} \* processing through breakName if $attrs->\{break\} is defined \* escaping of $vars if $attrs->\{protectdollar\} is defined \* | is replaced with &#124; or the value of $attrs->\{bar\} if defined
This object provides an interface to the outside world. All calls to system functions, or handling of file names, should be brokered by this object.
+NOTE: TWiki creates a singleton sandbox that is **shared** by all TWiki runs under a single mod\_perl instance. If any TWiki run modifies the sandbox, that modification will carry over in to subsequent runs. Be very, very careful!
+
<div>
<ul>
<li><a href="#Package =TWiki::Sandbox="> Package TWiki::Sandbox</a><ul>
<li><a href="#ClassMethod <strong>new</strong> ($os,$realOS)"> ClassMethod new <tt>($os,$realOS)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
<li><a href="#StaticMethod *untaintUnchecked*"> StaticMethod untaintUnchecked <tt>($string) -> $untainted</tt></a></li>
<li><a href="#StaticMethod *normalize_FileName"> StaticMethod normalizeFileName <tt>($string) -> $filename</tt></a></li>
<li><a href="#StaticMethod *sanitize_Attachmen"> StaticMethod sanitizeAttachmentName <tt>($fname) -> ($fileName,$origName)</tt></a></li>
Construct a new sandbox suitable for $os, setting flags for platform features that help. $realOS distinguishes Perl variants on platforms such as Windows.
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
+
+Break circular references.
+
## <a name="StaticMethod <strong>untaintUnchecked*"></a><a name="StaticMethod *untaintUnchecked</strong> "></a> [[StaticMethod]] **untaintUnchecked** `($string) -> $untainted`
Untaints $string without any checks (dangerous). If $string is undefined, return undef.
+# <a name="TWiki CGI and Command Line Scrip"></a> TWiki CGI and Command Line Scripts
+
+_Programs on the TWiki server performing actions such as rendering, saving and renaming topics._
+
+The TWiki scripts are located in the `twiki/bin` and `twiki/tools` directories. This topic describes the interfaces to some of those scripts. All scripts in the `twiki/bin` directory can be called from the CGI ([Common Gateway Interface](http://en.wikipedia.org/wiki/Common_Gateway_Interface)) environment or from the command line. The scripts in the `twiki/tools` directory can only be called from the command line.
+
<div>
<ul>
<li><a href="#TWiki CGI and Command Line Scrip"> TWiki CGI and Command Line Scripts</a><ul>
<li><a href="#=logon="> logon</a></li>
<li><a href="#=manage="> manage</a><ul>
<li><a href="#=action=createweb="> action=createweb</a></li>
- <li><a href="#=action=delete_UserAccount="> action=deleteUserAccount</a></li>
<li><a href="#=action=editSettings="> action=editSettings</a></li>
- <li><a href="#=action=bulkRegister="> action=bulkRegister</a></li>
<li><a href="#=action=saveSettings="> action=saveSettings</a></li>
- </ul>
- </li>
- <li><a href="#=oops="> oops</a></li>
- <li><a href="#=passwd="> passwd</a><ul>
+ <li><a href="#=action=bulkRegister="> action=bulkRegister</a></li>
<li><a href="#=action=changePassword="> action=changePassword</a></li>
+ <li><a href="#=action=resetPassword="> action=resetPassword</a></li>
+ <li><a href="#=action=delete_UserAccount="> action=deleteUserAccount</a></li>
</ul>
</li>
+ <li><a href="#=oops="> oops</a></li>
<li><a href="#=preview="> preview</a></li>
<li><a href="#=rdiff="> rdiff</a></li>
<li><a href="#=register="> register</a></li>
<li><a href="#=rename="> rename</a></li>
- <li><a href="#=resetpasswd="> resetpasswd</a></li>
<li><a href="#=rest="> rest</a><ul>
<li><a href="#Invocation Examples"> Invocation Examples</a></li>
</ul>
<li><a href="#=save="> save</a></li>
<li><a href="#=search="> search</a></li>
<li><a href="#=statistics="> statistics</a></li>
- <li><a href="#=twiki="> twiki</a></li>
<li><a href="#=upload="> upload</a></li>
<li><a href="#=view="> view</a></li>
<li><a href="#=viewfile="> viewfile</a></li>
</ul>
</div>
-# <a name="TWiki CGI and Command Line Scrip"></a> TWiki CGI and Command Line Scripts
-
-_Programs on the TWiki server performing actions such as rendering, saving and renaming topics._
-
-The TWiki scripts are located in the `twiki/bin` and `twiki/tools` directories. This topic describes the interfaces to some of those scripts. All scripts in the `twiki/bin` directory can be called from the CGI ([Common Gateway Interface](http://en.wikipedia.org/wiki/Common_Gateway_Interface)) environment or from the command line. The scripts in the `twiki/tools` directory can only be called from the command line.
-
## <a name="CGI Scripts"></a> CGI Scripts
Details on CGI scripts located in the `twiki/bin` directory.
</tr>
<tr>
<td><code>redirectto</code></td>
- <td> If the user continues from edit to save, and if the save process is successful, save will redirect to this topic or URL. The parameter value can be a <code>TopicName</code>, a <code>Web.TopicName</code>, or a URL.%BR% <strong><em>Note:</em></strong> Redirect to a URL only works if it is enabled in <code>configure</code> (Miscellaneous <code>{AllowRedirectUrl}</code>). </td>
+ <td> 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 <code>TopicName</code>, a <code>Web.TopicName</code>, or a URL.%BR% <strong><em>Note:</em></strong> Redirect to a URL only works if it is enabled in <code>configure</code> (Miscellaneous <code>{AllowRedirectUrl}</code>). </td>
<td> </td>
</tr>
</table>
</tr>
</table>
-#### <a name="=action=delete_UserAccount="></a> `action=deleteUserAccount`
+#### <a name="=action=editSettings="></a> `action=editSettings`
-Unregisters (removes) the currently logged-in user.
+No parameters
+
+#### <a name="=action=saveSettings="></a> `action=saveSettings`
<table border="1" cellpadding="0" cellspacing="0">
<tr>
<th bgcolor="#99CCCC"><strong> Default </strong></th>
</tr>
<tr>
- <td><code>password</code></td>
- <td> Users' password </td>
- <td> none </td>
+ <td><code>text</code></td>
+ <td> Text of the topic </td>
+ <td> '' </td>
+ </tr>
+ <tr>
+ <td><code>originalrev</code></td>
+ <td> Revision that the edit started on </td>
+ <td> Most recent revision </td>
+ </tr>
+ <tr>
+ <td><code>redirectto</code></td>
+ <td> If the savesettings process is successful, save will redirect to this topic or URL. The parameter value can be a <code>TopicName</code>, a <code>Web.TopicName</code>, or a URL.%BR% <strong><em>Note:</em></strong> Redirect to a URL only works if it is enabled in <code>configure</code> (Miscellaneous <code>{AllowRedirectUrl}</code>). </td>
</tr>
</table>
-#### <a name="=action=editSettings="></a> `action=editSettings`
-
-No parameters
+All other parameters may be interpreted as form fields, depending on the current form definition in the topic.
#### <a name="=action=bulkRegister="></a> `action=bulkRegister`
</tr>
</table>
-#### <a name="=action=saveSettings="></a> `action=saveSettings`
+#### <a name="=action=changePassword="></a> `action=changePassword`
+
+Change password, email address, or both, of a user.
<table border="1" cellpadding="0" cellspacing="0">
<tr>
<th bgcolor="#99CCCC"><strong> Default </strong></th>
</tr>
<tr>
- <td><code>text</code></td>
- <td> Text of the topic </td>
- <td> '' </td>
+ <td><code>username</code></td>
+ <td> god alone knows </td>
+ <td><em>none</em></td>
</tr>
<tr>
- <td><code>originalrev</code></td>
- <td> Revision that the edit started on </td>
- <td> Most recent revision </td>
+ <td><code>oldpassword</code></td>
+ <td> current password </td>
+ <td><em>none</em></td>
+ </tr>
+ <tr>
+ <td><code>password</code></td>
+ <td> new password </td>
+ <td><em>none</em></td>
+ </tr>
+ <tr>
+ <td><code>passwordA</code></td>
+ <td> new password confirmation </td>
+ <td><em>none</em></td>
+ </tr>
+ <tr>
+ <td><code>email</code></td>
+ <td> new email address </td>
+ <td><em>none</em></td>
</tr>
</table>
-All other parameters may be interpreted as form fields, depending on the current form definition in the topic.
+`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.
-### <a name="=oops="></a> `oops`
-
-This script is mainly used for rendering pages containing error messages, though it is also used for some functional actions such as manage pages (move topic etc).
+#### <a name="=action=resetPassword="></a> `action=resetPassword`
-`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:
+Reset the password for a single or multiple users
<table border="1" cellpadding="0" cellspacing="0">
<tr>
<th bgcolor="#99CCCC"><strong> Default </strong></th>
</tr>
<tr>
- <td><code>template</code></td>
- <td> Name of the template file to display </td>
- <td> </td>
- </tr>
- <tr>
- <td><code>def</code></td>
- <td> Optional, can be set to the name of a single definition within <code>template</code>. This definition will be instantiated in the <code>template</code> wherever <code>%INSTANTIATE%</code> is seen. This lets you use a single template file for many messages. For an example, see <code>oopsmanagebad.tmpl</code>. </td>
- <td> </td>
+ <td><code>LoginName</code></td>
+ <td><strong>list</strong> of usernames to reset </td>
+ <td> none - error if not set </td>
</tr>
<tr>
- <td><code>paramN</code></td>
- <td> Where N is an integer from 1 upwards. These values will be substituted into <code>template</code> for <code>%PARAM1%</code> etc. </td>
- <td> </td>
+ <td><code>Introduction</code></td>
+ <td> message to be sent alongside the reset, most often used to announce to the user that they have been given an account. </td>
+ <td> '' </td>
</tr>
</table>
-### <a name="=passwd="></a> `passwd`
+This is used by [[BulkResetPassword]] and [[ResetPassword]]. Only administrators can provide a list of [[LoginNames]], non-admins can only provide a single [[LoginName]].
+
+[[BulkRegistration]] provides the means to create multiple accounts but it does not announce those accounts to the users who own them. [[BulkResetPassword]] is used to assign the passwords, the Introduction is used to explain why they are receiving the mail.
+
+#### <a name="=action=delete_UserAccount="></a> `action=deleteUserAccount`
+
+Unregisters (removes) the currently logged-in user.
<table border="1" cellpadding="0" cellspacing="0">
<tr>
<th bgcolor="#99CCCC"><strong> Default </strong></th>
</tr>
<tr>
- <td><code>action</code></td>
- <td> one of <code>changePassword</code> or <code>resetPassword</code></td>
+ <td><code>password</code></td>
+ <td> Users' password </td>
<td> none </td>
</tr>
</table>
-Other parameters as described under `manage`, `action=changePassword`.
+### <a name="=oops="></a> `oops`
-#### <a name="=action=changePassword="></a> `action=changePassword`
+This script is mainly used for rendering pages containing error messages, though it is also used for some functional actions such as manage pages (move topic etc).
+
+`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:
<table border="1" cellpadding="0" cellspacing="0">
<tr>
<th bgcolor="#99CCCC"><strong> Default </strong></th>
</tr>
<tr>
- <td><code>username</code></td>
- <td> Username </td>
- <td> </td>
- </tr>
- <tr>
- <td><code>oldpassword</code></td>
- <td> Existing password (plain text) </td>
- <td> </td>
- </tr>
- <tr>
- <td><code>password</code></td>
- <td> New password (plain text) </td>
+ <td><code>template</code></td>
+ <td> Name of the template file to display </td>
<td> </td>
</tr>
<tr>
- <td><code>passwordA</code></td>
- <td> New password confirmation (plain text) </td>
+ <td><code>def</code></td>
+ <td> Optional, can be set to the name of a single definition within <code>template</code>. This definition will be instantiated in the <code>template</code> wherever <code>%INSTANTIATE%</code> is seen. This lets you use a single template file for many messages. For an example, see <code>oopsmanagebad.tmpl</code>. </td>
<td> </td>
</tr>
<tr>
- <td><code>TopicName</code></td>
- <td> ? </td>
+ <td><code>paramN</code></td>
+ <td> Where N is an integer from 1 upwards. These values will be substituted into <code>template</code> for <code>%PARAM1%</code> etc. </td>
<td> </td>
</tr>
</table>
<td> if defined, a non-wikiword is acceptable for the new topic name </td>
<td> </td>
</tr>
-</table>
-
-### <a name="=resetpasswd="></a> `resetpasswd`
-
-Reset the password for a single or multiple users
-
-<table border="1" cellpadding="0" cellspacing="0">
<tr>
- <th bgcolor="#99CCCC"><strong> Parameter </strong></th>
- <th bgcolor="#99CCCC"><strong> Description </strong></th>
- <th bgcolor="#99CCCC"><strong> Default </strong></th>
- </tr>
- <tr>
- <td><code>LoginName</code></td>
- <td><strong>list</strong> of usernames to reset </td>
- <td> none - error if not set </td>
- </tr>
- <tr>
- <td><code>Introduction</code></td>
- <td> message to be sent alongside the reset, most often used to announce to the user that they have been given an account. </td>
- <td> '' </td>
+ <td><code>redirectto</code></td>
+ <td> If the rename process is successful, rename will redirect to this topic or URL. The parameter value can be a <code>TopicName</code>, a <code>Web.TopicName</code>, or a URL.%BR% <strong><em>Note:</em></strong> Redirect to a URL only works if it is enabled in <code>configure</code> (Miscellaneous <code>{AllowRedirectUrl}</code>). </td>
+ <td> </td>
</tr>
</table>
-This is used by [[BulkResetPassword]] and [[ResetPassword]]. Only users belonging to the [[TWikiAdminGroup]] can provide a list of [[LoginNames]], non-admins can only provide a single [[LoginName]].
-
-[[BulkRegistration]] provides the means to create multiple accounts but it does not announce those accounts to the users who own them. [[BulkResetPassword]] is used to assign the passwords, the Introduction is used to explain why they are receiving the mail.
-
### <a name="=rest="></a> `rest`
This REST ([Representational State Transfer](http://en.wikipedia.org/wiki/REST)) script can be invoked via http in the same way as the other TWiki scripts (see **Invocation Examples**, below) to execute a function that is associated to a "subject" and a "verb" (see below). These functions are usually registered by plugins using the `TWiki::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.
</tr>
<tr>
<td><code>action_delRev</code></td>
- <td><strong>Administrators only</strong> delete the most recent revision of the topic - all other parameters are ignored. You have to be a member of [[Main/TWikiAdminGroup]] to use this, and not all store implementations will support it. </td>
+ <td><strong>Administrators only</strong> 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. </td>
<td> </td>
</tr>
<tr>
<td><code>action_repRev</code></td>
- <td><strong>Administrators only</strong> replace the text of the most recent revision of the topic with the text in the <code>text</code> parameter. <code>text</code> must included embedded meta-data tags. All other parameters are ignored. You have to be a member of [[Main/TWikiAdminGroup]] to use this, and not all store implementations will support it. </td>
+ <td><strong>Administrators only</strong> replace the text of the most recent revision of the topic with the text in the <code>text</code> parameter. <code>text</code> 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. </td>
<td> </td>
</tr>
<tr>
<td> N/A </td>
</tr>
<tr>
- <td><code>web="Name"</code><br /><code>web="Main, Know"</code><br /><code>web="all"</code></td>
+ <td><code>web="Name"</code><br /><code>web="%USERSWEB%, Know"</code><br /><code>web="all"</code></td>
<td> Comma-separated list of webs to search. See [[Main/TWikiVariables#VarSEARCH]] for more details. </td>
<td> Current web </td>
</tr>
</tr>
<tr>
<td><code>date="..."</code></td>
- <td> limits the results to those pages with latest edit time in the given [[Main/TimeInterval]]. </td>
+ <td> limits the results to those pages with latest edit time in the given [[Main/TimeSpecifications#TimeIntervals]]. </td>
<td> All results </td>
</tr>
<tr>
see [[TWikiSiteTools#WebStatistics_site_statistics]] for updating statistics using cron.
-### <a name="=twiki="></a> `twiki`
-
-Single-script interface to the functionality of all the other scripts. Experimental, not for production use. Read the code if you want to know more.
-
### <a name="=upload="></a> `upload`
Uploads an attachment to a topic. The HTTP request is expected to be in `multipart/form-data` format.
</tr>
<tr>
<td><code>section</code></td>
- <td> Allows to view only a part of the topic delimited by a named section (see [[TWiki/VarSTARTSECTION]]). If the given section is not present, no topic content is displayed. </td>
+ <td> Allows to view only a part of the topic delimited by a named section (see %SYSTEMWEB%.VarSTARTSECTION). If the given section is not present, no topic content is displayed. </td>
<td> </td>
</tr>
<tr>
<td> Allows you to specify a different skin template, overriding the 'view' template the view script would normally use. The default template is <code>view</code>. For example, you could specify [[%WEB%/%TOPIC%?template=edit]]. This is mainly useful when you have specialised templates for a TWiki Application. </td>
<td> </td>
</tr>
+ <tr>
+ <td><code>topic</code></td>
+ <td> 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} </td>
+ <td> </td>
+ </tr>
</table>
%X% For historical reasons, the view script has a special interpretation of the `text` skin. In earlier TWiki versions the `skin=text` parameter was used like this: `http://.../view/MyWeb/MyTopic?skin=text&contenttype=text/plain&raw=on` which shows the topic as plain text; useful for those who want to download plain text for the topic. Using `skin=text` this way is **DEPRECATED**, use `raw=text` instead.
</tr>
</table>
+Instead of using the `filename` parameter, you can append the attachment name to the end of the URL path (after the topic) e.g. `http://www.dementia.org/twiki/viewfile/Webname/TopicName/Attachment.gif`
+
## <a name="Command Line Scripts"></a> Command Line Scripts
Details on command line scripts located in the `twiki/tools` directory.
<ul>
<li><a href="#Package =TWiki::Search="> Package TWiki::Search</a><ul>
<li><a href="#ClassMethod <strong>new</strong> ($session)"> ClassMethod new <tt>($session)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
<li><a href="#StaticMethod <strong>get_TextPattern</strong> ("> StaticMethod getTextPattern <tt>($text,$pattern)</tt></a></li>
<li><a href="#ObjectMethod <strong>searchWeb</strong> (...)"> ObjectMethod searchWeb <tt>(...)</tt></a></li>
+ <li><a href="#StaticMethod *display_FormField*"> StaticMethod displayFormField <tt>($meta,$args) -> $text</tt></a></li>
</ul>
</li>
</ul>
Constructor for the singleton Search engine object.
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
+
+Break circular references.
+
## <a name="StaticMethod <strong>get_TextPattern</strong> ("></a> [[StaticMethod]] **getTextPattern** `($text,$pattern)`
Sanitise search pattern - currently used for [[FormattedSearch]] only
If `inline` is set, then the results are **not** decorated with the search template head and tail blocks.
+The function will throw Error::Simple if it encounters any problems with the syntax of the search string.
+
Note: If `format` is set, `template` will be ignored.
Note: For legacy, if `regex` is defined, it will force type='regex'
+If `type="word"` it will be changed to `type="keyword"` with `wordBoundaries=1`. This will be used for searching with scope="text" only, because scope="topic" will do a Perl search on topic names.
+
SMELL: If `template` is defined `bookview` will not work
SMELL: it seems that if you define `_callback` or `inline` then you are responsible for converting the TML to HTML yourself!
FIXME: `callback` cannot work with format parameter (consider format='| $topic |'
+
+## <a name="StaticMethod <strong>display_FormField*"></a> [[StaticMethod]] \*displayFormField `($meta,$args) -> $text`
+
+Parse the arguments to a $formfield specification and extract the relevant formfield from the given meta data.
+
+- `args` string containing name of form field
+
+In addition to the name of a field `args` can be appended with a commas followed by a string format (\\d+)([,\\s\*]\\.\\.\\.)?). This supports the formatted search function $formfield and is used to shorten the returned string or a hyphenated string.
>
> [[WikiName]]
>
-> . If your TWiki installation doesn't require a log-in, TWiki gives everyone the same username:
->
-> [[TWikiGuest]]
->
-> .
+> . If your TWiki installation doesn't require a log-in, TWiki gives everyone the same username: %USERSWEB%.TWikiGuest.
## <a name="Disclaimer"></a> Disclaimer
+# <a name="TWiki Site Tools"></a> TWiki Site Tools
+
+_Utilities for searching, navigation, and monitoring site activity_
+
+TWiki Site Tools include utilities for navigating, searching and keeping up with site activity. Preferences can be configured by web or site-wide. You are currently in the **%SYSTEMWEB%** web. In particular, TWiki provides two highly configurable, automated site monitoring tools, **WebNotify**, to e-mail alerts when topics are edited, and **WebStatistics**, to generate detailed activity reports.
+
<div>
<ul>
<li><a href="#TWiki Site Tools"> TWiki Site Tools</a><ul>
<li><a href="#WebNotify - recent changes alert"> WebNotify - recent changes alert</a></li>
<li><a href="#WebSearch - search TWiki site"> WebSearch - search TWiki site</a></li>
<li><a href="#WebChanges - what's new"> WebChanges - what's new</a></li>
+ <li><a href="#WebRss and _WebAtom - news feeds"> WebRss and WebAtom - news feeds on recent changes</a></li>
<li><a href="#WebIndex - list of topics"> WebIndex - list of topics</a></li>
<li><a href="#WebStatistics - site statistics"> WebStatistics - site statistics</a><ul>
<li><a href="#Configuring for automatic operat"> Configuring for automatic operation</a></li>
</ul>
</li>
<li><a href="#Site Permissions"> Site Permissions</a></li>
+ <li><a href="#Help with crontab"> Help with crontab</a></li>
</ul>
</li>
</ul>
</div>
-# <a name="TWiki Site Tools"></a> TWiki Site Tools
-
-_Utilities for searching, navigation, and monitoring site activity_
-
-TWiki Site Tools include utilities for navigating, searching and keeping up with site activity. Preferences can be configured by web or site-wide. You are currently in the **TWiki** web. In particular, TWiki provides two highly configurable, automated site monitoring tools, **WebNotify**, to e-mail alerts when topics are edited, and **WebStatistics**, to generate detailed activity reports.
-
<a name="WebNotify"></a>
## <a name="WebNotify - recent changes alert"></a><a name="_WebNotify - recent changes aler"></a> WebNotify - recent changes alert
- You can create a [[WebNotify]] link using [[TWikiVariables]] with <code>**%NOTIFYTOPIC%**</code>
-You can also use `%MAINWEB%` instead of `Main`, but this is not necessary even if you have renamed the main web by configuring `{MainWebName}` in [configure](http://www.dementia.org/twiki/configure).
+You can also use `%USERSWEB%` instead of `Main`, but this is not necessary even if you have renamed the main web by configuring `{MainWebName}` in [configure](http://www.dementia.org/twiki/configure).
<a name="WebSearch"></a>
> %SEARCH{ ".*" web="%INCLUDINGWEB%" type="regex" nosearch="on" order="modified"%BR% reverse="on"
> limit="50" }%
+<a name="WebRssAndAtom"></a>
+
+## <a name="WebRss and _WebAtom - news feeds"></a><a name="_WebRss and _WebAtom - news feed"></a> WebRss and WebAtom - news feeds on recent changes
+
+You can point your news reader at [[WebRss]] and [[WebAtom]] to find out what is new in a TWiki web. [[WebRssBase]] and [[WebAtomBase]] have the details. Like [[WebChanges]], this is based on a `%SEARCH{}%`.
+
<a name="WebIndex"></a>
## <a name="WebIndex - list of topics"></a><a name="_WebIndex - list of topics"></a> WebIndex - list of topics
- Call the `twiki/bin/statistics` script from a cron job, once a day is recommended. This will update the [[WebStatistics]] topics in all webs.
- **_Attention:_** The script must run as the same user as the CGI scripts are running, which is user `nobody` on many systems. Example crontab entry: %BR% `0 0 * * * (cd /path/to/twiki/bin; ./statistics >/dev/null 2>&1)`
- There is a workaround in case you can't run the script as user `nobody` : Run the utility `twiki/tools/geturl.pl` in your cron job and specify the URL of the `twiki/bin/statistics` script as a parameter. Example: %BR% `0 0 * * * (cd /path/to/twiki/tools; ./geturl.pl mydomain.com /urlpath/to/twiki/bin/statistics >/dev/null 2>&1)`
+ - **_NOTE:_** `geturl.pl` will do a TWiki CGI request as the TWikiGuest user, so if you use this workaround, the WebStatistics topics you are updating will have to be writable by TWikiGuest.
When running from the command line or a cron job, you can pass parameters to the script like this:
- The `twiki/bin/statistics` script can also be executed as a CGI script, just enter the URL in your browser. Examples:
- Update current month for all webs you have access to: %BR% `http://www.dementia.org/twiki/statistics`
- - Update current month for Main web only: %BR% `http://www.dementia.org/twiki/statistics/Main`
- - Update Jun 2010 for Main web: %BR% `http://www.dementia.org/twiki/statistics/Main?logdate=201006`
+ - Update current month for %USERSWEB% web only: %BR% `http://www.dementia.org/twiki/statistics/%USERSWEB%`
+ - Update Jun 2010 for %USERSWEB% web: %BR% `http://www.dementia.org/twiki/statistics/%USERSWEB%?logdate=201006`
- Update Jun 2010 for the ProjectX, ProjectY and ProjectZ webs: %BR% `http://www.dementia.org/twiki/statistics?logdate=201006;webs=ProjectX,ProjectY,ProjectZ`
<a name="LogFiles"></a>
- The file name is `log<year><month>.txt`
- Example path name: `twiki/logs/log201006.txt`
- Each access gets logged as: %BR% `| <time> | <wikiusername> | <action> | <web>.<topic> | <extra info> | <IP address> |`
-- Example log entry: %BR% <code>| 29 Jun 2010 - 12:02 | [[TWikiGuest]] | view | [[WebRss]] | | 66.124.232.02 |</code>
+- Example log entry: %BR% `| 29 Jun 2010 - 12:08 | %USERSWEB%.TWikiGuest | view | %SYSTEMWEB%.WebRss | | 66.124.232.02 |`
- Actions are logged if enabled in [configure](http://www.dementia.org/twiki/configure) by the **\{Log\}\{_action_\}** flags
- Logged actions: <table border="1" cellpadding="0" cellspacing="0">
<tr>
<td> when moving attachment: <code>Attachment filename moved to Newweb.NewTopic</code></td>
</tr>
<tr>
- <td> passwd </td>
- <td><code>resetpasswd</code></td>
- <td>[[Main/LoginName]], [[Main/WikiName]], E-mail address, success code from addUserPassword </td>
- </tr>
- <tr>
- <td> passwd </td>
- <td><code>changepasswd</code></td>
- <td>[[Main/LoginName]], [[Main/WikiName]]</td>
- </tr>
- <tr>
<td> save </td>
<td><code>save</code></td>
<td> when replacing existing revision: <code>repRev 3</code> %BR% when user checks the minor changes box: <code>dontNotify</code> %BR% when user changes attributes to an exising attachment: <code>filename.ext</code></td>
**For Unix platforms:** Edit the `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 2 * * * (cd /path/to/twiki/bin; ./mailnotify -q)
+ 0 1 * * * (cd /path/to/twiki/bin; ./mailnotify -q)
-The above line will run mailnotify nightly at 02:00. The `-q` switch suppresses all normal output.
+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.
- [[TWikiAccessControl]] describes how to restrict read and write access to topics and webs, by users and groups
- [[SitePermissions]] lists the permissions settings of the webs on this TWiki site
+## <a name="Help with crontab"></a> Help with crontab
+
+The crontab command is used to schedule commands to be executed periodically.
+
+- Wikipedia.org:Crontab - crontab documentation
+- [pycron](http://www.kalab.com/freeware/pycron/pycron.htm) - crontab for Windows
+
**_Related Topics:_** [[AdminDocumentationCategory]], [[AdminToolsCategory]]
+
+-- **_Contributors:_** TWiki:Main.MikeMannix, TWiki:Main.PeterThoeny, TWiki:Main.CrawfordCurrie, TWiki:Main.KennethLavrsen, TWiki:Main.SvenDowideit
+# <a name="TWiki Skins"></a> TWiki Skins
+
+_Skins overlay regular templates to give different looks and feels to TWiki screens._
+
<div>
<ul>
<li><a href="#TWiki Skins"> TWiki Skins</a><ul>
</ul>
</div>
-# <a name="TWiki Skins"></a> TWiki Skins
-
-_Skins overlay regular templates to give different looks and feels to TWiki screens._
-
## <a name="Overview"></a> Overview
TWiki uses [[TWikiTemplates]] files as the basis of all the screens it uses to interact with users. Each screen has an associated template file that contains the basic layout of the screen. This is then filled in by the code to generate what you see in the browser.
-TWiki ships with a default set of template files that give a basic look-and-feel. TWiki also includes support for _skins_ that can be selected to give different, more sophisticated, look and feels. A default TWiki installation will usually start up with the [[PatternSkin]] already selected. Skins may also be defined by third parties and loaded into a TWiki installation to give more options. To see how TWiki looks when **no** skin is selected, [[view this topic with a non-existant skin|%WEB%/%TOPIC%?skin=not_a_skin]].
+TWiki ships with a default set of template files that give a very basic, CSS-themable, look-and-feel. TWiki also includes support for _skins_ that can be selected to give different, more sophisticated, look and feels. A default TWiki installation will usually start up with the [[PatternSkin]] already selected. Skins may also be defined by third parties and loaded into a TWiki installation to give more options. To see how TWiki looks when **no** skin is selected, [[view this topic with a non-existant skin|%WEB%/%TOPIC%?skin=not_a_skin]].
Topic text is not affected by the choice of skin, though a skin can be defined to use a CSS (Cascading Style Sheet), which can sometimes give a radically different appearance to the text.
## <a name="Changing the default TWiki skin"></a> Changing the default TWiki skin
-TWiki default ships with the skin [[PatternSkin]] activated. If 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]].
+TWiki default ships with the skin [[PatternSkin]] activated. You can set the skin for the whole site, a single web or topic, or for each user individually, by setting the SKIN variable to the name of a skin. If the skin you select doesn't exist, then TWiki will pick up the default templates.
## <a name="Defining Skins"></a> Defining Skins
-You may want to define your own skin, for example to comply with corporate web guidelines, or because you have a aesthetic vision that you want to share.
+You may want to define your own skin, for example to comply with corporate web guidelines, or because you have a aesthetic vision that you want to share. There are a couple of places you an start doing this.
The [[TWikiTemplates]] files used for skins are located in the `twiki/templates` directory and are named according to the skin: <code>**<scriptname>.<skin>.tmpl**</code>. Skin files may also be defined in TWiki topics - see [[TWikiTemplates]] for details.
To start creating a new skin, copy the default [[TWikiTemplates]] (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 TWiki can be configured to fall back to another skin if a template is not defined in your skin. Name the files as described above (for example `view.myskin.tmpl`.
-For your own TWiki skin you are encouraged to show a small 80x31 pixel [<img src="http://www.dementia.org/twiki//view/TWiki/TWikiLogos/T-logo-80x15.gif" width="80" height="15" alt="This site is powered by the TWiki collaboration platform" title="This site is powered by the TWiki collaboration platform" />](http://twiki.org/) logo at the bottom of your skin:
+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]].
+
+For your own TWiki skin you are encouraged to show a small 80x31 pixel [<img src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiLogos/T-logo-80x15.gif" width="80" height="15" alt="This site is powered by the TWiki collaboration platform" title="This site is powered by the TWiki collaboration platform" />](http://twiki.org/) logo at the bottom of your skin:
-`<a href="http://twiki.org/"><img src="%PUBURL%/%TWIKIWEB%/TWikiLogos/T-logo-80x15.gif" alt="This site is powered by the TWiki collaboration platform" width="80" height="15" title="This site is powered by the TWiki collaboration platform" border="0" /></a>`
+`<a href="http://twiki.org/"><img src="%PUBURL%/%SYSTEMWEB%/TWikiLogos/T-logo-80x15.gif" alt="This site is powered by the TWiki collaboration platform" width="80" height="15" title="This site is powered by the TWiki collaboration platform" border="0" /></a>`
The standard TWiki skins show the logo in the `%WEBCOPYRIGHT%` variable.
and then set `SKIN=yourlocal,pattern`.
-Because [[ClassicSkin]] and the default templates use the same Template definition names, you can over-ride the edit links in them (or any skin derived from them) using the same `view.yourlocal.tmpl` (just set SKIN=yourlocal,classic either in [[TWikiPreferences]] for globally, or a Web's Webname.WebPreferences for a particular web)
+Because [[ClassicSkin]] and the default templates use the same Template definition names, you can over-ride the edit links in them (or any skin derived from them) using the same `view.yourlocal.tmpl` (just set SKIN=yourlocal,classic either in %USERSWEB%.TWikiPreferences for globally, or a Web's Webname.WebPreferences for a particular web)
## <a name="Variables in Skins"></a> Variables in Skins
<td> Navigate: </td>
<td><select name="sel" onchange="this.form.topic.value=this.options[this.selectedIndex].value; this.form.submit()"><option selected value="">...</option>
<option value="http://twiki.org/">Intranet home</option>
- <option value="Main.TWikiUsers">Employee index</option>
- <option value="Main.WebHome">Main web</option>
- <option value="TWiki.WebHome">TWiki web</option>
+ <option value="%USERSWEB%.TWikiUsers">Employee index</option>
+ <option value="%USERSWEB%.WebHome">%USERSWEB% web</option>
+ <option value="%SYSTEMWEB%.WebHome">%SYSTEMWEB% web</option>
<option value="http://www.google.com/">Google</option>
<option value="http://www.yahoo.com/">Yahoo!</option></select></td>
</tr>
- To see how CSS is used in the default TWiki skin, see: [[PatternSkin]]
- If you write a complete new skin, this is the syntax to use in a template file:
- <style type='text/css' media='all'>@import url('%PUBURLPATH%/%TWIKIWEB%/MySkin/mystyle.css');</style>
+ <style type='text/css' media='all'>@import url('%PUBURLPATH%/%SYSTEMWEB%/MySkin/mystyle.css');</style>
## <a name="Attachment Tables"></a> Attachment Tables
</tr>
<tr>
<td><code>%A_URL%</code></td>
- <td> URL that will recover the file </td>
+ <td><code>viewfile</code> URL that will recover the file </td>
</tr>
<tr>
<td><code>%A_REV%</code></td>
</tr>
<tr>
<td><code>%A_FILE%</code></td>
- <td> The name of the file </td>
+ <td> The name of the file. To get the 'pub' url of the file, use <code>%PUBURL%/%WEB%/%TOPIC%/%A_FILE%</code></td>
</tr>
<tr>
<td><code>%A_SIZE%</code></td>
<div>
<ul>
<li><a href="#Package =TWiki::Store="> Package TWiki::Store</a><ul>
- <li><a href="#ClassMethod <strong>new</strong> ()"> ClassMethod new <tt>()</tt></a></li>
- <li><a href="#ObjectMethod *finish*"> ObjectMethod finish <tt></tt></a></li>
+ <li><a href="#ClassMethod <strong>new</strong> ($session)"> ClassMethod new <tt>($session)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
<li><a href="#ObjectMethod <strong>readTopic</strong> ($user,"> ObjectMethod readTopic <tt>($user,$web,$topic,$version) -> ($metaObject,$text)</tt></a></li>
<li><a href="#ObjectMethod *_findAttachments*"> ObjectMethod _findAttachments <tt>($session,$web,$topic,$knownAttachments) -> @attachmentsFoundInPub</tt></a></li>
<li><a href="#ObjectMethod <strong>read_TopicRaw</strong> ($u"> ObjectMethod readTopicRaw <tt>($user,$web,$topic,$version) -> $topicText</tt></a></li>
<li><a href="#ObjectMethod <strong>topicExists</strong> ($web"> ObjectMethod topicExists <tt>($web,$topic) -> $boolean</tt></a></li>
<li><a href="#ObjectMethod <strong>get_TopicParent</strong> ("> ObjectMethod getTopicParent <tt>($web,$topic) -> $string</tt></a></li>
<li><a href="#ObjectMethod *get_TopicLatestRev"> ObjectMethod getTopicLatestRevTime <tt>($web,$topic) -> $epochSecs</tt></a></li>
- <li><a href="#ObjectMethod <strong>read_MetaData</strong> ($w"> ObjectMethod readMetaData <tt>($web,$name) -> $text</tt></a></li>
- <li><a href="#ObjectMethod <strong>save_MetaData</strong> ($w"> ObjectMethod saveMetaData <tt>($web,$name) -> $text</tt></a></li>
+ <li><a href="#ObjectMethod <strong>eachChange</strong> ($web,"> ObjectMethod eachChange <tt>($web,$time) -> $iterator</tt></a></li>
<li><a href="#ObjectMethod <strong>get_TopicNames</strong> ($"> ObjectMethod getTopicNames <tt>($web) -> @topics</tt></a></li>
<li><a href="#ObjectMethod <strong>get_ListOfWebs</strong> ($"> ObjectMethod getListOfWebs <tt>($filter) -> @webNames</tt></a></li>
<li><a href="#ObjectMethod <strong>createWeb</strong> ($user,"> ObjectMethod createWeb <tt>($user,$newWeb,$baseWeb,$opts)</tt></a></li>
<li><a href="#ObjectMethod <strong>clean_UpRevID</strong> ($r"> ObjectMethod cleanUpRevID <tt>($rev) -> $integer</tt></a></li>
<li><a href="#ObjectMethod <strong>copyTopic</strong> ($user,"> ObjectMethod copyTopic <tt>($user,$fromweb,$fromtopic,$toweb,$totopic)</tt></a></li>
<li><a href="#ObjectMethod <strong>search_MetaData</strong> ("> ObjectMethod searchMetaData <tt>($params) -> $text</tt></a></li>
+ <li><a href="#ObjectMethod *search_InWebMetaDa"> ObjectMethod searchInWebMetaData <tt>($query,$web,\@topics) -> \%matches</tt></a></li>
<li><a href="#ObjectMethod *search_InWebConten"> ObjectMethod searchInWebContent <tt>($searchString,$web,\@topics,\%options) -> \%map</tt></a></li>
<li><a href="#ObjectMethod *get_RevisionAtTime"> ObjectMethod getRevisionAtTime <tt>($web,$topic,$time) -> $rev</tt></a></li>
<li><a href="#ObjectMethod <strong>getLease</strong> ($web,$t"> ObjectMethod getLease <tt>($web,$topic) -> $lease</tt></a></li>
</ul>
</div>
-## <a name="ClassMethod <strong>new</strong> ()"></a> [[ClassMethod]] **new** `()`
+## <a name="ClassMethod <strong>new</strong> ($session)"></a> [[ClassMethod]] **new** `($session)`
Construct a Store module, linking in the chosen sub-implementation.
-## <a name="ObjectMethod <strong>finish*"></a><a name="ObjectMethod *finish</strong> "></a> [[ObjectMethod]] **finish** ``
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
-Complete processing after the client's HTTP request has been responded to.
-
-1. breaking circular references to allow garbage collection in persistent environments
+Break circular references.
## <a name="ObjectMethod <strong>readTopic</strong> ($user,"></a> [[ObjectMethod]] **readTopic** `($user,$web,$topic,$version) -> ($metaObject,$text)`
Return reference to an array of [ diffType, $right, $left ]
-- `$user` - the user object, or undef to suppress access control checks
+- `$user` - the user id, or undef to suppress access control checks
- `$web` - the web
- `$topic` - the topic
- `$rev1` Integer revision number
- `$rev` revision number. If 0, undef, or out-of-range, will get info about the most recent revision.
- `$attachment` attachment filename; undef for a topic
-Return list with: ( last update date, last user object, =
+Return list with: ( last update date, last user id, =
<table border="1" cellpadding="0" cellspacing="0">
<tr>
<td><code>filedate</code></td>
<td> Date </td>
</tr>
+ <tr>
+ <td><code>tmpFilename</code></td>
+ <td> Pathname of the server file the stream is attached to. Required if stream is set. </td>
+ </tr>
</table>
Saves a new revision of the attachment, invoking plugin handlers as appropriate.
- `$web` - Web name, required, e.g. `'Sandbox'`
-A web _has_ to have a home topic to be a web.
+A web _has_ to have a preferences topic to be a web.
## <a name="ObjectMethod <strong>topicExists</strong> ($web"></a> [[ObjectMethod]] **topicExists** `($web,$topic) -> $boolean`
Get an approximate rev time for the latest rev of the topic. This method is used to optimise searching. Needs to be as fast as possible.
-## <a name="ObjectMethod <strong>read_MetaData</strong> ($w"></a> [[ObjectMethod]] **readMetaData** `($web,$name) -> $text`
-
-Read a named meta-data string. If web is given the meta-data is stored alongside a web.
-
-## <a name="ObjectMethod <strong>save_MetaData</strong> ($w"></a> [[ObjectMethod]] **saveMetaData** `($web,$name) -> $text`
+## <a name="ObjectMethod <strong>eachChange</strong> ($web,"></a> [[ObjectMethod]] **eachChange** `($web,$time) -> $iterator`
-Write a named meta-data string. If web is given the meta-data is stored alongside a web.
+Get an iterator over the list of all the changes in the given web between `$time` and now. $time is a time in seconds since 1st Jan 1970, and is not guaranteed to return any changes that occurred before (now - \{Store\}\{RememberChangesFor\}). Changes are returned in most-recent-first order.
## <a name="ObjectMethod <strong>get_TopicNames</strong> ($"></a> [[ObjectMethod]] **getTopicNames** `($web) -> @topics`
<td><code>web</code></td>
<td> web to search in, default is all webs </td>
</tr>
+ <tr>
+ <td><code>format</code></td>
+ <td> string for custom formatting results </td>
+ </tr>
</table>
The idea is that people can search for meta-data values without having to be aware of how or where meta-data is stored.
SMELL: should be replaced with a proper SQL-like search, c.f. [[DBCacheContrib]].
+## <a name="ObjectMethod <strong>search_InWebMetaDa"></a> [[ObjectMethod]] \*searchInWebMetaData `($query,$web,\@topics) -> \%matches`
+
+Search for a meta-data expression in the content of a web. `$query` must be a `TWiki::Query` object.
+
+Returns a reference to a hash that maps the names of topics that all matched to the result of the query expression (e.g. if the query expression is 'TOPICPARENT.name' then you will get back a hash that maps topic names to their parent.
+
## <a name="ObjectMethod <strong>search_InWebConten"></a> [[ObjectMethod]] \*searchInWebContent `($searchString,$web,\@topics,\%options) -> \%map`
Search for a string in the content of a web. The search must be over all content and all formatted meta-data, though the latter search type is deprecated (use searchMetaData instead).
--- /dev/null
+# <a name="Package <code>TWiki::Store::_QueryAlg"></a> Package =TWiki::Store::QueryAlgorithms::BruteForce
+
+Default brute-force query algorithm
+
+Has some basic optimisation: it hoists regular expressions out of the query to use with grep, so we can narrow down the set of topics that we have to evaluate the query on.
+
+Not sure exactly where the breakpoint is between the costs of hoisting and the advantages of hoisting. Benchmarks suggest that it's around 6 topics, though this may vary depending on disk speed and memory size. It also depends on the complexity of the query.
+
+<div>
+ <ul>
+ <li><a href="#Package =TWiki::Store::_QueryAlg"> Package TWiki::Store::QueryAlgorithms::BruteForce</a></li>
+ </ul>
+</div>
# <a name="Package <code>TWiki::Store::_RcsFile="></a> Package =TWiki::Store::RcsFile
-This class is PACKAGE PRIVATE to Store, and should never be used from anywhere else. Base class of implementations of stores that manipulate RCS format files.
+This class is PACKAGE PRIVATE to Store, and should never be used from anywhere else. It is the base class of implementations of stores that manipulate RCS format files.
The general contract of the methods on this class and its subclasses calls for errors to be signalled by Error::Simple exceptions.
<ul>
<li><a href="#Package =TWiki::Store::_RcsFile="> Package TWiki::Store::RcsFile</a><ul>
<li><a href="#ClassMethod <strong>new</strong> ($session,$web"> ClassMethod new <tt>($session,$web,$topic,$attachment)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
<li><a href="#ObjectMethod *get_RevisionInfo*"> ObjectMethod getRevisionInfo <tt>($version) -> ($rev,$date,$user,$comment)</tt></a></li>
<li><a href="#ObjectMethod *get_LatestRevision"> ObjectMethod getLatestRevision <tt>() -> $text</tt></a></li>
<li><a href="#ObjectMethod *get_LatestRevision"> ObjectMethod getLatestRevisionTime <tt>() -> $text</tt></a></li>
- <li><a href="#ObjectMethod <strong>read_MetaData</strong> ($n"> ObjectMethod readMetaData <tt>($name) -> $text</tt></a></li>
<li><a href="#ObjectMethod <strong>get_WorkArea</strong> ($ke"> ObjectMethod getWorkArea <tt>($key) -> $directorypath</tt></a></li>
- <li><a href="#ObjectMethod <strong>save_MetaData</strong> ($w"> ObjectMethod saveMetaData <tt>($web,$name) -> $text</tt></a></li>
<li><a href="#ObjectMethod <strong>get_TopicNames</strong> ()"> ObjectMethod getTopicNames <tt>() -> @topics</tt></a></li>
<li><a href="#ObjectMethod <strong>get_WebNames</strong> () -"> ObjectMethod getWebNames <tt>() -> @webs</tt></a></li>
<li><a href="#ObjectMethod *search_InWebConten"> ObjectMethod searchInWebContent <tt>($searchString,$web,\@topics,\%options) -> \%map</tt></a></li>
+ <li><a href="#ObjectMethod *search_InWebMetaDa"> ObjectMethod searchInWebMetaData <tt>($query,\@topics) -> \%matches</tt></a></li>
<li><a href="#ObjectMethod <strong>moveWeb</strong> ($newWeb)"> ObjectMethod moveWeb <tt>($newWeb)</tt></a></li>
<li><a href="#ObjectMethod <strong>getRevision</strong> ($ver"> ObjectMethod getRevision <tt>($version) -> $text</tt></a></li>
<li><a href="#ObjectMethod *stored_DataExists*"> ObjectMethod storedDataExists <tt>() -> $boolean</tt></a></li>
<li><a href="#ObjectMethod <strong>getTimestamp</strong> () -"> ObjectMethod getTimestamp <tt>() -> $integer</tt></a></li>
- <li><a href="#ObjectMethod *restore_LatestRevi"> ObjectMethod restoreLatestRevision <tt>($wikiname)</tt></a></li>
+ <li><a href="#ObjectMethod *restore_LatestRevi"> ObjectMethod restoreLatestRevision <tt>($user)</tt></a></li>
<li><a href="#ObjectMethod <strong>removeWeb</strong> ($web)"> ObjectMethod removeWeb <tt>($web)</tt></a></li>
<li><a href="#ObjectMethod <strong>moveTopic</strong> ($newWe"> ObjectMethod moveTopic <tt>($newWeb,$newTopic)</tt></a></li>
<li><a href="#ObjectMethod <strong>copyTopic</strong> ($newWe"> ObjectMethod copyTopic <tt>($newWeb,$newTopic)</tt></a></li>
<li><a href="#ObjectMethod *get_AttachmentAttr"> ObjectMethod getAttachmentAttributes <tt>($web,$topic,$attachment)</tt></a></li>
<li><a href="#ObjectMethod *get_AttachmentList"> ObjectMethod getAttachmentList <tt>($web,$topic)</tt></a></li>
<li><a href="#ObjectMethod <strong>stringify</strong> ()"> ObjectMethod stringify <tt>()</tt></a></li>
+ <li><a href="#ObjectMethod <strong>recordChange</strong> ($us"> ObjectMethod recordChange <tt>($user,$rev,$more)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>eachChange</strong> ($sinc"> ObjectMethod eachChange <tt>($since) -> $iterator</tt></a></li>
</ul>
</li>
</ul>
Note that $web, $topic and $attachment must be untainted!
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
+
+Break circular references.
+
## <a name="ObjectMethod <strong>get_RevisionInfo*"></a><a name="ObjectMethod *get_RevisionInfo</strong> "></a> [[ObjectMethod]] **getRevisionInfo** `($version) -> ($rev,$date,$user,$comment)`
- `$version` if 0 or undef, or out of range (version number > number of revs) will return info about the latest revision.
Get the time of the most recent revision
-## <a name="ObjectMethod <strong>read_MetaData</strong> ($n"></a> [[ObjectMethod]] **readMetaData** `($name) -> $text`
-
-Get a meta-data block for this web
-
## <a name="ObjectMethod <strong>get_WorkArea</strong> ($ke"></a> [[ObjectMethod]] **getWorkArea** `($key) -> $directorypath`
Gets a private directory uniquely identified by $key. The directory is intended as a work area for plugins.
-The standard is a directory named the same as "key" under $TWiki::cfg\{RCS\}\{WorkAreaDir\}
-
-## <a name="ObjectMethod <strong>save_MetaData</strong> ($w"></a> [[ObjectMethod]] **saveMetaData** `($web,$name) -> $text`
-
-Write a named meta-data string. If web is given the meta-data is stored alongside a web.
+The standard is a directory named the same as "key" under $TWiki::cfg\{WorkingDir\}/work\_areas
## <a name="ObjectMethod <strong>get_TopicNames</strong> ()"></a> [[ObjectMethod]] **getTopicNames** `() -> @topics`
The return value is a reference to a hash which maps each matching topic name to a list of the lines in that topic that matched the search, as would be returned by 'grep'. If `files_without_match` is specified, it will return on the first match in each topic (i.e. it will return only one match per topic, and will not return matching lines).
+## <a name="ObjectMethod <strong>search_InWebMetaDa"></a> [[ObjectMethod]] \*searchInWebMetaData `($query,\@topics) -> \%matches`
+
+Search for a meta-data expression in the content of a web. `$query` must be a `TWiki::Query` object.
+
+Returns a reference to a hash that maps the names of topics that all matched to the result of the query expression (e.g. if the query expression is 'TOPICPARENT.name' then you will get back a hash that maps topic names to their parent.
+
+SMELL: this is **really** inefficient!
+
## <a name="ObjectMethod <strong>moveWeb</strong> ($newWeb)"></a> [[ObjectMethod]] **moveWeb** `($newWeb)`
Move a web.
Get the timestamp of the file Returns 0 if no file, otherwise epoch seconds
-## <a name="ObjectMethod <strong>restore_LatestRevi"></a> [[ObjectMethod]] \*restoreLatestRevision `($wikiname)`
+## <a name="ObjectMethod <strong>restore_LatestRevi"></a> [[ObjectMethod]] \*restoreLatestRevision `($user)`
Restore the plaintext file from the revision at the head.
returns [stat] for any given web, topic, $attachment SMELL - should this return a hash of arbitrary attributes so that SMELL + attributes supported by the underlying filesystem are supported SMELL + (eg: windows directories supporting photo "author", "dimension" fields)
-sub \_constructAttributesForAutoAttached as long as stat is defined, return an emulated set of attributes for that attachment.
-
## <a name="ObjectMethod <strong>get_AttachmentList"></a> [[ObjectMethod]] \*getAttachmentList `($web,$topic)`
returns \{\} of filename => \{ key => value, key2 => value \} for any given web, topic Ignores files starting with \_ or ending with ,v
## <a name="ObjectMethod <strong>stringify</strong> ()"></a> [[ObjectMethod]] **stringify** `()`
Generate string representation for debugging
+
+## <a name="ObjectMethod <strong>recordChange</strong> ($us"></a> [[ObjectMethod]] **recordChange** `($user,$rev,$more)`
+
+Record that the file changed
+
+## <a name="ObjectMethod <strong>eachChange</strong> ($sinc"></a> [[ObjectMethod]] **eachChange** `($since) -> $iterator`
+
+Return iterator over changes - see Store for details
# <a name="Package <code>TWiki::Store::_RcsLite="></a> Package =TWiki::Store::RcsLite
-**extends** <tt>[[TWiki::Store::RcsFile|Main/TWikiStoreRcsFileDotPm]]</tt>
-
This package does not publish any methods. It implements the virtual methods of the [[TWiki::Store::RcsFile|Main/TWikiStoreRcsFileDotPm]] superclass.
Simple replacement for RCS. Doesn't support:
<ul>
<li><a href="#Package =TWiki::Store::_RcsLite="> Package TWiki::Store::RcsLite</a><ul>
<li><a href="#File format"> File format</a></li>
- <li><a href="#ObjectMethod *finish*"> ObjectMethod finish <tt></tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
</ul>
</li>
</ul>
</div>
-## <a name="ObjectMethod <strong>finish*"></a><a name="ObjectMethod *finish</strong> "></a> [[ObjectMethod]] **finish** ``
-
-Complete processing after the client's HTTP request has been responded to.
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
-1. breaking circular references to allow garbage collection in persistent environments
+Break circular references.
# <a name="Package <code>TWiki::Store::_RcsWrap="></a> Package =TWiki::Store::RcsWrap
-**extends** <tt>[[TWiki::Store::RcsFile|Main/TWikiStoreRcsFileDotPm]]</tt>
-
This package does not publish any methods. It implements the virtual methods of the [[TWiki::Store::RcsFile|Main/TWikiStoreRcsFileDotPm]] superclass.
Wrapper around the RCS commands required by TWiki. There is one of these object for each file stored under RCS.
<div>
<ul>
<li><a href="#Package =TWiki::Store::_RcsWrap="> Package TWiki::Store::RcsWrap</a><ul>
- <li><a href="#ObjectMethod *finish*"> ObjectMethod finish <tt></tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
<li><a href="#StaticMethod *parse_RevisionDiff"> StaticMethod parseRevisionDiff <tt>($text) -> \@diffArray</tt></a></li>
</ul>
</li>
</ul>
</div>
-## <a name="ObjectMethod <strong>finish*"></a><a name="ObjectMethod *finish</strong> "></a> [[ObjectMethod]] **finish** ``
-
-Complete processing after the client's HTTP request has been responded to.
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
-1. breaking circular references to allow garbage collection in persistent environments
+Break circular references.
## <a name="StaticMethod <strong>parse_RevisionDiff"></a> [[StaticMethod]] \*parseRevisionDiff `($text) -> \@diffArray`
## <a name="search($searchString, $topics, $"></a> search($searchString, $topics, $options, $sDir) -> \\%seen
-Search .txt files in $dir for $string. See [[RcsFile]]::searchInWebContent for details.
+Search .txt files in $dir for $searchString. See [[RcsFile]]::searchInWebContent for details.
<div>
<ul>
+# <a name="TWiki System Requirements"></a> TWiki System Requirements
+
+_Server and client requirements_
+
+Low client and server base requirements are core features that keep TWiki widely deployable, particularly across a range of browser platforms and versions. Many [[Plugins|TWiki:Plugins/PluginPackage]] and [[contrib modules|TWiki:Plugins/ContribPackage]] exist which enhance and expand TWiki's capabilities; they may have additional requirements.
+
<div>
<ul>
<li><a href="#TWiki System Requirements"> TWiki System Requirements</a><ul>
</ul>
</div>
-# <a name="TWiki System Requirements"></a> TWiki System Requirements
-
-_Server and client requirements_
-
-Low client and server base requirements are core features that keep TWiki widely deployable, particularly across a range of browser platforms and versions. Many [[Plugins|TWiki:Plugins/PluginPackage]] and [[contrib modules|TWiki:Plugins/ContribPackage]] exist which enhance and expand TWiki's capabilities; they may have additional requirements.
-
## <a name="Server Requirements"></a> Server Requirements
TWiki is written in Perl 5, uses a number of shell commands, and requires [RCS (Revision Control System)](http://www.gnu.org/software/rcs/rcs.html), a GNU Free Software package. TWiki is developed in a basic Linux/Apache environment. It also works with Microsoft Windows, and should have no problem on any other platform that meets the requirements.
</tr>
<tr>
<td> Perl </td>
- <td> 5.005_03 or higher (5.8.4 or higher is recommended) </td>
+ <td> 5.6.1 or higher (5.8.4 or higher is recommended) </td>
</tr>
<tr>
<td> RCS </td>
CSS and Javascript are used in most skins, although there is a low-fat skin (Classic skin) available that minimises these requirements. Some skins will require more recent releases of browsers. The default skin (Pattern) is tested on IE 6, Safari, and Mozilla 5.0 based browsers (such as Firefox).
-You can easily select a balance of browser capability versus look and feel. Try the installed skins at [[TWikiSkinBrowser]] and more at TWiki:Plugins.SkinPackage.
+You can easily select a balance of browser capability versus look and feel. Try the installed skins at %SYSTEMWEB%.TWikiSkinBrowser and more at TWiki:Plugins.SkinPackage.
## <a name="Important note about TWiki Plugi"></a> Important note about TWiki Plugins
- Plugins can require just about anything - browser-specific functions, stylesheets (CSS), Java applets, cookies, specific Perl modules,... - check the individual Plugin specs.
- - **_%T% Note:_** Plugins included in the TWiki distribution do not add requirements, except for the [[CommentPlugin]] which requires Perl 5.6.1.
**_Related Topics:_** [[AdminDocumentationCategory]]
+# <a name="TWiki Templates"></a> TWiki Templates
+
+_Definition of the templates used to render all HTML pages displayed in TWiki_
+
<div>
<ul>
<li><a href="#TWiki Templates"> TWiki Templates</a><ul>
<li><a href="#Overview"> Overview</a></li>
- <li><a href="#The TWiki Template System"> The TWiki Template System</a><ul>
+ <li><a href="#Master Templates"> Master Templates</a><ul>
<li><a href="#How Template Directives Work"> How Template Directives Work</a></li>
<li><a href="#Finding Templates"> Finding Templates</a></li>
- <li><a href="#TMPL:INCLUDE recusion for piecew"> TMPL:INCLUDE recusion for piecewise customisation, or mixing in new features</a></li>
+ <li><a href="#TMPL:INCLUDE recursion for piece"> TMPL:INCLUDE recursion for piecewise customisation, or mixing in new features</a></li>
+ <li><a href="#Default master template"> Default master template</a></li>
</ul>
</li>
- <li><a href="#Master Templates"> Master Templates</a></li>
- <li><a href="#HTML Page Templates"> HTML Page Templates</a></li>
<li><a href="#Template Topics"> Template Topics</a><ul>
- <li><a href="#Edit Template Topics and Variabl"> Edit Template Topics and Variable Expansion</a></li>
+ <li><a href="#Variable Expansion"> Variable Expansion</a></li>
+ <li><a href="#Specifying a Form"> Specifying a Form</a></li>
+ <li><a href="#Automatically Generated Topic Na"> Automatically Generated Topic Names</a></li>
<li><a href="#Template Topics in Action"> Template Topics in Action</a></li>
- <li><a href="#Automatically Generated Topicnam"> Automatically Generated Topicname</a></li>
- </ul>
- </li>
- <li><a href="#Master Templates by Example"> Master Templates by Example</a><ul>
- <li><a href="#Base template oopsbase.tmpl"> Base template oopsbase.tmpl</a></li>
- <li><a href="#Test template oopstest.tmpl"> Test template oopstest.tmpl</a></li>
- <li><a href="#Sample screen shot of oopstest.t"> Sample screen shot of oopstest.tmpl</a></li>
+ <li><a href="#Using Absolute vs Relative URLs"> Using Absolute vs Relative URLs in Templates</a></li>
</ul>
</li>
</ul>
</ul>
</div>
-# <a name="TWiki Templates"></a> TWiki Templates
-
-_Definition of the templates used to render all HTML pages displayed in TWiki_
-
## <a name="Overview"></a> Overview
-There are three types of template:
+_Templates_ are plain text with embedded _template directives_ that tell TWiki how to compose blocks of text together, to create something new.
-- **Master Templates**: Define blocks of text for use in other templates
-- **HTML Page Templates**: Define the layout of %WIKITOOLNAME% pages
-- **Template Topics**: Define default text when you create a new topic
+There are two types of template:
-All three types of template use the TWiki template system.
+- **Master Templates**: Define the HTML used to display TWiki pages.
+- **Template Topics**: Define default text when you create a new topic
**_%T% Tip:_** TWiki:TWiki.TWikiTemplatesSupplement on TWiki.org has supplemental documentation on TWiki templates.
-## <a name="The TWiki Template System"></a> The TWiki Template System
+<a name="HtmlTemplates"></a>
+
+## <a name="Master Templates"></a> Master Templates
+
+TWiki uses master templates when composing the output from all actions, like topic view, edit, and preview. This allows you to change the look and feel of all pages by editing just a few template files.
+
+Master templates are also used in the definition of [[TWikiSkins]].
-_Templates_ are plain text with embedded _template directives_ that tell TWiki how to compose blocks of text together to create something new.
+Master templates are stored as text files with the extension `.tmpl`. They are usually HTML with embedded _template directives_. The directives are expanded when TWiki wants to generate a user interface screen.
<a name="TemplateVariables"></a>
### <a name="How Template Directives Work"></a> How Template Directives Work
-- Template directives are embedded in templates.
- Directives are of the form <code>**%TMPL:<key>%**</code> and <code>**%TMPL:<key>\{"attr"\}%**</code>.
- Directives:
- <code>**%TMPL:INCLUDE\{"file"\}%**</code>: Includes a template file. The file is found as described [[below|Main/WebHome#FindingTemplates]].
TMPL:P also supports simple parameters. For example, given the definition `%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.
+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 [[TWikiVariables]].
### <a name="Finding Templates"></a> Finding Templates
-Templates are stored either in the <code>**twiki/templates**</code> directory, or can also be read from user topics. As an example, <code>**twiki/templates/view.tmpl**</code> is the default template file for the <code>**twiki/bin/view**</code> script.
-
-Templates that are included using `%TMPL:INCLUDE%` are also found using the same search algorithm, unless you explicitly put `'.tmpl'` at the end of the template name. In this case, the string is assumed to be the full name of a template in the `templates` directory, and the algorithm isn't used.
-
-TWiki uses the following search order to determine which template file or topic to use for a particular script. The _skin path_ is set as described in [[TWikiSkins]].
-
-> 1. templates/%RED%web%ENDCOLOR%/%RED%script%ENDCOLOR%.%RED%skin%ENDCOLOR%.tmpl for each %RED%skin%ENDCOLOR% on the skin path
-> - %X% this usage is supported **for compatibility only** and is **deprecated**. Store web-specific templates in TWiki topics instead.
-> 2. templates/%RED%script%ENDCOLOR%.%RED%skin%ENDCOLOR%.tmpl for each %RED%skin%ENDCOLOR% on the skin path
-> 3. templates/%RED%web%ENDCOLOR%/%RED%script%ENDCOLOR%.tmpl
-> - %X% this usage is supported **for compatibility only** and is **deprecated**. Store web-specific templates in TWiki topics instead.
-> 4. templates/%RED%script%ENDCOLOR%.tmpl
-> 5. The TWiki topic aweb.atopic if the template name can be parsed into aweb.atopic
-> 6. The TWiki topic %RED%web%ENDCOLOR%.%RED%Skin%ENDCOLOR%Skin%RED%Script%ENDCOLOR%Template for each %RED%skin%ENDCOLOR% on the skin path
-> 7. The TWiki topic %RED%web%ENDCOLOR%.%RED%Script%ENDCOLOR%Template
-> 8. The TWiki topic %TWIKIWEB%.%RED%Skin%ENDCOLOR%Skin%RED%Script%ENDCOLOR%Template for each %RED%skin%ENDCOLOR% on the skin path
-> 9. The TWiki topic %TWIKIWEB%.%RED%Script%ENDCOLOR%Template
->
-> **Legend:**
->
-> - %RED%script%ENDCOLOR% refers to the script name, e.g `view`, `edit`
-> - %RED%Script%ENDCOLOR% refers to the same, but with the first character capitalized, e.g `View`
-> - %RED%skin%ENDCOLOR% refers to a skin name, e.g `dragon`, `pattern`. All skins are checked at each stage, in the order they appear in the skin path.
-> - %RED%Skin%ENDCOLOR% refers to the same, but with the first character capitalized, e.g `Dragon`
-> - %RED%web%ENDCOLOR% refers to the current web
+The master templates shipped with a twiki release are stored in the twiki/templates directory. As an example, <code>**twiki/templates/view.tmpl**</code> is the default template file for the <code>**twiki/bin/view**</code> 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](http://www.dementia.org/twiki/configure) page.
+
+You can also save templates in user topics. The `{TemplatePath}` configuration setting defines which topics will be accepted as templates.
+
+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 [[TWikiSkins]].
+
+1. templates/%RED%web%ENDCOLOR%/%RED%script%ENDCOLOR%.%RED%skin%ENDCOLOR%.tmpl for each %RED%skin%ENDCOLOR% on the skin path
+ - %X% this usage is supported **for compatibility only** and is **deprecated**. Store web-specific templates in TWiki topics instead.
+2. templates/%RED%script%ENDCOLOR%.%RED%skin%ENDCOLOR%.tmpl for each %RED%skin%ENDCOLOR% on the skin path
+3. templates/%RED%web%ENDCOLOR%/%RED%script%ENDCOLOR%.tmpl
+ - %X% this usage is supported **for compatibility only** and is **deprecated**. Store web-specific templates in TWiki topics instead.
+4. templates/%RED%script%ENDCOLOR%.tmpl
+5. The TWiki topic aweb.atopic if the template name can be parsed into aweb.atopic
+6. The TWiki topic %RED%web%ENDCOLOR%.%RED%Skin%ENDCOLOR%Skin%RED%Script%ENDCOLOR%Template for each %RED%skin%ENDCOLOR% on the skin path
+7. The TWiki topic %RED%web%ENDCOLOR%.%RED%Script%ENDCOLOR%Template
+8. The TWiki topic %SYSTEMWEB%.%RED%Skin%ENDCOLOR%Skin%RED%Script%ENDCOLOR%Template for each %RED%skin%ENDCOLOR% on the skin path
+9. The TWiki topic %SYSTEMWEB%.%RED%Script%ENDCOLOR%Template
+
+**Legend:**
+
+- %RED%script%ENDCOLOR% refers to the script name, e.g `view`, `edit`
+- %RED%Script%ENDCOLOR% refers to the same, but with the first character capitalized, e.g `View`
+- %RED%skin%ENDCOLOR% refers to a skin name, e.g `dragon`, `pattern`. All skins are checked at each stage, in the order they appear in the skin path.
+- %RED%Skin%ENDCOLOR% refers to the same, but with the first character capitalized, e.g `Dragon`
+- %RED%web%ENDCOLOR% refers to the current web
For example, the `example` template file will be searched for in the following places, when the current web is `Thisweb` and the skin path is `print,pattern`:
7. `Thisweb.PrintSkinExampleTemplate`
8. `Thisweb.PatternSkinExampleTemplate`
9. `Thisweb.ExampleTemplate`
-10. `TWiki.PrintSkinExampleTemplate`
-11. `TWiki.PatternSkinExampleTemplate`
-12. `TWiki.ExampleTemplate`
+10. `%SYSTEMWEB%.PrintSkinExampleTemplate`
+11. `%SYSTEMWEB%.PatternSkinExampleTemplate`
+12. `%SYSTEMWEB%.ExampleTemplate`
-Template names are usually derived from the name of the currently executing script; however it is also possible to override these settings in the `view` and `edit` scripts, for example when a topic-specific template is required. Two preference variables can be user to override the templates used:
+Template names are usually derived from the name of the currently executing script; however it is also possible to override these settings in the `view` and `edit` scripts, for example when a topic-specific template is required. Two preference variables can be used to override the templates used:
- `VIEW_TEMPLATE` sets the template to be used for viewing a topic
- `EDIT_TEMPLATE` sets the template for editing a topic.
-If these preferences are set locally (using _Local_ instead of _Set_) for a topic, in [[WebPreferences]], in [[Main.TWikiPreferences|Main/TWikiPreferences]], or [[TWiki.TWikiPreferences|TWiki/TWikiPreferences]] (using _Set_), the indicated templates will be chosen for `view` and `edit` respectively. The template search order is as specified above.
+If these preferences are set locally (using _Local_ instead of _Set_) for a topic, in [[WebPreferences]], in [[Main.TWikiPreferences|Main/TWikiPreferences]], or [[%SYSTEMWEB%.TWikiPreferences|SYSTEMWEB/TWikiPreferences]] (using _Set_), the indicated templates will be chosen for `view` and `edit` respectively. The template search order is as specified above.
-### <a name="TMPL:INCLUDE recusion for piecew"></a> TMPL:INCLUDE recusion for piecewise customisation, or mixing in new features
+### <a name="TMPL:INCLUDE recursion for piece"></a> TMPL:INCLUDE recursion for piecewise customisation, or mixing in new features
-If there is recusion in the TMPL:INCLUDE chain (eg twiki.classic.tmpl contains `%TMPL:INCLUDE{"twiki"}%`, the templating system will include the next twiki.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:
+If there is recursion in the TMPL:INCLUDE chain (eg twiki.classic.tmpl contains `%TMPL:INCLUDE{"twiki"}%`, the templating system will include the next twiki.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
-## <a name="Master Templates"></a> Master Templates
-
-Master templates use the block definition directives (`%TMPL:DEF` and `%TMPL:END%`) to define common sections that appear in two or more other templates. <code>**twiki.tmpl**</code> is the default master template.
-
-> <table border="1" cellpadding="0" cellspacing="0">
-> <tr>
-> <th bgcolor="#99CCCC"><strong> Template variable: </strong></th>
-> <th bgcolor="#99CCCC"><strong> Defines: </strong></th>
-> </tr>
-> <tr>
-> <td><code>%TMPL:DEF{"sep"}%</code></td>
-> <td> "|" separator </td>
-> </tr>
-> <tr>
-> <td><code>%TMPL:DEF{"htmldoctype"}%</code></td>
-> <td> Start of all HTML pages </td>
-> </tr>
-> <tr>
-> <td><code>%TMPL:DEF{"standardheader"}%</code></td>
-> <td> Standard header (ex: view, index, search) </td>
-> </tr>
-> <tr>
-> <td><code>%TMPL:DEF{"simpleheader"}%</code></td>
-> <td> Simple header with reduced links (ex: edit, attach, oops) </td>
-> </tr>
-> <tr>
-> <td><code>%TMPL:DEF{"standardfooter"}%</code></td>
-> <td> Footer, excluding revision and copyright parts </td>
-> </tr>
-> <tr>
-> <td><code>%TMPL:DEF{"oops"}%</code></td>
-> <td> Skeleton of oops dialog </td>
-> </tr>
-> </table>
-
-<a name="HtmlTemplates"></a>
-
-## <a name="HTML Page Templates"></a> HTML Page Templates
-
-HTML page templates are files of HTML mixed with template directives that tell TWiki how to build up an HTML page. As described above, the template system supports the use of 'include' directives that let you re-use the same sections of HTML - such as headers and footers - in several different places.
-
-TWiki uses HTML page templates when composing the output from all actions, like topic view, edit, and preview. This allows you to change the look and feel of all pages by editing just a few template files.
-
-HTML page templates are also used in the definition of [[TWikiSkins]].
+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`.
+
+### <a name="Default master template"></a> Default master template
+
+<code>**twiki.tmpl**</code> is the default master template. It defines the following sections.
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th bgcolor="#99CCCC"><strong> Template variable: </strong></th>
+ <th bgcolor="#99CCCC"><strong> Defines: </strong></th>
+ </tr>
+ <tr>
+ <td><code>%TMPL:DEF{"sep"}%</code></td>
+ <td> "|" separator </td>
+ </tr>
+ <tr>
+ <td><code>%TMPL:DEF{"htmldoctype"}%</code></td>
+ <td> Start of all HTML pages </td>
+ </tr>
+ <tr>
+ <td><code>%TMPL:DEF{"standardheader"}%</code></td>
+ <td> Standard header (ex: view, index, search) </td>
+ </tr>
+ <tr>
+ <td><code>%TMPL:DEF{"simpleheader"}%</code></td>
+ <td> Simple header with reduced links (ex: edit, attach, oops) </td>
+ </tr>
+ <tr>
+ <td><code>%TMPL:DEF{"standardfooter"}%</code></td>
+ <td> Footer, excluding revision and copyright parts </td>
+ </tr>
+</table>
<a name="TemplateTopics"></a>
## <a name="Template Topics"></a> Template Topics
-Template topics define the default text for new topics. There are three types of template topic:
-
-> <table border="1" cellpadding="0" cellspacing="0">
-> <tr>
-> <th bgcolor="#99CCCC"><strong> Topic Name: </strong></th>
-> <th bgcolor="#99CCCC"><strong> What it is: </strong></th>
-> </tr>
-> <tr>
-> <td>[[Main/WebTopicViewTemplate]]</td>
-> <td> Error page shown when you try to view a nonexistent topic </td>
-> </tr>
-> <tr>
-> <td>[[Main/WebTopicNonWikiTemplate]]</td>
-> <td> Alert page shown when you try to view a nonexistent topic with a non-WikiName </td>
-> </tr>
-> <tr>
-> <td>[[Main/WebTopicEditTemplate]]</td>
-> <td> Default text shown when you create a new topic. </td>
-> </tr>
-> </table>
-
-When you create a new topic, TWiki locates a topic to use as a content template according to the following search order:
+The second type of template in TWiki are template topics. Template topics define the default text for new topics. There are three types of template topic:
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th bgcolor="#99CCCC"><strong> Topic Name: </strong></th>
+ <th bgcolor="#99CCCC"><strong> What it is: </strong></th>
+ </tr>
+ <tr>
+ <td>[[Main/WebTopicViewTemplate]]</td>
+ <td> Alert page shown when you try to view a nonexistent topic. This page is usually used as a prompt to help you create a new topic. </td>
+ </tr>
+ <tr>
+ <td>[[Main/WebTopicNonWikiTemplate]]</td>
+ <td> Alert page shown when you try to view a nonexistent topic with a non-WikiName. Again, this page is used as a prompt to help you create the new topic. </td>
+ </tr>
+ <tr>
+ <td>[[Main/WebTopicEditTemplate]]</td>
+ <td> Default text used in a new topic. </td>
+ </tr>
+</table>
+
+When you create a new topic using the `edit` script, TWiki locates a topic to use as a content template according to the following search order:
1. A topic name specified by the `templatetopic` CGI parameter
- - if no web is specified, the current web is searched first and then the TWiki web
+ - if no web is specified, the current web is searched first and then the %SYSTEMWEB% web
2. WebTopicEditTemplate in the current web
-3. WebTopicEditTemplate in the TWiki web
+3. WebTopicEditTemplate in the %SYSTEMWEB% web
<a name="TemplateTopicsVars"></a>
-### <a name="Edit Template Topics and Variabl"></a> Edit Template Topics and Variable Expansion
-
-The following variables get expanded when a user creates a new topic based on a template topic:
-
-> <table border="1" cellpadding="0" cellspacing="0">
-> <tr>
-> <th bgcolor="#99CCCC"><strong> Variable: </strong></th>
-> <th bgcolor="#99CCCC"><strong> Description: </strong></th>
-> </tr>
-> <tr>
-> <td><code>%DATE%</code></td>
-> <td> Signature format date. See [[Main/VarDATE]]</td>
-> </tr>
-> <tr>
-> <td><code>%GMTIME%</code></td>
-> <td> Date/time. See [[Main/VarGMTIME]]</td>
-> </tr>
-> <tr>
-> <td><code>%GMTIME{...}%</code></td>
-> <td> Formatted date/time. See [[Main/VarGMTIME2]]</td>
-> </tr>
-> <tr>
-> <td><code>%NOP%</code></td>
-> <td> A no-operation variable that gets removed. Useful to prevent a SEARCH from hitting an edit template topic; also useful to escape a variable, such as <code>%URLPA%NOP%RAM{...}%</code> escaping URLPARAM </td>
-> </tr>
-> <tr>
-> <td><code>%STARTSECTION{type="templateonly"}%%BR%...%BR%%ENDSECTION{type="templateonly"}%</code></td>
-> <td> Text that gets removed when a new topic based on the template is created. See notes below. </td>
-> </tr>
-> <tr>
-> <td><code>%SERVERTIME%</code></td>
-> <td> Date/time. See [[Main/VarSERVERTIME]]</td>
-> </tr>
-> <tr>
-> <td><code>%SERVERTIME{...}%</code></td>
-> <td> Formatted date/time. See [[Main/VarSERVERTIME2]]</td>
-> </tr>
-> <tr>
-> <td><code>%USERNAME%</code></td>
-> <td> Login name of user who is instantiating the new topic, e.g. admin </td>
-> </tr>
-> <tr>
-> <td><code>%URLPARAM{"name"}%</code></td>
-> <td> Value of a named URL parameter </td>
-> </tr>
-> <tr>
-> <td><code>%WIKINAME%</code></td>
-> <td>[[Main/WikiName]] of user who is instantiating the new topic, e.g. admin </td>
-> </tr>
-> <tr>
-> <td><code>%WIKIUSERNAME%</code></td>
-> <td> User name of user who is instantiating the new tpoic, e.g. Main.admin </td>
-> </tr>
-> </table>
+### <a name="Variable Expansion"></a> Variable Expansion
+
+When the following variables are used in a template topic, they automatically get expanded when new topic is created based on it:
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th bgcolor="#99CCCC"><strong> Variable: </strong></th>
+ <th bgcolor="#99CCCC"><strong> Description: </strong></th>
+ </tr>
+ <tr>
+ <td><code>%DATE%</code></td>
+ <td> Signature format date. See [[Main/VarDATE]]</td>
+ </tr>
+ <tr>
+ <td><code>%GMTIME%</code></td>
+ <td> Date/time. See [[Main/VarGMTIME]]</td>
+ </tr>
+ <tr>
+ <td><code>%GMTIME{...}%</code></td>
+ <td> Formatted date/time. See [[Main/VarGMTIME2]]</td>
+ </tr>
+ <tr>
+ <td><code>%NOP%</code></td>
+ <td> A no-operation variable that gets removed. Useful to prevent a SEARCH from hitting an edit template topic; also useful to escape a variable, such as <code>%URLPA%NOP%RAM{...}%</code> escaping URLPARAM </td>
+ </tr>
+ <tr>
+ <td><code>%STARTSECTION{type="templateonly"}%%BR%...%BR%%ENDSECTION{type="templateonly"}%</code></td>
+ <td> Text that gets removed when a new topic based on the template is created. See notes below. </td>
+ </tr>
+ <tr>
+ <td><code>%SERVERTIME%</code></td>
+ <td> Date/time. See [[Main/VarSERVERTIME]]</td>
+ </tr>
+ <tr>
+ <td><code>%SERVERTIME{...}%</code></td>
+ <td> Formatted date/time. See [[Main/VarSERVERTIME2]]</td>
+ </tr>
+ <tr>
+ <td><code>%USERNAME%</code></td>
+ <td> Login name of user who is instantiating the new topic, e.g. admin </td>
+ </tr>
+ <tr>
+ <td><code>%URLPARAM{"name"}%</code></td>
+ <td> Value of a named URL parameter </td>
+ </tr>
+ <tr>
+ <td><code>%WIKINAME%</code></td>
+ <td>[[Main/WikiName]] of user who is instantiating the new topic, e.g. admin </td>
+ </tr>
+ <tr>
+ <td><code>%WIKIUSERNAME%</code></td>
+ <td> User name of user who is instantiating the new tpoic, e.g. Main.admin </td>
+ </tr>
+</table>
`%STARTSECTION{type="templateonly"}%%BR%...%BR%%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 can only be changed by:
- * Set ALLOWTOPICCHANGE = %MAINWEB%.TWikiAdminGroup
+ * Set ALLOWTOPICCHANGE = %USERSWEB%.TWikiAdminGroup
%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 TWiki variables that would otherwise be expanded during topic creation e.g.i escape `%nop>SERVERTIME%` with `%SER%NOP%VERTIME%`.
+`%NOP%` can be used to prevent expansion of TWiki variables that would otherwise be expanded during topic creation e.g.i escape `%SERVERTIME%` with `%SER%NOP%VERTIME%`.
All other variables are unchanged, e.g. are carried over "as is" into the new topic.
+### <a name="Specifying a Form"></a> Specifying a Form
+
+When you create a new topic based on a template, you often want the new topic to have a form attached to it. You can attach a form to the template topic, in which case it will be copied into the new topic.
+
+Sometimes this isn't quite what you want, as it copies all the existing data from the template topic into the new topic. To avoid this and use the default values specified in the form definition instead, you can use the `formtemplate` CGI parameter to the `edit` script to specify the name of a form to attach.
+
+See [[TWikiScripts]] for information about all the other parameters to `edit`.
+
+<a name="AutomaticallyGeneratedTopicname"></a>
+
+### <a name="Automatically Generated Topic Na"></a> Automatically Generated Topic Names
+
+For TWiki applications it is useful to be able to automatically generate unique topicnames, such as BugID0001, BugID0002, etc. You can add `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)
+
+Example link to create a new topic:%BR%
+
+ [[%SCRIPTURLPATH{edit}%/%WEB%/BugIDAUTOINC00001?templatetopic=BugTemplate;topicparent=%TOPIC%;t=%SERVERTIME{"$day$hour$min$sec"}%][Create new item]]
+
### <a name="Template Topics in Action"></a> Template Topics in Action
-Here is an example for creating new topics based on a specific template topic:
+Here is an example for creating new topics (in the Sandbox web) based on a specific template topic and form:
-<form action="http://www.dementia.org/twiki/edit/%WEB%/" name="new">
+<form action="http://www.dementia.org/twiki/edit/Sandbox/" name="new">
<ul>
- <li> New example topic: <input name="topic" size="26" type="text" value="ExampleTopic2010x06x29" /> <input type="submit" value="Create" /> <input name="templatetopic" type="hidden" value="ExampleTopicTemplate" /> <input name="topicparent" type="hidden" value="%TOPIC%" /> <input name="onlywikiname" type="hidden" value="on" /> <input name="onlynewtopic" type="hidden" value="on" /> (date format is YYYYxMMxDD) </li>
+ <li> New example topic: <input name="topic" size="30" type="text" value="ExampleTopicAUTOINC0001" /> <input type="submit" value="Create" /> <input name="templatetopic" type="hidden" value="ExampleTopicTemplate" /> <input name="topicparent" type="hidden" value="%TOPIC%" /> <input name="onlywikiname" type="hidden" value="on" /> <input name="onlynewtopic" type="hidden" value="on" /></li>
</ul>
</form>
The above form asks for a topic name. A hidden input tag named <code>**templatetopic**</code> specifies [[ExampleTopicTemplate]] as the template topic to use. Here is the HTML source of the form:
- <form name="new" action="%SCRIPTURLPATH{edit}%/%WEB%/">
+ <form name="new" action="%SCRIPTURLPATH{edit}%/Sandbox/">
* New example topic:
- <input type="text" name="topic" value="ExampleTopic%SERVERTIME{$yearx$mox$day}%" size="26" />
+ <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" value="Create" />
- (date format is <nop>YYYYxMMxDD)
</form>
See [[TWikiScripts#edit]] for details of the parameters that the `edit` script understands.
%T% **TIP:** You can use the `%WIKIUSERNAME%` and `%DATE%` variables in your topic templates to include the signature of the person creating a new topic. The variables are expanded into fixed text when a new topic is created. The standard signature is: <br /><code>**-- %WIKIUSERNAME% - %DATE%**</code>
-<a name="AutomaticallyGeneratedTopicname"></a>
-
-### <a name="Automatically Generated Topicnam"></a> Automatically Generated Topicname
-
-For TWiki application it is useful to automatically generate unique topicnames, such as BugID0001, BugID0002, etc. You can add `AUTOINC<n>` to the topic name in the edit and save scripts, it gets 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)
-
-Example link to create a new topic:%BR%
+### <a name="Using Absolute vs Relative URLs"></a><a name="Using Absolute vs Relative URLs "></a> Using Absolute vs Relative URLs in Templates
- [[%SCRIPTURLPATH{"edit"}%/%WEB%/BugIDAUTOINC00000?templatetopic=BugTemplate&topicparent=%TOPIC%&t=%SERVERTIME{"$day$hour$min$sec"}%][Create new item]]=
-
-## <a name="Master Templates by Example"></a> Master Templates by Example
-
-Attached is an example of an oops based template `oopsbase.tmpl` and an example oops dialog `oopstest.tmpl` based on the base template. %T% **NOTE:** This isn't the release version, just a quick, simple demo.
-
-### <a name="Base template oopsbase.tmpl"></a> Base template oopsbase.tmpl
-
-The first line declares a delimiter variable called "sep", used to separate multiple link items. The variable can be called anywhere by writing `%TMPL:P{"sep"}%`
-
-> %TMPL:DEF{"sep"}% | %TMPL:END%
-> <html>
-> <head>
-> <title> %WIKITOOLNAME% . %WEB% . %TOPIC% %.TMPL:P{"titleaction"}%</title>
-> <base href="%SCRIPTURLPATH{"view"}%/%WEB%/%TOPIC%">
-> <meta name="robots" content="noindex">
-> </head>
-> <body bgcolor="#FFFFFF">
-> <table width="100%" border="0" cellpadding="3" cellspacing="0">
-> <tr>
-> <td bgcolor="%WEBBGCOLOR%" rowspan="2" valign="top" width="1%">
-> <a href="%WIKIHOMEURL%">
-> <img src="%PUBURLPATH%/wikiHome.gif" border="0"></a>
-> </td>
-> <td>
-> <b>%WIKITOOLNAME% . %WEB% . </b><font size="+2">
-> <B>%TOPIC%</b> %TMPL:P{"titleaction"}%</font>
-> </td>
-> </tr>
-> <tr bgcolor="%WEBBGCOLOR%">
-> <td colspan="2">
-> %TMPL:P{"webaction"}%
-> </td>
-> </tr>
-> </table>
-> --- ++ %TMPL:P{"heading"}%
-> %TMPL:P{"message"}%
-> <table width="100%" border="0" cellpadding="3" cellspacing="0">
-> <tr bgcolor="%WEBBGCOLOR%">
-> <td valign="top">
-> Topic <b>%TOPIC%</b> . {
-> %TMPL:P{"topicaction"}%
-> }
-> </td>
-> </tr>
-> </table>
-> </body>
-
-### <a name="Test template oopstest.tmpl"></a> Test template oopstest.tmpl
-
-Each oops template basically just defines some variables and includes the base template that does the layout work.
-
-> %TMPL:DEF{"titleaction"}% (test =titleaction=) %TMPL:END%
-> %TMPL:DEF{"webaction"}% test =webaction= %TMPL:END%
-> %TMPL:DEF{"heading"}%
-> Test heading %TMPL:END%
-> %TMPL:DEF{"message"}%
-> Test =message=. Blah blah blah blah blah blah blah blah blah blah blah...
->
-> * Some more blah blah blah blah blah blah blah blah blah blah...
-> * Param1: %PARAM1%
-> * Param2: %PARAM2%
-> * Param3: %PARAM3%
-> * Param4: %PARAM4%
-> %TMPL:END%
-> %TMPL:DEF{"topicaction"}%
-> Test =topicaction=:
-> [[%WEB%.%TOPIC%][OK]] %TMPL:P{"sep"}%
-> [[%TWIKIWEB%.TWikiRegistration][Register]] %TMPL:END%
-> %TMPL:INCLUDE{"oopsbase"}%
-
-### <a name="Sample screen shot of oopstest.t"></a> Sample screen shot of oopstest.tmpl
-
-With URL: <code>**.../bin/oops/Sandbox/TestTopic2?template=oopstest&param1=WebHome&param2=WebNotify**</code>
-
-<img src="http://www.dementia.org/twiki//view/testscreen.gif" width="589" height="304" alt="testscreen.gif" style="border: 1px solid #ddd" />
+When you use [[TWikiVariables]] such as %PUBURL% and %PUBURLPATH% in templates you should be aware that using %PUBURL% instead of %PUBURLPATH% puts absolute URLs in the produced HTML. This means that when a user saves a TWiki page in HTML and emails the file to someone outside a company firewall, the receiver has a severe problem viewing it. It is therefore recommended always to use the %PUBURLPATH% to refer to images, CSS, Javascript files etc so links become relative. This way browsers just give up right away and show a usable html file.
**_Related Topics:_** [[TWikiSkins]], [[DeveloperDocumentationCategory]], [[AdminDocumentationCategory]]
--- **_Contributors:_** TWiki:Main.CrawfordCurrie, TWiki:Main.PeterThoeny, TWiki:Main.MikeMannix, TWiki:Main.DavidLeBlanc
+-- **_Contributors:_** TWiki:Main.PeterThoeny, TWiki:Main.MikeMannix, TWiki:Main.DavidLeBlanc, TWiki:Main.CrawfordCurrie
<ul>
<li><a href="#Package =TWiki::Templates="> Package TWiki::Templates</a><ul>
<li><a href="#ClassMethod <strong>new</strong> ($session)"> ClassMethod new <tt>($session)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
<li><a href="#ObjectMethod <strong>haveTemplate</strong> ($na"> ObjectMethod haveTemplate <tt>($name) -> $boolean</tt></a></li>
<li><a href="#ObjectMethod <strong>expandTemplate</strong> ($"> ObjectMethod expandTemplate <tt>($params) -> $string</tt></a></li>
</ul>
- $session - session (TWiki) object
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
+
+Break circular references.
+
## <a name="ObjectMethod <strong>haveTemplate</strong> ($na"></a> [[ObjectMethod]] **haveTemplate** `($name) -> $boolean`
Return true if the template exists and is loaded into the cache
Handles the following formats:
+Default TWiki format
+
- 31 Dec 2001 - 23:59
+
+TWiki format without time (defaults to 00:00)
+
+- 31 Dec 2001
+
+Date seperated by '/', '.' or '-', time with '.' or ':' Date and time separated by ' ', '.' and/or '-'
+
- 2001/12/31 23:59:59
- 2001.12.31.23.59.59
- 2001/12/31 23:59
- 2001.12.31.23.59
+- 2001-12-31 23:59
+- 2001-12-31 - 23:59
+
+ISO format
+
- 2001-12-31T23:59:59
ISO dates may have a timezone specifier, either Z or a signed difference in hh:mm format. For example:
Examples:
- `%INCLUDE{"http://www.google.com/"}%`
-- `%INCLUDE{"TWiki.WebHome"}%`
+- `%INCLUDE{"%SYSTEMWEB%.WebHome"}%`
- `%INCLUDE{"WebHome"}%`
[[See More Tips...|Main/TWikiTipsOfTheDay]]
More [[search help|Main/SearchHelp]]
-[[See More Tips...|TWiki/TWikiTipsOfTheDay]]
+[[See More Tips...|SYSTEMWEB/TWikiTipsOfTheDay]]
-- TWiki:Main.PeterThoeny - 06 Feb 2005
You can use an RSS news reader to find out what is new in a TWiki web. This complements [[WebChanges]] that shows recent changes in a web, and [[WebNotify]] where people can subscribe to get notified of recent changes by e-mail.
-For the Main web, point your RSS news reader to:
+For the %USERSWEB% web, point your RSS news reader to:
-<code> <http://www.dementia.org/twiki//view/Main/WebRss> </code>
+<code> <http://www.dementia.org/twiki//view/%USERSWEB%/WebRss> </code>
-For other TWiki webs, replace `/Main/` with the name of the web:
+For other TWiki webs, replace `/%USERSWEB%/` with the name of the web:
**_See also:_**
- [[WebRssBase]] - help on TWiki RSS news feeds
- TWiki:Codev/TWikiSyndication - TWiki RSS news feed documentation
-[[See More Tips...|TWiki/TWikiTipsOfTheDay]]
+[[See More Tips...|SYSTEMWEB/TWikiTipsOfTheDay]]
-- TWiki:Main.PeterThoeny - 06 Feb 2005
# <a name="TWiki Tips Of The Day"></a> TWiki Tips Of The Day
-These are all tips of the day. They are located in the TWiki web (official TWiki tips) and Main web (custom tips).
+These are all tips of the day. They are located in the %SYSTEMWEB% web (official TWiki tips) and %USERSWEB% web (custom tips).
# <a name="TWiki Installation Error"></a> TWiki Installation Error
## <a name="Add a Custom %WIKITOOLNAME% Tip"></a> Add a Custom %WIKITOOLNAME% Tip
-Custom tips are located in the Main web. You can add custom tips that are specific to your TWiki installation and to your organization in general.
+Custom tips are located in the %USERSWEB% web. You can add custom tips that are specific to your TWiki installation and to your organization in general.
-<form action="http://www.dementia.org/twiki//edit/Main/" name="newlocal"><input name="topic" type="hidden" value="TWikiCustomTip002" /> <input name="onlynewtopic" type="hidden" value="on" /> <input name="templatetopic" type="hidden" value="TWiki.TWikiTipsOfTheDayTemplate" /> New Custom Tip: TWikiCustomTip002 <input type="submit" value="Create" /></form>
+<form action="http://www.dementia.org/twiki//edit/%USERSWEB%/" name="newlocal"><input name="topic" type="hidden" value="TWikiCustomTip002" /> <input name="onlynewtopic" type="hidden" value="on" /> <input name="templatetopic" type="hidden" value="%SYSTEMWEB%.TWikiTipsOfTheDayTemplate" /> New Custom Tip: TWikiCustomTip002 <input type="submit" value="Create" /></form>
## <a name="Add an Official TWiki Tip"></a> Add an Official TWiki Tip
-Official TWiki tips are located in the TWiki web. Please do not submit new tips on your local TWiki installation since they will get lost on a TWiki upgrade. Visit TWiki:TWiki.TWikiTipsOfTheDayAddNew to contribute official TWiki tips.
+Official TWiki tips are located in the %SYSTEMWEB% web. Please do not submit new tips on your local TWiki installation since they will get lost on a TWiki upgrade. Visit TWiki:TWiki.TWikiTipsOfTheDayAddNew to contribute official TWiki tips.
<form action="http://www.dementia.org/twiki//edit/%WEB%/" name="new"><input name="topic" type="hidden" value="TWikiTip002" /> <input name="onlynewtopic" type="hidden" value="on" /> <input name="topicparent" type="hidden" value="TWikiTipsOfTheDay" /> <input name="templatetopic" type="hidden" value="TWikiTipsOfTheDayTemplate" /> New Official TWiki Tip: TWikiTip002 <input type="hidden" value="Create" /></form>
<table border="1" cellpadding="0" cellspacing="0">
<tr>
- <td>[[Main/TWikiTipsOfTheDay]] <a href="http://www.dementia.org/twiki//edit/%WEB%/TWikiTipsOfTheDay?t=115749" target="_top"><img alt="Edit topic" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/edittopic.gif" width="16" /></a> [[Main/TWikiTipsOfTheDay]]</td>
- <td> Aggregated List of All Tips, from Main and TWiki. </td>
+ <td>[[Main/TWikiTipsOfTheDay]] <a href="http://www.dementia.org/twiki//edit/%WEB%/TWikiTipsOfTheDay?t=120846" target="_top"><img alt="Edit topic" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/edittopic.gif" width="16" /></a> [[Main/TWikiTipsOfTheDay]]</td>
+ <td> Aggregated List of All Tips, from %USERSWEB% and %SYSTEMWEB%. </td>
</tr>
<tr>
- <td>[[Main/TWikiTipsOfTheDayAddNew]] <a href="http://www.dementia.org/twiki//edit/%WEB%/TWikiTipsOfTheDayAddNew?t=115749" target="_top"><img alt="Edit topic" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/edittopic.gif" width="16" /></a> [[Main/TWikiTipsOfTheDayAddNew]]</td>
+ <td>[[Main/TWikiTipsOfTheDayAddNew]] <a href="http://www.dementia.org/twiki//edit/%WEB%/TWikiTipsOfTheDayAddNew?t=120846" target="_top"><img alt="Edit topic" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/edittopic.gif" width="16" /></a> [[Main/TWikiTipsOfTheDayAddNew]]</td>
<td> Add A New Tip </td>
</tr>
<tr>
- <td>[[Main/TWikiTipsOfTheDayInclude]] <a href="http://www.dementia.org/twiki//edit/%WEB%/TWikiTipsOfTheDayInclude?t=115749" target="_top"><img alt="Edit topic" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/edittopic.gif" width="16" /></a> [[Main/TWikiTipsOfTheDayInclude]]</td>
+ <td>[[Main/TWikiTipsOfTheDayInclude]] <a href="http://www.dementia.org/twiki//edit/%WEB%/TWikiTipsOfTheDayInclude?t=120846" target="_top"><img alt="Edit topic" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/edittopic.gif" width="16" /></a> [[Main/TWikiTipsOfTheDayInclude]]</td>
<td> This topic generates the random tip to display. It gets included to the focus box. </td>
</tr>
<tr>
- <td>[[Main/TWikiTipsOfTheDayTemplate]] <a href="http://www.dementia.org/twiki//edit/%WEB%/TWikiTipsOfTheDayTemplate?t=115749" target="_top"><img alt="Edit topic" border="0" height="16" src="http://www.dementia.org/twiki//view/TWiki/TWikiDocGraphics/edittopic.gif" width="16" /></a> [[Main/TWikiTipsOfTheDayTemplate]]</td>
+ <td>[[Main/TWikiTipsOfTheDayTemplate]] <a href="http://www.dementia.org/twiki//edit/%WEB%/TWikiTipsOfTheDayTemplate?t=120846" target="_top"><img alt="Edit topic" border="0" height="16" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiDocGraphics/edittopic.gif" width="16" /></a> [[Main/TWikiTipsOfTheDayTemplate]]</td>
<td> Template for new TWiki Tips </td>
</tr>
</table>
Quick Summary with link to more information.
-[[See More Tips...|TWiki/TWikiTipsOfTheDay]]
+[[See More Tips...|SYSTEMWEB/TWikiTipsOfTheDay]]
-- Main.admin - 29 Jun 2010
</ul>
</div>
-The basic building block of a TWiki site is called a **_topic_**, identified by a unique, hopefully descriptive, [[WikiWord]] title. It may seem easier just to call them pages, but specifically a topic is the content of a page. The distinction seems small but will become more important as your skill using TWiki increases. [[TWikiSites]] are built using topics.
+The basic building block of a TWiki site is called a **_topic_**, identified by a unique, hopefully descriptive, %SYSTEMWEB%.WikiWord title. It may seem easier just to call them pages, but specifically a topic is the content of a page. The distinction seems small but will become more important as your skill using TWiki increases. [[TWikiSites]] are built using topics.
## <a name="Characteristics"></a> Characteristics
- include links to other topics, URLs, Web sites, files, images, sounds, or anything else you can put on a regular Web page
- handy pop-up quick reference
- do all of this through whatever web browser you are familiar with
-- [[access control|TWiki/TWikiAccessControl]]
+- [[access control|SYSTEMWEB/TWikiAccessControl]]
- independently determine who can see, edit, rename, move or delete topics
- set permissions by individual users and user groups
- over-ride topic, TWiki web or site
Features that can be used by topics and sites include:
-- [[TWiki Skins|TWiki/TWikiSkins]] to customize the look of headers and footers when topics are converted to Web pages for display:
+- [[TWiki Skins|SYSTEMWEB/TWikiSkins]] to customize the look of headers and footers when topics are converted to Web pages for display:
- default and user selectable per session
- fully configurable look and feel
- apply skins across an entire TWiki web, or to a single displayed page
- variables
- similar to a command line context with site wide and locally defined variables
- over-ride topic, TWiki web or site
-- [[forms|TWiki/TWikiForms]]
+- [[forms|SYSTEMWEB/TWikiForms]]
- store database-style info alongside the free-form topic content
- accesses meta-data
- use text fields and boxes, radio buttons, pulldown selector menus, checkboxes
- **To add a new topic**: the simplest way is to type a new [[WikiName]] in an existing topic, while you're in edit mode. When the topic is saved, the new name will appear highlighted, with a **?** at the end: click the **?** and a new edit window appears. Enter, preview and save as usual. The new topic now exists.
- Go back to the topic where you started, and you'll see the **?** has disappeared, and your [[WikiWord]] name is now a regular link. Type it anywhere on any topic in that web, and it will be turned into a link.
- - %H% **One little links rule: each topic, and its [[WikiWord]] link, belong to one unique web only.** To link _between_ webs, you must first enter the topic's web name. <br />**_Example:_** This is %TOPIC%, in the <code>**TWiki**</code> web, so that's all you need to type on any topic in this web. But to link to %TOPIC% from a topic in the <code>**Main**</code> web, you have to type <code>**TWiki.%TOPIC%**</code> - <code>**Webname.TopicName**</code>. It's easy.
+ - %H% **One little links rule: each topic, and its [[WikiWord]] link, belong to one unique web only.** To link _between_ webs, you must first enter the topic's web name. <br />**_Example:_** This is %TOPIC%, in the <code>**TWiki**</code> web, so that's all you need to type on any topic in this web. But to link to %TOPIC% from a topic in the <code>**%USERSWEB%**</code> web, you have to type <code>**%SYSTEMWEB%.%TOPIC%**</code> - <code>**Webname.TopicName**</code>. It's easy.
Another way to add a topic is to type a new topic name in the Go box or an unknown topic URL. You can type in either a [[WikiName]] to create the topic in the current web or Web.TopicName to create a topic in a different web than the current page. Topics created with the Go box or URLs do not have parent meta-data defined.
- Some controls are self-explanatory and also include instructions and help links.
- **Experiment**. You can always <code>**Cancel**</code> an edit or (using revision control) go Back whenever you like.
-- Get **in-depth info** from the [[complete documentation|TWiki/WebHome]], including the User's Guide, Configuration Manual and TWiki Reference.
+- Get **in-depth info** from the [[complete documentation|SYSTEMWEB/WebHome]], including the User's Guide, Configuration Manual and TWiki Reference.
<a name="RenamingTopics"></a>
+# <a name="20-Minute TWiki Tutorial"></a> 20-Minute TWiki Tutorial
+
+This step-by-step, hands-on tutorial gets you up to speed with all the [[TWikiSite]] basics, in _mere minutes_...
+
<div>
<ul>
<li><a href="#20-Minute TWiki Tutorial"> 20-Minute TWiki Tutorial</a><ul>
</ul>
</div>
-# <a name="20-Minute TWiki Tutorial"></a> 20-Minute TWiki Tutorial
-
-This step-by-step, hands-on tutorial gets you up to speed with all the [[TWikiSite]] basics, in _mere minutes_...
-
## <a name="1. Get set..."></a> 1. Get set...
Open two browser windows, so that you can follow these steps in one window, while trying things out in the other.
## <a name="4. Check out TWiki users, groups"></a> 4. Check out TWiki users, groups.
-- Go to the [[TWikiUsers]] topic in the TWiki.Main web; it has a list of all users of TWiki. Your [[WikiName]] will be in this list after you register.
-- Go to the [[TWikiGroups]] topic in the Main web; it has a list of groups which can be used to define fine grained [[TWikiAccessControl]] in TWiki.
+- Go to the %USERSWEB%.TWikiUsers topic; it has a list of all users of TWiki. Your [[WikiName]] will be in this list after you register.
+- Go to the %USERSWEB%.TWikiGroups topic in the %USERSWEB% web; it has a list of groups which can be used to define fine grained [[TWikiAccessControl]] in TWiki.
## <a name="5. Test the page controls..."></a> 5. Test the page controls...
2. Preview and save the topic. The name appears, highlighted, with a linked question mark at the end. This means that the topic doesn't exist yet.
3. Click on the question mark. Now you're in edit mode of the new topic.
4. Type some text, basically, like you write an e-mail.
- 5. A signature with your name is already entered by default. **_NOTE:_** The `Main.` in front of your name means that you have a link from the current web to your personal topic located in the Main web.
+ 5. A signature with your name is already entered by default. **_NOTE:_** The `%USERSWEB%.` in front of your name means that you have a link from the current web to your personal topic located in the %USERSWEB% web.
6. Preview and save the topic...
- Learn about text formatting. You can enter text in TWikiShorthand, a very simple markup language. Follow the [[TWikiShorthand]] link to see how, then:
1. Go back to your sandbox topic end edit it.
## <a name="StaticMethod <strong>edit</strong> ($session)"></a> [[StaticMethod]] **edit** `($session)`
-Edit command handler. This method is designed to be invoked via the `TWiki::UI::run` method. Most parameters are in the CGI query:
+Edit command handler. This method is designed to be invoked via the `UI::run` method. Most parameters are in the CGI query:
<table border="1" cellpadding="0" cellspacing="0">
<tr>
## <a name="StaticMethod <strong>manage</strong> ($session)"></a> [[StaticMethod]] **manage** `($session)`
-`manage` command handler. This method is designed to be invoked via the `TWiki::UI::run` method.
+`manage` command handler. This method is designed to be invoked via the `UI::run` method.
## <a name="StaticMethod <strong>rename</strong> ($session)"></a> [[StaticMethod]] **rename** `($session)`
-`rename` command handler. This method is designed to be invoked via the `TWiki::UI::run` method. Rename the given topic. Details of the new topic name are passed in CGI parameters:
+`rename` command handler. This method is designed to be invoked via the `UI::run` method. Rename the given topic. Details of the new topic name are passed in CGI parameters:
<table border="1" cellpadding="0" cellspacing="0">
<tr>
## <a name="StaticMethod <strong>oops_cgi</strong> ($sessio"></a> [[StaticMethod]] **oops\_cgi** `($session)`
-`oops` command handler. This method is designed to be invoked via the `TWiki::UI::run` method. CGI parameters:
+`oops` command handler. This method is designed to be invoked via the `UI::run` method. CGI parameters:
<table border="1" cellpadding="0" cellspacing="0">
<tr>
## <a name="StaticMethod <strong>diff</strong> ($session,$w"></a> [[StaticMethod]] **diff** `($session,$web,$topic,$query)`
-`diff` command handler. This method is designed to be invoked via the `TWiki::UI::run` method.
+`diff` command handler. This method is designed to be invoked via the `UI::run` method.
Renders the differences between version of a [[TwikiTopic]]
<ul>
<li><a href="#Package =TWiki::UI::Register="> Package TWiki::UI::Register</a><ul>
<li><a href="#StaticMethod <strong>register_cgi</strong> ($se"> StaticMethod register_cgi <tt>($session)</tt></a></li>
- <li><a href="#StaticMethod <strong>passwd_cgi</strong> ($sess"> StaticMethod passwd_cgi <tt>($session)</tt></a></li>
<li><a href="#StaticMethod <strong>bulkRegister</strong> ($se"> StaticMethod bulkRegister <tt>($session)</tt></a></li>
- <li><a href="#StaticMethod *register_AndNext*"> StaticMethod registerAndNext <tt>($session,$tempUserDir)</tt></a></li>
+ <li><a href="#StaticMethod *register_AndNext*"> StaticMethod registerAndNext <tt>($session)</tt></a></li>
<li><a href="#StaticMethod <strong>register</strong> ($sessio"> StaticMethod register <tt>($session)</tt></a></li>
<li><a href="#StaticMethod <strong>resetPassword</strong> ($s"> StaticMethod resetPassword <tt>($session)</tt></a></li>
<li><a href="#StaticMethod <strong>changePassword</strong> ($"> StaticMethod changePassword <tt>($session)</tt></a></li>
- <li><a href="#StaticMethod *verify_EmailAddres"> StaticMethod verifyEmailAddress <tt>($session,$tempUserDir)</tt></a></li>
- <li><a href="#StaticMethod *finish*"> StaticMethod finish <tt></tt></a></li>
+ <li><a href="#StaticMethod *verify_EmailAddres"> StaticMethod verifyEmailAddress <tt>($session)</tt></a></li>
</ul>
</li>
</ul>
## <a name="StaticMethod <strong>register_cgi</strong> ($se"></a> [[StaticMethod]] **register\_cgi** `($session)`
-`register` command handler. This method is designed to be invoked via the `TWiki::UI::run` method.
-
-## <a name="StaticMethod <strong>passwd_cgi</strong> ($sess"></a> [[StaticMethod]] **passwd\_cgi** `($session)`
-
-`passwd` command handler. This method is designed to be invoked via the `TWiki::UI::run` method.
+`register` command handler. This method is designed to be invoked via the `UI::run` method.
## <a name="StaticMethod <strong>bulkRegister</strong> ($se"></a> [[StaticMethod]] **bulkRegister** `($session)`
Called by [[ManageCgiScript]]::bulkRegister (requires authentication) with topic = the page with the entries on it.
-1. Makes sure you are an admin user ;)
-2. Calls TWiki::Data::DelimitedFile (delimiter => '|', content =>textReadFromTopic)
-3. ensures requiredFieldsPresent()
-4. starts a log file
-5. calls registerSingleBulkUser() for each row
-6. writes output to log file, sets [[TWiki.TOPICPARENT|TWiki/TOPICPARENT]] back to page with entries on it.
-7. redirects to log file
-
-## <a name="StaticMethod <strong>register_AndNext*"></a><a name="StaticMethod *register_AndNext</strong> "></a> [[StaticMethod]] **registerAndNext** `($session,$tempUserDir)`
+## <a name="StaticMethod <strong>register_AndNext*"></a><a name="StaticMethod *register_AndNext</strong> "></a> [[StaticMethod]] **registerAndNext** `($session)`
This is called when action = register or action = ""
This is called through: [[TWikiRegistration]] -> [[RegisterCgiScript]] -> here
-1. gets rows and fields from the query
-2. calls \_validateRegistration() to ensure required fields correct, else [[OopsException]]
-
## <a name="StaticMethod <strong>resetPassword</strong> ($s"></a> [[StaticMethod]] **resetPassword** `($session)`
-Generates a password. Mails it to them and asks them to change it. Entry point intended to be called from TWiki::UI::run
+Generates a password. Mails it to them and asks them to change it. Entry point intended to be called from UI::run
## <a name="StaticMethod <strong>changePassword</strong> ($"></a> [[StaticMethod]] **changePassword** `($session)`
An admin user can change other user's passwords.
-## <a name="StaticMethod <strong>verify_EmailAddres"></a> [[StaticMethod]] \*verifyEmailAddress `($session,$tempUserDir)`
+## <a name="StaticMethod <strong>verify_EmailAddres"></a> [[StaticMethod]] \*verifyEmailAddress `($session)`
This is called: on receipt of the activation password -> [[RegisterCgiScript]] -> here
-1. calls \_reloadUserContext(activation password)
+1. calls \_loadPendingRegistration(activation password)
2. throws oops if appropriate
3. calls emailRegistrationConfirmations
4. still calls 'oopssendmailerr' if a problem, but this is not done uniformly
-
-## <a name="StaticMethod <strong>finish*"></a><a name="StaticMethod *finish</strong> "></a> [[StaticMethod]] **finish** ``
-
-Presently this is called in [[RegisterCgiScript]] directly after a call to verify. The separation is intended for the [[RegistrationApprovals]] functionality
-
-1. calls \_reloadUserContext (throws oops if appropriate)
-2. calls createUserTopic()
-3. if using the htpasswdFormatFamily, calls \_addUserToPasswordSystem
-4. calls the misnamed [[RegistrationHandler]] to set cookies
-5. calls addUserToMapping
-6. writes the logEntry (if wanted :/)
-7. redirects browser to 'oopsregthanks'
-
-reloads the context by code these two are separate in here to ease the implementation of administrator approval
## <a name="StaticMethod <strong>save</strong> ($session)"></a> [[StaticMethod]] **save** `($session)`
-Command handler for `save` command. This method is designed to be invoked via the `TWiki::UI::run` method.
+Command handler for `save` command. This method is designed to be invoked via the `UI::run` method.
See [[TWikiScripts]] for details of parameters.
<td> N/A </td>
</tr>
<tr>
- <td><code>web="Name"</code><br /><code>web="Main, Know"</code><br /><code>web="all"</code></td>
+ <td><code>web="Name"</code><br /><code>web="%USERSWEB%, Know"</code><br /><code>web="all"</code></td>
<td> Comma-separated list of webs to search. The special word <code>all</code> means all webs that doe <strong>not</strong> have the <code>NOSEARCHALL</code> variable set to <code>on</code> in their [[Main/WebPreferences]]. You can specifically <strong>exclude</strong> webs from an <code>all</code> search using a minus sign - for example, <code>web="all,-Secretweb"</code>. </td>
<td> Current web </td>
</tr>
## <a name="StaticMethod <strong>statistics</strong> ($sess"></a> [[StaticMethod]] **statistics** `($session)`
-`statistics` command handler. This method is designed to be invoked via the `TWiki::UI::run` method.
+`statistics` command handler. This method is designed to be invoked via the `UI::run` method.
Generate statistics topic. If a web is specified in the session object, generate [[WebStatistics]] topic update for that web. Otherwise do it for all webs
## <a name="StaticMethod <strong>attach</strong> ($session)"></a> [[StaticMethod]] **attach** `($session)`
-`upload` command handler. This method is designed to be invoked via the `TWiki::UI::run` method.
+`attach` command handler. This method is designed to be invoked via the `UI::run` method.
-Adds the meta-data for an attachment to a toic. Does **not** upload the attachment itself, just modifies the meta-data.
+Generates a prompt page for adding an attachment.
## <a name="StaticMethod <strong>upload</strong> ($session)"></a> [[StaticMethod]] **upload** `($session)`
-`upload` command handler. This method is designed to be invoked via the `TWiki::UI::run` method. CGI parameters, passed in $query:
+`upload` command handler. This method is designed to be invoked via the `UI::run` method. CGI parameters, passed in $query:
<table border="1" cellpadding="0" cellspacing="0">
<tr>
</tr>
<tr>
<td><code>filecomment</code></td>
- <td> Comment to associate with file in attachment table </td>
+ <td> comment to associate with file in attachment table </td>
</tr>
<tr>
<td><code>createlink</code></td>
<td><code>changeproperties</code></td>
<td> </td>
</tr>
+ <tr>
+ <td><code>redirectto</code></td>
+ <td> URL to redirect to after upload. <code>{AllowRedirectUrl}</code> must be enabled in <code>configure</code>. The parameter value can be a <code>TopicName</code>, a <code>Web.TopicName</code>, or a URL. Redirect to a URL only works if it is enabled in <code>configure</code>. </td>
+ </tr>
</table>
-Does the work of uploading a file to a topic. Designed to be useable as a REST method (it will redirect to the 'view' script unless the 'noredirect' parameter is specified, in which case it will print a message to STDOUT, starting with 'OK' on success and 'ERROR' on failure.
+Does the work of uploading a file to a topic. Designed to be useable for a crude RPC (it will redirect to the 'view' script unless the 'noredirect' parameter is specified, in which case it will print a message to STDOUT, starting with 'OK' on success and 'ERROR' on failure.
## <a name="StaticMethod <strong>view</strong> ($session)"></a> [[StaticMethod]] **view** `($session)`
-`view` command handler. This method is designed to be invoked via the `TWiki::UI::run` method.
+`view` command handler. This method is designed to be invoked via the `UI::run` method.
Generate a complete HTML page that represents the viewed topics. The view is controlled by CGI parameters as follows:
## <a name="StaticMethod <strong>viewfile</strong> ($sessio"></a> [[StaticMethod]] **viewfile** `($session,$web,$topic,$query)`
-`viewfile` command handler. This method is designed to be invoked via the `TWiki::UI::run` method. Command handler for viewfile. View a file in the browser. Some parameters are passed in CGI query:
+`viewfile` command handler. This method is designed to be invoked via the `UI::run` method. Command handler for viewfile. View a file in the browser. Some parameters are passed in CGI query:
<table border="1" cellpadding="0" cellspacing="0">
<tr>
-# <a name="TWiki Upgrade Guide"></a><a name=" TWiki Upgrade Guide"></a> TWiki Upgrade Guide
+# <a name="TWiki Upgrade Guide"></a> TWiki Upgrade Guide
-_This guide covers upgrading from a previous version of TWiki (such as Cairo or TWiki4.0) to TWiki 4.1\__
+_This guide covers upgrading from a previous version of TWiki (such as Cairo or TWiki4.0) to TWiki 4.2_
<div>
<ul>
- <li><a href="#Overview"> Overview</a></li>
- <li><a href="#Upgrade Requirements"> Upgrade Requirements</a></li>
- <li><a href="#Major Changes Compared to TWiki"> Major Changes Compared to TWiki Release 01-Sep-2004 and TWiki Release 4.0.0</a></li>
- <li><a href="#Upgrade Procedure"> Upgrade Procedure</a><ul>
- <li><a href="#Installation"> Installation</a></li>
- <li><a href="#Install Extensions"> Install Extensions</a></li>
- <li><a href="#Copy your old webs to new TWiki"> Copy your old webs to new TWiki</a></li>
- <li><a href="#Copy Users And Their Topics From"> Copy Users And Their Topics From Main Web</a></li>
- <li><a href="#Apply Customizations To The Skin"> Apply Customizations To The Skin</a></li>
- <li><a href="#Apply Preferences From Old Insta"> Apply Preferences From Old Installation</a></li>
- </ul>
- </li>
- <li><a href="#Upgrading from Cairo to TWiki4 ("> Upgrading from Cairo to TWiki4 (additional advice)</a><ul>
- <li><a href="#Favicon"> Favicon</a></li>
- <li><a href="#!_TWikiUsers topic in Main web"> TWikiUsers topic in Main web</a></li>
- </ul>
- </li>
- <li><a href="#Important Changes since 4.0.5"> Important Changes since 4.0.5</a><ul>
- <li><a href="#Supported Perl version"> Supported Perl version</a></li>
- <li><a href="#Template spec changed"> Template spec changed</a></li>
- </ul>
- </li>
- <li><a href="#Important Changes since 4.1.0"> Important Changes since 4.1.0</a><ul>
- <li><a href="#New location for session files"> New location for session files</a></li>
+ <li><a href="#TWiki Upgrade Guide"> TWiki Upgrade Guide</a><ul>
+ <li><a href="#Overview"> Overview</a></li>
+ <li><a href="#Upgrade Requirements"> Upgrade Requirements</a></li>
+ <li><a href="#Major Changes Compared to TWiki"> Major Changes Compared to TWiki Release 01-Sep-2004 and TWiki Release 4.0.0</a></li>
+ <li><a href="#Upgrade Procedure"> Upgrade Procedure</a><ul>
+ <li><a href="#Installation"> Installation</a></li>
+ <li><a href="#Install Extensions"> Install Extensions</a></li>
+ <li><a href="#Copy your old webs to new TWiki"> Copy your old webs to new TWiki</a></li>
+ <li><a href="#Copy Users And Their Topics From"> Copy Users And Their Topics From Main Web</a></li>
+ <li><a href="#Apply Customizations To The Skin"> Apply Customizations To The Skin</a></li>
+ <li><a href="#Apply Preferences From Old Insta"> Apply Preferences From Old Installation</a></li>
+ </ul>
+ </li>
+ <li><a href="#Customization of Special Pages"> Customization of Special Pages</a></li>
+ <li><a href="#Upgrading from Cairo to TWiki4 ("> Upgrading from Cairo to TWiki4 (additional advice)</a><ul>
+ <li><a href="#Favicon"> Favicon</a></li>
+ <li><a href="#!_TWikiUsers topic in Main web"> TWikiUsers topic in Main web</a></li>
+ </ul>
+ </li>
+ <li><a href="#Important Changes since 4.0.5"> Important Changes since 4.0.5</a><ul>
+ <li><a href="#Supported Perl version"> Supported Perl version</a></li>
+ <li><a href="#Template spec changed"> Template spec changed</a></li>
+ </ul>
+ </li>
+ <li><a href="#Important Changes since 4.1.0"> Important Changes since 4.1.0</a><ul>
+ <li><a href="#New location for session and oth"> New location for session and other temporary files</a></li>
+ </ul>
+ </li>
+ <li><a href="#Important Changes since 4.1.2"> Important Changes since 4.1.2</a><ul>
+ <li><a href="#New WYSIWYG Editor"> New WYSIWYG Editor</a></li>
+ <li><a href="#NEWTOPICLINKSYMBOL removed"> NEWTOPICLINKSYMBOL removed</a></li>
+ <li><a href="#!_UserForm and _NewUserTemplate"> UserForm and NewUserTemplate Customization</a></li>
+ <li><a href="#!_TWikiUsers no longer distribut"> TWikiUsers no longer distributed</a></li>
+ <li><a href="#New <code>working</code> directory"> New working directory</a></li>
+ <li><a href="#New Internal Admin Login"> New Internal Admin Login</a></li>
+ </ul>
+ </li>
</ul>
</li>
</ul>
## <a name="Overview"></a> Overview
-TWiki-4.0.0 was a major new release. TWiki-4.1.0 is a minor release without dramatic changes since 4.0.0
+TWiki-4.0.0 was a major new release. TWiki-4.1.0 was a minor release without dramatic changes since 4.0.0. TWiki-4.2.0 is also a minor release containing a few new features that can be seen by the end user, a large number of bug fixes, and a face lift for the skin. It also contains some important updates under the hood to the way users are handled which enables new types of authentication and integration with other systems. The most important new feature is the [[QuerySearch]] feature.
## <a name="Upgrade Requirements"></a> Upgrade Requirements
- Please review the [[AdminSkillsAssumptions]] before you upgrade TWiki
-- Review TWiki:TWiki.TWikiUpgradeTo04x00x00 for latest information and experience notes.
+- Review TWiki:TWiki.TWikiUpgradeTo04x02 for latest information and experience notes.
- To upgrade from a release prior to TWiki Release 01-Sep-2004, start with TWiki:TWiki.UpgradingTWiki on TWiki.org
- To upgrade from a standard TWiki Release 01-Sep-2004 to the latest TWiki-4.X Production Release, follow the instructions below
- Once the upgrade has been applied, an existing earlier installation will still be able to read all the topics, but should not be used to write. Make sure you take a backup!
## <a name="Major Changes Compared to TWiki"></a><a name="Major Changes Compared to TWiki "></a> Major Changes Compared to TWiki Release 01-Sep-2004 and TWiki Release 4.0.0
-See [[TWikiReleaseNotes04x00]] and [[TWikiReleaseNotes04x01]]
+See [[TWikiReleaseNotes04x00]], [[TWikiReleaseNotes04x01]] and [[TWikiReleaseNotes04x02]]
<a name="ManualUpgradeProcedure"></a>
- Follow the installation instructions in INSTALL.html which you find in the root of the new installation. Install the new release in a new directory. Do not install on top of the old release.
- Use the [configure](http://www.dementia.org/twiki/configure) script to configure TWiki.
- - If you are upgrading from a 4.0.x release, carry over the configure settings from the old release.
+ - If you are upgrading from a 4.x.x release, you can carry over the configure settings from the old release.
+ - You need to run configure and save the configuration once when you upgrade as this will update the altered and added settings.
+ - You can also choose to start with a fresh configuration and walk through all the settings using your old LocalSite.cfg as a reference. This way you will not have old obsolete settings in the new LocalSite.cfg.
+ - If at any time during the installation you want to start over from fresh all you need to do is delete the `lib/LocalSite.cfg` file and re-run configure.
- Additional resources
- TWiki:TWiki.UpgradingTWiki04x00PatchReleases
- TWiki:TWiki.InstallingTWiki#OtherPlatforms
- TWiki:TWiki.ApacheConfigGenerator
- TWiki:TWiki.SettingFileAccessRightsLinuxUnix
- - Your `lib/TWiki.cfg` from the old TWiki installation is a good resource for some of the settings you will need but you cannot reuse the old TWiki.cfg.
+ - If you upgrade from an older TWiki your `lib/TWiki.cfg` from the old TWiki installation is a good resource for some of the settings you will need but you cannot reuse the old TWiki.cfg.
- Make sure you have a working basic TWiki before you continue
### <a name="Install Extensions"></a> Install Extensions
- [[InterwikiPlugin]] - Set RULESTOPIC
- [[InterWikis]] - If you added your own rules you should save this topic and not overwrite it.
- [[SlideShowPlugin]] - Make sure you did not change the embedded 'Default Slide Template' If you did you should save it. It is a bad idea to do. It is better to define your own slide show templates as separate topics that do not get overwritten when you upgrade.
- - [[SmiliesPlugin]] - Did you add your own smileys? No smileys were added 4.0.0 and 4.0.2 so you can just leave this topic as it is.
+ - [[SmiliesPlugin]] - Did you add your own smileys? No real changes were made to the smilies topic October 2005 so you can just leave this topic as it is.
- [[TablePlugin]] - Set TABLEATTRIBUTES
- Remember that a plugin must be activated in [configure](http://www.dementia.org/twiki/configure).
+- To avoid having to re-apply plugin settings each time you upgrade a plugin or TWiki itself, define the altered plugin settings in `Main.TWikiPreferences` instead
### <a name="Copy your old webs to new TWiki"></a> Copy your old webs to new TWiki
- `find data -name '*,v' -exec rcs -u -M '{}' \;`
- `find pub -name '*,v' -exec rcs -u -M '{}' \;`
- Copy your local webs over to the data and pub directories of the new install. Do not copy the default webs: TWiki, Main, Trash, Sandbox, \_default, and \_empty.
+- Make sure all data and pub files and directories are owned by the webserver user.
+- **_Note:_** TWiki's [[WebChanges]] topics depend on the file timestamp. If you touch the .txt files make sure to preserve the timestamp, or to change them in the sequence of old file timestamps.
### <a name="Copy Users And Their Topics From"></a> Copy Users And Their Topics From Main Web
- Copy all the topics from the Main web and corresponding pub/Main directories from the old TWiki to the new TWiki but do not overwrite any of the new topics already inside the new Main directory!
-- Manually merge all the users from the old `TWiki.TWikiUsers` topic to the new TWiki. If you upgrade from Cairo you can simply use the old file and add the missing new system users to the list of users. If you upgrade from TWiki-4.0.X simply use the old topic.
+- Manually merge all the users from the old `Main.TWikiUsers` topic to the new TWiki. If you upgrade from Cairo you can simply use the old file and add the missing new system users to the list of users. If you upgrade from TWiki-4.0.X simply use the old topic. Starting from 4.2.0 TWiki no longer ships with a `Main.TWikiUsers` topic. When you register the first user TWiki now checks for an existing `Main.TWikiUsers` and if it does not exist it gets created.
- If you use `data/.htpasswd` for authentication copy this file from the old TWiki to the new.
- - If you upgrade from Cairo and you are using the Htpasswd login manager, then note that email addresses for users have moved out of user topics and into the password database. There is a script that performs this extra upgrade step for you - see `tools/upgrade_emails.pl`.
+ - If you upgrade from Cairo and you are using the Htpasswd login manager, then note that email addresses for users have moved out of user topics and into the password file. There is a script that performs this extra upgrade step for you - see `tools/upgrade_emails.pl`.
- The old sandbox web may have a lot of useful topic and users may use it actively for drafts. Manually select the topics (remember the corresponding pub directories) from the old Sandbox web and copy them to the new TWiki. Decide if you want to overwrite the sandbox homepage and left menu bar or keep the new.
+- If you added or removed fields from the user topic form you may also have tailored `TWiki.TWikiRegistration`. Make sure you either reuse the registration topic from the old installation or apply the same field changes to the new `TWiki.TWikiRegistration` topic.
+- Starting from 4.2.0 TWiki ships with `NewUserTemplate` and `UserForm` in the TWiki web. If you choose to tailor anything you are strongly adviced to copy `NewUserTemplate` and `UserForm` to the Main web and tailor the Main web copies. TWiki will look for the `NewUserTemplate` in the Main web first and if it does not exist it uses the default from the TWiki web. By creating a `Main.NewUserTemplate` and its `Main.UserForm` you will not loose your tailorings next time you upgrade TWiki.
+- Make sure all data and pub files and directories are owned by the webserver user.
### <a name="Apply Customizations To The Skin"></a> Apply Customizations To The Skin
### <a name="Apply Preferences From Old Insta"></a> Apply Preferences From Old Installation
-- Transfer any customized and local settings from [[TWiki.TWikiPreferences|TWiki/TWikiPreferences]] to the topic pointed at by \{LocalSitePreferences\} ([[Main.TWikiPreferences|Main/TWikiPreferences]]). Per default this is `Main.TWikiPreferences`. This avoids having to write over files in the distribution on a later upgrade.
-- If you changed any of the topics in the original TWiki distribution, you will have to transfer your changes to the new install manually. There is no simple way to do this, though a suggestion is to use 'diff' to find changed files in the `data/TWiki` of the old and new TWiki installation, and transfer the changes into the new TWiki install.
+- Transfer any customized and local settings from [[%SYSTEMWEB%.TWikiPreferences|SYSTEMWEB/TWikiPreferences]] to the topic pointed at by \{LocalSitePreferences\} ([[Main.TWikiPreferences|Main/TWikiPreferences]]). Per default this is `Main.TWikiPreferences`. This avoids having to write over files in the distribution on a later upgrade.
+- If you changed any of the topics in the original TWiki distribution, you will have to transfer your changes to the new install manually. There is no simple way to do this, though a suggestion is to use 'diff' to find changed files in the `data/TWiki` of the old and new TWiki installation, and transfer the changes into the new TWiki install. If you can run a GUI on your server, you may find that using a visual diff tool like WinMerge, meld, kdiff3, xxdiff, etc. is helpful.
- Compare the `WebPreferences` topics in the old TWiki Installation with the default from the new TWiki installation and add any new Preferences that may be relevant.
- Compare the `WebLeftBar` topics in the old TWiki Installation with the default from the new TWiki installation and add any new feature that you desire.
+## <a name="Customization of Special Pages"></a> Customization of Special Pages
+
+Some pages in the TWiki web are meant to be customized after choice of authentication. If you do not use the internal TWiki password manager the topics that contains the features for changing and resetting passwords and changing the email address should be changed to a note describing how to perform these tasks in your organization. If you have made such customizations remember to replace these topics in the TWiki web with the tailored versions from your old installation. The topics are:
+
+- `TWiki.ChangePassword`
+- `TWiki.ResetPassword`
+- `TWiki.ChangeEmailAddress`
+
## <a name="Upgrading from Cairo to TWiki4 ("></a> Upgrading from Cairo to TWiki4 (additional advice)
### <a name="Favicon"></a> Favicon
To change the location of favicon.ico in TWikiPreferences to the TWiki web add this line to [[TWikiPreferences]]
- * Set FAVICON = %PUBURLPATH%/%TWIKIWEB%/%WEBPREFSTOPIC%/favicon.ico
+ * Set FAVICON = %PUBURLPATH%/%SYSTEMWEB%/%WEBPREFSTOPIC%/favicon.ico
### <a name="TWikiUsers topic in Main web"></a><a name="_TWikiUsers topic in Main web"></a> TWikiUsers topic in Main web
## <a name="Important Changes since 4.1.0"></a> Important Changes since 4.1.0
-### <a name="New location for session files"></a> New location for session files
+### <a name="New location for session and oth"></a> New location for session and other temporary files
-An upgrader upgrading to 4.1.1 should note the following important change
+**An upgrader upgrading to 4.1.1 should note the following important change**
The directory for passthrough files and session files have been replaced by a common directory for temporary files used by TWiki. Previously the two configure settings `{PassthroughDir}` and `{Sessions}{Dir}` were by default set to `/tmp`. These config settings have been replaced by `{TempfileDir}` with the default setting value `/tmp/twiki`. If the `twiki` directory does not exist twiki will create it first time it needs it.
It is highly recommended no longer to use the tmp directory common to other web applications and the new default will work fine for most. You may want to delete all the old session files in /tmp after the upgrade to 4.1.1. They all start with cgisess\_. It is additionally highly recommended to limit write access to the `{TempfileDir}` for security reasons if you have non-admin users with login access to the webserver just like you would do with the other webserver directories.
+## <a name="Important Changes since 4.1.2"></a> Important Changes since 4.1.2
+
+### <a name="New WYSIWYG Editor"></a> New WYSIWYG Editor
+
+TWiki now ships with a new WYSIWYG editor based on TinyMCE replaces the Kupu based editor.%BR% TinyMCE is not a perfect Wysiwyg editor but it is magnitudes better than the Kupu editor
+
+The WysiwygPlugin that drives the engine behind both TinyMCE has additionally been heavily improved so that less TWiki Applications are negatively affected by editing WYSIWYG
+
+When TinyMCEPlugin is enabled the Edit button per default becomes WYSIWYG editing mode. A new Raw Edit link has been added to enable application developers to edit the good old way
+
+The WYSIWYG button has been removed.
+
+### <a name="NEWTOPICLINKSYMBOL removed"></a> NEWTOPICLINKSYMBOL removed
+
+The NEWTOPICLINKSYMBOL preference which was deprecated in 4.1 has now been removed from the code. If you want to control the appearance of new links, you can use NEWLINKFORMAT.
+
+### <a name="UserForm and _NewUserTemplate Cu"></a><a name="_UserForm and _NewUserTemplate C"></a> UserForm and NewUserTemplate Customization
+
+When a new user registers on TWiki his user topic is created based on the `NewUserTemplate` and `UserForm`.
+
+The `NewUserTemplate` was located in the TWiki web and the `UserForm` in the Main web. When upgrading TWiki these were some of the topics you had to take care not to overwrite.
+
+From 4.2.0 the `UserForm` and `NewUserTemplate` are distributed in the TWiki web. If you create the two in the Main web the Main web version will be used instead. So if you tailor the user topic format or the form then you should always copy the two files to the Main web and modify the ones in the Main web. When you later upgrade TWiki your tailored template and form will not be overwritten.
+
+### <a name="TWikiUsers no longer distributed"></a><a name="_TWikiUsers no longer distribute"></a> TWikiUsers no longer distributed
+
+The `Main.TWikiUsers` topic contains all the registered users. It is a topic you do not want to overwrite when you upgrade TWiki.
+
+From 4.2.0 this file is no longer included in the TWiki distribution. When you register the first time TWiki creates the `Main.TWikiUsers` topic in the Main web if it does not exist already. This means that you can now upgrade TWiki without risk of overwriting the important `TWikiUsers` topic.
+
+- For new installers this makes no difference at all
+- For upgraders this is one less problem to worry about as your important Main.TWikiUsers topic now no longer gets overwritten when upgrading.
+
+### <a name="New <code>working</code> directory"></a> New `working` directory
+
+A new directory `working` which per default is located in the twiki root, has been introduced which contains:
+
+- registration\_approvals - with 4.2.0 it is moved to here from the data directory)
+- tmp - so we now avoid having to fight with special access rights and /tmp directory that gets cleaned out when booting.
+- work\_areas - with 4.2.0 it is moved to here from the pub directory. Configure automatically moved the directory when you upgrade.
+
+Note: Remember to restrict access to this new directory when you upgrade.
+
+The configuration setting `{WorkingDir}` defines the container directory for temporary files, extensions' work areas, and intermediate registration data. The default is `working` under your installation root.
+
+Take care for that change if you run your own routine to delete obsolete session files, which will now be found under `working/tmp/cgisess*`.
+
+### <a name="New Internal Admin Login"></a> New Internal Admin Login
+
+TWiki 4.2 introduces a new _Internal Admin Login_ feature which uses "admin" (configurable) as username and the password used for configure to become temporary administrator. When you do a new installation you need to use this feature as Main.TWikiAdminGroup is now access restricted by default to avoid security attacks during the hours an installation may take. From configure there is a link to the TWikiAdminGroup topic and on TWikiAdminGroup the step by step instructions are written in a yellow box. Our advice is not to remove this help text in case you need it later.
+
**_Related Topics:_** [[AdminDocumentationCategory]], TWiki:TWiki.UpgradingTWiki, TWiki:TWiki.UpgradingTWiki04x00PatchReleases, TWiki:TWiki.InstallingTWiki#OtherPlatforms, TWiki:TWiki.ApacheConfigGenerator, TWiki:TWiki.SettingFileAccessRightsLinuxUnix
+# <a name="TWiki User Authentication"></a> TWiki User Authentication
+
+_TWiki site access control and user activity tracking options_
+
<div>
<ul>
<li><a href="#TWiki User Authentication"> TWiki User Authentication</a><ul>
</ul>
</div>
-# <a name="TWiki User Authentication"></a> TWiki User Authentication
-
-_TWiki site access control and user activity tracking options_
-
## <a name="Overview"></a> Overview
Authentication, or "login", is the process by which a user lets TWiki know who they are.
**_%T% Tip:_** TWiki:TWiki.TWikiUserAuthenticationSupplement on TWiki.org has supplemental documentation on user authentication.
+<a name="PasswordManagement"></a>
+
## <a name="Password Management"></a> Password Management
As shipped, TWiki supports the Apache 'htpasswd' password manager. This manager supports the use of `.htpasswd` files on the server. These files can be unique to TWiki, 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 \[[http://www.dementia.org/twiki/configure]\[configure] interface for more details.
You can easily plug in alternate password management modules to support interfaces to other third-party authentication databases.
+<a name="UserMapping"></a>
+
## <a name="User Mapping"></a> User Mapping
Often when you are using an external authentication method, you want to map from an unfriendly "login name" to a more friendly [[WikiName]]. Also, an external authentication database may well have user information you want to import to TWiki, such as user groups.
By default, TWiki supports mapping of usernames to wikinames, and supports TWiki groups internal to TWiki. If you want, you can plug in an alternate user mapping module to support import of groups etc.
+<a name="UserRegistration"></a>
+
## <a name="User Registration"></a> User Registration
New user registration uses the password manager to set and change passwords and store email addresses. It is also responsible for the new user verification process. the registration process supports **single user registration** via the [[TWikiRegistration]] page, and **bulk user registration** via the [[BulkRegistration]] page (for admins only).
The registration process is also responsible for creating user topics, and setting up the mapping information used by the User Mapping support.
+<a name="LoginManagement"></a>
+
## <a name="Login Management"></a> Login Management
Login management controls the way users have to log in. There are three basic options; no login, login via a TWiki login page, and login using the webserver authentication support.
+<a name="NoLogin"></a>
+
### <a name="No Login (select <code>none</code> in confi"></a> No Login (select `none` in configure)
-Does exactly what it says on the tin. Forget about authentication to make your site completely public - anyone can browse and edit freely, in classic Wiki style. All visitors are given the [[TWikiGuest]] default identity, so you can't track individual user activity.
+Does exactly what it says on the tin. Forget about authentication to make your site completely public - anyone can browse and edit freely, in classic Wiki style. All visitors are given the %USERSWEB%.TWikiGuest default identity, so you can't track individual user activity.
-**_%X% Note:_** This setup is **not** recommended on public websites for security reasons; anyone would be able to change system settings and perform tasks usually restricted to the [[TWikiAdminGroup]].
+**_%X% Note:_** This setup is **not** recommended on public websites for security reasons; anyone would be able to change system settings and perform tasks usually restricted to administrators.
+
+<a name="TemplateLogin"></a>
### <a name="Template Login (select <code>TWiki::C"></a> Template Login (select =TWiki::Client::TemplateLogin in configure)
-Template Login asks for a username and password in a web page, and processes them using whatever Password Manager you choose. Users can log in and log out. Client Sessions are used to remember users.
+Template Login asks for a username and password in a web page, and processes them using whatever Password Manager you choose. Users can log in and log out. Client Sessions are used to remember users. Users can choose to have their session remembered so they will automatically be logged in the next time they start their browser.
#### <a name="Enabling Template Login"></a> Enabling Template Login
2. select the appropriate password manager for your system, or provide your own.
2. Register yourself in the [[TWikiRegistration]] topic. <br /> %H% Check that the password manager recognises the new user. If you are using `.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.
3. Create a new topic to check if authentication works.
-4. **Edit the [[TWikiAdminGroup]] topic in the Main web to include users with system administrator status.**<br /> %X% **This is a very important step**, as users in this group can access _all_ topics, independent of TWiki access controls.
+4. **Edit the %USERSWEB%.TWikiAdminGroup topic in the %USERSWEB% web to include users with system administrator status.**<br /> %X% **This is a very important step**, as users in this group can access _all_ topics, independent of TWiki access controls.
[[TWikiAccessControl]] has more information on setting up access controls.
%X% At this time [[TWikiAccessControls]] cannot control access to files in the `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.
-%T% You can create a custom version of the [[TWikiRegistration]] form by deleting or adding input tags. 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.
+%T% You can create a custom version of the [[TWikiRegistration]] 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 [[TWikiRegistration]] shipped with TWiki, as your changes will be overwritten next time you upgrade.
+
+%T% The default new user template page is in [[%SYSTEMWEB%.NewUserTemplate|SYSTEMWEB/NewUserTemplate]]. The same variables get expanded as in the [[template topics|Main/TWikiTemplates#Template_Topics]]. You can create a custom new user home page by creating the [[%USERSWEB%.NewUserTemplate|USERSWEB/NewUserTemplate]] topic, which will then override the default.
-%T% You can customize the default user home page in [[NewUserTemplate]]. The same variables get expanded as in the [[template topics|Main/TWikiTemplates#Template_Topics]]
+<a name="ApacheLogin"></a>
### <a name="Apache Login (select <code>TWiki::Cli"></a> Apache Login (select =TWiki::Client::ApacheLogin in configure)
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.
-TWiki maps the `REMOTE_USER` that was used to log in to the webserver to a [[WikiName]] using the table in [[TWikiUsers]]. 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]]).
+TWiki maps the `REMOTE_USER` that was used to log in to the webserver to a [[WikiName]] using the table in %USERSWEB%.TWikiUsers. 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 TWiki Template Login can be used to authenticate Apache users, using the Apache Basic Authentication support.
1. Use [configure](http://www.dementia.org/twiki/configure#LoginManager) to select the `TWiki::Client::ApacheLogin` login manager.
2. Use [configure](http://www.dementia.org/twiki/configure#PasswordManager) to set up TWiki to create the right kind of `.htpasswd` entries.
3. Create a `.htaccess` file in the `twiki/bin` directory.<br />%H% There is an template for this file in `twiki/bin/.htaccess.txt` that you can copy and change. The comments in the file explain what need to be done.<br />%H% If you got it right, the browser should now ask for login name and password when you click on the <u>Edit</u>. If `.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) <br /> %X% At this time [[TWikiAccessControls]] do not control access to files in the `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
-4. You can create a custom version of [[TWikiRegistration]] by deleting or adding input tags. 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. <br />You can customize the default user home page in [[NewUserTemplate]]. The same variables get expanded as in the [[template topics|Main/TWikiTemplates#Template_Topics]]
+4. You can create a custom version of the [[TWikiRegistration]] form by copying the default 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 [[TWikiRegistration]] shipped with TWiki, as your changes will be overwritten next time you upgrade. <br />The default new user template page is in [[%SYSTEMWEB%.NewUserTemplate|SYSTEMWEB/NewUserTemplate]]. The same variables get expanded as in the [[template topics|Main/TWikiTemplates#Template_Topics]]. You can create a custom new user home page by creating the [[%USERSWEB%.NewUserTemplate|USERSWEB/NewUserTemplate]] topic, which will then override the default.
5. Register yourself in the [[TWikiRegistration]] topic. <br /> %H% Check that a new line with the username and encrypted password is added to the `.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.
6. Create a new topic to check if authentication works.
-7. **Edit the [[TWikiAdminGroup]] topic in the Main web to include users with system administrator status.**<br /> %X% **This is a very important step**, as users in this group can access _all_ topics, independent of TWiki access controls.
+7. **Edit the %USERSWEB%.TWikiAdminGroup topic in the %USERSWEB% web to include users with system administrator status.**<br /> %X% **This is a very important step**, as users in this group can access _all_ topics, independent of TWiki access controls.
[[TWikiAccessControl]] has more information on setting up access controls.
The <code>**bin/logon**</code> script accomplishes this. The <code>**bin/logon**</code> script must be setup in the <code>**bin/.htaccess**</code> file to be a script which requires a `valid user`. However, once authenticated, it will simply redirect the user to the view URL for the page from which the `logon` script was linked.
+<a name="TrackSessions"></a>
+
## <a name="Sessions"></a> Sessions
TWiki uses the CPAN:CGI::Session and CPAN:CGI::Cookie modules to track sessions. These modules are de facto standards for session management among Perl programmers. If you can't use Cookies for any reason, CPAN:CGI::Session also supports session tracking using the client IP address.
For a number of reasons, it may not be possible to use cookies. In this case, TWiki has a fallback mechanism; it will automatically rewrite every internal URL it sees on pages being generated to one that also passes session information.
+<a name="UsernameVsLoginName"></a>
+
## <a name="TWiki Username vs. Login Usernam"></a> TWiki Username vs. Login Username
This section applies only if you are using authentication with existing login names (i.e. mapping from login names to [[WikiNames]]).
- **Login Username:** When you login to the intranet, you use your existing login username, ex: <code>**pthoeny**</code>. This name is normally passed to TWiki by the <code>**REMOTE\_USER**</code> environment variable, and used internally. Login Usernames are maintained by your system administrator.
-- **TWiki Username:** Your name in [[WikiNotation]], ex: <code>**PeterThoeny**</code>, is recorded when you register using [[TWikiRegistration]]; doing so also generates a personal home page in the Main web.
+- **TWiki Username:** Your name in [[WikiNotation]], ex: <code>**PeterThoeny**</code>, is recorded when you register using [[TWikiRegistration]]; doing so also generates a personal home page in the %USERSWEB% web.
TWiki can automatically map an Intranet (Login) Username to a TWiki Username if the \{AllowLoginName\} is enabled in [configure](http://www.dementia.org/twiki/configure). The default is to use your [[WikiName]] as a login name.
>
> **To correctly enter a [[WikiName]]**
>
-> - your own or someone else's - be sure to include the Main web name in front of the Wiki username, followed by a period, and no spaces, for example
+> - your own or someone else's - be sure to include the %USERSWEB% web name in front of the Wiki username, followed by a period, and no spaces, for example
>
-> <code>**Main.WikiUsername**</code>
+> <code>**%USERSWEB%.WikiUsername**</code>
>
> or
>
-> <code>**%MAINWEB%.WikiUsername**</code>
+> <code>**%USERSWEB%.WikiUsername**</code>
>
> . This points
>
> <code>**WikiUsername**</code>
>
-> 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
+> to the %USERSWEB% 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.
+> everywhere but in the %USERSWEB% web.
<a name="ChangingPasswords"></a>
--- /dev/null
+# <a name="TWikiUserMappingContrib"></a><a name=" _TWikiUserMappingContrib"></a> TWikiUserMappingContrib
+
+%SHORTDESCRIPTION%
+
+<div>
+ <ul>
+ <li><a href="#Settings"> Settings</a></li>
+ <li><a href="#Installation Instructions"> Installation Instructions</a></li>
+ <li><a href="#Contrib Info"> Contrib Info</a></li>
+ </ul>
+</div>
+
+The _User Mapping Manager_ interface provides services for mapping between a 'user identity' as used when talking to an external authentication provider, an internal TWiki canonical user ID, and the displayed name used to identify the user in TWiki. This is the default TWikiUserMapping in which user information is stored in TWiki topics - one per user, and then any mapping needed is done using the TWikiUsers topic in the Main.
+
+see [SimplifiedUserMappingCodeInterface](http://twiki.org/cgi-bin/view/Codev/SimplifiedUserMappingCodeInterface) on TWiki.org for a more detailed discussion of the concepts.
+
+It includes the topics that are used when registering and managing users and groups via TWiki, in [[TWikiTopics]].
+
+it includes:
+
+- Registration and user management topics
+ - [[TWikiRegistration]]
+ - [[ResetPassword]]
+ - [[ChangePassword]]
+ - [[ChangeEmailAddress]]
+ - [[BulkRegistration]]
+ - [[BulkResetPassword]]
+- Documentation topics
+ - [[ManagingUsers]]
+ - [[UserToolsCategory]]
+ - [[LoginName]]
+- default groups and user
+ - [[NobodyGroup]]
+ - [[TWikiAdminGroup]]
+ - [[TWikiRegistrationAgent]]
+- User lists
+ - [[UserList]]
+ - [[UserListHeader]]
+ - [[UserListByDateJoined]]
+ - [[UserListByLocation]]
+ - [[UserListByPhotograph]]
+- User and Group template files
+ - [[NewUserTemplate]]
+ - [[UserForm]]
+ - [[TWikiUsersTemplate]]
+ - [[UserHomepageHeader]]
+ - [[TWikiUserSetting]]
+ - [[TWikiGroupTemplate]]
+
+If you are developing a non-TWiki based User mapper, you might like to consider removeing or replacing the files installed by this Contrib.
+
+## <a name="Settings"></a> Settings
+
+The [[TWikiUserMappingContrib]] specific settings have not yet been moved out of the standard TWiki.spec. This will be done in a future release.
+
+## <a name="Installation Instructions"></a> Installation Instructions
+
+It's a part of the default distribution of the TWiki Core.
+
+## <a name="Contrib Info"></a> Contrib Info
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <td align="right"> Contrib Author(s): </td>
+ <td> Copyright (C) 2007 Sven Dowideit, <a href="mailto:SvenDowideit@WikiRing.com">SvenDowideit@WikiRing.com</a> and TWiki Contributors. </td>
+ </tr>
+ <tr>
+ <td align="right"> Contrib Version: </td>
+ <td> 4.2.0 </td>
+ </tr>
+ <tr>
+ <td align="right"> Copyright: </td>
+ <td> © </td>
+ </tr>
+ <tr>
+ <td align="right"> License: </td>
+ <td><a href="http://www.gnu.org/licenses/gpl.html" target="_top">GPL (Gnu General Public License)</a></td>
+ </tr>
+ <tr>
+ <td align="right"> Change History: </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td align="right"> Dependencies: </td>
+ <td> None </td>
+ </tr>
+ <tr>
+ <td align="right"> Contrib Home: </td>
+ <td><a href="http://twiki.org/cgi-bin/view/Plugins/TWikiUserMappingContrib" target="_top">http://twiki.org/cgi-bin/view/Plugins/TWikiUserMappingContrib</a></td>
+ </tr>
+ <tr>
+ <td align="right"> Feedback: </td>
+ <td><a href="http://twiki.org/cgi-bin/view/Plugins/TWikiUserMappingContribDev" target="_top">http://twiki.org/cgi-bin/view/Plugins/TWikiUserMappingContribDev</a></td>
+ </tr>
+ <tr>
+ <td align="right"> Appraisal: </td>
+ <td><a href="http://twiki.org/cgi-bin/view/Plugins/TWikiUserMappingContribAppraisal" target="_top">http://twiki.org/cgi-bin/view/Plugins/TWikiUserMappingContribAppraisal</a></td>
+ </tr>
+</table>
--- /dev/null
+# <a name="Package <code>TWiki::_UserMapping="></a> Package =TWiki::UserMapping
+
+This is a virtual base class (a.k.a an interface) for all user mappers. It is **not** useable as a mapping in TWiki - use the [[BaseUserMapping]] for default behaviour.
+
+User mapping is the process by which TWiki maps from a username (a login name) to a display name and back. It is also where groups are maintained.
+
+See TWiki::Users::BaseUserMapping and TWiki::Users::TWikiUserMapping for the default implementations of this interface.
+
+If you want to write a user mapper, you will need to implement the methods described in this class.
+
+User mappings work by mapping both login names and display names to a _canonical user id_. This user id is composed from a prefix that defines the mapper in use (something like 'BaseUserMapping\_' or 'LdapUserMapping\_') and a unique user id that the mapper uses to identify the user.
+
+The null prefix is reserver for the [[TWikiUserMapping]] for compatibility with old TWiki releases.
+
+**_Note:_** in all the following documentation, `$user` refers to a **canonical user id**.
+
+<div>
+ <ul>
+ <li><a href="#Package =TWiki::_UserMapping="> Package TWiki::UserMapping</a><ul>
+ <li><a href="#PROTECTED _ClassMethod new ($ses"> PROTECTED ClassMethod new ($session, $mapping_id)</a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
+ <li><a href="#ObjectMethod *login_TemplateName"> ObjectMethod loginTemplateName <tt>() -> $templateFile</tt></a></li>
+ <li><a href="#ObjectMethod *supportsRegistrati"> ObjectMethod supportsRegistration <tt>() -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>handlesUser</strong> ($cUI"> ObjectMethod handlesUser <tt>($cUID,$login,$wikiname) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod *get_CanonicalUserI"> ObjectMethod getCanonicalUserID <tt>($login,$dontcheck) -> cUID</tt></a></li>
+ <li><a href="#ObjectMethod <strong>get_LoginName</strong> ($c"> ObjectMethod getLoginName <tt>($cUID) -> login</tt></a></li>
+ <li><a href="#ObjectMethod <strong>addUser</strong> ($login,$"> ObjectMethod addUser <tt>($login,$wikiname,$password,$emails) -> cUID</tt></a></li>
+ <li><a href="#ObjectMethod <strong>removeUser</strong> ($user"> ObjectMethod removeUser <tt>($user) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>get_WikiName</strong> ($cU"> ObjectMethod getWikiName <tt>($cUID) -> wikiname</tt></a></li>
+ <li><a href="#ObjectMethod <strong>userExists</strong> ($cUID"> ObjectMethod userExists <tt>($cUID) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>eachUser</strong> () -> li"> ObjectMethod eachUser <tt>() -> listIteratorofcUIDs</tt></a></li>
+ <li><a href="#ObjectMethod *each_GroupMember*"> ObjectMethod eachGroupMember <tt>($group) -> TWiki::ListIteratorofcUIDs</tt></a></li>
+ <li><a href="#ObjectMethod <strong>isGroup</strong> ($user) -"> ObjectMethod isGroup <tt>($user) -> boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>eachGroup</strong> () ->"> ObjectMethod eachGroup <tt>() -> ListIteratorofgroupnames</tt></a></li>
+ <li><a href="#ObjectMethod <strong>eachMembership</strong> ($"> ObjectMethod eachMembership <tt>($cUID) -> ListIteratorofgroupsthisuserisin</tt></a></li>
+ <li><a href="#ObjectMethod <strong>isAdmin</strong> ($user) -"> ObjectMethod isAdmin <tt>($user) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>is_InGroup</strong> ($user"> ObjectMethod isInGroup <tt>($user,$group,$scanning) -> bool</tt></a></li>
+ <li><a href="#ObjectMethod *find_UserByEmail*"> ObjectMethod findUserByEmail <tt>($email) -> \@users</tt></a></li>
+ <li><a href="#ObjectMethod <strong>getEmails</strong> ($user)"> ObjectMethod getEmails <tt>($user) -> @emailAddress</tt></a></li>
+ <li><a href="#ObjectMethod <strong>setEmails</strong> ($user,"> ObjectMethod setEmails <tt>($user,@emails)</tt></a></li>
+ <li><a href="#ObjectMethod *find_UserByWikiNam"> ObjectMethod findUserByWikiName <tt>($wikiname) -> listofcUIDsassociatedwiththatwikiname</tt></a></li>
+ <li><a href="#ObjectMethod <strong>checkPassword</strong> ($u"> ObjectMethod checkPassword <tt>($userName,$passwordU) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>setPassword</strong> ($use"> ObjectMethod setPassword <tt>($user,$newPassU,$oldPassU) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>passwordError</strong> ()"> ObjectMethod passwordError <tt>() -> $string</tt></a></li>
+ <li><a href="#ObjectMethod *ASSERT_IS_CANONICA"> ObjectMethod ASSERT_IS_CANONICAL_USER_ID <tt>($user_id) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod *ASSERT_IS_USER_LOG"> ObjectMethod ASSERT_IS_USER_LOGIN_ID <tt>($user_login) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod *ASSERT_IS_USER_DIS"> ObjectMethod ASSERT_IS_USER_DISPLAY_NAME <tt>($user_display) -> $boolean</tt></a></li>
+ </ul>
+ </li>
+ </ul>
+</div>
+
+## <a name="PROTECTED _ClassMethod new ($ses"></a> PROTECTED [[ClassMethod]] new ($session, $mapping\_id)
+
+Construct a user mapping object, using the given mapping id.
+
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
+
+Break circular references.
+
+## <a name="ObjectMethod <strong>login_TemplateName"></a> [[ObjectMethod]] \*loginTemplateName `() -> $templateFile`
+
+Allows [[UserMappings]] to come with customised login screens - that should preferably only over-ride the UI function
+
+Default is "login"
+
+## <a name="ObjectMethod <strong>supportsRegistrati"></a> [[ObjectMethod]] \*supportsRegistration `() -> $boolean`
+
+Return true if the [[UserMapper]] supports registration (ie can create new users)
+
+Default is **false**
+
+## <a name="ObjectMethod <strong>handlesUser</strong> ($cUI"></a> [[ObjectMethod]] **handlesUser** `($cUID,$login,$wikiname) -> $boolean`
+
+Called by the TWiki::Users object to determine which loaded mapping to use for a given user (must be fast).
+
+Default is **false**
+
+## <a name="ObjectMethod <strong>get_CanonicalUserI"></a> [[ObjectMethod]] \*getCanonicalUserID `($login,$dontcheck) -> cUID`
+
+Convert a login name to the corresponding canonical user name. The canonical name can be any string of 7-bit alphanumeric and underscore characters, and must correspond 1:1 to the login name. (undef on failure)
+
+(if dontcheck is true, return a cUID for a nonexistant user too - used for registration)
+
+Subclasses **must** implement this method.
+
+## <a name="ObjectMethod <strong>get_LoginName</strong> ($c"></a> [[ObjectMethod]] **getLoginName** `($cUID) -> login`
+
+Converts an internal cUID to that user's login (undef on failure)
+
+Subclasses **must** implement this method.
+
+## <a name="ObjectMethod <strong>addUser</strong> ($login,$"></a> [[ObjectMethod]] **addUser** `($login,$wikiname,$password,$emails) -> cUID`
+
+Add a user to the persistant mapping that maps from usernames to wikinames and vice-versa, via a **canonical user id** (cUID).
+
+$login and $wikiname must be acceptable to $TWiki::cfg\{NameFilter\}. $login must **always** be specified. $wikiname may be undef, in which case the user mapper should make one up.
+
+This function must return a canonical user id that it uses to uniquely identify the user. This can be the login name, or the wikiname if they are all guaranteed unigue, or some other string consisting only of 7-bit alphanumerics and underscores.
+
+If you fail to create a new user (for eg your Mapper has read only access),
+
+ throw Error::Simple('Failed to add user: '.$error);
+
+where $error is a descriptive string.
+
+Throws an Error::Simple if user adding is not supported (the default).
+
+## <a name="ObjectMethod <strong>removeUser</strong> ($user"></a> [[ObjectMethod]] **removeUser** `($user) -> $boolean`
+
+Delete the users entry from this mapper. Throws an Error::Simple if user removal is not supported (the default).
+
+## <a name="ObjectMethod <strong>get_WikiName</strong> ($cU"></a> [[ObjectMethod]] **getWikiName** `($cUID) -> wikiname`
+
+Map a canonical user name to a wikiname.
+
+Returns the $cUID by default.
+
+## <a name="ObjectMethod <strong>userExists</strong> ($cUID"></a> [[ObjectMethod]] **userExists** `($cUID) -> $boolean`
+
+Determine if the user already exists or not. Whether a user exists or not is determined by the password manager.
+
+Subclasses **must** implement this method.
+
+## <a name="ObjectMethod <strong>eachUser</strong> () - lis"></a> [[ObjectMethod]] **eachUser** `() -> listIteratorofcUIDs`
+
+Called from TWiki::Users. See the documentation of the corresponding method in that module for details.
+
+Subclasses **must** implement this method.
+
+## <a name="ObjectMethod <strong>each_GroupMember*"></a><a name="ObjectMethod *each_GroupMember</strong> "></a> [[ObjectMethod]] **eachGroupMember** `($group) -> TWiki::ListIteratorofcUIDs`
+
+Called from TWiki::Users. See the documentation of the corresponding method in that module for details.
+
+Subclasses **must** implement this method.
+
+## <a name="ObjectMethod <strong>isGroup</strong> ($user) -"></a> [[ObjectMethod]] **isGroup** `($user) -> boolean`
+
+Called from TWiki::Users. See the documentation of the corresponding method in that module for details.
+
+Subclasses **must** implement this method.
+
+## <a name="ObjectMethod <strong>eachGroup</strong> () - _L"></a> [[ObjectMethod]] **eachGroup** <tt>() -> [[ListIteratorofgroupnames]]</tt>
+
+Called from TWiki::Users. See the documentation of the corresponding method in that module for details.
+
+Subclasses **must** implement this method.
+
+## <a name="ObjectMethod <strong>eachMembership</strong> ($"></a> [[ObjectMethod]] **eachMembership** <tt>($cUID) -> [[ListIteratorofgroupsthisuserisin]]</tt>
+
+Called from TWiki::Users. See the documentation of the corresponding method in that module for details.
+
+Subclasses **must** implement this method.
+
+## <a name="ObjectMethod <strong>isAdmin</strong> ($user) -"></a> [[ObjectMethod]] **isAdmin** `($user) -> $boolean`
+
+True if the user is an administrator. Default is **false**
+
+## <a name="ObjectMethod <strong>is_InGroup</strong> ($user"></a> [[ObjectMethod]] **isInGroup** `($user,$group,$scanning) -> bool`
+
+Called from TWiki::Users. See the documentation of the corresponding method in that module for details.
+
+Default is **false**
+
+## <a name="ObjectMethod <strong>find_UserByEmail*"></a><a name="ObjectMethod *find_UserByEmail</strong> "></a> [[ObjectMethod]] **findUserByEmail** `($email) -> \@users`
+
+- `$email` - email address to look up
+
+Return a list of canonical user names for the users that have this email registered with the password manager or the user mapping manager.
+
+Returns an empty list by default.
+
+## <a name="ObjectMethod <strong>getEmails</strong> ($user)"></a> [[ObjectMethod]] **getEmails** `($user) -> @emailAddress`
+
+If this is a user, return their email addresses. If it is a group, return the addresses of everyone in the group.
+
+Duplicates should be removed from the list.
+
+By default, returns the empty list.
+
+## <a name="ObjectMethod <strong>setEmails</strong> ($user,"></a> [[ObjectMethod]] **setEmails** `($user,@emails)`
+
+Set the email address(es) for the given user. Does nothing by default.
+
+## <a name="ObjectMethod <strong>find_UserByWikiNam"></a> [[ObjectMethod]] \*findUserByWikiName `($wikiname) -> listofcUIDsassociatedwiththatwikiname`
+
+Called from TWiki::Users. See the documentation of the corresponding method in that module for details.
+
+Subclasses **must** implement this method.
+
+## <a name="ObjectMethod <strong>checkPassword</strong> ($u"></a> [[ObjectMethod]] **checkPassword** `($userName,$passwordU) -> $boolean`
+
+Finds if the password is valid for the given user.
+
+Returns 1 on success, undef on failure.
+
+Default behaviour is to return 1.
+
+## <a name="ObjectMethod <strong>setPassword</strong> ($use"></a> [[ObjectMethod]] **setPassword** `($user,$newPassU,$oldPassU) -> $boolean`
+
+If the $oldPassU matches matches the user's password, then it will replace it with $newPassU.
+
+If $oldPassU is not correct and not 1, will return 0.
+
+If $oldPassU is 1, will force the change irrespective of the existing password, adding the user if necessary.
+
+Otherwise returns 1 on success, undef on failure.
+
+Default behaviour is to fail.
+
+## <a name="ObjectMethod <strong>passwordError</strong> ()"></a><a name="ObjectMethod <strong>passwordError</strong> () "></a> [[ObjectMethod]] **passwordError** `() -> $string`
+
+Returns a string indicating the error that happened in the password handlers TODO: these delayed errors should be replaced with Exceptions.
+
+returns undef if no error 9the default)
+
+## <a name="ObjectMethod <strong>ASSERT_IS_CANONICA"></a> [[ObjectMethod]] \*ASSERT\_IS\_CANONICAL\_USER\_ID `($user_id) -> $boolean`
+
+Used for debugging to ensure we are actually passing a canonical\_id
+
+## <a name="ObjectMethod <strong>ASSERT_IS_USER_LOG"></a> [[ObjectMethod]] \*ASSERT\_IS\_USER\_LOGIN\_ID `($user_login) -> $boolean`
+
+Used for debugging to ensure we are actually passing a user login
+
+## <a name="ObjectMethod <strong>ASSERT_IS_USER_DIS"></a> [[ObjectMethod]] \*ASSERT\_IS\_USER\_DISPLAY\_NAME `($user_display) -> $boolean`
+
+Used for debugging to ensure we are actually passing a user display\_name (commonly a [[WikiWord]] Name)
+
+Returns true by default.
# <a name="Package <code>TWiki::Users::_ApacheHt"></a> Package =TWiki::Users::ApacheHtpasswdUser
-**extends** <tt>[[TWiki::Users::Password |Main/TWikiUsersPasswordDotPm]]</tt>
-
Password manager that uses Apache::HtPasswd to manage users and passwords.
Subclass of [[ TWiki::Users::Password |Main/TWikiUsersPasswordDotPm]]. See documentation of that class for descriptions of the methods of this class.
<div>
<ul>
- <li><a href="#Package =TWiki::Users::_ApacheHt"> Package TWiki::Users::ApacheHtpasswdUser</a></li>
+ <li><a href="#Package =TWiki::Users::_ApacheHt"> Package TWiki::Users::ApacheHtpasswdUser</a><ul>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
+ <li><a href="#ObjectMethod <strong>readOnly</strong> () -> bo"> ObjectMethod readOnly <tt>() -> boolean</tt></a></li>
+ </ul>
+ </li>
</ul>
</div>
+
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
+
+Break circular references.
+
+## <a name="ObjectMethod <strong>readOnly</strong> () - boo"></a> [[ObjectMethod]] **readOnly** `() -> boolean`
+
+returns true if the password file is not currently modifyable
# <a name="Package <code>TWiki::Users="></a> Package =TWiki::Users
-Singleton object that handles mapping of users to wikinames and vice versa, and user authentication checking.
+This package provides services for the lookup and manipulation of login and wiki names of users, and their authentication.
+
+It is a Facade that presents a common interface to the User Mapping and Password modules. The rest of the core should **only** use the methods of this package, and should **never** call the mapping or password managers directly.
+
+TWiki uses the concept of a _login name_ which is used to authenticate a user. A login name maps to a _wiki name_ that is used to identify the user for display. Each login name is unique to a single user, though several login names may map to the same wiki name.
+
+Using this module (and the associated plug-in user mapper) TWiki supports the concept of _groups_. Groups are sets of login names that are treated equally for the purposes of access control. Group names do not have to be wiki names, though it is helpful for display if they are.
+
+Internally in the code TWiki uses something referred to as a \_canonical user id\_ or just _user id_. The user id is also used externally to uniquely identify the user when (for example) recording topic histories. The user id is **usually** just the login name, but it doesn't need to be. It just has to be a unique 7-bit alphanumeric and underscore string that can be mapped to/from login and wiki names by the user mapper.
+
+The canonical user id should **never** be seen by a user. On the other hand, core code should never use anything **but** a canonical user id to refer to a user.
+
+**Terminology**
+
+- A **login name** is the name used to log in to TWiki. Each login name is assumed to be unique to a human. The Password module is responsible for authenticating and manipulating login names.
+- A **canonical user id** is an internal TWiki representation of a user. Each canonical user id maps 1:1 to a login name.
+- A **wikiname** is how a user is displayed. Many user ids may map to a single wikiname. The user mapping module is responsible for mapping the user id to a wikiname.
+- A **group id** represents a group of users and other groups. The user mapping module is responsible for mapping from a group id to a list of canonical user ids for the users in that group.
+- An **email** is an email address asscoiated with a **login name**. A single login name may have many emails.
+
+**NOTE:**
+
+- wherever the code references $user, its a canonical\_id
+- wherever the code references $group, its a group\_name
<div>
<ul>
<li><a href="#Package =TWiki::Users="> Package TWiki::Users</a><ul>
- <li><a href="#ClassMethod <strong>new</strong> ($session,$imp"> ClassMethod new <tt>($session,$impl)</tt></a></li>
- <li><a href="#ObjectMethod *finish*"> ObjectMethod finish <tt></tt></a></li>
- <li><a href="#ObjectMethod <strong>findUser</strong> ($name[,"> ObjectMethod findUser <tt>($name[,$wikiname][,$nocreate]) -> $userObject</tt></a></li>
+ <li><a href="#ClassMethod <strong>new</strong> ($session)"> ClassMethod new <tt>($session)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
+ <li><a href="#ObjectMethod *login_TemplateName"> ObjectMethod loginTemplateName <tt>() -> templateFile</tt></a></li>
+ <li><a href="#ObjectMethod *supportsRegistrati"> ObjectMethod supportsRegistration <tt>() -> boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>initialiseUser</strong> ($"> ObjectMethod initialiseUser <tt>($login) -> cUID</tt></a></li>
+ <li><a href="#randomPassword()"> randomPassword()</a></li>
+ <li><a href="#ObjectMethod <strong>addUser</strong> ($login,$"> ObjectMethod addUser <tt>($login,$wikiname,$password,$emails) -> $cUID</tt></a></li>
+ <li><a href="#StaticMethod <strong>forceCUID</strong> ($cUID)"> StaticMethod forceCUID <tt>($cUID) -> $cUID</tt></a></li>
+ <li><a href="#ObjectMethod *get_CanonicalUserI"> ObjectMethod getCanonicalUserID <tt>($login) -> $user</tt></a></li>
+ <li><a href="#ObjectMethod *find_UserByWikiNam"> ObjectMethod findUserByWikiName <tt>($wn) -> \@users</tt></a></li>
<li><a href="#ObjectMethod *find_UserByEmail*"> ObjectMethod findUserByEmail <tt>($email) -> \@users</tt></a></li>
- <li><a href="#ObjectMethod <strong>createUser</strong> ($logi"> ObjectMethod createUser <tt>($login,$wikiname) -> $userobject</tt></a></li>
- <li><a href="#ObjectMethod *add_UserToMapping*"> ObjectMethod addUserToMapping <tt>($user) -> $topicName</tt></a></li>
+ <li><a href="#ObjectMethod <strong>getEmails</strong> ($user)"> ObjectMethod getEmails <tt>($user) -> @emailAddress</tt></a></li>
+ <li><a href="#ObjectMethod <strong>setEmails</strong> ($user,"> ObjectMethod setEmails <tt>($user,@emails)</tt></a></li>
+ <li><a href="#ObjectMethod <strong>isAdmin</strong> ($cUID) -"> ObjectMethod isAdmin <tt>($cUID) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>is_InList</strong> ($user,"> ObjectMethod isInList <tt>($user,$list) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>get_LoginName</strong> ($c"> ObjectMethod getLoginName <tt>($cUID) -> $string</tt></a></li>
+ <li><a href="#ObjectMethod <strong>get_WikiName</strong> ($cU"> ObjectMethod getWikiName <tt>($cUID) -> $wikiName</tt></a></li>
+ <li><a href="#ObjectMethod <strong>web_DotWikiName</strong> ("> ObjectMethod webDotWikiName <tt>($user) -> $webDotWiki</tt></a></li>
+ <li><a href="#ObjectMethod <strong>userExists</strong> ($cUID"> ObjectMethod userExists <tt>($cUID) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>eachUser</strong> () -> $i"> ObjectMethod eachUser <tt>() -> $iterator</tt></a></li>
+ <li><a href="#ObjectMethod <strong>eachGroup</strong> () -> $"> ObjectMethod eachGroup <tt>() -> $iterator</tt></a></li>
+ <li><a href="#ObjectMethod *each_GroupMember*"> ObjectMethod eachGroupMember <tt>($group) -> $iterator</tt></a></li>
+ <li><a href="#ObjectMethod <strong>isGroup</strong> ($user) -"> ObjectMethod isGroup <tt>($user) -> boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>is_InGroup</strong> ($user"> ObjectMethod isInGroup <tt>($user,$group) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>eachMembership</strong> ($"> ObjectMethod eachMembership <tt>($cUID) -> $iterator</tt></a></li>
+ <li><a href="#ObjectMethod <strong>checkPassword</strong> ($u"> ObjectMethod checkPassword <tt>($userName,$passwordU) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>setPassword</strong> ($use"> ObjectMethod setPassword <tt>($user,$newPassU,$oldPassU) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>passwordError</strong> ()"> ObjectMethod passwordError <tt>() -> $string</tt></a></li>
+ <li><a href="#ObjectMethod <strong>removeUser</strong> ($user"> ObjectMethod removeUser <tt>($user) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod *ASSERT_IS_CANONICA"> ObjectMethod ASSERT_IS_CANONICAL_USER_ID <tt>($user_id) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod *ASSERT_IS_USER_LOG"> ObjectMethod ASSERT_IS_USER_LOGIN_ID <tt>($user_login) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod *ASSERT_IS_USER_DIS"> ObjectMethod ASSERT_IS_USER_DISPLAY_NAME <tt>($user_display) -> $boolean</tt></a></li>
</ul>
</li>
</ul>
</div>
-## <a name="ClassMethod <strong>new</strong> ($session,$imp"></a> [[ClassMethod]] **new** `($session,$impl)`
+## <a name="ClassMethod <strong>new</strong> ($session)"></a> [[ClassMethod]] **new** `($session)`
+
+Construct the user management object that is the facade to the [[BaseUserMapping]] and the user mapping chosen in the configuration.
+
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
+
+Break circular references.
+
+## <a name="ObjectMethod <strong>login_TemplateName"></a> [[ObjectMethod]] \*loginTemplateName `() -> templateFile`
+
+allows [[UserMappings]] to come with customised login screens - that should preffereably only over-ride the UI function
+
+## <a name="ObjectMethod <strong>supportsRegistrati"></a> [[ObjectMethod]] \*supportsRegistration `() -> boolean`
+
+#return 1 if the main [[UserMapper]] supports registration (ie can create new users)
+
+## <a name="ObjectMethod <strong>initialiseUser</strong> ($"></a> [[ObjectMethod]] **initialiseUser** `($login) -> cUID`
+
+## <a name="randomPassword()"></a> randomPassword()
+
+Static function that returns a random password
+
+## <a name="ObjectMethod <strong>addUser</strong> ($login,$"></a> [[ObjectMethod]] **addUser** `($login,$wikiname,$password,$emails) -> $cUID`
+
+- `$login` - user login name. If `undef`, `$wikiname` will be used as the login name.
+- `$wikiname` - user wikiname. If `undef`, the user mapper will be asked to provide it.
+- `$password` - password. If undef, a password will be generated.
-Construct the user management object
+Add a new TWiki user identity, returning the canonical user id for the new user. Used ONLY for user registration.
-## <a name="ObjectMethod <strong>finish*"></a><a name="ObjectMethod *finish</strong> "></a> [[ObjectMethod]] **finish** ``
+The user is added to the password system (if there is one, and if it accepts changes). If the user already exists in the password system, then the password is checked and an exception thrown if it doesn't match. If there is no existing user, and no password is given, a random password is generated.
-Complete processing after the client's HTTP request has been responded to.
+$login can be undef; $wikiname must always have a value.
-1. breaking circular references to allow garbage collection in persistent environments
+The return value is the canonical user id that is used by TWiki to identify the user.
-## <a name="ObjectMethod <strong>findUser</strong> ($name[,"></a> [[ObjectMethod]] **findUser** `($name[,$wikiname][,$nocreate]) -> $userObject`
+## <a name="StaticMethod <strong>forceCUID</strong> ($cUID)"></a> [[StaticMethod]] **forceCUID** `($cUID) -> $cUID`
-- `$name` - login name or wiki name
-- `$wikiname` - optional, wikiname for created user
-- `$nocreate` - optional, disable creation of user object for user not found
+This function ensures that any cUID's are able to be used for rcs, and other internals not capable of coping with user identifications that contain more than 7 bit ascii.
-Find the user object corresponding to `$name`, which may be either a login name or a wiki name. If `$name` is found (either in the list of login names or the list of wiki names) the corresponding user object is returned. In this case `$wikiname` is ignored.
+repeated calls must result in the same result (sorry, can't spell the word for it)so the '\_' must not be re-encoded
-If they are not found, and `$nocreate` is true, then return undef.
+Please, call this function in any custom Usermapper to simplifyyour mapping code.
-If `$nocreate` is false, then a user object is returned even if the user is not known.
+## <a name="ObjectMethod <strong>get_CanonicalUserI"></a> [[ObjectMethod]] \*getCanonicalUserID `($login) -> $user`
-If `$nocreate` is false, and no `$wikiname` is given, then the `$name` is used for both login name and wiki name.
+Works out the unique TWiki identifier for the user who logs in with the given login. The canonical user ID is an alphanumeric string that is unique to the login name, and can be mapped back to a login name and the corresponding wiki name using the methods of this class.
-If nocreate is off, then a default user will be created with their wikiname set the same as their login name. This user/wiki name pair can be overridden by a later createUser call when the correct wikiname is known, if necessary.
+returns undef if the user does not exist.
+
+## <a name="ObjectMethod <strong>find_UserByWikiNam"></a> [[ObjectMethod]] \*findUserByWikiName `($wn) -> \@users`
+
+- `$wn` - wikiname to look up
+
+Return a list of canonical user names for the users that have this wikiname. Since a single wikiname might be used by multiple login ids, we need a list.
+
+If $wn is the name of a group, the group will **not** be expanded.
## <a name="ObjectMethod <strong>find_UserByEmail*"></a><a name="ObjectMethod *find_UserByEmail</strong> "></a> [[ObjectMethod]] **findUserByEmail** `($email) -> \@users`
- `$email` - email address to look up
-Return a list of user objects for the users that have this email registered with the password manager.
+Return a list of canonical user names for the users that have this email registered with the user mapping managers.
+
+## <a name="ObjectMethod <strong>getEmails</strong> ($user)"></a> [[ObjectMethod]] **getEmails** `($user) -> @emailAddress`
+
+If this is a user, return their email addresses. If it is a group, return the addresses of everyone in the group.
+
+The password manager and user mapping manager are both consulted for emails for each user (where they are actually found is implementation defined).
+
+Duplicates are removed from the list.
+
+## <a name="ObjectMethod <strong>setEmails</strong> ($user,"></a> [[ObjectMethod]] **setEmails** `($user,@emails)`
+
+Set the email address(es) for the given user. The password manager is tried first, and if it doesn't want to know the user mapping manager is tried.
+
+## <a name="ObjectMethod <strong>isAdmin</strong> ($cUID) -"></a> [[ObjectMethod]] **isAdmin** `($cUID) -> $boolean`
+
+True if the user is an admin
+
+- is $TWiki::cfg\{SuperAdminGroup\}
+- is a member of the $TWiki::cfg\{SuperAdminGroup\}
+
+## <a name="ObjectMethod <strong>is_InList</strong> ($user,"></a> [[ObjectMethod]] **isInList** `($user,$list) -> $boolean`
+
+Return true if $user is in a list of user **wikinames** and group ids.
+
+$list is a comma-separated wikiname and group list. The list may contain the conventional web specifiers (which are ignored).
+
+## <a name="ObjectMethod <strong>get_LoginName</strong> ($c"></a> [[ObjectMethod]] **getLoginName** `($cUID) -> $string`
+
+Get the login name of a user.
+
+## <a name="ObjectMethod <strong>get_WikiName</strong> ($cU"></a> [[ObjectMethod]] **getWikiName** `($cUID) -> $wikiName`
+
+Get the wikiname to display for a canonical user identifier.
+
+can return undef if the user is not in the mapping system (or the special case from initialiseUser)
+
+## <a name="ObjectMethod <strong>web_DotWikiName</strong> ("></a> [[ObjectMethod]] **webDotWikiName** `($user) -> $webDotWiki`
+
+Return the fully qualified wikiname of the user
+
+## <a name="ObjectMethod <strong>userExists</strong> ($cUID"></a> [[ObjectMethod]] **userExists** `($cUID) -> $boolean`
+
+Determine if the user already exists or not. A user exists if they are known to to the user mapper.
+
+## <a name="ObjectMethod <strong>eachUser</strong> () - $it"></a> [[ObjectMethod]] **eachUser** `() -> $iterator`
+
+Get an iterator over the list of all the registered users **not** including groups.
+
+list of canonical\_ids ???
+
+Use it as follows:
+
+ my $iterator = $umm->eachUser();
+ while ($iterator->hasNext()) {
+ my $user = $iterator->next();
+ ...
+ }
+
+## <a name="ObjectMethod <strong>eachGroup</strong> () - $i"></a> [[ObjectMethod]] **eachGroup** `() -> $iterator`
+
+Get an iterator over the list of all the groups.
+
+## <a name="ObjectMethod <strong>each_GroupMember*"></a><a name="ObjectMethod *each_GroupMember</strong> "></a> [[ObjectMethod]] **eachGroupMember** `($group) -> $iterator`
+
+Return a iterator of user ids that are members of this group. Should only be called on groups.
+
+Note that groups may be defined recursively, so a group may contain other groups. This method should **only** return users i.e. all contained groups should be fully expanded.
+
+## <a name="ObjectMethod <strong>isGroup</strong> ($user) -"></a> [[ObjectMethod]] **isGroup** `($user) -> boolean`
+
+Establish if a user refers to a group or not.
+
+The default implementation is to check if the wikiname of the user ends with 'Group'. Subclasses may override this behaviour to provide alternative interpretations. The $TWiki::cfg\{SuperAdminGroup\} is recognized as a group no matter what it's name is.
+
+QUESTION: is the $user parameter here a string, or a canonical\_id??
+
+## <a name="ObjectMethod <strong>is_InGroup</strong> ($user"></a> [[ObjectMethod]] **isInGroup** `($user,$group) -> $boolean`
+
+Test if user is in the given group.
+
+## <a name="ObjectMethod <strong>eachMembership</strong> ($"></a> [[ObjectMethod]] **eachMembership** `($cUID) -> $iterator`
+
+Return an iterator over the groups that $cUID is a member of.
+
+## <a name="ObjectMethod <strong>checkPassword</strong> ($u"></a> [[ObjectMethod]] **checkPassword** `($userName,$passwordU) -> $boolean`
+
+Finds if the password is valid for the given user.
+
+Returns 1 on success, undef on failure.
+
+TODO: add special check for [[BaseMapping]] admin user's login, and if its there (and we're in sudo\_context?) use that..
+
+## <a name="ObjectMethod <strong>setPassword</strong> ($use"></a> [[ObjectMethod]] **setPassword** `($user,$newPassU,$oldPassU) -> $boolean`
+
+If the $oldPassU matches matches the user's password, then it will replace it with $newPassU.
+
+If $oldPassU is not correct and not 1, will return 0.
+
+If $oldPassU is 1, will force the change irrespective of the existing password, adding the user if necessary.
+
+Otherwise returns 1 on success, undef on failure.
+
+## <a name="ObjectMethod <strong>passwordError</strong> ()"></a><a name="ObjectMethod <strong>passwordError</strong> () "></a> [[ObjectMethod]] **passwordError** `() -> $string`
+
+returns a string indicating the error that happened in the password handlers TODO: these delayed error's should be replaced with Exceptions.
+
+returns undef if no error
+
+## <a name="ObjectMethod <strong>removeUser</strong> ($user"></a> [[ObjectMethod]] **removeUser** `($user) -> $boolean`
+
+Delete the users entry. Removes the user from the password manager and user mapping manager. Does **not** remove their personal topics, which may still be linked.
+
+## <a name="ObjectMethod <strong>ASSERT_IS_CANONICA"></a> [[ObjectMethod]] \*ASSERT\_IS\_CANONICAL\_USER\_ID `($user_id) -> $boolean`
+
+used for debugging to ensure we are actually passing a canonical\_id
+
+These ASSERTS have been disabled, as they have been made dangerous and misleading due to the legacy cUID code
+
+## <a name="ObjectMethod <strong>ASSERT_IS_USER_LOG"></a> [[ObjectMethod]] \*ASSERT\_IS\_USER\_LOGIN\_ID `($user_login) -> $boolean`
+
+used for debugging to ensure we are actually passing a user login
-## <a name="ObjectMethod <strong>createUser</strong> ($logi"></a> [[ObjectMethod]] **createUser** `($login,$wikiname) -> $userobject`
+These ASSERTS have been disabled, as they have been made dangerous and misleading due to the legacy cUID code
-Create a user, and insert them in the maps (overwriting any current entry). Use this instead of findUser when you want to be sure you are not going to pick up any default user created by findUser. All parameters are required.
+## <a name="ObjectMethod <strong>ASSERT_IS_USER_DIS"></a> [[ObjectMethod]] \*ASSERT\_IS\_USER\_DISPLAY\_NAME `($user_display) -> $boolean`
-## <a name="ObjectMethod <strong>add_UserToMapping*"></a> [[ObjectMethod]] \*addUserToMapping `($user) -> $topicName`
+used for debugging to ensure we are actually passing a user display\_name (commonly a [[WikiWord]] Name)
-Add a user to the persistant mapping that maps from usernames to wikinames and vice-versa.
+These ASSERTS have been disabled, as they have been made dangerous and misleading due to the legacy cUID code
--- /dev/null
+# <a name="Package <code>TWiki::Users::_HtPasswd"></a> Package =TWiki::Users::HtPasswdUser
+
+Support for htpasswd and htdigest format password files.
+
+Subclass of [[ TWiki::Users::Password |Main/TWikiUsersPasswordDotPm]]. See documentation of that class for descriptions of the methods of this class.
+
+<div>
+ <ul>
+ <li><a href="#Package =TWiki::Users::_HtPasswd"> Package TWiki::Users::HtPasswdUser</a><ul>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
+ <li><a href="#ObjectMethod <strong>readOnly</strong> () -> bo"> ObjectMethod readOnly <tt>() -> boolean</tt></a></li>
+ </ul>
+ </li>
+ </ul>
+</div>
+
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
+
+Break circular references.
+
+## <a name="ObjectMethod <strong>readOnly</strong> () - boo"></a> [[ObjectMethod]] **readOnly** `() -> boolean`
+
+returns true if the password file is not currently modifyable
<ul>
<li><a href="#Package =TWiki::Users::Password="> Package TWiki::Users::Password</a><ul>
<li><a href="#ClassMethod <strong>new</strong> ($session) ->"> ClassMethod new <tt>($session) -> $object</tt></a></li>
- <li><a href="#ObjectMethod *finish*"> ObjectMethod finish <tt></tt></a></li>
+ <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
+ <li><a href="#ObjectMethod <strong>readOnly</strong> () -> bo"> ObjectMethod readOnly <tt>() -> boolean</tt></a></li>
<li><a href="#ObjectMethod <strong>fetchPass</strong> ($login"> ObjectMethod fetchPass <tt>($login) -> $passwordE</tt></a></li>
- <li><a href="#ObjectMethod <strong>checkPassword</strong> ($u"> ObjectMethod checkPassword <tt>($user,$passwordU) -> $boolean</tt></a></li>
- <li><a href="#ObjectMethod <strong>deleteUser</strong> ($user"> ObjectMethod deleteUser <tt>($user) -> $boolean</tt></a></li>
- <li><a href="#ObjectMethod <strong>passwd</strong> ($user,$ne"> ObjectMethod passwd <tt>($user,$newPassU,$oldPassU) -> $boolean</tt></a></li>
- <li><a href="#encrypt( $user, $passwordU, $fre"> encrypt( $user, $passwordU, $fresh ) -> $passwordE</a></li>
+ <li><a href="#ObjectMethod <strong>checkPassword</strong> ($l"> ObjectMethod checkPassword <tt>($login,$passwordU) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>removeUser</strong> ($logi"> ObjectMethod removeUser <tt>($login) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>setPassword</strong> ($log"> ObjectMethod setPassword <tt>($login,$newPassU,$oldPassU) -> $boolean</tt></a></li>
+ <li><a href="#encrypt( $login, $passwordU, $fr"> encrypt( $login, $passwordU, $fresh ) -> $passwordE</a></li>
<li><a href="#ObjectMethod <strong>error</strong> () -> $stri"> ObjectMethod error <tt>() -> $string</tt></a></li>
- <li><a href="#ObjectMethod <strong>getEmails</strong> ($user)"> ObjectMethod getEmails <tt>($user) -> @emails</tt></a></li>
- <li><a href="#ObjectMethod <strong>setEmails</strong> ($user,"> ObjectMethod setEmails <tt>($user,@emails)</tt></a></li>
+ <li><a href="#ObjectMethod *is_ManagingEmails*"> ObjectMethod isManagingEmails <tt>() -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>getEmails</strong> ($login"> ObjectMethod getEmails <tt>($login) -> @emails</tt></a></li>
+ <li><a href="#ObjectMethod <strong>setEmails</strong> ($login"> ObjectMethod setEmails <tt>($login,@emails) -> $boolean</tt></a></li>
+ <li><a href="#ObjectMethod *find_LoginByEmail*"> ObjectMethod findLoginByEmail <tt>($email) -> \@users</tt></a></li>
+ <li><a href="#ObjectMethod <strong>can_FetchUsers</strong> ()"> ObjectMethod canFetchUsers <tt>() -> boolean</tt></a></li>
+ <li><a href="#ObjectMethod <strong>fetchUsers</strong> () ->"> ObjectMethod fetchUsers <tt>() -> newTWiki::ListIterator(\@users)</tt></a></li>
</ul>
</li>
</ul>
Constructs a new password handler of this type, referring to $session for any required TWiki services.
-## <a name="ObjectMethod <strong>finish*"></a><a name="ObjectMethod *finish</strong> "></a> [[ObjectMethod]] **finish** ``
+## <a name="ObjectMethod <strong>finish</strong> ()"></a> [[ObjectMethod]] **finish** `()`
-Complete processing after the client's HTTP request has been responded to.
+Break circular references.
-1. breaking circular references to allow garbage collection in persistent environments
+## <a name="ObjectMethod <strong>readOnly</strong> () - boo"></a> [[ObjectMethod]] **readOnly** `() -> boolean`
+
+returns true if the password database is not currently modifyable also needs to call $this->\{session\}->enter\_context('passwords\_modifyable'); if you want to be able to use the existing [[TWikiUserMappingContrib]] [[ChangePassword]] topics
## <a name="ObjectMethod <strong>fetchPass</strong> ($login"></a> [[ObjectMethod]] **fetchPass** `($login) -> $passwordE`
Returns encrypted password if succeeds. Returns 0 if login is invalid. Returns undef otherwise.
-## <a name="ObjectMethod <strong>checkPassword</strong> ($u"></a> [[ObjectMethod]] **checkPassword** `($user,$passwordU) -> $boolean`
+## <a name="ObjectMethod <strong>checkPassword</strong> ($l"></a> [[ObjectMethod]] **checkPassword** `($login,$passwordU) -> $boolean`
-Finds if the password is valid for the given login.
+Finds if the password is valid for the given user.
Returns 1 on success, undef on failure.
-## <a name="ObjectMethod <strong>deleteUser</strong> ($user"></a> [[ObjectMethod]] **deleteUser** `($user) -> $boolean`
-
-Delete users entry.
-
-Returns 1 on success, undef on failure.
+## <a name="ObjectMethod <strong>removeUser</strong> ($logi"></a> [[ObjectMethod]] **removeUser** `($login) -> $boolean`
-## <a name="ObjectMethod <strong>passwd</strong> ($user,$ne"></a> [[ObjectMethod]] **passwd** `($user,$newPassU,$oldPassU) -> $boolean`
+Delete the users entry.
-If the $oldPassU is undef, it will try to add the user, failing if they are already there.
+## <a name="ObjectMethod <strong>setPassword</strong> ($log"></a> [[ObjectMethod]] **setPassword** `($login,$newPassU,$oldPassU) -> $boolean`
-If the $oldPassU matches matches the login's password, then it will replace it with $newPassU.
+If the $oldPassU matches matches the user's password, then it will replace it with $newPassU.
If $oldPassU is not correct and not 1, will return 0.
Otherwise returns 1 on success, undef on failure.
-## <a name="encrypt( $user, $passwordU, $fre"></a> encrypt( $user, $passwordU, $fresh ) -> $passwordE
+## <a name="encrypt( $login, $passwordU, $fr"></a> encrypt( $login, $passwordU, $fresh ) -> $passwordE
-Will return an encrypted password. Repeated calls to encrypt with the same user/passU will return the same passE.
+Will return an encrypted password. Repeated calls to encrypt with the same login/passU will return the same passE.
-However if the passU is changed, and subsequently changed _back_ to the old user/passU pair, then the old passE is no longer valid.
+However if the passU is changed, and subsequently changed _back_ to the old login/passU pair, then the old passE is no longer valid.
If $fresh is true, then a new password not based on any pre-existing salt will be used. Set this if you are generating a completely new password.
Return any error raised by the last method call, or undef if the last method call succeeded.
-## <a name="ObjectMethod <strong>getEmails</strong> ($user)"></a> [[ObjectMethod]] **getEmails** `($user) -> @emails`
+## <a name="ObjectMethod <strong>is_ManagingEmails*"></a> [[ObjectMethod]] \*isManagingEmails `() -> $boolean`
+
+Determines if this manager can store and retrieve emails. The password manager is used in preference to the user mapping manager for storing emails, on the basis that emails need to be secure, and the password database is the most secure place. If a password manager does not manage emails, then TWiki will fall back to using the user mapping manager (which by default will store emails in user topics)
+
+The default ('none') password manager does **not** manage emails.
+
+## <a name="ObjectMethod <strong>getEmails</strong> ($login"></a> [[ObjectMethod]] **getEmails** `($login) -> @emails`
+
+Fetch the email address(es) for the given login. Default behaviour is to return an empty list. Called by Users.pm. Only used if `isManagingEmails` -> `true`.
+
+## <a name="ObjectMethod <strong>setEmails</strong> ($login"></a> [[ObjectMethod]] **setEmails** `($login,@emails) -> $boolean`
+
+Set the email address(es) for the given login name. Returns true if the emails were set successfully. Default behaviour is a nop, which will result in the user mapping manager taking over. Called by Users.pm. Only used if `isManagingEmails` -> `true`.
+
+## <a name="ObjectMethod <strong>find_LoginByEmail*"></a> [[ObjectMethod]] \*findLoginByEmail `($email) -> \@users`
+
+Returns an array of login names that relate to a email address. Defaut behaviour is a nop, which will result in the user mapping manager being asked for its opinion. If subclass implementations return a value for this, then the user mapping manager will **not** be asked. Only used if `isManagingEmails` -> `true`.
+
+Called by Users.pm.
+
+## <a name="ObjectMethod <strong>can_FetchUsers</strong> ()"></a> [[ObjectMethod]] **canFetchUsers** `() -> boolean`
-Fetch the email address(es) for the given username. Default behaviour is to look up the users' personal topic.
+returns true if the fetchUsers method is implemented and can return an iterator of users. returns undef / nothing in this case, as we are unable to generate a list of users
-## <a name="ObjectMethod <strong>setEmails</strong> ($user,"></a> [[ObjectMethod]] **setEmails** `($user,@emails)`
+## <a name="ObjectMethod <strong>fetchUsers</strong> () - n"></a> [[ObjectMethod]] **fetchUsers** `() -> newTWiki::ListIterator(\@users)`
-Set the email address(es) for the given username in the user topic.
+returns a [[TWikiIterator]] of loginnames from the password source. If [[AllowLoginNames]] is false this is used to remove the need for a [[TWikiUsers]] topic.
--- /dev/null
+# <a name="List of %WIKITOOLNAME% users"></a> List of %WIKITOOLNAME% users
+
+Below is a list of users with accounts. If you want to edit topics or see protected areas of the site then you can get added to the list by registering: fill out the form in [[TWikiRegistration]].
+
+If you forget your password, [[ResetPassword]] will get a new one sent to you.
+
+----
+
+<a name="ListStart"></a> [[A|Main/WebHome#A]] [[B|Main/WebHome#B]] [[C|Main/WebHome#C]] [[D|Main/WebHome#D]] [[E|Main/WebHome#E]] [[F|Main/WebHome#F]] [[G|Main/WebHome#G]] [[H|Main/WebHome#H]] [[I|Main/WebHome#I]] [[J|Main/WebHome#J]] [[K|Main/WebHome#K]] [[L|Main/WebHome#L]] [[M|Main/WebHome#M]] [[N|Main/WebHome#N]] [[O|Main/WebHome#O]] [[P|Main/WebHome#P]] [[Q|Main/WebHome#Q]] [[R|Main/WebHome#R]] [[S|Main/WebHome#S]] [[T|Main/WebHome#T]] [[U|Main/WebHome#U]] [[V|Main/WebHome#V]] [[W|Main/WebHome#W]] [[X|Main/WebHome#X]] [[Y|Main/WebHome#Y]] [[Z|Main/WebHome#Z]]
+
+- A - <a name="A">- - - -</a>
+- B - <a name="B">- - - -</a>
+- C - <a name="C">- - - -</a>
+- D - <a name="D">- - - -</a>
+- E - <a name="E">- - - -</a>
+- F - <a name="F">- - - -</a>
+- G - <a name="G">- - - -</a>
+- H - <a name="H">- - - -</a>
+- I - <a name="I">- - - -</a>
+- J - <a name="J">- - - -</a>
+- K - <a name="K">- - - -</a>
+- L - <a name="L">- - - -</a>
+- M - <a name="M">- - - -</a>
+- N - <a name="N">- - - -</a>
+- O - <a name="O">- - - -</a>
+- P - <a name="P">- - - -</a>
+- Q - <a name="Q">- - - -</a>
+- R - <a name="R">- - - -</a>
+- S - <a name="S">- - - -</a>
+- T - <a name="T">- - - -</a>
+- [[TWikiContributor]] - 1 Jan 2005
+- [[TWikiGuest]] - guest - 10 Feb 1999
+- [[TWikiRegistrationAgent]] - 1 Jan 2005
+- U - <a name="U">- - - -</a>
+- [[UnknownUser]] - 1 Jan 2005
+- V - <a name="V">- - - -</a>
+- W - <a name="W">- - - -</a>
+- X - <a name="X">- - - -</a>
+- Y - <a name="Y">- - - -</a>
+- Z - <a name="Z">- - - -</a>
+
+**_%X% Note:_** There are four default system users:
+
+- **TWikiContributor** - placeholder for a TWiki developer, and is used in TWiki documentation
+- **TWikiGuest** - guest user, used as a fallback if the user can't be identified
+- **TWikiRegistrationAgent** - special user used during the new user registration process
+- **UnknownUser** - used where the author of a previously stored piece of data can't be determined
+
+**_Access Control:_**
+
+- Set ALLOWTOPICCHANGE = [[TWikiAdminGroup]], [[TWikiRegistrationAgent]]
+# <a name="TWiki Variables"></a> TWiki Variables
+
+_Special text strings expand on the fly to display user data or system info_
+
+TWikiVariables are text strings - `%VARIABLE%` or `%VARIABLE{ parameter="value" }%` - that expand into content whenever a topic is rendered for viewing. There are two types of variables:
+
+1. Preferences variables: Can be defined and changed by the user
+2. Predefined variables: Defined by the TWiki system or by Plugins (for example, the [[SpreadSheetPlugin]] introduces a `%CALC{}%` variable)
+
<div>
<ul>
<li><a href="#TWiki Variables"> TWiki Variables</a><ul>
</ul>
</div>
-# <a name="TWiki Variables"></a> TWiki Variables
-
-_Special text strings expand on the fly to display user data or system info_
-
-TWikiVariables are text strings - `%VARIABLE%` or `%VARIABLE{ parameter="value" }%` - that expand into content whenever a topic is rendered for viewing. There are two types of variables:
-
-1. Preferences variables: Can be defined and changed by the user
-2. Predefined variables: Defined by the TWiki system or by Plugins (for example, the [[SpreadSheetPlugin]] introduces a `%CALC{}%` variable)
-
## <a name="Using Variables"></a> Using Variables
To use a variable type its name. For example,
You can set variables in all the following places:
-1. local site level in [[TWiki.TWikiPreferences|TWiki/TWikiPreferences]]
+1. local site level in [[%SYSTEMWEB%.TWikiPreferences|SYSTEMWEB/TWikiPreferences]]
2. plugin topics (see [[TWikiPlugins]])
3. local site level in [[Main.TWikiPreferences|Main/TWikiPreferences]]
-4. user level in individual user topics in Main web
+4. user level in individual user topics in %USERSWEB% web
5. web level in [[WebPreferences]] of each web
6. topic level in topics in webs
7. session variables (if sessions are enabled)
Settings at higher-numbered levels override settings of the same variable at lower numbered levels, unless the variable was included in the setting of FINALPREFERENCES at a lower-numbered level, in which case it is locked at the value it has at that level.
+If you are setting a variable and using it in the same topic, note that TWiki reads all the variable settings from the saved version of the topic before it displays anything. This means you can use a variable anywhere in the topic, even if you set it somewhere inconspicuous near the end. **But beware:** it also means that if you change the setting of a variable you are using in the same topic, <code>**Preview**</code> will show the wrong thing, and you must <code>**Save**</code> the topic to see it correctly.
+
The syntax for setting Variables is the same anywhere in TWiki (on its own TWiki bullet line, including nested bullets): <br />`[multiple of 3 spaces] * [space] Set [space] VARIABLENAME [space] = [space] value`
> **Examples:**
## <a name="TWiki Variables Quickstart"></a> TWiki Variables Quickstart
-TWiki Variables are names that are enclosed in percent signs `%` that are expanded on the fly. Some variables take arguments, such as `%INCLUDE%`. For those variables, the arguments are included in curly braces (\{ and \}).
+TWiki Variables are names enclosed in percent signs that are that are expanded to some other text when the topic is displayed. For example, `%TOPIC%` is expanded to %TOPIC%. Some variables can take arguments in curly braces - for example, `%INCLUDE{"OtherTopic" ARG="arg"}%`.
-<table border="1" cellpadding="0" cellspacing="0">
- <tr>
- <th bgcolor="#99CCCC"><strong> Variable </strong></th>
- <th bgcolor="#99CCCC"><strong> In brief </strong></th>
- <th bgcolor="#99CCCC"><strong> Full documentation </strong></th>
- </tr>
- <tr>
- <td><code>%TOC%</code></td>
- <td> Automatically generates a table of contents based on headings in a topic - see the top of this page for an example. </td>
- <td>[[Main/VarTOC]]</td>
- </tr>
- <tr>
- <td><code>%WEB%</code></td>
- <td> The current web, is <b>%WEB%</b>. </td>
- <td>[[Main/VarWEB]]</td>
- </tr>
- <tr>
- <td><code>%TOPIC%</code></td>
- <td> The current topic name, is <b>WebHome</b>. </td>
- <td>[[Main/VarTOPIC]]</td>
- </tr>
- <tr>
- <td><code>%ATTACHURL%</code></td>
- <td> The attachment URL of the current topic. Example usage: If you attach a file to a topic you can refer to it as <code><b>%ATTACHURL%/image.gif</b></code> to show the URL of the file or the image in your text. </td>
- <td>[[Main/VarATTACHURL]]</td>
- </tr>
- <tr>
- <td><code>%INCLUDE{"SomeTopic"}%</code></td>
- <td> Server side include, includes another topic. The current web is the default web. Example: <code><b>%INCLUDE{"TWiki.SiteMap"}%</b></code></td>
- <td>[[Main/VarINCLUDE]]</td>
- </tr>
- <tr>
- <td><code>%SEARCH{"sushi"}%</code></td>
- <td> Inline search showing the search result embedded in a topic. [[Main/FormattedSearch]] gives you control over formatting, useful for creating web-based applications. </td>
- <td>[[Main/VarSEARCH]]</td>
- </tr>
-</table>
+Many TWiki variables are built-in, and others are predefined for your convenience. You can also define your own TWiki Variables at the entire site, individual web, or individual topic level. For more information, go to **[[TWikiVariables]]**
-[[TWikiPreferences]] defines some site-wide variables. Among them are:
-
-- **Line break:** Write `%BR%` to start a new line.
-- **Colored text:** Write: `%RED% Red %ENDCOLOR% and %BLUE% blue %ENDCOLOR% colors` to get: %RED% Red %ENDCOLOR% and %BLUE% blue %ENDCOLOR% colors.
-
-There are many more variables. To see them all, go to **[[TWikiVariables]]**.
+TWiki Variables are fully expanded _before_ any of the TWiki 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: %H%, %T%, and %X%, respectively. [[TWikiDocGraphics]] lists them all.
-<font>(included from [[SiteMap]]; change %INCLUDINGWEB%.%INCLUDINGTOPIC% to include from SiteMap instead of TWikiWebsTable)</font>
+<font>(included from %SYSTEMWEB%.SiteMap; change %INCLUDINGWEB%.%INCLUDINGTOPIC% to include from SiteMap instead of TWikiWebsTable)</font>
- Set SORT = all
- Default table attributes:
- - Set TABLEATTRIBUTES = tableborder="1" cellpadding="0" cellspacing="0" valign="top" headeralign="center" headercolor="#ffffff" headerbg="#6b7f93" headerbgsorted="#334455" headercolor="#ffffff" databg="#ffffff,#edf4f9" databgsorted="#f5f5f5,#dce7ee"
- - Classic skin table attributes:
- - #Set TABLEATTRIBUTES = tableborder="1" cellpadding="0" cellspacing="1" headerbg="#99cccc" databg="#ffffff,#ffffcc"
+ - Set TABLEATTRIBUTES = tableborder="1" cellpadding="0" cellspacing="0" valign="top" headercolor="#ffffff" headerbg="#687684" headerbgsorted="#334455" databg="#ffffff,#edf4f9" databgsorted="#f1f7fc,#ddebf6" tablerules="rows"
## <a name="Table Attributes"></a> Table Attributes
Attributes are defined as a `TABLEATTRIBUTES` Plugin setting in this topic, a `TABLEATTRIBUTES` preferences setting, or on line before the table using `%TABLE{...}%`:
-<table border="1" cellpadding="0" cellspacing="0" style="border-width: 1px">
- <tr>
- <th bgcolor="#6b7f93" maxcols="0" style=""><a href="http://localhost?sortcol=0;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Argument</font></a></th>
- <th bgcolor="#6b7f93" maxcols="0" style=""><a href="http://localhost?sortcol=1;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Comment</font></a></th>
- <th bgcolor="#6b7f93" maxcols="0" style=""><a href="http://localhost?sortcol=2;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Default value</font></a></th>
- <th bgcolor="#6b7f93" maxcols="0" style=""><a href="http://localhost?sortcol=3;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">Example</font></a></th>
- </tr>
- <tr>
- <td bgcolor="#ecf2f8" style=""><code>sort</code></td>
- <td bgcolor="#ecf2f8" style=""> Set table sorting <code>"on"</code> or <code>"off"</code>. </td>
- <td bgcolor="#ecf2f8" style=""><span>unspecified</span></td>
- <td bgcolor="#ecf2f8" style=""><code>sort="on"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ffffff" style=""><code>initsort</code></td>
- <td bgcolor="#ffffff" style=""> Column to sort initially (<code>"1"</code> to number of columns). </td>
- <td bgcolor="#ffffff" style=""><span>unspecified</span></td>
- <td bgcolor="#ffffff" style=""><code>initsort="2"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ecf2f8" style=""><code>initdirection</code></td>
- <td bgcolor="#ecf2f8" style=""> Initial sorting direction for <code>initsort</code>, set to <code>"up"</code> (descending) or <code>"down"</code> (ascending). </td>
- <td bgcolor="#ecf2f8" style=""><span>unspecified</span></td>
- <td bgcolor="#ecf2f8" style=""><code>initdirection="up"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ffffff" style=""><code>headerbg</code></td>
- <td bgcolor="#ffffff" style=""> Header cell background colour. </td>
- <td bgcolor="#ffffff" style=""><code>"#6b7f93"</code></td>
- <td bgcolor="#ffffff" style=""><code>headerbg="#999999"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ecf2f8" style=""><code>headerbgsorted</code></td>
- <td bgcolor="#ecf2f8" style=""> Header cell background colour of a sorted column. </td>
- <td bgcolor="#ecf2f8" style=""> the value of <code>headerbg</code></td>
- <td bgcolor="#ecf2f8" style=""><code>headerbgsorted="#32596c"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ffffff" style=""><code>headercolor</code></td>
- <td bgcolor="#ffffff" style=""> Header cell text colour. </td>
- <td bgcolor="#ffffff" style=""><code>"#ffffff"</code></td>
- <td bgcolor="#ffffff" style=""><code>headercolor="#0000cc"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ecf2f8" style=""><code>databg</code></td>
- <td bgcolor="#ecf2f8" style=""> Data cell background colour, a comma separated list. Specify <code>"none"</code> for no colour, that is to use the colour/background of the page the table is on. </td>
- <td bgcolor="#ecf2f8" style=""><code>"#edf4f9,#ffffff"</code></td>
- <td bgcolor="#ecf2f8" style=""><code>databg="#f2f2f2,#ffffff"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ffffff" style=""><code>databgsorted</code></td>
- <td bgcolor="#ffffff" style=""> Data cell background colour of a sorted column; see <code>databg</code>. </td>
- <td bgcolor="#ffffff" style=""> the values of <code>databg</code></td>
- <td bgcolor="#ffffff" style=""><code>databgsorted="#d4e8e4,#e5f5ea"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ecf2f8" style=""><code>datacolor</code></td>
- <td bgcolor="#ecf2f8" style=""> Data cell text colour, a comma separated list. </td>
- <td bgcolor="#ecf2f8" style=""><span>unspecified</span></td>
- <td bgcolor="#ecf2f8" style=""><code>datacolor="#0000CC, #000000"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ffffff" style=""><code>tableborder</code></td>
- <td bgcolor="#ffffff" style=""> Table border width (pixels). </td>
- <td bgcolor="#ffffff" style=""><code>"1"</code></td>
- <td bgcolor="#ffffff" style=""><code>tableborder="2"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ecf2f8" style=""><code>tableframe</code></td>
- <td bgcolor="#ecf2f8" style=""> Table frame, set to <code>"void"</code> (no sides), <code>"above"</code> (the top side only), <code>"below"</code> (the bottom side only), <code>"hsides"</code> (the top and bottom sides only), <code>"lhs"</code> (the left-hand side only), <code>"rhs"</code> (the right-hand side only), <code>"vsides"</code> (the right and left sides only), <code>"box"</code> (all four sides), <code>"border"</code> (all four sides). </td>
- <td bgcolor="#ecf2f8" style=""><span>unspecified</span></td>
- <td bgcolor="#ecf2f8" style=""><code>tableframe="hsides"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ffffff" style=""><code>tablerules</code></td>
- <td bgcolor="#ffffff" style=""> Table rules, set to <code>"none"</code> (no rules), <code>"groups"</code> (rules will appear between row groups and column groups only), <code>"rows"</code> (rules will appear between rows only), <code>"cols"</code> (rules will appear between columns only), <code>"all"</code> (rules will appear between all rows and columns). </td>
- <td bgcolor="#ffffff" style=""><span>unspecified</span></td>
- <td bgcolor="#ffffff" style=""><code>tablerules="rows"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ecf2f8" style=""><code>cellpadding</code></td>
- <td bgcolor="#ecf2f8" style=""> Cell padding (pixels). </td>
- <td bgcolor="#ecf2f8" style=""><code>"0"</code></td>
- <td bgcolor="#ecf2f8" style=""><code>cellpadding="0"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ffffff" style=""><code>cellspacing</code></td>
- <td bgcolor="#ffffff" style=""> Cell spacing (pixels). </td>
- <td bgcolor="#ffffff" style=""><code>"0"</code></td>
- <td bgcolor="#ffffff" style=""><code>cellspacing="3"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ecf2f8" style=""><code>cellborder</code></td>
- <td bgcolor="#ecf2f8" style=""> Cell border width (pixels). </td>
- <td bgcolor="#ecf2f8" style=""><span>unspecified</span></td>
- <td bgcolor="#ecf2f8" style=""><code>cellborder="0"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ffffff" style=""><code>valign</code></td>
- <td bgcolor="#ffffff" style=""> Vertical alignment of cells and headers, set to <code>"top"</code>, <code>"middle"</code>, <code>"bottom"</code> or <code>"baseline"</code>. </td>
- <td bgcolor="#ffffff" style=""><span>unspecified</span></td>
- <td bgcolor="#ffffff" style=""><code>valign="top"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ecf2f8" style=""><code>headervalign</code></td>
- <td bgcolor="#ecf2f8" style=""> Vertical alignment of header cells; overrides <code>valign</code>. </td>
- <td bgcolor="#ecf2f8" style=""><span>unspecified</span></td>
- <td bgcolor="#ecf2f8" style=""><code>headervalign="top"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ffffff" style=""><code>datavalign</code></td>
- <td bgcolor="#ffffff" style=""> Vertical alignment of data cells; overrides <code>valign</code>. </td>
- <td bgcolor="#ffffff" style=""><span>unspecified</span></td>
- <td bgcolor="#ffffff" style=""><code>datavalign="top"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ecf2f8" style=""><code>headeralign</code></td>
- <td bgcolor="#ecf2f8" style=""> Header cell alignment, one value for all columns, or a comma separated list for different alignment of individual columns. Set to <code>"left"</code>, <code>"center"</code>, <code>"right"</code> or <code>"justify"</code>. Overrides individual cell settings. </td>
- <td bgcolor="#ecf2f8" style=""><span>unspecified</span></td>
- <td bgcolor="#ecf2f8" style=""><code>headeralign="left,right"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ffffff" style=""><code>dataalign</code></td>
- <td bgcolor="#ffffff" style=""> Data cell alignment, one value for all columns, or a comma separated list for different alignment of individual columns. Set to <code>"left"</code>, <code>"center"</code>, <code>"right"</code> or <code>"justify"</code>. Overrides individual cell settings. </td>
- <td bgcolor="#ffffff" style=""><span>unspecified</span></td>
- <td bgcolor="#ffffff" style=""><code>dataalign="center"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ecf2f8" style=""><code>tablewidth</code></td>
- <td bgcolor="#ecf2f8" style=""> Table width: Percentage of window width, or absolute pixel value. </td>
- <td bgcolor="#ecf2f8" style=""><span>unspecified</span></td>
- <td bgcolor="#ecf2f8" style=""><code>tablewidth="100%"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ffffff" style=""><code>columnwidths</code></td>
- <td bgcolor="#ffffff" style=""> Column widths: Comma delimited list of column widths, percentage or absolute pixel value. </td>
- <td bgcolor="#ffffff" style=""><span>unspecified</span></td>
- <td bgcolor="#ffffff" style=""><code>columnwidths="80%,20%"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ecf2f8" style=""><code>headerrows</code></td>
- <td bgcolor="#ecf2f8" style=""> Number of header rows to exclude from sort. </td>
- <td bgcolor="#ecf2f8" style=""><code>"1"</code></td>
- <td bgcolor="#ecf2f8" style=""><code>headerrows="1"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ffffff" style=""><code>footerrows</code></td>
- <td bgcolor="#ffffff" style=""> Number of footer rows to exclude from sort. </td>
- <td bgcolor="#ffffff" style=""><code>"0"</code></td>
- <td bgcolor="#ffffff" style=""><code>footerrows="1"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ecf2f8" style=""><code>id</code></td>
- <td bgcolor="#ecf2f8" style=""> Table identifier string. </td>
- <td bgcolor="#ecf2f8" style=""><span>unspecified</span></td>
- <td bgcolor="#ecf2f8" style=""><code>id="userTable"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ffffff" style=""><code>summary</code></td>
- <td bgcolor="#ffffff" style=""> Table summary used by screenreaders: A summary of what the table presents. It should provide an orientation for someone who listens to the table. </td>
- <td bgcolor="#ffffff" style=""><span>unspecified</span></td>
- <td bgcolor="#ffffff" style=""><code>summary="List of subscribed users"</code></td>
- </tr>
- <tr>
- <td bgcolor="#ecf2f8" style=""><code>caption</code></td>
- <td bgcolor="#ecf2f8" style=""> Table caption: A title that will be displayed just above the table. </td>
- <td bgcolor="#ecf2f8" style=""><span>unspecified</span></td>
- <td bgcolor="#ecf2f8" style=""><code>caption="Users"</code></td>
- </tr>
-</table>
-
The `%TABLE{...}%` settings override `TABLEATTRIBUTES` preferences settings, which override the `TABLEATTRIBUTES` Plugin settings.
+The setting `disableallsort` is normally not used as a TABLE or TABLEATTRIBUTES setting. Plugins such as [[EditTablePlugin]] dynamically sets `disableallsort` to disable sorting while editing a table. For this to work it is important that [[EditTablePlugin]] runs before [[TablePlugin]], which is the default. The setting `sort` can be overwritten by a URL parameter or hidden formfield of the same name. Plugins such as [[EditTablePlugin]] can use this to disable table header sorting while in edit mode.
+
## <a name="Examples"></a> Examples
### <a name="Use of %TABLE{...}%"></a> Use of %TABLE\{...\}%
<th bgcolor="#D5CCB1" colspan="6" maxcols="0" style="border-width: 0px"><span><font color="#666666"> <strong> Table with two Header Rows and Footer Row </strong> </font></span></th>
</tr>
<tr>
- <th bgcolor="#D5CCB1" maxcols="0" style="border-width: 0px"><a href="http://localhost?sortcol=0;table=3;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#666666">Num</font></a></th>
- <th bgcolor="#D5CCB1" maxcols="0" style="border-width: 0px"><a href="http://localhost?sortcol=1;table=3;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#666666">Status</font></a></th>
- <th bgcolor="#D5CCB1" maxcols="0" style="border-width: 0px"><a href="http://localhost?sortcol=2;table=3;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#666666">Action</font></a></th>
- <th bgcolor="#D5CCB1" maxcols="0" style="border-width: 0px"><a href="http://localhost?sortcol=3;table=3;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#666666">Who</font></a></th>
- <th bgcolor="#D5CCB1" maxcols="0" style="border-width: 0px"><a href="http://localhost?sortcol=4;table=3;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#666666">When</font></a></th>
- <th bgcolor="#D5CCB1" maxcols="0" style="border-width: 0px"><a href="http://localhost?sortcol=5;table=3;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#666666">Progress</font></a></th>
+ <th bgcolor="#D5CCB1" maxcols="0" style="border-width: 0px"><a href="http://localhost?sortcol=0;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#666666">Num</font></a></th>
+ <th bgcolor="#D5CCB1" maxcols="0" style="border-width: 0px"><a href="http://localhost?sortcol=1;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#666666">Status</font></a></th>
+ <th bgcolor="#D5CCB1" maxcols="0" style="border-width: 0px"><a href="http://localhost?sortcol=2;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#666666">Action</font></a></th>
+ <th bgcolor="#D5CCB1" maxcols="0" style="border-width: 0px"><a href="http://localhost?sortcol=3;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#666666">Who</font></a></th>
+ <th bgcolor="#D5CCB1" maxcols="0" style="border-width: 0px"><a href="http://localhost?sortcol=4;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#666666">When</font></a></th>
+ <th bgcolor="#D5CCB1" maxcols="0" style="border-width: 0px"><a href="http://localhost?sortcol=5;table=2;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#666666">Progress</font></a></th>
</tr>
<tr>
<td bgcolor="#FAF0D4" style="border-width: 0px"> 1 </td>
<table border="1" cellpadding="0" cellspacing="0" style="border-width: 1px">
<tr>
- <th bgcolor="#6b7f93" maxcols="0" style=""><a href="http://localhost?sortcol=0;table=4;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">When</font></a></th>
+ <th bgcolor="#6b7f93" maxcols="0" style=""><a href="http://localhost?sortcol=0;table=3;up=0#sorted_table" rel="nofollow" title="Sort by this column"><font color="#ffffff">When</font></a></th>
</tr>
<tr>
<td bgcolor="#ecf2f8" style=""> 1-Jan-2004 </td>
</tr>
</table>
+## <a name="TablePlugin and CSS"></a><a name="_TablePlugin and CSS"></a> TablePlugin and CSS
+
+Information for programmers.
+
+TablePlugin implements the following precedence:
+
+- the `TABLEATTRIBUTE` settings only write html styling, no CSS
+- the `TABLEATTRIBUTE` settings can be overridden by a skin's CSS
+- the `TABLE` tag attributes are converted to CSS styling, written in the head; these override any skin's CSS
+
+### <a name="CSS written by _TablePlugin"></a> CSS written by TablePlugin
+
+<table border="1" cellpadding="0" cellspacing="0" style="border-width: 1px">
+ <tr>
+ <td bgcolor="#ecf2f8" style=""><code>.twikiTable</code></td>
+ <td bgcolor="#ecf2f8" style=""> The table </td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><code>.twikiSortedCol</code></td>
+ <td bgcolor="#ffffff" style=""> A sorted column </td>
+ </tr>
+ <tr>
+ <td bgcolor="#ecf2f8" style=""><code>.twikiSortedAscendingCol</code></td>
+ <td bgcolor="#ecf2f8" style=""> Sorted column, ascending </td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><code>.twikiSortedDescendingCol</code></td>
+ <td bgcolor="#ffffff" style=""> Sorted column, descending </td>
+ </tr>
+ <tr>
+ <td bgcolor="#ecf2f8" style=""><code>.tableSortIcon</code></td>
+ <td bgcolor="#ecf2f8" style=""> The sort icon holder (span) </td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><code>.twikiFirstCol</code></td>
+ <td bgcolor="#ffffff" style=""> The first column </td>
+ </tr>
+ <tr>
+ <td bgcolor="#ecf2f8" style=""><code>.twikiTableEven</code></td>
+ <td bgcolor="#ecf2f8" style=""> Even numbered rows </td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><code>.twikiTableOdd</code></td>
+ <td bgcolor="#ffffff" style=""> Odd numbered rows </td>
+ </tr>
+ <tr>
+ <td bgcolor="#ecf2f8" style=""><code>.twikiTableCol</code> + column number </td>
+ <td bgcolor="#ecf2f8" style=""> Unique column identifier, for instance: <code>twikiTableCol0</code></td>
+ </tr>
+ <tr>
+ <td bgcolor="#ffffff" style=""><code>.twikiTableRow</code> + type + row number </td>
+ <td bgcolor="#ffffff" style=""> Unique row identifier, for instance: <code>twikiTableRowdataBg0</code></td>
+ </tr>
+</table>
+
## <a name="Plugin Installation Instructions"></a> Plugin Installation Instructions
This plugin is pre-installed with your TWiki release. You should not have to install it other than to do an upgrade.
<td bgcolor="#ecf2f8" style=""> Plugin topic </td>
</tr>
<tr>
- <td bgcolor="#ffffff" style=""><code><b>data/TWiki/%TOPIC%.txt,v</b></code></td>
- <td bgcolor="#ffffff" style=""> Plugin topic repository </td>
+ <td bgcolor="#ffffff" style=""><code><b>lib/TWiki/Plugins/%TOPIC%.pm</b></code></td>
+ <td bgcolor="#ffffff" style=""> Plugin Perl module </td>
</tr>
<tr>
- <td bgcolor="#ecf2f8" style=""><code><b>lib/TWiki/Plugins/%TOPIC%.pm</b></code></td>
+ <td bgcolor="#ecf2f8" style=""><code><b>lib/TWiki/Plugins/%TOPIC%/Core.pm</b></code></td>
<td bgcolor="#ecf2f8" style=""> Plugin Perl module </td>
</tr>
- <tr>
- <td bgcolor="#ffffff" style=""><code><b>pub/TWiki/%TOPIC%/diamond.gif</b></code></td>
- <td bgcolor="#ffffff" style=""> Diamond symbol </td>
- </tr>
- <tr>
- <td bgcolor="#ecf2f8" style=""><code><b>pub/TWiki/%TOPIC%/down.gif</b></code></td>
- <td bgcolor="#ecf2f8" style=""> Down arrow </td>
- </tr>
- <tr>
- <td bgcolor="#ffffff" style=""><code><b>pub/TWiki/%TOPIC%/up.gif</b></code></td>
- <td bgcolor="#ffffff" style=""> Up arrow </td>
- </tr>
</table>
- (Dakar) Visit `configure` in your TWiki installation, and enable the plugin in the \{Plugins\} section.
- Test if the plugin is correctly installed:
<td bgcolor="#ecf2f8" style=""> TWiki:Main/JohnTalintyre, TWiki:Main/PeterThoeny </td>
</tr>
<tr>
+ <td align="right" bgcolor="#ffffff" style=""> Copyright: </td>
+ <td bgcolor="#ffffff" style=""> © 2001-2007, TWiki:Main/JohnTalintyre, <a href="mailto:Peter@Thoeny.org">Peter@Thoeny.org</a> (<a href="http://www.twiki.net/" target="_top">TWIKI.NET</a>), TWiki Contributors </td>
+ </tr>
+ <tr>
+ <td align="right" bgcolor="#ecf2f8" style=""> License: </td>
+ <td bgcolor="#ecf2f8" style=""> GPL (<a href="http://www.gnu.org/copyleft/gpl.html" target="_top">GNU General Public License</a>) </td>
+ </tr>
+ <tr>
<td align="right" bgcolor="#ffffff" style=""> Plugin Version: </td>
- <td bgcolor="#ffffff" style=""> 1.020 </td>
+ <td bgcolor="#ffffff" style=""> 1.032 (22 Dec 2007) </td>
</tr>
<tr>
<td align="right" bgcolor="#ecf2f8" style=""> Change History: </td>
<td bgcolor="#ecf2f8" style=""> </td>
</tr>
<tr>
+ <td align="right" bgcolor="#ffffff" style=""> 16 Dec 2007 </td>
+ <td bgcolor="#ffffff" style=""> 1.030: Kenneth Lavrsen: Fixed the problem of tables being sorted by by [[Main/TablePlugin]] while the table is being edited by plugins such as [[Main/EditTablePlugin]]. This required adding a new attribute <code>disableallsort</code> so plugins such as [[Main/EditTablePlugin]] can temporarily disable all sorting for a table. Additionally the CGI variable (URL parameter or hidden formfield) <code>sort</code> can be set to "off" which disables all header sorting in the topic. This is used by plugins such as [[Main/EditTablePlugin]] to disable the sorting by clicking header fields during editing of tables. Ref: TWikibug:Item5135 and TWikibug:Item2690. </td>
+ </tr>
+ <tr>
+ <td align="right" bgcolor="#ecf2f8" style=""> 03 Dec 2007 </td>
+ <td bgcolor="#ecf2f8" style=""> Arthur Clemens: Fixed rendering and order of html elements <code>thead</code>, <code>tfoot</code> and <code>tbody</code>; corrected <code>id</code> parameter. </td>
+ </tr>
+ <tr>
+ <td align="right" bgcolor="#ffffff" style=""> 24 Nov 2007 </td>
+ <td bgcolor="#ffffff" style=""> Arthur Clemens: Fixed sorting of columns with only icons; also removed TWiki formatting before sorting. </td>
+ </tr>
+ <tr>
+ <td align="right" bgcolor="#ecf2f8" style=""> 06 Oct 2007 </td>
+ <td bgcolor="#ecf2f8" style=""> 15180: PTh: Added [[TWiki/VarTABLE]] to have it listed in [[TWiki/TWikiVariables]]</td>
+ </tr>
+ <tr>
+ <td align="right" bgcolor="#ffffff" style=""> 27 Jun 2007 </td>
+ <td bgcolor="#ffffff" style=""> 1.024 - 1.027 Various small bug fixes. </td>
+ </tr>
+ <tr>
+ <td align="right" bgcolor="#ecf2f8" style=""> 24 Jun 2007 </td>
+ <td bgcolor="#ecf2f8" style=""> 1.023: Arthur Clemens: Inline styles are now written to the head; updated default sort icons (from [[TWiki/TWikiDocGraphics]]). </td>
+ </tr>
+ <tr>
+ <td align="right" bgcolor="#ffffff" style=""> 23 Jun 2007 </td>
+ <td bgcolor="#ffffff" style=""> 1.022: Arthur Clemens: Fixed styling of param <code>tablerules</code> on Internet Explorer. </td>
+ </tr>
+ <tr>
+ <td align="right" bgcolor="#ecf2f8" style=""> 23 May 2007 </td>
+ <td bgcolor="#ecf2f8" style=""> 1.021: Michael Daum: Fixed css attribute priority to cooperate nicely with skin themes. </td>
+ </tr>
+ <tr>
<td align="right" bgcolor="#ffffff" style=""> 27 Dec 2006 </td>
<td bgcolor="#ffffff" style=""> 1.020: Kenneth Lavrsen: Fixed initsort so all tables can be initsorted and not only the first. When you sort a table by clicking on the header of a column the table gets sorted accordingly. When you click the header of another table the previously sorted table goes back being sorted as specified by initsort. </td>
</tr>
<td align="right" bgcolor="#ecf2f8" style=""> Feedback: </td>
<td bgcolor="#ecf2f8" style=""><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev</a></td>
</tr>
+ <tr>
+ <td align="right" bgcolor="#ffffff" style=""> Appraisal: </td>
+ <td bgcolor="#ffffff" style=""><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal</a></td>
+ </tr>
</table>
**_Related Topics:_** [[TWikiPreferences]], [[TWikiPlugins]], [[StandardColors]]
## <a name="Purpose"></a> Purpose
-Template webs were created to act as templates in creating webs. It is now possible to create webs via the [[ManagingWebs]] topic. In the not so distant past TWiki webs were created by hand. The data directory contains the different webs such as **Main** and **TWiki**. A web that begins with an underscore "\_" character is considered invisible and a template. All files in the **\_default** (or any other web that begins with an underscore) template web will be copied into your new web. The [[_default|_default/WebHome]] web template contains the following topics: `WebHome, WebChanges, WebIndex, WebNotify, WebPreferences, WebSearch, WebStatistics and WebTopicList.`
+Template webs were created to act as templates in creating webs. It is now possible to create webs via the %SYSTEMWEB%.ManagingWebs topic. In the not so distant past TWiki webs were created by hand. The data directory contains the different webs such as **Main** and **TWiki**. A web that begins with an underscore "\_" character is considered invisible and a template. All files in the **\_default** (or any other web that begins with an underscore) template web will be copied into your new web. The [[_default|_default/WebHome]] web template contains the following topics: `WebHome, WebChanges, WebIndex, WebNotify, WebPreferences, WebSearch, WebStatistics and WebTopicList.`
## <a name="Customizing"></a> Customizing
<li><a href="#How do I create a heading?"> How do I create a heading?</a></li>
<li><a href="#Text enclosed in angle brackets"> Text enclosed in angle brackets like <filename> is not displayed. How can I show it as it is?</a></li>
<li><a href="#Some words appear highlighted, w"> Some words appear highlighted, with a "?" link at the end. How can I prevent that?</a></li>
+ <li><a href="#How do I start a word with an ex"> How do I start a word with an exclamation mark?</a></li>
<li><a href="#How can I write fixed font text?"> How can I write fixed font text?</a></li>
<li><a href="#Text I enter gets wrapped around"> Text I enter gets wrapped around. How can I keep the formatting as it is?</a></li>
<li><a href="#How do I create tables?"> How do I create tables?</a></li>
You can create six sizes of headings - <h1>...<h6> in HTML - by typing, from the beginning of a line, three dashes (-), from one to six plus signs (+), a space, and your heading text. The FAQ questions on this page are created with: `---+++ Have a question?`.
-- You can insert a nested table of contents, generated from headings, by placing `%TOC%` wherever you like on a page (see [[TWikiVariables]] for more `%TOC%` options).
+- You can insert a nested table of contents, generated from headings, by placing `%TOC%` wherever you like on a page (see %SYSTEMWEB%.TWikiVariables for more `%TOC%` options).
----
A question mark after a word is a link to a topic that doesn't yet exist - click it to create the new page. This is a TWiki feature - typing a [[MeaningfulTitle]] in a comment is an invitation for someone else to add a new branch to the topic.
-To prevent auto-linking - say you want to enter a word like JavaScript (the proper spelling!) - prefix the [[WikiStyleWord]] with an exclamation point:
+To prevent auto-linking - say you want to enter a word like JavaScript - prefix the [[WikiStyleWord]] with an exclamation point:
- `!WikiStyleWord` displays as WikiStyleWord
----
+### <a name="How do I start a word with an ex"></a> How do I start a word with an exclamation mark?
+
+A leading exclamation point is used to escape wiki formatting, as we have learned in the previous question. Sometimes it has an unwanted effect, such as when you want to write "!=" (e.g. "not equal"), you will not see the exclamation mark.
+
+To escape the exclamation mark escape, try prefixing a `<nop>`, e.g. write `A <nop>!= B` to get "A != B". Alternatively, use the HTML entity `!`, which renders as an exclamation mark, e.g. write `A != B` to get "A != B".
+
+----
+
### <a name="How can I write fixed font text?"></a> How can I write fixed font text?
The quickest way is to enclose the text in equal signs:
The `pre` tag is standard HTML; `verbatim` is a special TWiki tag that forces text to fixed font mode, and also prevents other tags and TWiki shortcuts from being expanded.
-**NOTE:** VARIABLES are still Set within verbatim tags (this is a historical peculiarity)
+**_NOTE:_** VARIABLES are still Set within verbatim tags (this is a historical peculiarity)
+
+**_NOTE:_** The `verbatim` opening and closing tags are converted into `pre` tags; any HTML attributes (e.g., `class`, `id`) in the opening `verbatim` tag are included in the corresponding `pre` tag.
----
This is a simple and automatic way of including inline images. Simply write the URL of the image file, this will create the inline image for you. **_NOTE:_** The images must be [[accessible|Main/WebHome#ImgUpload]] as a URL.
-- **_You enter:_** ` %PUBURL%/TWiki/TWikiLogos/T-logo-80x15.gif logo.`<br />**_Result:_**  logo.
+- **_You enter:_** ` %PUBURL%/%SYSTEMWEB%/TWikiLogos/T-logo-80x15.gif logo.`<br />**_Result:_**  logo.
<a name="ImgUpload"></a> You can upload images directly to your server with FTP access. You can also [[attach|Main/FileAttachment]] image files to a topic - you could even create a dedicated image topic, like `ImageLibrary` - and then link to the images directly:
**2\. Using <img> tag**
-This is a manual process where you have more control over the rendering of the image. Use the <img> tag of HTML to include GIF, JPG and PNG files. **Note:** The rendering of the topic is faster if you include the `width` and `height` parameters that have the actual image size. <http://www.htmlhelp.com/reference/wilbur/special/img.html> has more on inline images.
+This is a manual process where you have more control over the rendering of the image. Use the <img> tag of HTML to include GIF, JPG and PNG files. **_Note:_** The rendering of the topic is faster if you include the `width` and `height` parameters that have the actual image size. <http://www.htmlhelp.com/reference/wilbur/special/img.html> has more on inline images.
-- **_You enter:_** ` <img src="%PUBURLPATH%/TWiki/TWikiLogos/T-logo-80x15.gif" width="80" height="15" border="0" alt="logo" /> logo.`<br />**_Result:_**<br /><img src="http://www.dementia.org/twiki//view/TWiki/TWikiLogos/T-logo-80x15.gif" width="80" height="15" alt="logo" /> logo.
+- **_You enter:_** ` <img src="%PUBURLPATH%/%SYSTEMWEB%/TWikiLogos/T-logo-80x15.gif" width="80" height="15" border="0" alt="logo" /> logo.`<br />**_Result:_**<br /><img src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiLogos/T-logo-80x15.gif" width="80" height="15" alt="logo" /> logo.
----
The code is the _hexadecimal RGB color code_, which is simply Red, Green and Blue values in hex notation (base 16, 0-F). For pure red, the RGB components are 255-0-0 - full red (255), no green or blue. That's FF-0-0 in hex, or `"#ff0000"` for Web page purposes. [[StandardColors]] lists basic colors.
----
+
+-- **_Contributors:_** TWiki:Main.PeterThoeny, TWiki:Main.MikeMannix
+# <a name="TWiki Text Formatting"></a> TWiki Text Formatting
+
+Working in TWiki is as easy as typing in text. You don't need to know HTML, though you can use it if you prefer. Links to topics are created automatically when you enter [[WikiWords]]. And TWiki shorthand gives you all the power of HTML with a simple coding system that takes no time to learn. It's all laid out below.
+
<div>
<ul>
<li><a href="#TWiki Text Formatting"> TWiki Text Formatting</a><ul>
<li><a href="#TWiki Editing Shorthand"> TWiki Editing Shorthand</a></li>
- <li><a href="#Using HTML"> Using HTML</a><ul>
- <li><a href="#Script tags"> Script tags</a></li>
- </ul>
- </li>
+ <li><a href="#Using HTML"> Using HTML</a></li>
<li><a href="#Hyperlinks"> Hyperlinks</a><ul>
<li><a href="#Internal Links"> Internal Links</a></li>
<li><a href="#External Links"> External Links</a></li>
</ul>
</div>
-# <a name="TWiki Text Formatting"></a> TWiki Text Formatting
-
-Working in TWiki is as easy as typing in text. You don't need to know HTML, though you can use it if you prefer. Links to topics are created automatically when you enter [[WikiWords]]. And TWiki shorthand gives you all the power of HTML with a simple coding system that takes no time to learn. It's all laid out below.
-
<a name="TWikiShorthand"></a>
## <a name="TWiki Editing Shorthand"></a> TWiki Editing Shorthand
## <a name="Using HTML"></a> Using HTML
-### <a name="Script tags"></a> Script tags
-
-You can use HTML `<script>` tags for your TWiki applications. However note that your TWiki administrator can disable `<script>` in topics, and may have chosen to do so for security considerations. TWiki markup and [[TWikiVariables]] are **not** expanded inside script tags.
-
## <a name="Hyperlinks"></a> Hyperlinks
Being able to create links without any special formatting is a core TWiki feature, made possible with [[WikiWords]] and inline URLs.
--- /dev/null
+## <a name="Time Specifications"></a> Time Specifications
+
+TWiki recognises the following formats for date/time strings. For all strings the time is optional.
+
+- 31 Dec 2001 - 23:59
+- 2001/12/31 23:59:59
+- 2001.12.31.23.59.59
+- 2001/12/31 23:59
+- 2001.12.31.23.59
+- `2001-12-31T23:59:59` - ISO 8601 format
+
+ISO dates may have a timezone specifier, either Z or a signed difference in hh:mm format. For example:
+
+- 2001-12-31T23:59:59+01:00
+- 2001-12-31T23:59Z
+
+## <a name="Time Intervals"></a> Time Intervals
+
+Some features of TWiki, such as searches, permit the specification of _time intervals_. A time interval is a period of time, such as "1337 to 1451" (the Hundred Years War) or "9th February 2005 to 26th March 2005" (the Christian season of Lent).
+
+The recognised format is a [[restricted|Main/WebHome#RestrictedInterpretation]] interpretation of the [ISO standard 8601](http://www.iso.ch/iso/en/prods-services/popstds/datesandtime.html).
+
+A string is accepted as a valid time interval string if it conforms to the following grammar:
+
+ interval ::= date
+ | date '/' date
+ | 'P' duration '/' date
+ | date '/' 'P' duration
+ ;
+
+ date ::= year ('-' month ('-' day ('T' hour (':' minute (':' second)))))
+ | '$today'
+ | '$now'
+ ;
+
+ duration ::= NUM unit
+ | duration NUM unit
+ ;
+
+ unit ::= 'y' | 'm' | 'w' | 'd' | 'h' | 'M' | 'S'
+
+ year, month, day, hour, minute, second ::= NUM
+
+An incompletely specified date will be completed by including as much time as possible.
+
+For example, if the start of a date range is specified by just a year, e.g. `1999/2006`, it will be interpreted as starting at January 1st 1999, at zero hours zero minutes zero seconds. Similarly for the end of the range; `2006` will be interpreted as the last second of 2006.
+
+If only one date is specified (e.g. the interval string is `1999`) it will be treated as if the same date were the start and the end i.e. `1999-1999`. Thus `1999` is interpreted as the whole of the year 1999.
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th bgcolor="#99CCCC"><strong> You write </strong></th>
+ <th bgcolor="#99CCCC"><strong> You mean </strong></th>
+ </tr>
+ <tr>
+ <td><code>2003</code></td>
+ <td> the whole year 2003 </td>
+ </tr>
+ <tr>
+ <td><code>2003-03-28T/2003-05-15</code></td>
+ <td> from March 28th to May 15th of the year 2003 </td>
+ </tr>
+ <tr>
+ <td><code>P3w/$today</code></td>
+ <td> three weeks until today </td>
+ </tr>
+ <tr>
+ <td> 2003-12-12 </td>
+ <td> 12th Dec 2003, from 0:00 to 23:59:59 </td>
+ </tr>
+ <tr>
+ <td> 2003 </td>
+ <td> any time in the year 2003 </td>
+ </tr>
+ <tr>
+ <td> 2003/P20w </td>
+ <td> the first 20 weeks of the year 2003 </td>
+ </tr>
+ <tr>
+ <td> P20w/2003 </td>
+ <td> the last 20 weeks of the year 2003 </td>
+ </tr>
+ <tr>
+ <td> $today </td>
+ <td> any second during the present day </td>
+ </tr>
+ <tr>
+ <td> P2d/$today </td>
+ <td> today and yesterday </td>
+ </tr>
+ <tr>
+ <td> P1d/$now </td>
+ <td> the last 24 hours </td>
+ </tr>
+ <tr>
+ <td> $now/P50y </td>
+ <td> the next 50 years </td>
+ </tr>
+</table>
+
+Further examples can be seen [here](http://www.iso.ch/iso/en/prods-services/popstds/datesandtime.html#three).
+
+<a name="RestrictedInterpretation"></a>
+
+### <a name="Limitations"></a> Limitations
+
+If you are entering a date at both ends of the time interval string, the end date must include all leading fields, even if these are the same as in the start date. This limitation forms a proper restriction to the ISO8601 standard. i.e. ISO8601 specifies that `2003-12-12/14` means 12th Dec 2003 00:00 to 14th Dec 2003 23:59:59. However this shorthand is not supported by TWiki and must be written as `2003-12-12/2003-12-14`
--- /dev/null
+# <a name="TinyMCEPlugin"></a><a name=" _TinyMCEPlugin"></a> TinyMCEPlugin
+
+%SHORTDESCRIPTION%
+
+
+
+<div>
+ <ul>
+ <li><a href="#Editor Notes"> Editor Notes</a></li>
+ <li><a href="#Installation Instructions"> Installation Instructions</a></li>
+ <li><a href="#Settings"> Settings</a></li>
+ <li><a href="#Configuring the buttons on TWiki"> Configuring the buttons on TWiki < 4.2.0</a></li>
+ <li><a href="#Plugin Info"> Plugin Info</a></li>
+ </ul>
+</div>
+
+This is an integration of the [<img src="http://tinymce.sourceforge.net/buttons/tinymce_button.png" width="80" height="15" alt="TinyMCE" />](http://tinymce.moxiecode.com?id=powered_by_tinymce_mini) WYSIWYG editor. This is great little editor, fast and highly functional, and supporting a wide range of browsers, including Firefox, IE and Safari. At the time of writing it doesn't work with Opera or Konqueror.
+
+The integration uses the TWiki:Plugins.WysiwygPlugin to translate text to and from a format that TinyMCE can edit.
+
+Unlike the other editor integrations in TWiki, which install "Word in a Browser" style editors, this plugin is able to swap out the _standard_ text areas in an edit and replace them with WYSIWYG editors. This means you get WYSIWYG editors for textareas in forms, as well as for the main text of the topic. It can also co-exist alongside other WYSIWYG editors, such as Kupu.
+
+The editor automatically "switches itself off" (i.e. reverts to the old text-only window) when editing topics that contain TWiki content it can't handle, such as complex TWiki variables.
+
+## <a name="Editor Notes"></a> Editor Notes
+
+The editor uses a translator module to convert from TWiki markup language (TML) to HTML and back. The translator converts special TWiki tags - such as %VARIABLES% - to plain text, and encloses them within HTML spans using a special style called `WYSIWYG_PROTECTED`. In this way the editor can detect text that is not meant to be HTML formatted. This style is _also_ used to protect special text you enter into the editor from being interpreted when the topic is translated back into TML. If you want to add any special TWiki features that are sensitive to formatting, such as `Set` statements, then you have to format those regions using 'Protect on save' or 'Protect forever'.
+
+## <a name="Installation Instructions"></a> Installation Instructions
+
+**_NOTES:_**
+
+- This plugin comes pre-installed on TWiki 4.2.0. You should only need to re-install if there is an upgrade to the plugin.
+- It requires the very latest revision of [[WysiwygPlugin]]. It will **not** work with the version shipped with TWiki 4.1.2.
+- When installed, it **replaces** the old "textarea" editor. If you want to maintain access to the old editor from the standard screens, follow the instructions under [[Configuring the buttons on TWiki < 4.2.0|Main/WebHome#InstallingOnOldTWikis]].
+
+First follow the installation instructions to install the Plugin:
+
+You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.
+
+Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.
+
+- If you have TWiki 4.2 or later, you can install from the `configure` interface (Go to Plugins->Find More Extensions)
+ - See the [installation supplement](http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement) on TWiki.org for more information.
+- If you have any problems, then you can still install manually from the command-line:
+ 1. Download one of the `.zip` or `.tgz` archives
+ 2. Unpack the archive in the root directory of your TWiki installation.
+ 3. Run the installer script ( `perl <module>_installer` )
+ 4. Run `configure` and enable the module, if it is a plugin.
+ 5. Repeat for any missing dependencies.
+- If you are **still** having problems, then instead of running the installer script:
+ 1. Make sure that the file permissions allow the webserver user to access all files.
+ 2. Check in any installed files that have existing `,v` files in your existing install (take care **not** to lock the files when you check in)
+ 3. Manually edit LocalSite.cfg to set any configuration variables.
+
+<div class="twikiAlert">%X% WARNING: SYSTEMWEB is not defined in this TWiki. Please add these definitions to your [[Main/TWikiPreferences]], if they are not already there:<br /><pre> * Set SYSTEMWEB = %TWIKIWEB%<br /> * Set USERSWEB = %MAINWEB%</pre></div>
+
+- **Enable** the [[WysiwygPlugin]] in `configure`.
+- **Enable** the [[TinyMCEPlugin]] in `configure`.
+- **Click** on edit of any topic.
+
+## <a name="Settings"></a> Settings
+
+You can override this setting by defining TINYMCEPLUGIN\_DEBUG to enable some simple debug features.
+
+- Set DEBUG = 0
+
+This setting contains all the options passed to the [[TinyMCE]] editor on startup. For a full explanation of the available options, and guidance on reconfiguring [[TinyMCE]], see the [Moxicode TinyMCE Wiki](http://wiki.moxiecode.com/index.php/TinyMCE:Configuration). Note the inclusion of the Pattern Skin standard CSS files in the `content_css` setting.
+
+ * Set INIT = mode : "exact",
+ save_on_tinymce_forms: true,
+ elements : "text",
+ cleanup : true,
+ theme : "advanced",
+ convert_urls : true,
+ relative_urls : false,
+ remove_script_host : false,
+ setupcontent_callback : TWikiTiny.setUpContent,
+ urlconverter_callback : "TWikiTiny.convertLink",
+ hide_instance_callback : TWikiTiny.switchToRaw,
+ show_instance_callback : TWikiTiny.switchToWYSIWYG,
+ twikipuburl_callback : "TWikiTiny.convertPubURL",
+ save_callback : "TWikiTiny.saveCallback",
+ %IF{"$TINYMCEPLUGIN_DEBUG" then="debug:true,"}%
+ plugins : "table,searchreplace,autosave,paste,twikibuttons,twikiimage%IF{"$TINYMCEPLUGIN_DEBUG" then=",devkit"}%",
+ twiki_secret_id : "%WYSIWYG_SECRET_ID%",
+ twiki_vars : { PUBURLPATH : "%PUBURLPATH%", PUBURL : "%PUBURL%", WEB : "%WEB%", TOPIC : "%TOPIC%", ATTACHURL : "%ATTACHURL%", ATTACHURLPATH : "%ATTACHURLPATH%", VIEWSCRIPTURL : "%SCRIPTURL{view}%", SCRIPTSUFFIX: "%SCRIPTSUFFIX%", SCRIPTURL : "%SCRIPTURL%" },
+ theme_advanced_toolbar_align : "left",
+ twikibuttons_formats : [
+ { name: "Normal", el: "", style: null },
+ { name: "Heading 1", el: "h1", style: false },
+ { name: "Heading 2", el: "h2", style: false },
+ { name: "Heading 3", el: "h3", style: false },
+ { name: "Heading 4", el: "h4", style: false },
+ { name: "Heading 5", el: "h5", style: false },
+ { name: "Heading 6", el: "h6", style: false },
+ { name: "VERBATIM", el: "pre", style: "TMLverbatim" },
+ { name: "LITERAL", el: "span", style: "WYSIWYG_LITERAL" },
+ { name: "Protect on save", el: null, style: "WYSIWYG_PROTECTED" },
+ { name: "Protect forever", el: null, style: "WYSIWYG_STICKY" }
+ ],
+ paste_create_paragraphs : true,
+ paste_create_linebreaks : false,
+ paste_convert_middot_lists : true,
+ paste_convert_headers_to_strong : false,
+ paste_remove_spans: true,
+ paste_remove_styles: true,
+ paste_strip_class_attributes: "all",
+ theme_advanced_buttons1 : "twikiformat,separator,bold,italic,tt,colour,removeformat,separator,bullist,numlist,outdent,indent,separator,link,unlink,anchor,separator,attach,image,charmap,hr,separator,undo,redo,separator,search,replace",
+ theme_advanced_buttons2: "tablecontrols,separator,code,hide",
+ theme_advanced_buttons3: "",
+ theme_advanced_toolbar_location: "top",
+ theme_advanced_resize_horizontal : false,
+ theme_advanced_resizing : true,
+ theme_advanced_path: false,
+ theme_advanced_statusbar_location : "bottom",
+ content_css : "%PUBURLPATH%/%TWIKIWEB%/TinyMCEPlugin/wysiwyg%IF{"$TINYMCEPLUGIN_DEBUG" then="_src"}%.css,%PUBURLPATH%/%TWIKIWEB%/TWikiTemplates/base.css,%TWIKISTYLEURL%,%TWIKICOLORSURL%"
+
+- Additional settings for specific browsers.
+ - Warning: if you enable `paste_auto_cleanup_on_paste then it automatically implies =past_use_dialog` on all non-MSIE browsers.
+ - Set INIT\_MSIE = paste\_auto\_cleanup\_on\_paste : true
+ - Set INIT\_OPERA =
+ - Set INIT\_GECKO =
+ - Set INIT\_SAFARI =
+
+You can override these settings in the same way as any other TWiki variable, by setting e.g. `TINYMCEPLUGIN_INIT` in the site, web or topic preferences. You are **not** recommended to edit the setting here.
+
+- You can **disable** the plugin in any web or topic, or for any specific user, by setting the `TINYMCEPLUGIN_DISABLE` variable to 1.
+- Some browsers don't support TinyMCE. You can prevent the editor from being invoked on these browsers by setting `TINYMCEPLUGIN_BAD_BROWSERS` to a regular expression that matches the user-agent string for any broken browsers. The default is `(?i-xsm:Konqueror|Opera)`.
+
+<a name="InstallingOnOldTWikis"></a>
+
+## <a name="Configuring the buttons on TWiki"></a> Configuring the buttons on TWiki < 4.2.0
+
+When installed on TWiki versions before 4.2.0, this plugin **replaces** the old textarea editor with the TinyMCE editor. The shock of this change can be too much for some older contributors, so we have written instructions for reconfiguring your templates in TWiki:Plugins.TinyMCEFrequentlyAskedQuestions.
+
+## <a name="Plugin Info"></a> Plugin Info
+
+Another great TWiki extension from the [ **WikiRing** ](http://wikiring.com) - working together to improve your wiki experience!
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <td align="right"> Plugin Author(s): </td>
+ <td> TWiki:Main.CrawfordCurrie </td>
+ </tr>
+ <tr>
+ <td align="right"> Plugin Version: </td>
+ <td> 16268 (22 Jan 2008) </td>
+ </tr>
+ <tr>
+ <td align="right"> Copyright: </td>
+ <td> © 2007 Crawford Currie <a href="http://c-dot.co.uk" target="_top">http://c-dot.co.uk</a></td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td> This package also includes the complete sources for version 2.1.1.1 of the TinyMCE editor </td>
+ </tr>
+ <tr>
+ <td align="right"> License: </td>
+ <td><a href="http://www.gnu.org/licenses/gpl.html" target="_top">GPL (Gnu General Public License)</a></td>
+ </tr>
+ <tr>
+ <td align="right"> Change History: </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td> 20 Dec 2007 </td>
+ <td> TWikibug:Item5047: disable save and preview during page load TWikibug:Item5111: make the entry in the format menu sensitive to where the cursor is TWikibug:Item5022: made TT font size same as verbatim. Had to add a new style to do it, as TMCE didn't want to play with TT or CODE tags. </td>
+ </tr>
+ <tr>
+ <td align="right"> 19 Nov 2007 </td>
+ <td> TWikibug:Item4742: auto-disable if Wysiwyg is not enabled TWikibug:Item4820: validate mandatory fields on save TWikibug:Item4747: add <sticky> TWikibug:Item4811: noautolink <strong>looks</strong> like an HTML construct but in fact is not; the tag is infact an "on-off" switch and does not imply any HTML structure, so cannot be converted to a DIV or a span, so has to be removed. TWikibug:Item4817: added typewriter text button TWikibug:Item4850: added font colour controls TWikibug:Item4645: added attachment management features TWikibug:Item4945: added switch to raw and back </td>
+ </tr>
+ <tr>
+ <td align="right"> 16 Sep 2007 </td>
+ <td> TWikibug:Item4630: polished up the way the secret string is done, to ensure synch between perl and JS. TWikibug:Item4622: added UTF-8 handling steps that fixup malformed UTF8 strings before presenting them to the editor (saves Moz) and stops the editor passing them back to TWiki (saves IE). TWikibug:Item4603: added the draft help, so we can at least build the beta without the nasty warning </td>
+ </tr>
+ <tr>
+ <td align="right"> 13 Sep 2007 </td>
+ <td> TWikibug:Item4613 fixed navigate-away prompt when unchanged TWikibug:Item4583 TWikibug:Item4604 TWikibug:Item4614 TWikibug:Item4616 A clutch of issues caused by use of the wrong encoding function when passing UTF8 parameters to REST using [[Main/XMLHttpRequest]]. </td>
+ </tr>
+ <tr>
+ <td align="right"> 12 Sep 2007 </td>
+ <td> TWikibug:Item4604 Converted to REST call for content conversion, to provide safe callback if JS is disabled in the browser TWikibug:Item4583 relaxed regex to try and make it work for UTF-8 topic names </td>
+ </tr>
+ <tr>
+ <td align="right"> 11 Sep 2007 </td>
+ <td> TWikibug:Item4535 refinements to link handling to improve topic name recognition </td>
+ </tr>
+ <tr>
+ <td align="right"> 7 Sep 2007 </td>
+ <td> TWikibug:Item4503 excess empty lines TWikibug:Item4486 no toc headers with unofficial syntax TWikibug:Item4560: empty lines lost TWikibug:Item4566: corrupted table on save </td>
+ </tr>
+ <tr>
+ <td align="right"> 6 Sep 2007 </td>
+ <td> TWikibug:Item4557 added missing files to package </td>
+ </tr>
+ <tr>
+ <td align="right"> 4 Sep 2007 </td>
+ <td> TWikibug:Item4534 TWikibug:Item4535 fixed </td>
+ </tr>
+ <tr>
+ <td align="right"> 14679 </td>
+ <td> TWikibug:Item4481 TWikibug:Item4524 fixed </td>
+ </tr>
+ <tr>
+ <td align="right"> 14668 </td>
+ <td> Bugfixes and refinements done as part of 4.2 release </td>
+ </tr>
+ <tr>
+ <td align="right"> 14543 </td>
+ <td> Added PROTECTED style, to allow protection of special text. Disable on unsupported browsers (untested) </td>
+ </tr>
+ <tr>
+ <td align="right"> 14538 </td>
+ <td> First release </td>
+ </tr>
+ <tr>
+ <td align="right"> Dependencies: </td>
+ <td>
+ <table border="1">
+ <tr>
+ <th>Name</th>
+ <th>Version</th>
+ <th>Description</th>
+ </tr>
+ <tr>
+ <td align="left">TWiki::Plugins::BehaviourContrib</td>
+ <td align="left">>=15357</td>
+ <td align="left">Javascript module</td>
+ </tr>
+ <tr>
+ <td align="left">TWiki::Plugins::WysiwygPlugin</td>
+ <td align="left">>=14523</td>
+ <td align="left">Translator module</td>
+ </tr>
+ </table>
+ </td>
+ </tr>
+ <tr>
+ <td align="right"> Plugin Home: </td>
+ <td><a href="http://twiki.org/cgi-bin/view/Plugins/TinyMCEPlugin" target="_top">http://twiki.org/cgi-bin/view/Plugins/TinyMCEPlugin</a></td>
+ </tr>
+ <tr>
+ <td align="right"> Feedback: </td>
+ <td><a href="http://twiki.org/cgi-bin/view/Plugins/TinyMCEPluginDev" target="_top">http://twiki.org/cgi-bin/view/Plugins/TinyMCEPluginDev</a></td>
+ </tr>
+ <tr>
+ <td align="right"> Appraisal: </td>
+ <td><a href="http://twiki.org/cgi-bin/view/Plugins/TinyMCEPluginAppraisal" target="_top">http://twiki.org/cgi-bin/view/Plugins/TinyMCEPluginAppraisal</a></td>
+ </tr>
+</table>
+
+Many thanks to the following sponsors for supporting this work:
+
+- [ILOG](http://ilog.fr)
+- [Carrier Corporation](http://www.carrier.com)
+- [TWIKI.NET](http://twiki.net)
--- /dev/null
+# <a name="TinyMCE Editor Help Summary"></a><a name=" _TinyMCE Editor Help Summary"></a> TinyMCE Editor Help Summary
+
+<table>
+ <tr>
+ <td rowspan="3" style="vertical-align: top; background-color: #f9f9f9" width="100px">
+ <p>
+ </p><select><option>Normal</option>
+ <option>Heading 1</option>
+ <option>Heading 2</option>
+ <option>Heading 3</option>
+ <option>Heading 4</option>
+ <option>Heading 5</option>
+ <option>Heading 6</option>
+ <option>VERBATIM</option>
+ <option>LITERAL</option>
+ <option>Protect on save</option>
+ <option>Protect forever</option></select></td>
+ <td rowspan="3" style="vertical-align: top">
+ <ul>
+ <li><code><b>Normal</b></code> - Normal text style </li>
+ <li><code><b>Heading 1-6</b></code> - Headings. 1 is largest </li>
+ <li><code><b>VERBATIM</b></code> - Text is shown in monospace with line breaks.%BR% <em>Wraps <verbatim> tags around the selected text. No TWiki Variables are interpreted inside verbatim tags</em></li>
+ <li><code><b>LITERAL</b></code> - Styled content is saved exactly as it appears in the editor.%BR% <em>Saves the selected content as raw HTML and wraps it in <literal> tags</em></li>
+ <li><code><b>Protect on save</b></code> - Prevent any change to the selected text when the edit is saved.%BR% <em>Use this to save advanced TWiki Variables where you do not want the Wysiwyg editor to modify the text during save</em></li>
+ <li><code><b>Protect forever</b></code> - Content is saved exactly as it is typed, and the protection is still there in future edit sessions.%BR% <em>Content is wrapped in <sticky> tags</em></li>
+ </ul>
+ </td>
+ <td style="vertical-align: top; background-color: #f9f9f9"><img alt="indent" src="http://www.dementia.org/twiki//view/%WEB%/TinyMCEPlugin/tinymce/jscripts/tiny_mce/themes/advanced/images/indent.gif" /> <img alt="outdent" src="http://www.dementia.org/twiki//view/%WEB%/TinyMCEPlugin/tinymce/jscripts/tiny_mce/themes/advanced/images/outdent.gif" /></td>
+ <td style="vertical-align: top">
+ <ul>
+ <li> If the cursor is in a list item, change the indent </li>
+ <li> Otherwise mark text with <BLOCKQUOTE> tags (the default TWiki skin shows blockquotes indented with a blue background)</li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td style="vertical-align: top; background-color: #f9f9f9"><img alt="link" src="http://www.dementia.org/twiki//view/%WEB%/TinyMCEPlugin/tinymce/jscripts/tiny_mce/themes/advanced/images/link.gif" /> <img alt="unlink" src="http://www.dementia.org/twiki//view/%WEB%/TinyMCEPlugin/tinymce/jscripts/tiny_mce/themes/advanced/images/unlink.gif" /></td>
+ <td style="vertical-align: top">
+ <ul>
+ <li> Links can either point to a URL or to the name of a TWiki topic. </li>
+ <li> E.g. <code>http://twiki.org</code>, <code>TopicNames</code>, <code>Webname.TopicNames</code>, or <code>Webname.Subweb.WebName</code>. </li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ <td style="vertical-align: top; background-color: #f9f9f9"><img alt="anchor" src="http://www.dementia.org/twiki//view/%WEB%/TinyMCEPlugin/tinymce/jscripts/tiny_mce/themes/advanced/images/anchor.gif" /></td>
+ <td style="vertical-align: top">
+ <ul>
+ <li> An anchor is a hidden mark you can use to link to a certain part of a topic, e.g a heading or a paragraph. An anchor must be a WikiWord. </li>
+ </ul>
+ </td>
+ </tr>
+ <tr>
+ </tr>
+ <tr>
+ <td colspan="2" width="50%">
+ <h3><a name="Setting a TWiki variable"></a> Setting a TWiki variable </h3>
+ <ol>
+ <li> Create a list item using the toolbar button</li>
+ <li> In the list item, type <code>Set NAME = value</code></li>
+ <li> Select the value, and assign the <code><b>Protect on save</b></code> style to it (only required if the value contains any TWiki Markup Language or if you style it e.g. to add bold, or if it's sensitive to the number of spaces) </li>
+ </ol>
+ </td>
+ <td colspan="2">
+ <h3><a name="Using a TWiki Variable"></a> Using a TWiki Variable </h3>
+ <ul>
+ <li> Just type it in. When the topic is saved, what you type will be saved just as you wrote it. </li>
+ <li> If any part of your variable parameters is sensitive to spacing, then select the entire TWiki variable and assign the <code><b>PROTECTED</b></code> style to it before you save. </li>
+ </ul>
+ </td>
+ </tr>
+</table>
+
+### <a name="Editing the raw text instead of"></a><a name="Editing the raw text instead of "></a> Editing the raw text instead of Wysiwyg
+
+- Select  , or use the _Raw Edit_ link in the bottom action bar.
## <a name="Summary of Contents"></a> Summary of Contents
-- Set on `TWikiTip` topics providing brief lessons on TWiki features. See [[TWikiTips]].
-- Set of topics for creating and managing `TWikiTipXXX` topics. See [[TWikiTipsOfTheDayAdmin]].
+- Set on `TWikiTip` topics providing brief lessons on TWiki features. See %SYSTEMWEB%.TWikiTips.
+- Set of topics for creating and managing `TWikiTipXXX` topics. See %SYSTEMWEB%.TWikiTipsOfTheDayAdmin.
## <a name="Detailed Documentation"></a> Detailed Documentation
-- See [[TWikiTipsOfTheDayAdmin]] for instructions on managing and displaying tips.
-- See [[TWikiTipsOfTheDayAddNew]] for instructions for adding new custom tips.
+- See %SYSTEMWEB%.TWikiTipsOfTheDayAdmin for instructions on managing and displaying tips.
+- See %SYSTEMWEB%.TWikiTipsOfTheDayAddNew for instructions for adding new custom tips.
## <a name="Settings"></a> Settings
-This extension requires no settings. See [[TWikiTipsOfTheDayAdmin]] for administration details.
+This extension requires no settings. See %SYSTEMWEB%.TWikiTipsOfTheDayAdmin for administration details.
- One line description:
- Set SHORTDESCRIPTION = Displays rotating list of "TWiki Tip-of-the-day"
</tr>
</table>
-**_Related Topics:_** [[TWikiPreferences]]
+**_Related Topics:_** %SYSTEMWEB%.TWikiPreferences
-- TWiki:Main.PeterThoeny - 2007-01-04
It is recommended to use the TwistyPlugin as it eases the deployment and use of this contrib.
-This Contrib should work in all versions of TWiki. It has been tested against [[TWiki 3|TWiki:Codev/CairoRelease]] and [[TWiki 4|TWiki:Codev/DakarRelease]].
+This Contrib should work with [[TWiki 4|TWiki:Codev/DakarRelease]] and newer.
<div><span>On this page:</span><ul>
<li><a href="#Usage examples"> Usage examples</a><ul>
## <a name="Settings"></a> Settings
- Set SHORTDESCRIPTION = Twisty section javascript library to open/close content dynamically
-- Set STUB = TWiki::Contrib::TwistyContrib
+
+You can also set the global TWiki variable TWISTYCONTRIB\_DEBUG to 1 to make the contrib use uncompressed javascript sources, in the event of problems.
## <a name="Installation Instructions"></a> Installation Instructions
-- Download the ZIP file from the Plugin web (see below)
-- Unzip <code>**%TOPIC%.zip**</code> in your ($TWIKI\_ROOT) directory. Content: <table border="1" cellpadding="0" cellspacing="0">
- <tr>
- <th bgcolor="#99CCCC"><strong> File: </strong></th>
- <th bgcolor="#99CCCC"><strong> Description: </strong></th>
- </tr>
- <tr>
- <td><code><b>data/TWiki/TwistyContrib.txt</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>lib/TWiki/Contrib/TwistyContrib.pm</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/TwistyContrib/twist.css</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/TwistyContrib/twist.js</b></code></td>
- <td> </td>
- </tr>
- <tr>
- <td><code><b>pub/TWiki/TwistyContrib/twist.compressed.js</b></code></td>
- <td> </td>
- </tr>
-</table>
+%\*INSTALL\_INSTRUCTIONS%
-- Optionally, run <code>**%TOPIC%\_installer**</code> to automatically check and install other TWiki modules that this module depends on. You can also do this step manually.
-- Alternatively, manually make sure the dependencies listed in the table below are resolved. <table border="1">
- <tr>
- <th>Name</th>
- <th>Version</th>
- <th>Description</th>
- </tr>
- <tr>
- <td align="left">TWiki::Plugins::BehaviourContrib</td>
- <td align="left">>=1.000</td>
- <td align="left">Required</td>
- </tr>
-</table>
+- TwistyContrib uses these header includes:
+ <style type="text/css" media="all">
+ @import url("%PUBURL%/%TWIKIWEB%/TwistyContrib/twist.css");
+ </style>
+ <script type="text/javascript" src="%PUBURL%/%TWIKIWEB%/TWikiJavascripts/twikilib.js"></script>
+ <script type="text/javascript" src="%PUBURL%/%TWIKIWEB%/TWikiJavascripts/twikiPref.js"></script>
+ <script type="text/javascript" src="%PUBURL%/%TWIKIWEB%/TWikiJavascripts/twikiCSS.js"></script>
+ <script type="text/javascript" src="%PUBURL%/%TWIKIWEB%/BehaviourContrib/behaviour.js"></script>
+ <script type="text/javascript" src="%PUBURL%/%TWIKIWEB%/TwistyContrib/twist.js"></script>
## <a name="Contrib Info"></a> Contrib Info
<table border="1" cellpadding="0" cellspacing="0">
<tr>
- <td> Authors: </td>
- <td> JavaScript created by TWiki:Main.SamHasler, Contrib packaged by TWiki:Main.RafaelAlvarez </td>
+ <td align="right"> Authors: </td>
+ <td> JavaScript written by TWiki:Main.ArthurClemens; Contrib packaged by TWiki:Main.RafaelAlvarez; original JavaScript written by TWiki:Main.SamHasler. </td>
</tr>
<tr>
- <td> Copyright ©: </td>
- <td> 2005 Sam Hasler and Rafael Alvarez, 2006 Arthur Clemens </td>
+ <td align="right"> Copyright ©: </td>
+ <td> 2005 Sam Hasler and Rafael Alvarez; 2006,2007 Arthur Clemens </td>
</tr>
<tr>
- <td> License: </td>
+ <td align="right"> License: </td>
<td><a href="http://www.gnu.org/copyleft/gpl.html" target="_top">GPL</a></td>
</tr>
<tr>
- <td> Dependencies: </td>
+ <td align="right"> Dependencies: </td>
<td>
<table border="1">
<tr>
</td>
</tr>
<tr>
- <td> 25 Oct 2006 </td>
+ <td align="right"> Plugin Version: </td>
+ <td> 20 Jun 2007 (version 1.4.1) </td>
+ </tr>
+ <tr>
+ <td align="right"> Version: </td>
+ <td> 15675 (22 Jan 2008) </td>
+ </tr>
+ <tr>
+ <td align="right"> Change History: </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td align="right"> 20 Jun 2007 </td>
+ <td> 1.4 Arthur Clemens - Updated script so [[Main/TwistyPlugin]] can work without extra javascript 'init' calls. </td>
+ </tr>
+ <tr>
+ <td align="right"> 18 Jun 2007 </td>
+ <td> 1.3 Arthur Clemens - Updated with TWiki 4 JavaScript files. </td>
+ </tr>
+ <tr>
+ <td align="right"> 25 Oct 2006 </td>
<td> 1.2 Arthur Clemens - Updated JavaScript to support TwistyPlugin version 1.2 </td>
</tr>
<tr>
- <td> 26 Sep 2006 </td>
+ <td align="right"> 26 Sep 2006 </td>
<td> 1.010 Arthur Clemens - Complete JavaScript rewrite </td>
</tr>
<tr>
- <td> 12 Sep 2005 </td>
+ <td align="right"> 12 Sep 2005 </td>
<td> 1.000 First Version </td>
</tr>
<tr>
- <td> Home: </td>
+ <td align="right"> Home: </td>
<td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%</a></td>
</tr>
<tr>
- <td> Feedback: </td>
+ <td align="right"> Feedback: </td>
<td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev</a></td>
</tr>
<tr>
- <td> Appraisal: </td>
+ <td align="right"> Appraisal: </td>
<td><a href="http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal" target="_top">http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal</a></td>
</tr>
</table>
- use a span or div for the content
- set a class for the content span or div
-Twisty has a fallback mechanism in case JavaScript is not available: all content is displayed and the control buttons are hidden. Unless parameter `noscript="hide"` is used to specifically set the content to hide.
-
-<div><strong>What's new in version 1.2:</strong><ul>
- <li> New variables to set default values: <code>TWISTYSHOWLINK</code>, <code>TWISTYHIDELINK</code>, <code>TWISTYMODE</code>, <code>TWISTYREMEMBER</code></li>
- <li> Property <code>id</code> is no longer required as this is automatically set (still recommended in some cases with <code>remember="on"</code>) </li>
- <li> Property value <code>remember="off"</code> will clear a previously stored setting </li>
- <li> New properties <code>prefix</code> and <code>suffix</code></li>
- <li> JavaScript to collapse or expand all Twisties on the page </li>
- </ul>
-</div>
+Twisty has a fallback mechanism in case JavaScript is not available: all content is displayed and the control buttons are hidden.
<div><span>On this page:</span><ul>
<li><a href="#Usage examples"> Usage examples</a><ul>
<li><a href="#Triad"> Triad</a></li>
- <li><a href="#Working Twisty"> Working Twisty</a></li>
+ <li><a href="#Shorthand"> Shorthand</a></li>
<li><a href="#Twisty with icons"> Twisty with icons</a></li>
<li><a href="#Make it remember"> Make it remember</a></li>
<li><a href="#Make it obey"> Make it obey</a></li>
<li><a href="#All on, all off"> All on, all off</a></li>
</ul>
</li>
+ <li><a href="#Special syntax: format tokens"> Special syntax: format tokens</a></li>
<li><a href="#Syntax"> Syntax</a><ul>
<li><a href="#TWISTY"> TWISTY</a></li>
<li><a href="#ENDTWISTY"> ENDTWISTY</a></li>
(there may be other things between buttons and content)
%TWISTYTOGGLE{}% my content %ENDTWISTYTOGGLE%
-### <a name="Working Twisty"></a> Working Twisty
+### <a name="Shorthand"></a> Shorthand
The Twisty triad is conveniently packed into shorthand `%TWISTY{some parameters}% Collapsing content %ENDTWISTY%`:
- %TWISTY{showlink="Show..." hidelink="Hide"}%
+ %TWISTY{}%
my twisty content
%ENDTWISTY%
-It will look like this:
+Will generate:
-<span><span>[<span>Show...</span>](#)</span><span>[<span>Hide</span>](#)</span></span>
+<span><span>[<span></span>](#)</span><span>[<span></span>](#)</span></span>
-<div style="display: inline"><span id="twistyId1toggle"> my twisty content </span></div>
+<div style="display: inline"><span id="twistyId1toggle"> %GREEN% my twisty content %ENDCOLOR% </span></div>
+
+You may have noticed that no parameters are passed to `%TWISTY{}%` but the show and hide links _do_ have text! The default values are fetched from plugin settings `TWISTYSHOWLINK` and `TWISTYHIDELINK`, see [[Plugin Settings|Main/WebHome#PluginSettings]] below.
### <a name="Twisty with icons"></a> Twisty with icons
-We will use `mode="div"` to put the collapsing content below the button.
+We will use `mode="div"` to put the collapsing content below the button (the default mode is `"span"`).
- %TWISTY{mode="div" showlink="Show..." hidelink="Hide"
+ %TWISTY{
+ mode="div"
+ showlink="Show..."
+ hidelink="Hide"
showimgleft="%ICONURLPATH{toggleopen-small}%"
- hideimgleft="%ICONURLPATH{toggleclose-small}%"}%
+ hideimgleft="%ICONURLPATH{toggleclose-small}%"
+ }%
my twisty content
%ENDTWISTY%
<span><span>[<span>Show...</span>](#)</span><span>[<span>Hide</span>](#)</span></span>
<div style="display: inline">
- <div id="twistyId2toggle"> my twisty content </div>
+ <div id="twistyId2toggle"> %GREEN% my twisty content %ENDCOLOR% </div>
</div>
To put icons at the right side, write
- %TWISTY{mode="div" showlink="Show " hidelink="Hide "
+ %TWISTY{
+ mode="div"
+ showlink="Show "
+ hidelink="Hide "
showimgright="%ICONURLPATH{toggleopen-small}%"
- hideimgright="%ICONURLPATH{toggleclose-small}%"}%
+ hideimgright="%ICONURLPATH{toggleclose-small}%"
+ }%
my twisty content
%ENDTWISTY%
<span><span>[<span>Show </span>](#)</span><span>[<span>Hide </span>](#)</span></span>
<div style="display: inline">
- <div id="twistyId3toggle"> my twisty content </div>
+ <div id="twistyId3toggle"> %GREEN% my twisty content %ENDCOLOR% </div>
</div>
### <a name="Make it remember"></a> Make it remember
To store the last state in a TWIKIPREF cookie, add the parameter `remember="on"`.%BR% To test this, reload the page after toggling.
- %TWISTY{showlink="Show..." hidelink="Hide" remember="on"}%
+ %TWISTY{
+ showlink="Show..."
+ hidelink="Hide"
+ remember="on"
+ }%
my twisty content
%ENDTWISTY%
<span><span>[<span>Show...</span>](#)</span><span>[<span>Hide</span>](#)</span></span>
-<div style="display: inline"><span id="twistyId4toggle"> my twisty content </span></div>
+<div style="display: inline"><span id="twistyId4toggle"> %GREEN% my twisty content %ENDCOLOR% </span></div>
If a Twisty state has been stored in a TWIKIPREF cookie before, it can be cleared by using `remember="off"`:
- %TWISTY{showlink="Show..." hidelink="Hide" remember="off"}%
+ %TWISTY{
+ showlink="Show..."
+ hidelink="Hide"
+ remember="off"
+ }%
my twisty content
%ENDTWISTY%
<span><span>[<span>Show...</span>](#)</span><span>[<span>Hide</span>](#)</span></span>
-<div style="display: inline"><span id="twistyId5toggle"> my twisty content </span></div>
+<div style="display: inline"><span id="twistyId5toggle"> %GREEN% my twisty content %ENDCOLOR% </span></div>
**NOTE:** Twisty ids are generated automatically. If you need control over exactly _which_ Twisty should be remembered, add the parameter `id`:
- %TWISTY{id="currentCustomerList" showlink="Show..." hidelink="Hide" remember="on"}%
+ %TWISTY{
+ id="currentCustomerList"
+ showlink="Show..."
+ hidelink="Hide"
+ remember="on"
+ }%
my customer list
%ENDTWISTY%
+Note that `id` sets a sitewide cookie. To create a unique id, add topic or web variables:
+
+ id="%WEB%_%TOPIC%_currentCustomerList"
+
### <a name="Make it obey"></a> Make it obey
To let the Twisty start with its content folded open, add parameter `start="show"`.
- %TWISTY{showlink="Show..." hidelink="Hide" start="show"}%
+ %TWISTY{
+ showlink="Show..."
+ hidelink="Hide"
+ start="show"
+ }%
my twisty content
%ENDTWISTY%
<span><span>[<span>Show...</span>](#)</span><span>[<span>Hide</span>](#)</span></span>
-<div style="display: inline"><span id="twistyId6toggle"> my twisty content </span></div>
+<div style="display: inline"><span id="twistyId6toggle"> %GREEN% my twisty content %ENDCOLOR% </span></div>
Likewise use `start="hide"` to start with hidden content.
- %TWISTY{showlink="Show..." hidelink="Hide" start="hide"}%
+ %TWISTY{
+ showlink="Show..."
+ hidelink="Hide
+ start="hide"
+ }%
my twisty content
%ENDTWISTY%
-<span><span>[<span>Show...</span>](#)</span><span>[<span>Hide</span>](#)</span></span>
+<span><span>[<span>Show...</span>](#)</span><span>[<span>Hide start=</span>](#)</span></span>
-<div style="display: inline"><span id="twistyId7toggle"> my twisty content </span></div>
+<div style="display: inline"><span id="twistyId7toggle"> %GREEN% my twisty content %ENDCOLOR% </span></div>
### <a name="Make it obey only the first time"></a> Make it obey only the first time
To let the Twisty start with its content folded open the first time the visitor sees the Twisty, add the parameter `firststart="show"`. If `remember="on"` is used, subsequential visits to the page will display the Twisty according the cookie setting.
- %TWISTY{showlink="Show..." hidelink="Hide" firststart="show"}%
+ %TWISTY{
+ showlink="Show..."
+ hidelink="Hide"
+ firststart="show"
+ }%
my twisty content
%ENDTWISTY%
<span><span>[<span>Show...</span>](#)</span><span>[<span>Hide</span>](#)</span></span>
-<div style="display: inline"><span id="twistyId8toggle"> my twisty content </span></div>
+<div style="display: inline"><span id="twistyId8toggle"> %GREEN% my twisty content %ENDCOLOR% </span></div>
### <a name="Other use: hide interface parts"></a><a name="Other use: hide interface parts "></a> Other use: hide interface parts in case of no JavaScript
Put the "JavaScript content" in an almost bare bones Twisty. Write `showlink="" hidelink=""` to not display any default link texts.
- %TWISTY{link="" noscript="hide" start="show"}%
+ %TWISTY{
+ link=""
+ noscript="hide"
+ start="show"
+ }%
<input type="submit" class="twikiButton" value="You surely have !JavaScript" />
%ENDTWISTY%
This code will show the button when JavaScript is off:
- %TWISTY{link="" start="show"}%
- <input type="submit" class="twikiButton" value="You surely have !JavaScript" />
+ %TWISTY{
+ link=""
+ start="show"
+ }%
+ <input type="submit" class="twikiButton" value="You might have !JavaScript" />
%ENDTWISTY%
<span><span>[<span></span>](#)</span><span>[<span></span>](#)</span></span>
-<div style="display: inline"><span id="twistyId10toggle"><input type="submit" value="You surely have JavaScript" /> </span></div>
+<div style="display: inline"><span id="twistyId10toggle"><input type="submit" value="You might have JavaScript" /> </span></div>
### <a name="Styling the Twisty"></a> Styling the Twisty
Use parameter `class` to style the content div or class:
- %TWISTY{mode="div" showlink="Show..." hidelink="Hide" class="twikiHelp"}%
+ %TWISTY{
+ mode="div"
+ showlink="Show..."
+ hidelink="Hide"
+ class="twikiHelp"
+ }%
my twisty content
%ENDTWISTY%
Generates: %BR% <span><span>[<span>Show...</span>](#)</span><span>[<span>Hide</span>](#)</span></span>
<div style="display: inline">
- <div id="twistyId11toggle"> my twisty content </div>
+ <div id="twistyId11toggle"> %GREEN% my twisty content %ENDCOLOR% </div>
</div>
### <a name="Twisty headers"></a> Twisty headers
To be able to use header tags like `<h2>`, use the properties `prefix` and `suffix`. Because we have identical show and hide links we can use the shorthand property `link`.
- %TWISTY{prefix="<h4>!!" link="Header"
+ %TWISTY{
+ prefix="<h4>!!"
+ mode="div"
+ link="Header"
showimgleft="%ICONURLPATH{toggleopen}%"
- hideimgleft="%ICONURLPATH{toggleclose}%" suffix="</h4>"}%
+ hideimgleft="%ICONURLPATH{toggleclose}%"
+ suffix="</h4>"
+ }%
my twisty content
%ENDTWISTY%
+Add the `!!` to prevent the twisty header appear in the table of contents when you use `%TOC%`.
+
Will create:
#### <a name="Header%_TWISTYSCRIPT{"TWiki._Twi"></a> <span><span>[<span>Header</span>](#)</span><span>[<span>Header</span>](#)</span></span>
-<div style="display: inline"><span id="twistyId12toggle"> my twisty content </span></div>
+<div style="display: inline"><span id="twistyId12toggle"> %GREEN% my twisty content %ENDCOLOR% </span></div>
### <a name="All on, all off"></a> All on, all off
You can toggle all Twisties on or off at once by putting a link or button on the page with class `twistyExpandAll` or `twistyCollapseAll`.
- <button class="twistyExpandAll twikiButton">Expand all</button>
- <button class="twistyCollapseAll twikiButton">Collapse all</button>
+ <button class="twistyExpandAll twikiButton">Expand all</button> <button class="twistyCollapseAll twikiButton">Collapse all</button>
Creates these controls:
<button>Expand all</button>
+
<button>Collapse all</button>
When you want to use links, write:
#VarTOGGLE
- <a href="#TOGGLE" class="twistyExpandAll">Expand all</a>
+ <a href="#TOGGLE" class="twistyExpandAll">Expand all</a>
<a href="#TOGGLE" class="twistyCollapseAll">Collapse all</a>
<a name="VarTOGGLE"></a>
-[Expand all](#TOGGLE) [Collapse all](#TOGGLE)
+[Expand all](#TOGGLE) [Collapse all](#TOGGLE)
+
+## <a name="Special syntax: format tokens"></a> Special syntax: format tokens
+
+If you use TWiki variables inside TWISTY parameters chances are it will mess up the variable, or the rendered html. Use format tokens to 'delay' rendering of these variables until the Twisty parameters are parsed.
+
+The format tokens are the same as with [[FormattedSearch]]:
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th bgcolor="#99CCCC"><strong> Escape: </strong></th>
+ <th bgcolor="#99CCCC"><strong> Expands To: </strong></th>
+ </tr>
+ <tr>
+ <td><code>$n</code> or <code>$n()</code></td>
+ <td> New line. Use <code>$n()</code> if followed by alphanumeric character, e.g. write <code>Foo$n()Bar</code> instead of <code>Foo$nBar</code></td>
+ </tr>
+ <tr>
+ <td><code>$nop</code> or <code>$nop()</code></td>
+ <td> Is a "no operation". </td>
+ </tr>
+ <tr>
+ <td><code>$quot</code></td>
+ <td> Double quote (<code>"</code>) </td>
+ </tr>
+ <tr>
+ <td><code>$percnt</code></td>
+ <td> Percent sign (<code>%</code>) </td>
+ </tr>
+ <tr>
+ <td><code>$dollar</code></td>
+ <td> Dollar sign (<code>$</code>) </td>
+ </tr>
+</table>
+
+For example, to show an icon inside the link, do not write:
+
+ link="%Y%"
+
+but use format tokens:
+
+ link="$percntY$percnt"
+
+... to get:
+
+<span><span>[<span>$percntY$percnt</span>](#)</span><span>[<span>$percntY$percnt</span>](#)</span></span>
+
+<div style="display: inline">
+ <div id="twistyId13toggle"> my twisty content </div>
+</div>
+
+Or a more complex example using [[SpreadsheetPlugin]]; do not write:
+
+ link="Count: (%CALC{"$GET(infoCount)"}%)"
+
+but use format tokens:
+
+ link="Count: ($percntCALC{$quot$dollarGET(infoCount)$quot}$percnt)"
## <a name="Syntax"></a> Syntax
<tr>
<td><code>img</code></td>
<td> Image url </td>
- <td> %RED%Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.%ENDCOLOR% </td>
+ <td> %GREEN%Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.%ENDCOLOR% </td>
<td> optional, defaults to no image </td>
</tr>
<tr>
<td><code>imgleft</code></td>
<td> Image url </td>
- <td> %RED%Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.%ENDCOLOR% </td>
+ <td> %GREEN%Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.%ENDCOLOR% </td>
<td> optional, defaults to no image </td>
</tr>
<tr>
<td><code>imgright</code></td>
<td> Image url </td>
- <td> %RED%Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.%ENDCOLOR% </td>
+ <td> %GREEN%Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.%ENDCOLOR% </td>
<td> optional, defaults to no image </td>
</tr>
<tr>
<td><code>hideimg</code></td>
<td> Image url </td>
- <td> %RED%Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.%ENDCOLOR% </td>
+ <td> %GREEN%Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.%ENDCOLOR% </td>
<td> optional, defaults to no image </td>
</tr>
<tr>
<td><code>showimg</code></td>
<td> Image url </td>
- <td> %RED%Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.%ENDCOLOR% </td>
+ <td> %GREEN%Deprecated, use showimgleft, hideimgleft, showimgright or hideimgright.%ENDCOLOR% </td>
<td> optional, defaults to no image </td>
</tr>
</table>
- Automatically fills in default values
- Global preference settings can be set in this topic or locally in individual topics
+<a name="PluginSettings"></a>
+
## <a name="Plugin Settings"></a> Plugin Settings
Plugin settings are stored as preferences variables. To reference a plugin setting write <code>**%<plugin>\_<setting>%**</code>, i.e. <code>**%TWISTYPLUGIN\_SHORTDESCRIPTION%**</code>
<th bgcolor="#99CCCC"><strong> Description: </strong></th>
</tr>
<tr>
+ <td><code><b>TwistyBundleTWiki04x02_installer</b></code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code><b>TwistyBundleTWiki04x02_installer.pl</b></code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code><b>data/TWiki/TwistyBundleTWiki04x02.txt</b></code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code><b>data/TWiki/BehaviourContrib.txt</b></code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code><b>data/TWiki/TwistyContrib.txt</b></code></td>
+ <td> </td>
+ </tr>
+ <tr>
<td><code><b>data/TWiki/TwistyPlugin.txt</b></code></td>
<td> </td>
</tr>
<tr>
+ <td><code><b>lib/TWiki/Contrib/BehaviourContrib.pm</b></code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code><b>lib/TWiki/Contrib/TwistyBundleTWiki04x02.pm</b></code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code><b>lib/TWiki/Contrib/TwistyContrib.pm</b></code></td>
+ <td> </td>
+ </tr>
+ <tr>
<td><code><b>lib/TWiki/Plugins/TwistyPlugin.pm</b></code></td>
<td> </td>
</tr>
-</table>
-
-- Optionally, if it exists, run <code>**%TOPIC%\_installer**</code> to automatically check and install other TWiki modules that this module depends on. You can also do this step manually.
-- Alternatively, manually make sure the dependencies listed in the table below are resolved. <table border="1">
<tr>
- <th>Name</th>
- <th>Version</th>
- <th>Description</th>
+ <td><code><b>pub/TWiki/BehaviourContrib/behaviour.compressed.js</b></code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code><b>pub/TWiki/BehaviourContrib/behaviour.compressed_src.js</b></code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code><b>pub/TWiki/BehaviourContrib/behaviour.js</b></code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code><b>pub/TWiki/BehaviourContrib/behaviour_src.js</b></code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code><b>pub/TWiki/BehaviourContrib/cssQuery/cssQuery-p.js</b></code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code><b>pub/TWiki/BehaviourContrib/cssQuery/src/cssQuery-level2.js</b></code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code><b>pub/TWiki/BehaviourContrib/cssQuery/src/cssQuery-level3.js</b></code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code><b>pub/TWiki/BehaviourContrib/cssQuery/src/cssQuery-standard.js</b></code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code><b>pub/TWiki/BehaviourContrib/cssQuery/src/cssQuery.js</b></code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code><b>pub/TWiki/BehaviourContrib/cssQuery/src/test.html</b></code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code><b>pub/TWiki/BehaviourContrib/cssQuery/test.html</b></code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code><b>pub/TWiki/TwistyContrib/twist.compressed.js</b></code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code><b>pub/TWiki/TwistyContrib/twist.compressed_src.js</b></code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code><b>pub/TWiki/TwistyContrib/twist.css</b></code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code><b>pub/TWiki/TwistyContrib/twist.js</b></code></td>
+ <td> </td>
</tr>
<tr>
- <td align="left">TWiki::Contrib::TwistyContrib</td>
- <td align="left">>=1.200</td>
- <td align="left">Required. Twisty javascript library</td>
+ <td><code><b>pub/TWiki/TwistyContrib/twist_src.js</b></code></td>
+ <td> </td>
</tr>
</table>
+
+- Optionally, if it exists, run <code>**%TOPIC%\_installer**</code> to automatically check and install other TWiki modules that this module depends on. You can also do this step manually.
+- Alternatively, manually make sure the dependencies listed in the table below are resolved. None
- Visit `configure` in your TWiki installation, and enable the plugin in the \{Plugins\} section.
## <a name="Plugin Info"></a> Plugin Info
</tr>
<tr>
<td> Copyright ©: </td>
- <td> 2005 Rafael Alvarez, 2006 Arthur Clemens </td>
+ <td> 2005 Rafael Alvarez; 2006, 2007 Arthur Clemens </td>
</tr>
<tr>
<td> License: </td>
</tr>
<tr>
<td> Dependencies: </td>
- <td>
- <table border="1">
- <tr>
- <th>Name</th>
- <th>Version</th>
- <th>Description</th>
- </tr>
- <tr>
- <td align="left">TWiki::Contrib::TwistyContrib</td>
- <td align="left">>=1.200</td>
- <td align="left">Required. Twisty javascript library</td>
- </tr>
- </table>
- </td>
+ <td> None </td>
+ </tr>
+ <tr>
+ <td> Plugin Version: </td>
+ <td> 24 Nov 2007 (version 1.4.8) </td>
+ </tr>
+ <tr>
+ <td> Change History: </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td> 24 Nov 2007 </td>
+ <td> 1.4.6 - 1.4.8 Arthur Clemens - Added format tokens. </td>
+ </tr>
+ <tr>
+ <td> 07 Oct 2007 </td>
+ <td> 1.4.5 Arthur Clemens - Fix html tag with show/hide controls. </td>
+ </tr>
+ <tr>
+ <td> 25 Sep 2007 </td>
+ <td> 1.4.4 Arthur Clemens - Fix rendering of headers when <code>prefix</code> is used. </td>
+ </tr>
+ <tr>
+ <td> 11 Jul 2007 </td>
+ <td> 1.4.3 Arthur Clemens - Fix invalid html when <code>prefix</code> and <code>suffix</code> is used. </td>
+ </tr>
+ <tr>
+ <td> 23 Jun 2007 </td>
+ <td> 1.4.2 Arthur Clemens - Fixed bugs with parameters <code>firststart</code> and <code>noscript</code> (since version 1.4). </td>
+ </tr>
+ <tr>
+ <td> 20 Jun 2007 </td>
+ <td> 1.4 Arthur Clemens - Updated to work without ugly inserted javascript 'init' calls. This will change nothing to the functionality, but it will produce cleaner HTML, while at the same time the twisty is still set immediately (not at page onload) and graceful fallback in case of no javascript is maintained. </td>
+ </tr>
+ <tr>
+ <td> 19 Jun 2006 </td>
+ <td> 1.3 Arthur Clemens - Updated with TWiki 4 JavaScript files. </td>
</tr>
<tr>
<td> 25 Oct 2006 </td>
--- /dev/null
+# <a name="User Form"></a> User Form
+
+**_Note:_** This is a maintenance topic, used by the TWiki administrator.
+
+This form defines the form of the home pages of registered TWiki users listed in [[TWikiUsers]]. **Do not edit this topic** - if you want to customise the user form, then:
+
+1. Take a copy of this topic and save it to Main.UserForm
+2. Customise Main.UserForm
+3. Take a copy of [[NewUserTemplate]] and save it to Main.NewUserTemplate
+4. Modify Main.NewUserTemplate and change the form to select your new user form.
+
+<table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th bgcolor="#99CCCC"><strong> Name </strong></th>
+ <th bgcolor="#99CCCC"><strong> Type </strong></th>
+ <th bgcolor="#99CCCC"><strong> Size </strong></th>
+ <th bgcolor="#99CCCC"><strong> Values </strong></th>
+ <th bgcolor="#99CCCC"><strong> Tooltip message </strong></th>
+ <th bgcolor="#99CCCC"><strong> Attributes </strong></th>
+ </tr>
+ <tr>
+ <td> FirstName </td>
+ <td> text </td>
+ <td> 40 </td>
+ <td> </td>
+ <td> </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td> LastName </td>
+ <td> text </td>
+ <td> 40 </td>
+ <td> </td>
+ <td> </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td> OrganisationName </td>
+ <td> text </td>
+ <td> 40 </td>
+ <td> </td>
+ <td> </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td> OrganisationURL </td>
+ <td> text </td>
+ <td> 40 </td>
+ <td> </td>
+ <td> </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td> Profession </td>
+ <td> text </td>
+ <td> 40 </td>
+ <td> </td>
+ <td> </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td> Country </td>
+ <td> text </td>
+ <td> 40 </td>
+ <td> </td>
+ <td> </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td> State </td>
+ <td> text </td>
+ <td> 40 </td>
+ <td> </td>
+ <td> </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td> Address </td>
+ <td> text </td>
+ <td> 40 </td>
+ <td> </td>
+ <td> </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td> Location </td>
+ <td> text </td>
+ <td> 40 </td>
+ <td> </td>
+ <td> </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td> Telephone </td>
+ <td> text </td>
+ <td> 40 </td>
+ <td> </td>
+ <td> </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td> VoIP </td>
+ <td> text </td>
+ <td> 40 </td>
+ <td> </td>
+ <td> </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td> InstantMessaging (IM) </td>
+ <td> textarea </td>
+ <td> 50x4 </td>
+ <td> </td>
+ <td> (One account per line, if several) </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td> Email </td>
+ <td> text </td>
+ <td> 40 </td>
+ <td> </td>
+ <td> </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td> HomePage </td>
+ <td> text </td>
+ <td> 40 </td>
+ <td> </td>
+ <td> </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td> Comment </td>
+ <td> textarea </td>
+ <td> 50x6 </td>
+ <td> </td>
+ <td> </td>
+ <td> </td>
+ </tr>
+</table>
+
+**_%X% Note:_** Please keep the [[TWikiRegistration]] form and this form definition in sync. When you update this form you need to edit/save the [[NewUserTemplate]] topic. This ensures that the fields are in the right order.
+
+**_Related topics:_** [[TWikiUsers]], [[UserViewTemplate]], [[NewUserTemplate]], [[UserHomepageHeader]], [[TWikiForms]], [[TWikiRegistration]]
## <a name="Using HTML"></a> Using HTML
-You can use just about any HTML tag without a problem. You can add HTML if there is no TWiki equivalent, for example, write `<strike>deleted text</strike>` to get <strike>deleted text</strike>.
+You can use most HTML tags in TWiki topics without a problem. This is useful where you want to add some content that is formatted in a way that is not supported using [[TWiki shorthand|Main/WebHome#TWikiShorthand]], for example, you can write `<strike>deleted text</strike>` to get <strike>deleted text</strike>.
-%X% There are a few usability and technical considerations to keep in mind:
+There are a few usability and technical considerations to keep in mind:
-- On collaboration pages, it's better **not** to use HTML, but to use [[TWiki shorthand|Main/WebHome#TWikiShorthand]] instead - this keeps the text uncluttered and easy to edit.
-- If you use HTML use [XHTML 1.0 Transitional](http://www.w3.org/TR/xhtml1/) syntax.
+- On collaboration pages, it's better **not** to use HTML, but to use [[TWiki shorthand|Main/WebHome#TWikiShorthand]] instead - this keeps the text uncluttered and easy to edit using the plaintext editor.
+- If you _must_ use HTML, use [XHTML 1.0 Transitional](http://www.w3.org/TR/xhtml1/) syntax.
+- Use `<literal>..</literal>` tags around blocks of HTML to avoid accidental interpretation of [[TWiki shorthand|Main/WebHome#TWikiShorthand]] within the HTML.
- %X% Script tags may be filtered out, at the discretion of your TWiki administrator.
-Recommendations when pasting HTML from other sources:
+Recommendations when pasting HTML from other sources (using the plain-text editor):
- Copy only text between `<body>` and `</body>` tags.
- Remove all empty lines. TWiki inserts `<p />` paragraph tags on empty lines, which causes problems if done between HTML tags that do not allow paragraph tags, like for example between table tags.
- Remove leading spaces. TWiki might interpret some text as lists.
-- Do not span a tag over more than one line. TWiki requires that the opening and closing angle brackets - <code>**<...>**</code> - of an HTML tag are on the same line, or the tag will be broken.
+- Do not span a tag over more than one line. TWiki requires that the opening and closing angle brackets - <code>**<...>**</code> - of a HTML tag are on the same line, or the tag will be broken.
- In your HTML editing program, save without hard line breaks on text wrap.
-%T% TWiki converts shorthand notation to HTML for display. To copy a fully marked-up page, simply view the source in your browser and save the contents. If you need to save HTML frequently, you may want to check out TWiki:Plugins/PublishAddOn.
+When using a WYSIWYG editor, you can just copy-paste directly into the editor, and the content will be converted to [[TWiki shorthand|Main/WebHome#TWikiShorthand]] automatically when you save.
- Syntax: `%ACTIVATEDPLUGINS%`
- Expands to: [[SpreadSheetPlugin]], [[CommentPlugin]], [[EditTablePlugin]], [[InterwikiPlugin]], [[PreferencesPlugin]], [[SlideShowPlugin]], [[SmiliesPlugin]], [[TablePlugin]], [[TwistyPlugin]]
-- Related: [[PLUGINDESCRIPTIONS|Main/WebHome#VarPLUGINDESCRIPTIONS]], [[FAILEDPLUGINS|Main/WebHome#VarFAILEDPLUGINS]], [[PLUGINVERSION|Main/WebHome#VarPLUGINVERSION2]]
+- Related: [[PLUGINDESCRIPTIONS|Main/VarPLUGINDESCRIPTIONS]], [[FAILEDPLUGINS|Main/VarFAILEDPLUGINS]], [[PLUGINVERSION|Main/VarPLUGINVERSION]]
- Syntax: `%AQUA% aqua text %ENDCOLOR%`
- Expands to: %AQUA% aqua text %ENDCOLOR%
- **_Note:_** `%<color>%` text must end with `%ENDCOLOR%`. If you want to switch from one color to another one you first need to end the active color with `%ENDCOLOR%`, e.g. write `%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%`.
-- Related: [[ENDCOLOR|Main/TWikiVariables#VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
+- Related: [[ENDCOLOR|Main/VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
- Syntax: `%ATTACHURL%`
- Expands to: `http://www.dementia.org/twiki//view`
- Example: If you attach a file you can refer to it as `%ATTACHURL%/image.gif`
-- Related: [[ATTACHURLPATH|Main/WebHome#VarATTACHURLPATH]], [[PUBURL|Main/WebHome#VarPUBURL]], [[PUBURLPATH|Main/WebHome#VarPUBURLPATH]], [[SCRIPTURL|Main/WebHome#VarSCRIPTURL]], [[SCRIPTURLPATH|Main/WebHome#VarSCRIPTURL]], [[FileAttachments]]
+- Related: [[ATTACHURLPATH|Main/VarATTACHURLPATH]], [[PUBURL|Main/VarPUBURL]], [[PUBURLPATH|Main/VarPUBURLPATH]], [[SCRIPTURL|Main/VarSCRIPTURL]], [[SCRIPTURLPATH|Main/VarSCRIPTURL]], [[FileAttachments]]
- Syntax: `%ATTACHURLPATH%`
- Expands to: `http://www.dementia.org/twiki//view`
-- Related: [[ATTACHURL|Main/WebHome#VarATTACHURL]], [[PUBURL|Main/WebHome#VarPUBURL]], [[PUBURLPATH|Main/WebHome#VarPUBURLPATH]], [[SCRIPTURL|Main/WebHome#VarSCRIPTURL]], [[SCRIPTURLPATH|Main/WebHome#VarSCRIPTURL]], [[FileAttachments]]
+- Related: [[ATTACHURL|Main/VarATTACHURL]], [[PUBURL|Main/VarPUBURL]], [[PUBURLPATH|Main/VarPUBURLPATH]], [[SCRIPTURL|Main/VarSCRIPTURL]], [[SCRIPTURLPATH|Main/VarSCRIPTURL]], [[FileAttachments]]
- String defined as \{AuthRealm\} in [configure](http://www.dementia.org/twiki/configure). This is used in certain password encodings, and in login templates as part of the login prompt.
- Syntax: `%AUTHREALM%`
- Expands to: Enter your [[LoginName]]. (Typically First name and last name, no space, no dots, capitalized, e.g. JohnSmith, unless you chose otherwise). Visit [[TWikiRegistration]] if you do not have one.
-- Related: [[TWikiUserAuthentication]], [[SESSIONID|Main/WebHome#VarSESSIONID]], [[SESSIONVAR|Main/WebHome#VarSESSIONVAR]], [[LOGIN|Main/WebHome#VarLOGIN]], [[LOGOUT|Main/WebHome#VarLOGOUT]], [[SESSION_VARIABLE|Main/WebHome#VarSESSION_VARIABLE]]
+- Related: [[TWikiUserAuthentication]], [[SESSIONID|Main/VarSESSIONID]], [[SESSIONVAR|Main/VarSESSIONVAR]], [[LOGIN|Main/VarLOGIN]], [[LOGOUT|Main/VarLOGOUT]], [[SESSION_VARIABLE|Main/VarSESSION_VARIABLE]]
- The name of the topic where a single or nested INCLUDE started - same as `%TOPIC%` if there is no INCLUDE
- Syntax: `%BASETOPIC%`
-- Related: [[BASEWEB|Main/WebHome#VarBASEWEB]], [[INCLUDINGTOPIC|Main/WebHome#VarINCLUDINGTOPIC]], [[INCLUDE|Main/WebHome#VarINCLUDE]], [[TOPIC|Main/WebHome#VarTOPIC]]
+- Related: [[BASEWEB|Main/VarBASEWEB]], [[INCLUDINGTOPIC|Main/VarINCLUDINGTOPIC]], [[INCLUDE|Main/VarINCLUDE]], [[TOPIC|Main/VarTOPIC]]
- The web name where the includes started, e.g. the web of the first topic of nested includes. Same as `%WEB%` in case there is no include.
- Syntax: `%BASEWEB%`
-- Related: [[BASETOPIC|Main/WebHome#VarBASETOPIC]], [[INCLUDINGWEB|Main/WebHome#VarINCLUDINGWEB]], [[INCLUDE|Main/WebHome#VarINCLUDE]], [[WEB|Main/WebHome#VarWEB]]
+- Related: [[BASETOPIC|Main/VarBASETOPIC]], [[INCLUDINGWEB|Main/VarINCLUDINGWEB]], [[INCLUDE|Main/VarINCLUDE]], [[WEB|Main/VarWEB]]
- Line break and bullet without indentation.
- Type: Preference variable - [[TWikiRenderingShortcut]].
- Current value: BB = %BB%
-- Related: [[BR|Main/WebHome#VarBR]], [[BULLET|Main/WebHome#VarBULLET]], [[BB2|Main/WebHome#VarBB2]], [[BB3|Main/WebHome#VarBB3]], [[BB4|Main/WebHome#VarBB4]], [[VBAR|Main/WebHome#VarVBAR]]
+- Related: [[BR|Main/VarBR]], [[BULLET|Main/VarBULLET]], [[BB2|Main/VarBB2]], [[BB3|Main/VarBB3]], [[BB4|Main/VarBB4]], [[CARET|Main/VarCARET]], [[VBAR|Main/VarVBAR]]
- Line break and bullet, level 2.
- Type: Preference variable - [[TWikiRenderingShortcut]].
- Current value: BB2 = %BB2%
-- Related: [[BR|Main/WebHome#VarBR]], [[BULLET|Main/WebHome#VarBULLET]], [[BB|Main/WebHome#VarBB]], [[BB3|Main/WebHome#VarBB3]], [[BB4|Main/WebHome#VarBB4]], [[VBAR|Main/WebHome#VarVBAR]]
+- Related: [[BR|Main/VarBR]], [[BULLET|Main/VarBULLET]], [[BB|Main/VarBB]], [[BB3|Main/VarBB3]], [[BB4|Main/VarBB4]], [[VBAR|Main/VarVBAR]]
- Line break and bullet, level 3.
- Type: Preference variable - [[TWikiRenderingShortcut]].
- Current value: BB3 = %BB3%
-- Related: [[BR|Main/WebHome#VarBR]], [[BULLET|Main/WebHome#VarBULLET]], [[BB|Main/WebHome#VarBB]], [[BB2|Main/WebHome#VarBB2]], [[BB4|Main/WebHome#VarBB4]], [[VBAR|Main/WebHome#VarVBAR]]
+- Related: [[BR|Main/VarBR]], [[BULLET|Main/VarBULLET]], [[BB|Main/VarBB]], [[BB2|Main/VarBB2]], [[BB4|Main/VarBB4]], [[VBAR|Main/VarVBAR]]
- Line break and bullet, level 4.
- Type: Preference variable - [[TWikiRenderingShortcut]].
- Current value: BB4 = %BB4%
-- Related: [[BR|Main/WebHome#VarBR]], [[BULLET|Main/WebHome#VarBULLET]], [[BB|Main/WebHome#VarBB]], [[BB2|Main/WebHome#VarBB2]], [[BB3|Main/WebHome#VarBB3]], [[VBAR|Main/WebHome#VarVBAR]]
+- Related: [[BR|Main/VarBR]], [[BULLET|Main/VarBULLET]], [[BB|Main/VarBB]], [[BB2|Main/VarBB2]], [[BB3|Main/VarBB3]], [[VBAR|Main/VarVBAR]]
- Syntax: `%BLACK% black text %ENDCOLOR%`
- Expands to: %BLACK% black text %ENDCOLOR%
- **_Note:_** `%<color>%` text must end with `%ENDCOLOR%`. If you want to switch from one color to another one you first need to end the active color with `%ENDCOLOR%`, e.g. write `%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%`.
-- Related: [[ENDCOLOR|Main/TWikiVariables#VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
+- Related: [[ENDCOLOR|Main/VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
- Syntax: `%BLUE% blue text %ENDCOLOR%`
- Expands to: %BLUE% blue text %ENDCOLOR%
- **_Note:_** `%<color>%` text must end with `%ENDCOLOR%`. If you want to switch from one color to another one you first need to end the active color with `%ENDCOLOR%`, e.g. write `%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%`.
-- Related: [[ENDCOLOR|Main/TWikiVariables#VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
+- Related: [[ENDCOLOR|Main/VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
- Type: Preference variable - [[TWikiRenderingShortcut]].
- Current value: BR = %BR%
-- Related: [[BULLET|Main/WebHome#VarBULLET]], [[BB|Main/WebHome#VarBB]], [[BB2|Main/WebHome#VarBB2]], [[BB3|Main/WebHome#VarBB3]], [[BB4|Main/WebHome#VarBB4]], [[VBAR|Main/WebHome#VarVBAR]]
+- Related: [[BULLET|Main/VarBULLET]], [[BB|Main/VarBB]], [[BB2|Main/VarBB2]], [[BB3|Main/VarBB3]], [[BB4|Main/VarBB4]], [[CARET|Main/VarCARET]], [[VBAR|Main/VarVBAR]]
- Syntax: `%BROWN% brown text %ENDCOLOR%`
- Expands to: %BROWN% brown text %ENDCOLOR%
- **_Note:_** `%<color>%` text must end with `%ENDCOLOR%`. If you want to switch from one color to another one you first need to end the active color with `%ENDCOLOR%`, e.g. write `%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%`.
-- Related: [[ENDCOLOR|Main/TWikiVariables#VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
+- Related: [[ENDCOLOR|Main/VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
- Type: Preference variable - [[TWikiRenderingShortcut]].
- Current value: BULLET = %BULLET%
-- Related: [[BR|Main/WebHome#VarBR]], [[BB|Main/WebHome#VarBB]], [[BB2|Main/WebHome#VarBB2]], [[BB3|Main/WebHome#VarBB3]], [[BB4|Main/WebHome#VarBB4]], [[VBAR|Main/WebHome#VarVBAR]]
+- Related: [[BR|Main/VarBR]], [[BB|Main/VarBB]], [[BB2|Main/VarBB2]], [[BB3|Main/VarBB3]], [[BB4|Main/VarBB4]], [[CARET|Main/VarCARET]], [[VBAR|Main/VarVBAR]]
--- /dev/null
+<a name="VarCALC"></a>
+
+### <a name="CALC{"formula"} -- add spreadshe"></a> CALC\{"formula"\} -- add spreadsheet calculations to tables and outside tables
+
+- The `%CALC{"formula"}%` variable is handled by the [[SpreadSheetPlugin]]. There are around 80 formulae, such as `$ABS()`, `$EXACT()`, `$EXISTS()`, `$GET()/$SET()`, `$IF()`, `$LOG()`, `$LOWER()`, `$PERCENTILE()`, `$TIME()`, `$VALUE()`.
+- Syntax: `%CALC{"formula"}%`
+- Examples:
+ - `%CALC{"$SUM($ABOVE())"}%` returns the sum of all cells above the current cell
+ - `%CALC{"$EXISTS(Web.SomeTopic)"}%` returns `1` if the topic exists
+ - `%CALC{"$UPPER(Collaboration)"}%` returns `COLLABORATION`
+- Related: [[IF|Main/WebHome#VarIF]], [[SpreadSheetPlugin]]
--- /dev/null
+<a name="VarCARET"></a>
+
+### <a name="CARET -- caret symbol"></a> CARET -- caret symbol
+
+- The caret variable can be used in TWiki tables.
+- Type: Preference variable - [[TWikiRenderingShortcut]].
+- Current value: CARET = %CARET%
+- Related: [[BR|Main/VarBR]], [[BULLET|Main/VarBULLET]], [[BB|Main/VarBB]], [[BB2|Main/VarBB2]], [[BB3|Main/VarBB3]], [[BB4|Main/VarBB4]], [[VBAR|Main/VarVBAR]]
--- /dev/null
+<a name="VarCOMMENT"></a>
+
+### <a name="COMMENT{ <em>attributes</em> } -- inser"></a> COMMENT\{ _attributes_ \} -- insert an edit box into the topic to easily add comments.
+
+- A `%COMMENT%` without parameters shows a simple text box.
+- The following standard attributes are recognized <table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th bgcolor="#99CCCC"><strong> Name </strong></th>
+ <th bgcolor="#99CCCC"><strong> Description </strong></th>
+ <th bgcolor="#99CCCC"><strong> Default </strong></th>
+ </tr>
+ <tr>
+ <td><code>type</code></td>
+ <td> This is the name of the template to use for this comment. Comment templates are defined in a TWiki template - see [[Main/CommentPlugin#TemPlates]], below. If this attribute is not defined, the type is whatever is defined by COMMENTPLUGIN_DEFAULT_TYPE, either in this topic or in your [[Main/WebPreferences]]. </td>
+ <td><code>below</code></td>
+ </tr>
+ <tr>
+ <td><code>default</code></td>
+ <td> Default text to put into the textarea of the prompt. </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code>target</code></td>
+ <td> Name of the topic to add the comment to </td>
+ <td> the current topic </td>
+ </tr>
+ <tr>
+ <td><code>location</code></td>
+ <td> Regular expression specifying the comment location in the target topic. Read <em>carefully</em> the [[Main/CommentPlugin]] documentation! </td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code>mode</code></td>
+ <td> For compatibility with older versions only, synonymous with <code>type</code></td>
+ <td> </td>
+ </tr>
+ <tr>
+ <td><code>nonotify</code></td>
+ <td> Set to "on" to disable change notification for target topics </td>
+ <td><code>off</code></td>
+ </tr>
+ <tr>
+ <td><code>noform</code></td>
+ <td> Set to "on" to disable the automatic form that encloses your comment block - <em>remember</em> to insert <code><form></code> tags yourself! See [[Main/CommentPluginExamples#noform]] for an example. </td>
+ <td><code>off</code></td>
+ </tr>
+ <tr>
+ <td><code>nopost</code></td>
+ <td> Set to "on" to disable insertion of the posted text into the topic. </td>
+ <td><code>off</code></td>
+ </tr>
+ <tr>
+ <td><code>remove</code></td>
+ <td> Set to "on" to remove the comment prompt after the first time it is clicked. </td>
+ <td><code>off</code></td>
+ </tr>
+ <tr>
+ <td><code>button</code></td>
+ <td> Button label text </td>
+ <td><code>Add comment</code></td>
+ </tr>
+</table>
+
+- See [[CommentPlugin]] for more information
- Syntax: `%DATE%`
- Expands to: `29 Jun 2010`
+- Date format defined as \{DefaultDateFormat\} in [configure](http://www.dementia.org/twiki/configure)
- **_%X% Note:_** When used in a template topic, this variable will be expanded when the template is used to create a new topic. See [[TWikiTemplates#TemplateTopicsVars]] for details.
-- Related: [[DISPLAYTIME|Main/WebHome#VarDISPLAYTIME]], [[GMTIME{"format"}|Main/WebHome#VarGMTIME2]], [[SERVERTIME|Main/WebHome#VarSERVERTIME]]
+- Related: [[DISPLAYTIME|Main/VarDISPLAYTIME]], [[GMTIME{"format"}|Main/VarGMTIME2]], [[SERVERTIME|Main/VarSERVERTIME]]
### <a name="DISPLAYTIME -- display time"></a> DISPLAYTIME -- display time
- Syntax: `%DISPLAYTIME%`
-- Expands to: `29 Jun 2010 - 16:00`
-- Related: [[DISPLAYTIME{"format"}|Main/WebHome#VarDISPLAYTIME2]], [[GMTIME|Main/WebHome#VarGMTIME]], [[SERVERTIME|Main/WebHome#VarSERVERTIME]]
+- Expands to: `29 Jun 2010 - 16:09`
+- Date format defined as \{DefaultDateFormat\} in [configure](http://www.dementia.org/twiki/configure)
+- Related: [[DISPLAYTIME{"format"}|Main/VarDISPLAYTIME2]], [[GMTIME|Main/VarGMTIME]], [[SERVERTIME|Main/VarSERVERTIME]]
- Formatted time - either GMT or Local server time, depending on setting in [configure](http://www.dementia.org/twiki/configure). Same format qualifiers as `%GMTIME%`
- Syntax: `%DISPLAYTIME{"format"}%`
-- Example: `%DISPLAYTIME{"$hou:$min"}%` expands to `16:00`
-- Related: [[DISPLAYTIME|Main/WebHome#VarDISPLAYTIME]], [[GMTIME|Main/WebHome#VarGMTIME]], [[SERVERTIME|Main/WebHome#VarSERVERTIME]]
+- Example: `%DISPLAYTIME{"$hou:$min"}%` expands to `16:09`
+- Related: [[DISPLAYTIME|Main/VarDISPLAYTIME]], [[GMTIME|Main/VarGMTIME]], [[SERVERTIME|Main/VarSERVERTIME]]
--- /dev/null
+<a name="VarEDITTABLE"></a>
+
+### <a name="EDITTABLE{ <em>attributes</em> } -- edi"></a> EDITTABLE\{ _attributes_ \} -- edit TWiki tables using edit fields and other input fields
+
+- The `%EDITTABLE{}%` variable is handled by the [[EditTablePlugin]]
+- Syntax: <code>%EDITTABLE\{ _attributes_ \}%</code>
+
+- Supported attributes: <table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th bgcolor="#99CCCC"><strong> Attribute </strong></th>
+ <th bgcolor="#99CCCC"><strong> Comment </strong></th>
+ <th bgcolor="#99CCCC"><strong> Default </strong></th>
+ </tr>
+ <tr>
+ <td><code>header</code></td>
+ <td> Specify the header format of a new table like <code>"%VBAR%*Food*%VBAR%*Drink*%VBAR%"</code>. Useful to start a table with only a button </td>
+ <td> (no header) </td>
+ </tr>
+ <tr>
+ <td><code>format</code></td>
+ <td> The format of one column when editing the table. A cell can be a text input field, or any of these edit field types:%BR% %BB% Text input field (1 line):%BR% <code>%VBAR% text, <size>, <initial value> %VBAR%</code> %BR% %BB% Textarea input field:%BR% <code>%VBAR% textarea, <rows>x<columns>, <initial value> %VBAR%</code> %BR% %BB% Drop down box: %BR% <code>%VBAR% select, <size>, <option 1>, <option 2>, etc* %VBAR%</code> %BR% <code>*</code> only one item can be selected %BR% %BB% Radio buttons: %BR% <code>%VBAR% radio, <size*>, <option 1>, <option 2>, etc %VBAR%</code> %BR% <code>*</code> size indicates the number of buttons per line in edit mode %BR% %BB% Checkboxes: %BR% <code>%VBAR% checkbox, <size*>, <option 1>, <option 2>, etc %VBAR%</code> %BR% <code>*</code> size indicates the number of checkboxes per line in edit mode %BR% %BB% Fixed label: %BR% <code>%VBAR% label, 0, <label text> %VBAR%</code> %BR% %BB% Row number: %BR% <code>%VBAR% row, <offset> %VBAR%</code> %BR% %BB% Date: %BR% <code>%VBAR% date, <size>, <initial value>, <DHTML date format> %VBAR%</code> (see [[Main/WebHome#DateField]]) </td>
+ <td><code>"text, 16"</code> %BR% for all cells </td>
+ </tr>
+ <tr>
+ <td><code>changerows</code></td>
+ <td> Rows can be added and removed if <code>"on"</code><br /> Rows can be added but not removed if <code>"add"</code><br /> Rows cannot be added or removed if <code>"off"</code></td>
+ <td><code>CHANGEROWS</code> %BR% Plugin setting </td>
+ </tr>
+ <tr>
+ <td><code>quietsave</code></td>
+ <td> Quiet Save button is shown if <code>"on"</code>, hidden if <code>"off"</code></td>
+ <td><code>QUIETSAVE</code> %BR% Plugin setting </td>
+ </tr>
+ <tr>
+ <td><code>include</code></td>
+ <td> 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. </td>
+ <td> (none) </td>
+ </tr>
+ <tr>
+ <td><code>helptopic</code></td>
+ <td> Topic name containing help text shown below the table when editing a table. The %STARTINCLUDE% and %STOPINCLUDE% variables can be used in the topic to specify what is shown. </td>
+ <td> (no help text) </td>
+ </tr>
+ <tr>
+ <td><code>headerislabel</code></td>
+ <td> Table header cells are read-only (labels) if <code>"on"</code>; header cells can be edited if <code>"off"</code> or "0" </td>
+ <td><code>"on"</code></td>
+ </tr>
+ <tr>
+ <td><code>editbutton</code></td>
+ <td> Set edit button text, e.g. <code>"Edit this table"</code>; set button image with alt text, e.g. <code>"Edit table, %PUBURL%/%TWIKIWEB%/TWikiDocGraphics/edittopic.gif"</code>; hide edit button at the end of the table with <code>"hide"</code> (Note: Button is automatically hidden if an edit button is present in a cell) </td>
+ <td><code>EDITBUTTON</code> %BR% Plugin setting </td>
+ </tr>
+</table>
+
+- Example:%BR% `%EDITTABLE{ format="| text, 20 | select, 1, one, two, three |" changerows="on" }%` %BR% `| *Name* | *Type* |` %BR% `| Foo | two |`
+- Related: See [[EditTablePlugin]] for more details
<td><code>type="url"</code></td>
</tr>
<tr>
- <td><code>type="quote"</code></td>
+ <td><code>type="quotes"</code></td>
<td> Escape double quotes with backslashes (<code>\"</code>), does not change other characters </td>
<td><code>type="url"</code></td>
</tr>
- **_%X% Note:_** Values of HTML input fields must be entity encoded.%BR% Example: `<input type="text" name="address" value="%ENCODE{ "any text" type="entity" }%" />`
- **_%X% Note:_** Double quotes in strings must be escaped when passed into other TWiki variables.%BR% Example: `%SEARCH{ "%ENCODE{ "string with "quotes"" type="quotes" }%" noheader="on" }%`
-- Related: [[URLPARAM|Main/WebHome#VarURLPARAM]]
+- Related: [[URLPARAM|Main/VarURLPARAM]]
- Syntax: `%RED% red text %ENDCOLOR%`
- Expands to: %RED% red text %ENDCOLOR%
- **_Note:_** `%<color>%` text must end with `%ENDCOLOR%`. If you want to switch from one color to another one you first need to end the active color with `%ENDCOLOR%`, e.g. write `%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%`.
-- Related: [[VarAQUA|Main/TWikiVariables#VarAQUA]], [[VarBLACK|Main/TWikiVariables#VarBLACK]], [[VarBLUE|Main/TWikiVariables#VarBLUE]], [[VarBROWN|Main/TWikiVariables#VarBROWN]], [[VarGRAY|Main/TWikiVariables#VarGRAY]], [[VarGREEN|Main/TWikiVariables#VarGREEN]], [[VarLIME|Main/TWikiVariables#VarLIME]], [[VarMAROON|Main/TWikiVariables#VarMAROON]], [[VarNAVY|Main/TWikiVariables#VarNAVY]], [[VarOLIVE|Main/TWikiVariables#VarOLIVE]], [[VarORANGE|Main/TWikiVariables#VarORANGE]], [[VarPINK|Main/TWikiVariables#VarPINK]], [[VarPURPLE|Main/TWikiVariables#VarPURPLE]], [[VarRED|Main/TWikiVariables#VarRED]], [[VarSILVER|Main/TWikiVariables#VarSILVER]], [[VarTEAL|Main/TWikiVariables#VarTEAL]], [[VarWHITE|Main/TWikiVariables#VarWHITE]], [[VarYELLOW|Main/TWikiVariables#VarYELLOW]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
+- Related: [[VarAQUA]], [[VarBLACK]], [[VarBLUE]], [[VarBROWN]], [[VarGRAY]], [[VarGREEN]], [[VarLIME]], [[VarMAROON]], [[VarNAVY]], [[VarOLIVE]], [[VarORANGE]], [[VarPINK]], [[VarPURPLE]], [[VarRED]], [[VarSILVER]], [[VarTEAL]], [[VarWHITE]], [[VarYELLOW]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
</tr>
</table>
- If the `STARTSECTION` is named, the corresponding `ENDSECTION` must also be named with the same name. If the `STARTSECTION` specifies a type, then the corresponding `ENDSECTION` must also specify the same type. If the section is unnamed, `ENDSECTION` will match with the nearest unnamed `%STARTSECTION%` **of the same type** above it.
-- Related: [[STARTSECTION|Main/WebHome#VarSTARTSECTION]]
+- Related: [[STARTSECTION|Main/VarSTARTSECTION]]
--- /dev/null
+<a name="VarENV"></a>
+
+### <a name="ENV{"varname"} -- inspect the va"></a> ENV\{"varname"\} -- inspect the value of an environment variable
+
+- Returns the current value of the environment variable in the CGI (Common Gateway Interface) environment. This is the environment that the TWiki scripts run in on the web server.
+- **_Note:_** For security reasons, only those variables whose names match the regular expression in `{AccessibleENV}` in the **Security Settings/Miscellaneous** section of `configure` can be displayed. Any other variable will just be shown as an empty string, irrespective of its real value.
+- Example: `%ENV{MOD_PERL}%` displays as:
+- If a variable is undefined (as against being set to the empty string) it will be returned as `not set`.
+- Related: [[HTTP_HOST|Main/VarHTTPHOST]], [[REMOTE_ADDR|Main/VarREMOTEADDR]], [[REMOTE_PORT|Main/VarREMOTEPORT]], [[REMOTE_USER|Main/VarREMOTEUSER]]
- Syntax: `%FAILEDPLUGINS%`
- Expands to: See [[TWikiPlugins#FAILEDPLUGINS]]
-- Related: [[PLUGINDESCRIPTIONS|Main/WebHome#VarPLUGINDESCRIPTIONS]], [[ACTIVATEDPLUGINS|Main/WebHome#ACTIVATEDPLUGINS]], [[PLUGINVERSION|Main/WebHome#PLUGINVERSION2]]
+- Related: [[PLUGINDESCRIPTIONS|Main/VarPLUGINDESCRIPTIONS]], [[ACTIVATEDPLUGINS]], [[PLUGINVERSION|Main/PLUGINVERSION2]]
</tr>
<tr>
<td><code>format="..."</code></td>
- <td> Format string. <code>$value</code> expands to the field value, and <code>$title</code> expands to the field title </td>
+ <td> Format string. <code>$value</code> expands to the field value, and <code>$title</code> expands to the fieldname </td>
<td><code>"$value"</code></td>
</tr>
<tr>
</tr>
</table>
- Example: `%FORMFIELD{"ProjectName" topic="Projects.SushiProject" default="(not set)" alttext="ProjectName field found"}%`
-- Related: [[SEARCH|Main/WebHome#VarSEARCH]]
+- Related: [[SEARCH|Main/VarSEARCH]]
### <a name="GMTIME -- GM time"></a> GMTIME -- GM time
- Syntax: `%GMTIME%`
-- Expands to: `29 Jun 2010 - 16:00`
+- Expands to: `29 Jun 2010 - 16:09`
+- Date format defined as \{DefaultDateFormat\} in [configure](http://www.dementia.org/twiki/configure)
- **_%X% Note:_** When used in a template topic, this variable will be expanded when the template is used to create a new topic. See [[TWikiTemplates#TemplateTopicsVars]] for details.
-- Related: [[DISPLAYTIME|Main/WebHome#VarDISPLAYTIME]], [[GMTIME{"format"}|Main/WebHome#VarGMTIME2]], [[SERVERTIME|Main/WebHome#VarSERVERTIME]]
+- Related: [[DISPLAYTIME|Main/VarDISPLAYTIME]], [[GMTIME{"format"}|Main/VarGMTIME2]], [[SERVERTIME|Main/VarSERVERTIME]]
</tr>
<tr>
<td><code>$month</code></td>
- <td> month in ISO format </td>
+ <td> short name of month </td>
<td> Dec </td>
</tr>
<tr>
<tr>
<td><code>$iso</code></td>
<td> ISO format timestamp </td>
- <td> 2010-06-29T16:03:15Z </td>
+ <td> 2010-06-29T16:09:19Z </td>
</tr>
<tr>
<td><code>$rcs</code></td>
<td> RCS format timestamp </td>
- <td> 2010/06/29 16:03:15 </td>
+ <td> 2010/06/29 16:09:19 </td>
</tr>
<tr>
<td><code>$http</code></td>
<td> E-mail & http format timestamp </td>
- <td> Tue, 29 Jun 2010 16:03:15 GMT </td>
+ <td> Tue, 29 Jun 2010 16:09:19 GMT </td>
</tr>
<tr>
<td><code>$epoch</code></td>
<td> Number of seconds since 00:00 on 1st January, 1970 </td>
- <td> 1277827395 </td>
+ <td> 1277827759 </td>
</tr>
</table>
- Variables can be shortened to 3 characters
-- Example: `%GMTIME{"$day $month, $year - $hour:$min:$sec"}%` expands to `29 Jun, 2010 - 16:03:15`
+- Example: `%GMTIME{"$day $month, $year - $hour:$min:$sec"}%` expands to `29 Jun, 2010 - 16:09:19`
- **_%X% Note:_** When used in a template topic, this variable will be expanded when the template is used to create a new topic. See [[TWikiTemplates#TemplateTopicsVars]] for details.
-- Related: [[DISPLAYTIME|Main/WebHome#VarDISPLAYTIME]], [[GMTIME|Main/WebHome#VarGMTIME]], [[REVINFO|Main/WebHome#VarREVINFO2]], [[SERVERTIME|Main/WebHome#VarSERVERTIME]]
+- Related: [[DISPLAYTIME|Main/VarDISPLAYTIME]], [[GMTIME|Main/VarGMTIME]], [[REVINFO|Main/VarREVINFO2]], [[SERVERTIME|Main/VarSERVERTIME]]
- Syntax: `%GRAY% gray text %ENDCOLOR%`
- Expands to: %GRAY% gray text %ENDCOLOR%
- **_Note:_** `%<color>%` text must end with `%ENDCOLOR%`. If you want to switch from one color to another one you first need to end the active color with `%ENDCOLOR%`, e.g. write `%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%`.
-- Related: [[ENDCOLOR|Main/TWikiVariables#VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
+- Related: [[ENDCOLOR|Main/VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
- Syntax: `%GREEN% green text %ENDCOLOR%`
- Expands to: %GREEN% green text %ENDCOLOR%
- **_Note:_** `%<color>%` text must end with `%ENDCOLOR%`. If you want to switch from one color to another one you first need to end the active color with `%ENDCOLOR%`, e.g. write `%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%`.
-- Related: [[ENDCOLOR|Main/TWikiVariables#VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
+- Related: [[ENDCOLOR|Main/VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
- Expands to a formatted list of user groups in your %WIKITOOLNAME%.
- Syntax: `%GROUPS%`
-- The variable is intended to be used in [[TWikiGroups]], to allow a group listing for various user mapping managers.
-- Related: [[REMOTE_USER|Main/TWikiVariables#VarREMOTEUSER]], [[USERINFO|Main/TWikiVariables#VarUSERINFO]], [[USERNAME|Main/TWikiVariables#VarUSERNAME]], [[WIKIUSERNAME|Main/TWikiVariables#VarWIKIUSERNAME]], [[WIKIUSERSTOPIC|Main/TWikiVariables#VarWIKIUSERSTOPIC]]
+- The variable is intended to be used in %USERSWEB%.TWikiGroups, to allow a group listing for various user mapping managers.
+- Related: [[REMOTE_USER|Main/VarREMOTEUSER]], [[USERINFO|Main/VarUSERINFO]], [[USERNAME|Main/VarUSERNAME]], [[WIKIUSERNAME|Main/VarWIKIUSERNAME]], [[WIKIUSERSTOPIC|Main/VarWIKIUSERSTOPIC]]
- Type: Preference variable - [[TWikiRenderingShortcut]].
- Current value: H = %H%
-- Related: [[I|Main/WebHome#VarI]], [[ICON|Main/WebHome#VarICON]], [[M|Main/WebHome#VarM]], [[N|Main/WebHome#VarN]], [[P|Main/WebHome#VarP]], [[Q|Main/WebHome#VarQ]], [[S|Main/WebHome#VarS]], [[T|Main/WebHome#VarT]], [[U|Main/WebHome#VarU]], [[X|Main/WebHome#VarX]], [[Y|Main/WebHome#VarY]]
+- Related: [[I|Main/VarI]], [[ICON|Main/VarICON]], [[M|Main/VarM]], [[N|Main/VarN]], [[P|Main/VarP]], [[Q|Main/VarQ]], [[S|Main/VarS]], [[T|Main/VarT]], [[U|Main/VarU]], [[X|Main/VarX]], [[Y|Main/VarY]]
- Syntax: `%HOMETOPIC%`
- Expands to: `WebHome`, renders as [[WebHome]]
-- Related: [[NOTIFYTOPIC|Main/WebHome#VarNOTIFYTOPIC]], [[STATISTICSTOPIC|Main/WebHome#VarSTATISTICSTOPIC]], [[TOPIC|Main/WebHome#VarTOPIC]]
+- Related: [[NOTIFYTOPIC|Main/VarNOTIFYTOPIC]], [[STATISTICSTOPIC|Main/VarSTATISTICSTOPIC]], [[TOPIC|Main/VarTOPIC]]
</tr>
</table>
- **_%X% Note:_** You can see the HTTP headers your browser sends to the server on a number of sites e.g. <http://www.ericgiguere.com/tools/http-header-viewer.html>
-- Related: [[HTTPS|Main/WebHome#VarHTTPS]], [[REMOTE_ADDR|Main/WebHome#VarREMOTEADDR]], [[REMOTE_PORT|Main/WebHome#VarREMOTEPORT]], [[REMOTE_USER|Main/WebHome#VarREMOTEUSER]]
+- Related: [[HTTPS|Main/VarHTTPS]], [[REMOTE_ADDR|Main/VarREMOTEADDR]], [[REMOTE_PORT|Main/VarREMOTEPORT]], [[REMOTE_USER|Main/VarREMOTEUSER]]
- Syntax: `%HTTP_HOST%`
- Expands to: ==
-- Related: [[REMOTE_ADDR|Main/WebHome#VarREMOTEADDR]], [[REMOTE_PORT|Main/WebHome#VarREMOTEPORT]], [[REMOTE_USER|Main/WebHome#VarREMOTEUSER]]
+- Related: [[ENV|Main/VarENV]], [[REMOTE_ADDR|Main/VarREMOTEADDR]], [[REMOTE_PORT|Main/VarREMOTEPORT]], [[REMOTE_USER|Main/VarREMOTEUSER]]
- The same as `%HTTP%` but operates on the HTTPS environment variables present when the SSL protocol is in effect. Can be used to determine whether SSL is turned on.
- Syntax: `%HTTPS%`
- Syntax: `%HTTPS{"Header-name"}%`
-- Related: [[HTTP|Main/WebHome#VarHTTP]], [[REMOTE_ADDR|Main/WebHome#VarREMOTEADDR]], [[REMOTE_PORT|Main/WebHome#VarREMOTEPORT]], [[REMOTE_USER|Main/WebHome#VarREMOTEUSER]]
+- Related: [[HTTP|Main/VarHTTP]], [[REMOTE_ADDR|Main/VarREMOTEADDR]], [[REMOTE_PORT|Main/VarREMOTEPORT]], [[REMOTE_USER|Main/VarREMOTEUSER]]
- Type: Preference variable - [[TWikiRenderingShortcut]].
- Current value: I = %I%
-- Related: [[H|Main/WebHome#VarH]], [[ICON|Main/WebHome#VarICON]], [[M|Main/WebHome#VarM]], [[N|Main/WebHome#VarN]], [[P|Main/WebHome#VarP]], [[Q|Main/WebHome#VarQ]], [[S|Main/WebHome#VarS]], [[T|Main/WebHome#VarT]], [[U|Main/WebHome#VarU]], [[X|Main/WebHome#VarX]], [[Y|Main/WebHome#VarY]]
+- Related: [[H|Main/VarH]], [[ICON|Main/VarICON]], [[M|Main/VarM]], [[N|Main/VarN]], [[P|Main/VarP]], [[Q|Main/VarQ]], [[S|Main/VarS]], [[T|Main/VarT]], [[U|Main/VarU]], [[X|Main/VarX]], [[Y|Main/VarY]]
- `%ICON{"http://twiki.org/doc/xhtml.xsl"}%` returns <img src="http://www.dementia.org/twiki//view/Main/WebHome/xsl.gif" width="16" height="16" alt="http://twiki.org/doc/xhtml.xsl" />
- Graphic samples: <img src="http://www.dementia.org/twiki//view/Main/WebHome/arrowbright.gif" width="16" height="16" alt="arrowbright" /> `arrowbright`, <img src="http://www.dementia.org/twiki//view/Main/WebHome/bubble.gif" width="16" height="16" alt="bubble" /> `bubble`, <img src="http://www.dementia.org/twiki//view/Main/WebHome/choice-yes.gif" width="16" height="16" alt="choice-yes" /> `choice-yes`, <img src="http://www.dementia.org/twiki//view/Main/WebHome/hand.gif" width="16" height="16" alt="hand" /> `hand`
- File type samples: <img src="http://www.dementia.org/twiki//view/Main/WebHome/bmp.gif" width="16" height="16" alt="bmp" /> `bmp`, <img src="http://www.dementia.org/twiki//view/Main/WebHome/doc.gif" width="16" height="16" alt="doc" /> `doc`, <img src="http://www.dementia.org/twiki//view/Main/WebHome/gif.gif" width="16" height="16" alt="gif" /> `gif`, <img src="http://www.dementia.org/twiki//view/Main/WebHome/hlp.gif" width="16" height="16" alt="hlp" /> `hlp`, <img src="http://www.dementia.org/twiki//view/Main/WebHome/html.gif" width="16" height="16" alt="html" /> `html`, <img src="http://www.dementia.org/twiki//view/Main/WebHome/mp3.gif" width="16" height="16" alt="mp3" /> `mp3`, <img src="http://www.dementia.org/twiki//view/Main/WebHome/pdf.gif" width="16" height="16" alt="pdf" /> `pdf`, <img src="http://www.dementia.org/twiki//view/Main/WebHome/ppt.gif" width="16" height="16" alt="ppt" /> `ppt`, <img src="http://www.dementia.org/twiki//view/Main/WebHome/txt.gif" width="16" height="16" alt="txt" /> `txt`, <img src="http://www.dementia.org/twiki//view/Main/WebHome/xls.gif" width="16" height="16" alt="xls" /> `xls`, <img src="http://www.dementia.org/twiki//view/Main/WebHome/xml.gif" width="16" height="16" alt="xml" /> `xml`, <img src="http://www.dementia.org/twiki//view/Main/WebHome/zip.gif" width="16" height="16" alt="zip" /> `zip`
-- Related: [[ICONURL|Main/WebHome#VarICONURL]], [[ICONURLPATH|Main/WebHome#VarICONURLPATH]], [[TWikiPreferences]], [[FileAttachments]], [[TWikiDocGraphics]]
+- Related: [[ICONURL|Main/VarICONURL]], [[ICONURLPATH|Main/VarICONURLPATH]], [[TWikiPreferences]], [[FileAttachments]], [[TWikiDocGraphics]]
### <a name="ICONURL{"name"} -- URL of small"></a><a name="ICONURL{"name"} -- URL of small "></a> ICONURL\{"name"\} -- URL of small documentation graphic or icon
-- Generates the full URL of a [[TWikiDocGraphics]] image, which TWiki renders as an image. The related `%ICON{"name"}%` generates the full HTML img tag. Specify image name or full filename (see [[ICON|Main/WebHome#VarICON]] for details on filenames.)
+- Generates the full URL of a [[TWikiDocGraphics]] image, which TWiki renders as an image. The related `%ICON{"name"}%` generates the full HTML img tag. Specify image name or full filename (see [[ICON|Main/VarICON]] for details on filenames.)
- Syntax: `%ICONURL{"name"}%`
- Examples:
- `%ICONURL{"arrowbright"}%` returns http://www.dementia.org/twiki//view/Main/WebHome/arrowbright.gif
- `%ICONURL{"novel.pdf"}%` returns http://www.dementia.org/twiki//view/Main/WebHome/pdf.gif
- `%ICONURL{"/queen/boheme.mp3"}%` returns http://www.dementia.org/twiki//view/Main/WebHome/mp3.gif
-- Related: [[ICONURLPATH|Main/WebHome#VarICONURLPATH]], [[ICON|Main/WebHome#VarICON]], [[TWikiPreferences]], [[FileAttachments]], [[TWikiDocGraphics]]
+- Related: [[ICONURLPATH|Main/VarICONURLPATH]], [[ICON|Main/VarICON]], [[TWikiPreferences]], [[FileAttachments]], [[TWikiDocGraphics]]
### <a name="ICONURLPATH{"name"} -- URL path"></a><a name="ICONURLPATH{"name"} -- URL path "></a> ICONURLPATH\{"name"\} -- URL path of small documentation graphic or icon
-- Generates the URL path of a [[TWikiDocGraphics]] image, typically used in an HTML img tag. Specify image name or full filename (see [[ICON|Main/WebHome#VarICON]] for details on filenames.)
+- Generates the URL path of a [[TWikiDocGraphics]] image, typically used in an HTML img tag. Specify image name or full filename (see [[ICON|Main/VarICON]] for details on filenames.)
- Syntax: `%ICONURLPATH{"name"}%`
- Examples:
- `%ICONURLPATH{"locktopic"}%` returns 
- `%ICONURLPATH{"eggysmell.xml"}%` returns 
- `%ICONURLPATH{"/doc/xhtml.xsl"}%` returns 
-- Related: [[ICONURL|Main/WebHome#VarICONURL]], [[ICON|Main/WebHome#VarICON]], [[TWikiPreferences]], [[FileAttachments]], [[TWikiDocGraphics]]
+- Related: [[ICONURL|Main/VarICONURL]], [[ICON|Main/VarICON]], [[TWikiPreferences]], [[FileAttachments]], [[TWikiDocGraphics]]
- Evaluate a condition and show one text or another based on the result. See details in [[IfStatements]]
- Syntax: `%IF{"CONDITION" then="THEN" else="ELSE"}%` shows `"THEN"` if `"CONDITION"` evaluates to `TRUE`, otherwise `"ELSE"` will be shown
-- Example: `%IF{"defined FUNFACTOR" then="FUNFACTOR is defined" else=" is not defined"}%` renders as ==
+- Example: `%IF{"defined FUNFACTOR" then="FUNFACTOR is defined" else="FUNFACTOR is not defined"}%` renders as `FUNFACTOR is not defined`
- Related: [[$IF()|Main/SpreadSheetPlugin#FuncIF]] of [[SpreadSheetPlugin]]
</tr>
<tr>
<td><code>"Web.Topic"</code></td>
- <td> A topic in another web, i.e. <code>%INCLUDE{"TWiki.SiteMap"}%</code></td>
+ <td> A topic in another web, i.e. <code>%INCLUDE{"%SYSTEMWEB%.SiteMap"}%</code></td>
<td> </td>
</tr>
<tr>
</tr>
<tr>
<td><code>section="name"</code></td>
- <td> Includes only the specified named section, as defined in the included topic by the [[Main/WebHome#VarSTARTSECTION]] and [[Main/WebHome#VarENDSECTION]] variables. Nothing is shown if the named section does not exists. </td>
+ <td> Includes only the specified named section, as defined in the included topic by the [[Main/VarSTARTSECTION]] and [[Main/VarENDSECTION]] variables. Nothing is shown if the named section does not exists. </td>
<td> </td>
</tr>
<tr>
</table>
- **_Note:_** JavaScript in included webpages is filtered out as a security precaution per default (disable filter with `disableremovescript` parameter)
- Examples: See [[IncludeTopicsAndWebPages]]
-- Related: [[BASETOPIC|Main/WebHome#VarBASETOPIC]], [[BASEWEB|Main/WebHome#VarBASEWEB]], [[INCLUDINGTOPIC|Main/WebHome#VarINCLUDINGTOPIC]], [[INCLUDINGWEB|Main/WebHome#VarINCLUDINGWEB]], [[STARTINCLUDE|Main/WebHome#VarSTARTINCLUDE]], [[STOPINCLUDE|Main/WebHome#VarSTOPINCLUDE]], [[STARTSECTION|Main/WebHome#VarSTARTSECTION]], [[ENDSECTION|Main/WebHome#VarENDSECTION]]
+- Related: [[BASETOPIC|Main/VarBASETOPIC]], [[BASEWEB|Main/VarBASEWEB]], [[INCLUDINGTOPIC|Main/VarINCLUDINGTOPIC]], [[INCLUDINGWEB|Main/VarINCLUDINGWEB]], [[STARTINCLUDE|Main/VarSTARTINCLUDE]], [[STOPINCLUDE|Main/VarSTOPINCLUDE]], [[STARTSECTION|Main/VarSTARTSECTION]], [[ENDSECTION|Main/VarENDSECTION]]
- The name of the topic that includes the current topic - same as `%TOPIC%` in case there is no include
- Syntax: `%INCLUDINGTOPIC%`
-- Related: [[BASETOPIC|Main/WebHome#VarBASETOPIC]], [[INCLUDINGWEB|Main/WebHome#VarINCLUDINGWEB]], [[INCLUDE|Main/WebHome#VarINCLUDE]], [[TOPIC|Main/WebHome#VarTOPIC]]
+- Related: [[BASETOPIC|Main/VarBASETOPIC]], [[INCLUDINGWEB|Main/VarINCLUDINGWEB]], [[INCLUDE|Main/VarINCLUDE]], [[TOPIC|Main/VarTOPIC]]
- The web name of the topic that includes the current topic - same as `%WEB%` if there is no INCLUDE.
- Syntax: `%INCLUDINGWEB%`
-- Related: [[BASEWEB|Main/WebHome#VarBASEWEB]], [[INCLUDINGTOPIC|Main/WebHome#VarINCLUDINGTOPIC]], [[INCLUDE|Main/WebHome#VarINCLUDE]], [[WEB|Main/WebHome#VarWEB]]
+- Related: [[BASEWEB|Main/VarBASEWEB]], [[INCLUDINGTOPIC|Main/VarINCLUDINGTOPIC]], [[INCLUDE|Main/VarINCLUDE]], [[WEB|Main/VarWEB]]
- The language is detected from the user's browser, unless some site/web/user/session-defined setting overrides it:
- If the `LANGUAGE` preference is set, it's used as user's language instead of any language detected from the browser.
- Avoid defining `LANGUAGE` at a non per-user way, so each user can choose his/her preferred language.
-- Related: [[LANGUAGES|Main/WebHome#VarLANGUAGES]]
+- Related: [[LANGUAGES|Main/VarLANGUAGES]]
- Syntax: `%LIME% lime text %ENDCOLOR%`
- Expands to: %LIME% lime text %ENDCOLOR%
- **_Note:_** `%<color>%` text must end with `%ENDCOLOR%`. If you want to switch from one color to another one you first need to end the active color with `%ENDCOLOR%`, e.g. write `%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%`.
-- Related: [[ENDCOLOR|Main/TWikiVariables#VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
+- Related: [[ENDCOLOR|Main/VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
### <a name="LOCALSITEPREFS -- web.topicname"></a><a name="LOCALSITEPREFS -- web.topicname "></a> LOCALSITEPREFS -- web.topicname of site preferences topic
-- The full name of the local site preferences topic. This topic is read for preferences before TWiki.%TWIKIPREFSTOPIC% is read.
+- The full name of the local site preferences topic. These local site preferences overload the system level preferences defined in [[%SYSTEMWEB%.TWikiPreferences|SYSTEMWEB/TWikiPreferences]].
- Syntax: `%LOCALSITEPREFS%`
- Expands to: `Main.TWikiPreferences`, renders as [[TWikiPreferences]]
- Syntax: `%LOGIN%`
- Expand to:
-- Related: [[TWikiUserAuthentication]], [[SESSIONID|Main/WebHome#VarSESSIONID]], [[SESSIONVAR|Main/WebHome#VarSESSIONVAR]], [[LOGOUT|Main/WebHome#VarLOGOUT]], [[SESSION_VARIABLE|Main/WebHome#VarSESSION_VARIABLE]]
+- Related: [[TWikiUserAuthentication]], [[SESSIONID|Main/VarSESSIONID]], [[SESSIONVAR|Main/VarSESSIONVAR]], [[LOGOUT|Main/VarLOGOUT]], [[SESSION_VARIABLE|Main/VarSESSION_VARIABLE]]
- Syntax: `%LOGOUT%`
- Expand to: [[Main/WebHome?logout=1]]
-- Related: [[TWikiUserAuthentication]], [[SESSIONID|Main/WebHome#VarSESSIONID]], [[SESSIONVAR|Main/WebHome#VarSESSIONVAR]], [[LOGIN|Main/WebHome#VarLOGIN]], [[SESSION_VARIABLE|Main/WebHome#VarSESSION_VARIABLE]]
+- Related: [[TWikiUserAuthentication]], [[SESSIONID|Main/VarSESSIONID]], [[SESSIONVAR|Main/VarSESSIONVAR]], [[LOGIN|Main/VarLOGIN]], [[SESSION_VARIABLE|Main/VarSESSION_VARIABLE]]
- Type: Preference variable - [[TWikiRenderingShortcut]].
- Current value: M = %M%
-- Related: [[H|Main/WebHome#VarH]], [[I|Main/WebHome#VarI]], [[ICON|Main/WebHome#VarICON]], [[N|Main/WebHome#VarN]], [[P|Main/WebHome#VarP]], [[Q|Main/WebHome#VarQ]], [[S|Main/WebHome#VarS]], [[T|Main/WebHome#VarT]], [[U|Main/WebHome#VarU]], [[X|Main/WebHome#VarX]], [[Y|Main/WebHome#VarY]]
+- Related: [[H|Main/VarH]], [[I|Main/VarI]], [[ICON|Main/VarICON]], [[N|Main/VarN]], [[P|Main/VarP]], [[Q|Main/VarQ]], [[S|Main/VarS]], [[T|Main/VarT]], [[U|Main/VarU]], [[X|Main/VarX]], [[Y|Main/VarY]]
<a name="VarMAINWEB"></a>
-### <a name="MAINWEB -- name of Main web"></a> MAINWEB -- name of Main web
+### <a name="MAINWEB -- synonym forUSERSWEB"></a> MAINWEB -- synonym for [[USERSWEB|Main/VarUSERSWEB]]
-- The web containing [[TWikiUsers]], individual user topics and [[TWikiGroups]]
-- Syntax: `%MAINWEB%`
-- Expands to: `Main`
-- Related: [[TWIKIWEB|Main/WebHome#VarTWIKIWEB]]
+- Deprecated. Please use %USERSWEB% instead.
### <a name="MAKETEXT -- creates text using T"></a> MAKETEXT -- creates text using TWiki's I18N infrastructure
-- Syntax: `%MAKETEXT{"string" args="..."}`
+- Syntax: `%MAKETEXT{"string" args="..."}%`
- Supported parameters: <table border="1" cellpadding="0" cellspacing="0">
<tr>
<th bgcolor="#99CCCC"><strong> Parameter </strong></th>
- Examples:
- `%MAKETEXT{string="Notes:"}%` %BR% expands to %BR% _ Notes: _
- `%MAKETEXT{"If you have any questions, please contact [_1]." args="%WIKIWEBMASTER%"}%` %BR% expands to %BR% _ If you have any questions, please contact 0. _
- - `%MAKETEXT{"Did you want to [[[_1]][reset [_2]'s password]]?" args="%TWIKIWEB%.ResetPassword,%WIKIUSERNAME%"}%` %BR% expands to %BR% _ Did you want to [[reset Main.admin's password|TWiki/ResetPassword]]? _
+ - `%MAKETEXT{"Did you want to [[[_1]][reset [_2]'s password]]?" args="%SYSTEMWEB%.ResetPassword,%WIKIUSERNAME%"}%` %BR% expands to %BR% _ Did you want to [[reset Main.admin's password|TWiki/ResetPassword]]? _
- **_Notes:_**
- TWiki will translate the `string` to the current user's language _only_ if it has such string in its translation table for that language.
- Amperstands (`&`) followed by one letter (one of a...z, A...Z) (say, `X`) in the translatable string will be translated to `<span class='twikiAccessKey'>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.
- Syntax: `%MAROON% maroon text %ENDCOLOR%`
- Expands to: %MAROON% maroon text %ENDCOLOR%
- **_Note:_** `%<color>%` text must end with `%ENDCOLOR%`. If you want to switch from one color to another one you first need to end the active color with `%ENDCOLOR%`, e.g. write `%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%`.
-- Related: [[ENDCOLOR|Main/TWikiVariables#VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
+- Related: [[ENDCOLOR|Main/VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
</tr>
<tr>
<td><code>"formfield"</code></td>
- <td><code>name="..."</code>: name of the field. The field value can be shortened as described in [[TWiki/FormattedSearch]] for <code>$formfield</code> %BR% <code>newline="..."</code>: by default, each newline character will be rewritten to <code><br /></code> to allow metadata that contains newlines to be used in tables, etc. <code>$n</code> indicates a newline character. %BR% <code>bar="..."</code>: by default, each vertical bar is rewritten to an HTML entity so as to not be mistaken for a table separator. </td>
+ <td><code>name="..."</code>: name of the field. The field value can be shortened as described in %SYSTEMWEB%.FormattedSearch for <code>$formfield</code> %BR% <code>newline="..."</code>: by default, each newline character will be rewritten to <code><br /></code> to allow metadata that contains newlines to be used in tables, etc. <code>$n</code> indicates a newline character. %BR% <code>bar="..."</code>: by default, each vertical bar is rewritten to an HTML entity so as to not be mistaken for a table separator. </td>
<td> Show a single form field </td>
</tr>
<tr>
<td> Generates the parent link </td>
</tr>
</table>
-- Related: [[METASEARCH|Main/WebHome#VarMETASEARCH]]
+- Related: [[METASEARCH|Main/VarMETASEARCH]]
<tr>
<td><code>type="topicmoved"</code></td>
<td> What sort of search is required? <br /><code>"topicmoved"</code> if search for a topic that may have been moved <br /><code>"parent"</code> if searching for topics that have a specific parent i.e. its children <br /><code>"field"</code> if searching for topics that have a particular form field value (use the <code>name</code> and <code>value</code> parameters to specify which field to search) </td>
- <td> required </td>
+ <td> Required </td>
</tr>
<tr>
<td><code>web="%WEB%"</code></td>
<td> Wiki web to search: A web, a list of webs separated by whitespace, or <code>all</code> webs. </td>
- <td> current web </td>
+ <td> Current web </td>
</tr>
<tr>
<td><code>topic="%TOPIC%"</code></td>
<td> The topic the search relates to, for <code>topicmoved</code> and <code>parent</code> searches </td>
- <td> current topic </td>
+ <td> All topics in a web </td>
</tr>
<tr>
<td><code>name</code></td>
- <td> form field to search, for <code>field</code> type searches. May be a regular expression (see [[Main/WebHome#VarSEARCH]]). </td>
+ <td> form field to search, for <code>field</code> type searches. May be a regular expression (see [[Main/VarSEARCH]]). </td>
<td> </td>
</tr>
<tr>
<td><code>value</code></td>
- <td> form field value, for <code>field</code> type searches. May be a regular expression (see [[Main/WebHome#VarSEARCH]]). </td>
+ <td> form field value, for <code>field</code> type searches. May be a regular expression (see [[Main/VarSEARCH]]). </td>
<td> </td>
</tr>
<tr>
<td> empty </td>
</tr>
<tr>
+ <td><code>format="..."</code></td>
+ <td> Custom format results. Supports same format strings as [[Main/VarSEARCH]]. See <strong>[[Main/FormattedSearch]]</strong> for usage, variables & examples </td>
+ <td> Results in table </td>
+ </tr>
+ <tr>
<td><code>default="none"</code></td>
<td> Default text shown if no search hit </td>
- <td> empty </td>
+ <td> Empty </td>
</tr>
</table>
- Example: `%METASEARCH{type="topicmoved" web="%WEB%" topic="%TOPIC%" title="This topic used to exist and was moved to: "}%`
- Example: You may want to use this in [[WebTopicViewTemplate]] and [[WebTopicNonWikiTemplate]]:<br />`%METASEARCH{type="parent" web="%WEB%" topic="%TOPIC%" title="Children: "}%`
- Example: `%METASEARCH{type="field" name="Country" value="China"}%`
-- Related: [[SEARCH|Main/WebHome#VarSEARCH]], [[META|Main/WebHome#VarMETA]]
+- Related: [[SEARCH|Main/VarSEARCH]], [[META|Main/VarMETA]]
+- **_%X% Note:_** METASEARCH is deprecated in favour of the new and much more powerful query type search. See [[SEARCH|Main/VarSEARCH]] and [[QuerySearch]].
**_Related Topics:_** [[UserDocumentationCategory]]
- Type: Preference variable - [[TWikiRenderingShortcut]].
- Current value: N = %N%
-- Related: [[H|Main/WebHome#VarH]], [[I|Main/WebHome#VarI]], [[ICON|Main/WebHome#VarICON]], [[M|Main/WebHome#VarM]], [[P|Main/WebHome#VarP]], [[Q|Main/WebHome#VarQ]], [[S|Main/WebHome#VarS]], [[T|Main/WebHome#VarT]], [[U|Main/WebHome#VarU]], [[X|Main/WebHome#VarX]], [[Y|Main/WebHome#VarY]]
+- Related: [[H|Main/VarH]], [[I|Main/VarI]], [[ICON|Main/VarICON]], [[M|Main/VarM]], [[P|Main/VarP]], [[Q|Main/VarQ]], [[S|Main/VarS]], [[T|Main/VarT]], [[U|Main/VarU]], [[X|Main/VarX]], [[Y|Main/VarY]]
- Syntax: `%NAVY% navy text %ENDCOLOR%`
- Expands to: %NAVY% navy text %ENDCOLOR%
- **_Note:_** `%<color>%` text must end with `%ENDCOLOR%`. If you want to switch from one color to another one you first need to end the active color with `%ENDCOLOR%`, e.g. write `%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%`.
-- Related: [[ENDCOLOR|Main/TWikiVariables#VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
+- Related: [[ENDCOLOR|Main/VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
- Syntax: `%NOP{...}%` **deprecated**
- In normal topic text, expands to whatever is in the curly braces (if anything).
- **_%X% Note:_** This is deprecated. Do not use it. Use `%STARTSECTION{type="templateonly"}%` .. `%ENDSECTION{type="templateonly"}%` instead (see [[TWikiTemplates]] for more details).
-- Related: [[STARTSECTION|Main/WebHome#VarSTARTSECTION]], [[TWikiTemplates]]
+- Related: [[STARTSECTION|Main/VarSTARTSECTION]], [[TWikiTemplates]]
- Syntax: `%NOTIFYTOPIC%`
- Expands to: `WebNotify`, renders as [[WebNotify]]
-- Related: [[HOMETOPIC|Main/WebHome#VarHOMETOPIC]], [[STATISTICSTOPIC|Main/WebHome#VarSTATISTICSTOPIC]], [[TOPIC|Main/WebHome#VarTOPIC]]
+- Related: [[HOMETOPIC|Main/VarHOMETOPIC]], [[STATISTICSTOPIC|Main/VarSTATISTICSTOPIC]], [[TOPIC|Main/VarTOPIC]]
- Syntax: `%OLIVE% olive text %ENDCOLOR%`
- Expands to: %OLIVE% olive text %ENDCOLOR%
- **_Note:_** `%<color>%` text must end with `%ENDCOLOR%`. If you want to switch from one color to another one you first need to end the active color with `%ENDCOLOR%`, e.g. write `%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%`.
-- Related: [[ENDCOLOR|Main/TWikiVariables#VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
+- Related: [[ENDCOLOR|Main/VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
- Syntax: `%ORANGE% orange text %ENDCOLOR%`
- Expands to: %ORANGE% orange text %ENDCOLOR%
- **_Note:_** `%<color>%` text must end with `%ENDCOLOR%`. If you want to switch from one color to another one you first need to end the active color with `%ENDCOLOR%`, e.g. write `%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%`.
-- Related: [[ENDCOLOR|Main/TWikiVariables#VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
+- Related: [[ENDCOLOR|Main/VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
- Type: Preference variable - [[TWikiRenderingShortcut]].
- Current value: P = %P%
-- Related: [[H|Main/WebHome#VarH]], [[I|Main/WebHome#VarI]], [[ICON|Main/WebHome#VarICON]], [[M|Main/WebHome#VarM]], [[N|Main/WebHome#VarN]], [[Q|Main/WebHome#VarQ]], [[S|Main/WebHome#VarS]], [[T|Main/WebHome#VarT]], [[U|Main/WebHome#VarU]], [[X|Main/WebHome#VarX]], [[Y|Main/WebHome#VarY]]
+- Related: [[H|Main/VarH]], [[I|Main/VarI]], [[ICON|Main/VarICON]], [[M|Main/VarM]], [[N|Main/VarN]], [[Q|Main/VarQ]], [[S|Main/VarS]], [[T|Main/VarT]], [[U|Main/VarU]], [[X|Main/VarX]], [[Y|Main/VarY]]
- Syntax: `%PINK% pink text %ENDCOLOR%`
- Expands to: %PINK% pink text %ENDCOLOR%
- **_Note:_** `%<color>%` text must end with `%ENDCOLOR%`. If you want to switch from one color to another one you first need to end the active color with `%ENDCOLOR%`, e.g. write `%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%`.
-- Related: [[ENDCOLOR|Main/TWikiVariables#VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
+- Related: [[ENDCOLOR|Main/VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
- [[SmiliesPlugin]] <span>(Dakar, 8154)</span>:
- [[TablePlugin]] <span>(1.020, 12339)</span>:
- [[TwistyPlugin]] <span>(1.2.0, $Rev: 12154$)</span>:
-- Related: [[ACTIVATEDPLUGINS|Main/WebHome#VarACTIVATEDPLUGINS]], [[FAILEDPLUGINS|Main/WebHome#VarFAILEDPLUGINS]], [[PLUGINVERSION|Main/WebHome#VarPLUGINVERSION2]]
+- Related: [[ACTIVATEDPLUGINS|Main/VarACTIVATEDPLUGINS]], [[FAILEDPLUGINS|Main/VarFAILEDPLUGINS]], [[PLUGINVERSION|Main/VarPLUGINVERSION]]
- Example: `%PLUGINVERSION{"InterwikiPlugin"}%` expands to `$Rev: 11935$`
- Syntax: `%PLUGINVERSION%` to get the version of the API
- Expands to: `1.11`
-- Related: [[WIKIVERSION|Main/WebHome#VarWIKIVERSION]], [[ACTIVATEDPLUGINS|Main/WebHome#VarACTIVATEDPLUGINS]], [[FAILEDPLUGINS|Main/WebHome#FAILEDPLUGINS]], [[PLUGINDESCRIPTIONS|Main/WebHome#VarPLUGINDESCRIPTIONS]]
+- Related: [[WIKIVERSION|Main/VarWIKIVERSION]], [[ACTIVATEDPLUGINS|Main/VarACTIVATEDPLUGINS]], [[FAILEDPLUGINS|Main/WebHome#FAILEDPLUGINS]], [[PLUGINDESCRIPTIONS|Main/VarPLUGINDESCRIPTIONS]]
- Syntax: `%PUBURL%`
- Expands to: `http://www.dementia.org/twiki//view`
- Example: You can refer to a file attached to another topic with `%PUBURL%/%WEB%/OtherTopic/image.gif`
-- Related: [[ATTACHURL|Main/WebHome#VarATTACHURL]], [[ATTACHURLPATH|Main/WebHome#VarATTACHURLPATH]], [[PUBURLPATH|Main/WebHome#VarPUBURLPATH]], [[SCRIPTURL|Main/WebHome#VarSCRIPTURL]], [[SCRIPTURLPATH|Main/WebHome#VarSCRIPTURL]], [[FileAttachments]]
+- Related: [[ATTACHURL|Main/VarATTACHURL]], [[ATTACHURLPATH|Main/VarATTACHURLPATH]], [[PUBURLPATH|Main/VarPUBURLPATH]], [[SCRIPTURL|Main/VarSCRIPTURL]], [[SCRIPTURLPATH|Main/VarSCRIPTURL]], [[FileAttachments]]
- Syntax: `%PUBURLPATH%`
- Expands to: `http://www.dementia.org/twiki//view`
-- Related: [[ATTACHURL|Main/WebHome#VarATTACHURL]], [[ATTACHURLPATH|Main/WebHome#VarATTACHURLPATH]], [[PUBURL|Main/WebHome#VarPUBURL]], [[SCRIPTURL|Main/WebHome#VarSCRIPTURL]], [[SCRIPTURLPATH|Main/WebHome#VarSCRIPTURL]], [[FileAttachments]]
+- Related: [[ATTACHURL|Main/VarATTACHURL]], [[ATTACHURLPATH|Main/VarATTACHURLPATH]], [[PUBURL|Main/VarPUBURL]], [[SCRIPTURL|Main/VarSCRIPTURL]], [[SCRIPTURLPATH|Main/VarSCRIPTURL]], [[FileAttachments]]
- Syntax: `%PURPLE% purple text %ENDCOLOR%`
- Expands to: %PURPLE% purple text %ENDCOLOR%
- **_Note:_** `%<color>%` text must end with `%ENDCOLOR%`. If you want to switch from one color to another one you first need to end the active color with `%ENDCOLOR%`, e.g. write `%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%`.
-- Related: [[ENDCOLOR|Main/TWikiVariables#VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
+- Related: [[ENDCOLOR|Main/VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
- Type: Preference variable - [[TWikiRenderingShortcut]].
- Current value: Q = %Q%
-- Related: [[H|Main/WebHome#VarH]], [[I|Main/WebHome#VarI]], [[ICON|Main/WebHome#VarICON]], [[M|Main/WebHome#VarM]], [[N|Main/WebHome#VarN]], [[P|Main/WebHome#VarP]], [[S|Main/WebHome#VarS]], [[T|Main/WebHome#VarT]], [[U|Main/WebHome#VarU]], [[X|Main/WebHome#VarX]], [[Y|Main/WebHome#VarY]]
+- Related: [[H|Main/VarH]], [[I|Main/VarI]], [[ICON|Main/VarICON]], [[M|Main/VarM]], [[N|Main/VarN]], [[P|Main/VarP]], [[S|Main/VarS]], [[T|Main/VarT]], [[U|Main/VarU]], [[X|Main/VarX]], [[Y|Main/VarY]]
- Parameters:
- `format="..."` format string for each entry, default `$name=$value`
- `separator="..."` separator string, default `separator="$n"` (newline)
-- The following escape sequences are expanded in the format string: <table border="1" cellpadding="0" cellspacing="0">
+ - `encoding="..."` the encoding to apply to parameter values; see [[ENCODE|Main/VarENCODE]] for a description of the available encodings. If this parameter is not given, no encoding is performed.
+- The following escape sequences are expanded in the format string:
+
+<table border="1" cellpadding="0" cellspacing="0">
<tr>
<th bgcolor="#99CCCC"><strong> Sequence: </strong></th>
<th bgcolor="#99CCCC"><strong> Expands To: </strong></th>
<td><code>$value</code></td>
<td> String value of the parameter. Multi-valued parameters will have a "row" for each value. </td>
</tr>
- <tr>
- <td><code>$n</code> or <code>$n()</code></td>
- <td> New line. Use <code>$n()</code> if followed by alphanumeric character, e.g. write <code>Foo$n()Bar</code> instead of <code>Foo$nBar</code></td>
- </tr>
- <tr>
- <td><code>$nop</code> or <code>$nop()</code></td>
- <td> Is a "no operation". </td>
- </tr>
- <tr>
- <td><code>$quot</code></td>
- <td> Double quote (<code>"</code>) </td>
- </tr>
- <tr>
- <td><code>$percnt</code></td>
- <td> Percent sign (<code>%</code>) </td>
- </tr>
- <tr>
- <td><code>$dollar</code></td>
- <td> Dollar sign (<code>$</code>) </td>
- </tr>
</table>
+
- Example:
- - `%QUERYPARAMS{format="<input type='hidden' name='$name' value='$percntENCODE{$quot()$value$quot type=$quot()html$quot}$percnt' />"}%`
-- See also [[QUERYSTRING|Main/VarQUERYSTRING]], [[URLPARAM|Main/WebHome#VarURLPARAM]]
+ - `%QUERYPARAMS{format="<input type='hidden' name='$name' value='$value' encoding="entity" />"}%`
+- See also [[QUERYSTRING|Main/VarQUERYSTRING]], [[URLPARAM|Main/VarURLPARAM]]
- **_%X% Note:_** URLs built this way are typically restricted in length, typically to 2048 characters. If you need more space than this, you will need to use an HTML form and `%QUERYPARAMS%`.
- Syntax: `%QUERYSTRING%`
- Expands to: ` `
-- Related: [[QUERYPARAMS|Main/WebHome#VarQUERYPARAMS]], [[URLPARAM|Main/WebHome#VarURLPARAM]]
+- Related: [[QUERYPARAMS|Main/VarQUERYPARAMS]], [[URLPARAM|Main/VarURLPARAM]]
- Syntax: `%RED% red text %ENDCOLOR%`
- Expands to: %RED% red text %ENDCOLOR%
- **_Note:_** `%<color>%` text must end with `%ENDCOLOR%`. If you want to switch from one color to another one you first need to end the active color with `%ENDCOLOR%`, e.g. write `%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%`.
-- Related: [[ENDCOLOR|Main/TWikiVariables#VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
+- Related: [[ENDCOLOR|Main/VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
- Syntax: `%REMOTE_ADDR%`
- Expands to: ==
-- Related: [[HTTP_HOST|Main/WebHome#VarHTTPHOST]], [[REMOTE_PORT|Main/WebHome#VarREMOTEPORT]], [[REMOTE_USER|Main/WebHome#VarREMOTEUSER]]
+- Related: [[ENV|Main/VarENV]], [[HTTP_HOST|Main/VarHTTPHOST]], [[REMOTE_PORT|Main/VarREMOTEPORT]], [[REMOTE_USER|Main/VarREMOTEUSER]]
- Syntax: `%REMOTE_PORT%`
- Expands to: ``
-- Related: [[HTTP_HOST|Main/WebHome#VarHTTPHOST]], [[REMOTE_ADDR|Main/WebHome#VarREMOTEADDR]], [[REMOTE_USER|Main/WebHome#VarREMOTEUSER]]
+- Related: [[ENV|Main/VarENV]], [[HTTP_HOST|Main/VarHTTPHOST]], [[REMOTE_ADDR|Main/VarREMOTEADDR]], [[REMOTE_USER|Main/VarREMOTEUSER]]
- Syntax: `%REMOTE_USER%`
- Expands to: ``
-- Related: [[HTTP_HOST|Main/WebHome#VarHTTPHOST]], [[REMOTE_ADDR|Main/WebHome#VarREMOTEADDR]], [[REMOTE_PORT|Main/WebHome#VarREMOTEPORT]], [[USERNAME|Main/WebHome#VarUSERNAME]], [[WIKINAME|Main/WebHome#VarWIKINAME]], [[WIKIUSERNAME|Main/WebHome#VarWIKIUSERNAME]]
+- Related: [[ENV|Main/VarENV]], [[HTTP_HOST|Main/VarHTTPHOST]], [[REMOTE_ADDR|Main/VarREMOTEADDR]], [[REMOTE_PORT|Main/VarREMOTEPORT]], [[USERNAME|Main/VarUSERNAME]], [[WIKINAME|Main/VarWIKINAME]], [[WIKIUSERNAME|Main/VarWIKIUSERNAME]]
--- /dev/null
+<a name="VarRENDERLIST"></a>
+
+### <a name="RENDERLIST -- render bullet list"></a> RENDERLIST -- render bullet lists in a variety of formats
+
+- The `%RENDERLIST%` variable is handled by the [[RenderListPlugin]]
+- Syntax: `%RENDERLIST%`
+- Syntax: `%RENDERLIST{ "org" focus="Sales.WestCoastTeam" }%`
+- Example:%BR% `%RENDERLIST{ "org" }%` %BR% ` * [[Eng.WebHome][Engineering]]` %BR% ` * [[Eng.TechPubs][Tech Pubs]]` %BR% ` * [[Sales.WestCoastTeam][Sales]]` %BR% ` * [[Sales.EastCoastTeam][East Coast]]` %BR% ` * [[Sales.WestCoastTeam][West Coast]]`
+- Related: [[RenderListPlugin]]
- Syntax: `%REVINFO%`
- Expands to: <code>r1 - 01 Jan 1970 - 00:00:00 - [[TWikiGuest]]</code>
-- Related: [[REVINFO{"format"}|Main/WebHome#VarREVINFO2]]
+- Date format defined as \{DefaultDateFormat\} in [configure](http://www.dementia.org/twiki/configure)
+- Related: [[REVINFO{"format"}|Main/VarREVINFO2]]
</tr>
<tr>
<td><code>$wikiusername</code></td>
- <td> WikiName with Main web prefix </td>
- <td><code>Main.JohnSmith</code></td>
+ <td> WikiName with %USERSWEB% web prefix </td>
+ <td><code>%USERSWEB%.JohnSmith</code></td>
</tr>
<tr>
<td><code>$date</code></td>
- <td> Revision date </td>
+ <td> Revision date. Actual date format defined as {DefaultDateFormat} in <a href="http://www.dementia.org/twiki/configure" target="_top">configure</a></td>
<td><code>21 Sep 2006</code></td>
</tr>
<tr>
</tr>
<tr>
<td><code>$min</code>, <code>$sec</code>, etc. </td>
- <td> Same date format qualifiers as [[Main/WebHome#VarGMTIME2]]</td>
+ <td> Same date format qualifiers as [[Main/VarGMTIME2]]</td>
<td> </td>
</tr>
</table>
- Example: `%REVINFO{"$date - $wikiusername" rev="1.1"}%` returns revision info of first revision
-- Related: [[GMTIME{"format"}|Main/WebHome#VarGMTIME2]], [[REVINFO|Main/WebHome#VarREVINFO]]
+- Related: [[GMTIME{"format"}|Main/VarGMTIME2]], [[REVINFO|Main/VarREVINFO]]
- Type: Preference variable - [[TWikiRenderingShortcut]].
- Current value: S = %S%
-- Related: [[H|Main/WebHome#VarH]], [[I|Main/WebHome#VarI]], [[ICON|Main/WebHome#VarICON]], [[M|Main/WebHome#VarM]], [[N|Main/WebHome#VarN]], [[P|Main/WebHome#VarP]], [[Q|Main/WebHome#VarQ]], [[T|Main/WebHome#VarT]], [[U|Main/WebHome#VarU]], [[X|Main/WebHome#VarX]], [[Y|Main/WebHome#VarY]]
+- Related: [[H|Main/VarH]], [[I|Main/VarI]], [[ICON|Main/VarICON]], [[M|Main/VarM]], [[N|Main/VarN]], [[P|Main/VarP]], [[Q|Main/VarQ]], [[T|Main/VarT]], [[U|Main/VarU]], [[X|Main/VarX]], [[Y|Main/VarY]]
- The name of the current script is shown, including script suffix, if any (for example `viewauth.cgi`)
- Syntax: `%SCRIPTNAME%`
- Expands to: ==
-- Related: [[SCRIPTSUFFIX|Main/WebHome#VarSCRIPTSUFFIX]], [[SCRIPTURL|Main/WebHome#VarSCRIPTURL]], [[SCRIPTURLPATH|Main/WebHome#VarSCRIPTURLPATH]]
+- Related: [[SCRIPTSUFFIX|Main/VarSCRIPTSUFFIX]], [[SCRIPTURL|Main/VarSCRIPTURL]], [[SCRIPTURLPATH|Main/VarSCRIPTURLPATH]]
- Some %WIKITOOLNAME% installations require a file extension for CGI scripts, such as `.pl` or `.cgi`
- Syntax: `%SCRIPTSUFFIX%`
- Expands to: ``
-- Related: [[SCRIPTNAME|Main/WebHome#VarSCRIPTNAME]], [[SCRIPTURL|Main/WebHome#VarSCRIPTURL]], [[SCRIPTURLPATH|Main/WebHome#VarSCRIPTURLPATH]]
+- Related: [[SCRIPTNAME|Main/VarSCRIPTNAME]], [[SCRIPTURL|Main/VarSCRIPTURL]], [[SCRIPTURLPATH|Main/VarSCRIPTURLPATH]]
- Syntax: `%SCRIPTURL%`
- Expands to: `http://www.dementia.org/twiki/`
-- Related: [[PUBURL|Main/WebHome#VarPUBURL]], [[SCRIPTNAME|Main/WebHome#VarSCRIPTNAME]], [[SCRIPTSUFFIX|Main/WebHome#VarSCRIPTSUFFIX]], [[SCRIPTURL{"script"}|Main/WebHome#VarSCRIPTURL2]], [[SCRIPTURLPATH|Main/WebHome#VarSCRIPTURLPATH]]
+- **_Note:_** The `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
+- Related: [[PUBURL|Main/VarPUBURL]], [[SCRIPTNAME|Main/VarSCRIPTNAME]], [[SCRIPTSUFFIX|Main/VarSCRIPTSUFFIX]], [[SCRIPTURL{"script"}|Main/VarSCRIPTURL2]], [[SCRIPTURLPATH|Main/VarSCRIPTURLPATH]]
- Expands to: `http://www.dementia.org/twiki/script`
- Example: To get the authenticated version of the current topic you can write `%SCRIPTURL{"viewauth"}%/%WEB%/%TOPIC%` which expands to `http://www.dementia.org/twiki/viewauth/%WEB%/%INCLUDINGTOPIC%`
- **_%X% Note:_** In most cases you should use `%SCRIPTURLPATH{"script"}%` instead, as it works with URL rewriting much better
-- Related: [[PUBURL|Main/WebHome#VarPUBURL]], [[SCRIPTNAME|Main/WebHome#VarSCRIPTNAME]], [[SCRIPTSUFFIX|Main/WebHome#VarSCRIPTSUFFIX]], [[SCRIPTURL|Main/WebHome#VarSCRIPTURL]], [[SCRIPTURLPATH|Main/WebHome#VarSCRIPTURLPATH]], [[SCRIPTURLPATH{"script"}|Main/WebHome#VarSCRIPTURLPATH2]]
+- Related: [[PUBURL|Main/VarPUBURL]], [[SCRIPTNAME|Main/VarSCRIPTNAME]], [[SCRIPTSUFFIX|Main/VarSCRIPTSUFFIX]], [[SCRIPTURL|Main/VarSCRIPTURL]], [[SCRIPTURLPATH|Main/VarSCRIPTURLPATH]], [[SCRIPTURLPATH{"script"}|Main/VarSCRIPTURLPATH2]]
- As `%SCRIPTURL%`, but doesn't include the protocol and host part of the URL
- Syntax: `%SCRIPTURLPATH%`
- Expands to: `http://www.dementia.org/twiki/`
-- Related: [[PUBURLPATH|Main/WebHome#VarPUBURLPATH]], [[SCRIPTNAME|Main/WebHome#VarSCRIPTNAME]], [[SCRIPTSUFFIX|Main/WebHome#VarSCRIPTSUFFIX]], [[SCRIPTURL|Main/WebHome#VarSCRIPTURL]], [[SCRIPTURLPATH{"script"}|Main/WebHome#VarSCRIPTURLPATH2]]
+- **_Note:_** The `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
+- Related: [[PUBURLPATH|Main/VarPUBURLPATH]], [[SCRIPTNAME|Main/VarSCRIPTNAME]], [[SCRIPTSUFFIX|Main/VarSCRIPTSUFFIX]], [[SCRIPTURL|Main/VarSCRIPTURL]], [[SCRIPTURLPATH{"script"}|Main/VarSCRIPTURLPATH2]]
- As `%SCRIPTURL{"script"}%`, but doesn't include the protocol and host part of the URL
- Syntax: `%SCRIPTURLPATH{"script"}%`
- Expands to: `http://www.dementia.org/twiki/script`
-- Related: [[PUBURLPATH|Main/WebHome#VarPUBURLPATH]], [[SCRIPTNAME|Main/WebHome#VarSCRIPTNAME]], [[SCRIPTSUFFIX|Main/WebHome#VarSCRIPTSUFFIX]], [[SCRIPTURL|Main/WebHome#VarSCRIPTURL]], [[SCRIPTURL{"script"}|Main/WebHome#VarSCRIPTURL2]], [[SCRIPTURLPATH|Main/WebHome#VarSCRIPTURLPATH]]
+- Related: [[PUBURLPATH|Main/VarPUBURLPATH]], [[SCRIPTNAME|Main/VarSCRIPTNAME]], [[SCRIPTSUFFIX|Main/VarSCRIPTSUFFIX]], [[SCRIPTURL|Main/VarSCRIPTURL]], [[SCRIPTURL{"script"}|Main/VarSCRIPTURL2]], [[SCRIPTURLPATH|Main/VarSCRIPTURLPATH]]
</tr>
<tr>
<td><code>"text"</code></td>
- <td> Search term. Is a keyword search, literal search or regular expression search, depending on the <code>type</code> parameter. [[Main/SearchHelp]] has more </td>
+ <td> Search term. Is a keyword search, literal search, regular expression search, or query, depending on the <code>type</code> parameter. [[Main/SearchHelp]] has more </td>
<td> required </td>
</tr>
<tr>
<td> N/A </td>
</tr>
<tr>
- <td><code>web="Name"</code><br /><code>web="Main, Know"</code><br /><code>web="all"</code></td>
+ <td><code>web="Name"</code><br /><code>web="%USERSWEB%, Know"</code><br /><code>web="all"</code></td>
<td> Comma-separated list of webs to search. You can specifically <strong>exclude</strong> webs from an <code>all</code> search using a minus sign - for example, <code>web="all,-Secretweb"</code>. The special word <code>all</code> means all webs that do <strong>not</strong> have the <code>NOSEARCHALL</code> variable set to <code>on</code> in their [[Main/WebPreferences]]. Note that [[Main/TWikiAccessControls]] are respected when searching webs; it is <strong>much</strong> better to use them than <code>NOSEARCHALL</code>. </td>
<td> Current web </td>
</tr>
<td> None </td>
</tr>
<tr>
- <td><code>type="keyword"</code><br /><code>type="literal"</code><br /><code>type="regex"</code></td>
- <td> Do a keyword search like <code>soap "web service" -shampoo</code>; a literal search like <code>web service</code>; or [[Main/RegularExpression]] search like <code>soap;web service;!shampoo</code></td>
- <td><code>%SEARCHVAR- DEFAULTTYPE%</code> [[Main/TWikiPreferences]] setting (%SEARCHVARDEFAULTTYPE%) </td>
- </tr>
- <tr>
<td><code>scope="topic"</code><br /><code>scope="text"</code><br /><code>scope="all"</code></td>
- <td> Search topic name (title); the text (body) of topic; or all (both) </td>
+ <td> Search topic name (title); the text (body) of topic; or all (title and body) </td>
<td><code>"text"</code></td>
</tr>
<tr>
+ <td><code>type="keyword"</code><br /><code>type="word"</code><br /><code>type="literal"</code><br /><code>type="regex"</code><br /><code>type="query"</code></td>
+ <td> Control how the search is performed when <code>scope="text"</code> or <code>scope="all"</code><hr /><code>keyword</code>: use Google-like controls as in <code>soap "web service" -shampoo</code>; searches word parts: using the example, topics with "soapsuds" will be found as well, but topics with "shampoos" will be excluded <hr /><code>word</code>: identical to <code>keyword</code> but searches whole words: topics with "soapsuds" will not be found, and topics with "shampoos" will not be excluded <hr /><code>literal</code>: search for the exact string, like <code>web service</code><hr /><code>regex</code>: use a [[Main/RegularExpression]] search like <code>soap;web service;!shampoo</code>; to search on whole words use <code>\bsoap\b</code><hr /><code>query</code>: [[Main/QuerySearch]] of form fields and other meta-data, like <code>(Firstname='Emma' OR Firstname='John') AND Lastname='Peel'</code></td>
+ <td><code>%SEARCHVAR- DEFAULTTYPE%</code> [[Main/TWikiPreferences]] setting (%SEARCHVARDEFAULTTYPE%) </td>
+ </tr>
+ <tr>
<td><code>order="topic"</code><br /><code>order="created"</code><br /><code>order="modified"</code><br /><code>order="editby"</code><br /><code>order=<br /> "formfield(name)"</code></td>
<td> Sort the results of search by the topic names, topic creation time, last modified time, last editor, or named field of [[Main/TWikiForms]]. The sorting is done web by web; if you want to sort across webs, create a [[Main/FormattedSearch]] table and sort it with [[Main/TablePlugin]]'s initsort. Note that dates are sorted most recent date <strong>last</strong> (i.e at the bottom of the table). </td>
<td> Sort by topic name </td>
</tr>
<tr>
<td><code>date="..."</code></td>
- <td> limits the results to those pages with latest edit time in the given [[Main/TimeInterval]]. </td>
+ <td> limits the results to those pages with latest edit time in the given [[Main/TimeSpecifications#TimeIntervals]]. </td>
<td> All results </td>
</tr>
<tr>
<td><code>"$n"</code> (Newline) </td>
</tr>
</table>
-- Example: `%SEARCH{"wiki" web="Main" scope="topic"}%`
+- Example: `%SEARCH{"wiki" web="%USERSWEB%" scope="topic"}%`
- Example with format: `%SEARCH{"FAQ" scope="topic" nosearch="on" nototal="on" header="| *Topic: * | *Summary: * |" format="| $topic | $summary |"%` _(displays results in a table with header - [[details|Main/FormattedSearch]])_
- %H% Hint: If the TWiki:Plugins.TablePlugin is installed, you may set a `%TABLE{}%` variable just before the `%SEARCH{}%` to alter the output of a search. Example: `%TABLE{ tablewidth="90%" }%`
-- Related: [[METASEARCH|Main/WebHome#VarMETASEARCH]], [[TOPICLIST|Main/WebHome#VarTOPICLIST]], [[WEBLIST|Main/WebHome#VarWEBLIST]], [[FormattedSearch]], [[SearchHelp]], [[SearchPatternCookbook]], [[RegularExpression]]
+- Related: [[METASEARCH|Main/VarMETASEARCH]], [[TOPICLIST|Main/VarTOPICLIST]], [[WEBLIST|Main/VarWEBLIST]], [[FormattedSearch]], [[SearchHelp]], [[SearchPatternCookbook]], [[RegularExpression]]
### <a name="SERVERTIME -- server time"></a> SERVERTIME -- server time
- Syntax: `%SERVERTIME%`
-- Expands to: `29 Jun 2010 - 12:00`
+- Expands to: `29 Jun 2010 - 12:09`
+- Date format defined as \{DefaultDateFormat\} in [configure](http://www.dementia.org/twiki/configure)
- **_%X% Note:_** When used in a template topic, this variable will be expanded when the template is used to create a new topic. See [[TWikiTemplates#TemplateTopicsVars]] for details.
-- Related: [[DISPLAYTIME|Main/WebHome#VarDISPLAYTIME]], [[GMTIME|Main/WebHome#VarGMTIME]], [[SERVERTIME{"format"}|Main/WebHome#VarSERVERTIME2]]
+- Related: [[DISPLAYTIME|Main/VarDISPLAYTIME]], [[GMTIME|Main/VarGMTIME]], [[SERVERTIME{"format"}|Main/VarSERVERTIME2]]
- Same format qualifiers as `%GMTIME%`
- Syntax: `%SERVERTIME{"format"}%`
-- Example: `%SERVERTIME{"$hou:$min"}%` expands to `12:00`
+- Example: `%SERVERTIME{"$hou:$min"}%` expands to `12:09`
- **_%X% Note:_** When used in a template topic, this variable will be expanded when the template is used to create a new topic. See [[TWikiTemplates#TemplateTopicsVars]] for details.
-- Related: [[DISPLAYTIME|Main/WebHome#VarDISPLAYTIME]], [[GMTIME|Main/WebHome#VarGMTIME]], [[SERVERTIME|Main/WebHome#VarSERVERTIME]]
+- Related: [[DISPLAYTIME|Main/VarDISPLAYTIME]], [[GMTIME|Main/VarGMTIME]], [[SERVERTIME|Main/VarSERVERTIME]]
### <a name="SESSIONID -- unique ID for this"></a><a name="SESSIONID -- unique ID for this "></a> SESSIONID -- unique ID for this session
- Syntax: `%SESSIONID%`
-- Expand to: `941fd3d797f64451cc06ffcd03f96779`
-- Related: [[TWikiUserAuthentication]], [[AUTHREALM|Main/WebHome#VarAUTHREALM]], [[SESSIONVAR|Main/WebHome#VarSESSIONVAR]], [[LOGIN|Main/WebHome#VarLOGIN]], [[LOGOUT|Main/WebHome#VarLOGOUT]], [[SESSION_VARIABLE|Main/WebHome#VarSESSION_VARIABLE]]
+- Expand to: `544a3318f2c293cec889c7c1d62d6118`
+- Related: [[TWikiUserAuthentication]], [[AUTHREALM|Main/VarAUTHREALM]], [[SESSIONVAR|Main/VarSESSIONVAR]], [[LOGIN|Main/VarLOGIN]], [[LOGOUT|Main/VarLOGOUT]], [[SESSION_VARIABLE|Main/VarSESSION_VARIABLE]]
- Syntax: `%SESSIONVAR%`
- Expand to: `TWIKISID`
-- Related: [[TWikiUserAuthentication]], [[AUTHREALM|Main/WebHome#VarAUTHREALM]], [[SESSIONID|Main/WebHome#VarSESSIONID]], [[LOGIN|Main/WebHome#VarLOGIN]], [[LOGOUT|Main/WebHome#VarLOGOUT]], [[SESSION_VARIABLE|Main/WebHome#VarSESSION_VARIABLE]]
+- Related: [[TWikiUserAuthentication]], [[AUTHREALM|Main/VarAUTHREALM]], [[SESSIONID|Main/VarSESSIONID]], [[LOGIN|Main/VarLOGIN]], [[LOGOUT|Main/VarLOGOUT]], [[SESSION_VARIABLE|Main/VarSESSION_VARIABLE]]
- Syntax: `%SESSION_VARIABLE{"name" set="value"}%`
- Syntax: `%SESSION_VARIABLE{"name" clear=""}%`
- %H% Hint: The users ID is in the `AUTHUSER` session variable, and is read-only
-- Related: [[TWikiUserAuthentication]], [[AUTHREALM|Main/WebHome#VarAUTHREALM]], [[SESSIONID|Main/WebHome#VarSESSIONID]], [[SESSIONVAR|Main/WebHome#VarSESSIONVAR]], [[LOGIN|Main/WebHome#VarLOGIN]], [[LOGOUT|Main/WebHome#VarLOGOUT]]
+- Related: [[TWikiUserAuthentication]], [[AUTHREALM|Main/VarAUTHREALM]], [[SESSIONID|Main/VarSESSIONID]], [[SESSIONVAR|Main/VarSESSIONVAR]], [[LOGIN|Main/VarLOGIN]], [[LOGOUT|Main/VarLOGOUT]]
- Syntax: `%SILVER% silver text %ENDCOLOR%`
- Expands to: %SILVER% silver text %ENDCOLOR%
- **_Note:_** `%<color>%` text must end with `%ENDCOLOR%`. If you want to switch from one color to another one you first need to end the active color with `%ENDCOLOR%`, e.g. write `%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%`.
-- Related: [[ENDCOLOR|Main/TWikiVariables#VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
+- Related: [[ENDCOLOR|Main/VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
--- /dev/null
+<a name="VarSLIDESHOWEND"></a>
+
+### <a name="SLIDESHOWEND -- end slideshow"></a> SLIDESHOWEND -- end slideshow
+
+- The `%SLIDESHOWEND%` variable is handled by the [[SlideShowPlugin]]
+- Syntax: `%SLIDESHOWEND%`
+- Example: See SLIDESHOWSTART
+- Related: [[SLIDESHOWSTART|Main/WebHome#VarSLIDESHOWSTART]], [[SlideShowPlugin]]
--- /dev/null
+<a name="VarSLIDESHOWSTART"></a>
+
+### <a name="SLIDESHOWSTART -- convert a topi"></a> SLIDESHOWSTART -- convert a topic with headings into a slideshow
+
+- The `%SLIDESHOWSTART%` variable is handled by the [[SlideShowPlugin]]
+- Syntax: `%SLIDESHOWSTART%`
+- Syntax: `%SLIDESHOWSTART{ template="MyOwnSlideTemplate" }%`
+- Example:%BR% `%SLIDESHOWSTART%` %BR% `---++ Sample Slide 1` %BR% ` * Bullet 1` %BR% ` * Bullet 2` %BR% `---++ Sample Slide 2` %BR% ` * Bullet 1` %BR% ` * Bullet 2` %BR% `%SLIDESHOWEND%`
+- Related: [[SLIDESHOWEND|Main/WebHome#VarSLIDESHOWEND]], [[SlideShowPlugin]]
- Syntax: `%SPACEDTOPIC%`
- Expands to: ==
- **_%X% Note:_** This is a deprecated variable. It can be duplicated with `%ENCODE{%SPACEOUT{"%TOPIC%" separator=" *"}%}%`
-- Related: [[SPACEOUT|Main/WebHome#VarSPACEOUT]], [[TOPIC|Main/WebHome#VarTOPIC]], [[ENCODE|Main/WebHome#VarENCODE]]
+- Related: [[SPACEOUT|Main/VarSPACEOUT]], [[TOPIC|Main/VarTOPIC]], [[ENCODE|Main/VarENCODE]]
</tr>
</table>
- %T% Hint: Spaced out WikiWords are not automatically linked. To SPACEOUT a WikiWord but preserve the link use "double bracket" format. For example, `[[WebHome][%SPACEOUT{"WebHome"}%]]` expands to [[Web Home|Main/WebHome]]
-- Related: [[SPACEDTOPIC|Main/WebHome#VarSPACEDTOPIC]], [[$PROPERSPACE()|Main/SpreadSheetPlugin#FuncPROPERSPACE]] of [[SpreadSheetPlugin]]
+- Related: [[SPACEDTOPIC|Main/VarSPACEDTOPIC]], [[$PROPERSPACE()|Main/SpreadSheetPlugin#FuncPROPERSPACE]] of [[SpreadSheetPlugin]]
- If present in included topic, start to include text from this location up to the end, or up to the location of the `%STOPINCLUDE%` variable. A normal view of the topic shows everything exept the `%STARTINCLUDE%` variable itself.
- **_Note:_** If you want more than one part of the topic included, use `%STARTSECTION{type="include"}%` instead
- Syntax: `%STARTINCLUDE%`
-- Related: [[INCLUDE|Main/WebHome#VarINCLUDE]], [[STARTSECTION|Main/WebHome#VarSTARTSECTION]], [[STOPINCLUDE|Main/WebHome#VarSTOPINCLUDE]]
+- Related: [[INCLUDE|Main/VarINCLUDE]], [[STARTSECTION|Main/VarSTARTSECTION]], [[STOPINCLUDE|Main/VarSTOPINCLUDE]]
- Section boundaries are defined with `%STARTSECTION{}%` and `%ENDSECTION{}%`.
- Sections may be given a name to help identify them, and/or a type, which changes how they are used.
- - `type="section"` - the default, used for a generic section, such as a named section used by [[INCLUDE|Main/WebHome#VarINCLUDE]].
+ - `type="section"` - the default, used for a generic section, such as a named section used by [[INCLUDE|Main/VarINCLUDE]].
- `type="include"` - like `%STARTINCLUDE%` ... `%STOPINCLUDE%` except that you can have as many include blocks as you want (`%STARTINCLUDE%` is restricted to only one).
- `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 [[TWikiTemplates]] for more information.
- Syntax: `%STARTSECTION{"name"}% ................ %ENDSECTION{"name"}%`
</table>
- **_%X% Note:_** If a section is not given a name, it will be assigned one. Unnamed sections are assigned names starting with `_SECTION0` for the first unnamed section in the topic, `_SECTION1` for the second, etc..
- **_%X% Note:_** You can define nested sections. It is not recommended to overlap sections, although it is valid in TWiki. Use named sections to make sure that the correct START and ENDs are matched. Section markers are **not** displayed when a topic is viewed.
-- Related: [[ENDSECTION|Main/WebHome#VarENDSECTION]], [[INCLUDE|Main/WebHome#VarINCLUDE]], [[NOP|Main/WebHome#VarNOP]], [[STARTINCLUDE|Main/WebHome#VarSTARTINCLUDE]], [[STOPINCLUDE|Main/WebHome#VarSTOPINCLUDE]]
+- Related: [[ENDSECTION|Main/VarENDSECTION]], [[INCLUDE|Main/VarINCLUDE]], [[NOP|Main/VarNOP]], [[STARTINCLUDE|Main/VarSTARTINCLUDE]], [[STOPINCLUDE|Main/VarSTOPINCLUDE]]
- Syntax: `%STATISTICSTOPIC%`
- Expands to: `WebStatistics`, renders as [[WebStatistics]]
-- Related: [[HOMETOPIC|Main/WebHome#VarHOMETOPIC]], [[NOTIFYTOPIC|Main/WebHome#VarNOTIFYTOPIC]], [[TOPIC|Main/WebHome#VarTOPIC]]
+- Related: [[HOMETOPIC|Main/VarHOMETOPIC]], [[NOTIFYTOPIC|Main/VarNOTIFYTOPIC]], [[TOPIC|Main/VarTOPIC]]
- If present in included topic, stop to include text at this location and ignore the remaining text. A normal view of the topic shows everyting exept the `%STOPINCLUDE%` variable itself.
- Syntax: `%STOPINCLUDE%`
-- Related: [[INCLUDE|Main/WebHome#VarINCLUDE]], [[STARTINCLUDE|Main/WebHome#VarSTARTINCLUDE]]
+- Related: [[INCLUDE|Main/VarINCLUDE]], [[STARTINCLUDE|Main/VarSTARTINCLUDE]]
--- /dev/null
+<a name="VarSYSTEMWEB"></a>
+
+### <a name="SYSTEMWEB -- name of TWiki docum"></a> SYSTEMWEB -- name of TWiki documentation web
+
+- The web containing all documentation and default preference settings
+- Syntax: `%SYSTEMWEB%`
+- Expands to: `%SYSTEMWEB%`
+- Related: [[USERSWEB|Main/VarUSERSWEB]]
- Type: Preference variable - [[TWikiRenderingShortcut]].
- Current value: T = %T%
-- Related: [[H|Main/WebHome#VarH]], [[I|Main/WebHome#VarI]], [[ICON|Main/WebHome#VarICON]], [[M|Main/WebHome#VarM]], [[N|Main/WebHome#VarN]], [[P|Main/WebHome#VarP]], [[Q|Main/WebHome#VarQ]], [[S|Main/WebHome#VarS]], [[U|Main/WebHome#VarU]], [[X|Main/WebHome#VarX]], [[Y|Main/WebHome#VarY]]
+- Related: [[H|Main/VarH]], [[I|Main/VarI]], [[ICON|Main/VarICON]], [[M|Main/VarM]], [[N|Main/VarN]], [[P|Main/VarP]], [[Q|Main/VarQ]], [[S|Main/VarS]], [[U|Main/VarU]], [[X|Main/VarX]], [[Y|Main/VarY]]
--- /dev/null
+<a name="VarTABLE"></a>
+
+### <a name="TABLE{ <em>attributes</em> } -- control"></a> TABLE\{ _attributes_ \} -- control attributes of tables and sorting of table columns
+
+- The `%TABLE{}%` variable is handled by the [[TablePlugin]]
+- Syntax: <code>%TABLE\{ _attributes_ \}%</code>
+
+- Supported attributes: <table border="1" cellpadding="0" cellspacing="0">
+ <tr>
+ <th bgcolor="#99CCCC"><strong> Argument </strong></th>
+ <th bgcolor="#99CCCC"><strong> Comment </strong></th>
+ <th bgcolor="#99CCCC"><strong> Default value </strong></th>
+ <th bgcolor="#99CCCC"><strong> Example </strong></th>
+ </tr>
+ <tr>
+ <td><code>sort</code></td>
+ <td> Set table sorting by clicking headers <code>"on"</code> or <code>"off"</code>. </td>
+ <td><span>unspecified</span></td>
+ <td><code>sort="on"</code></td>
+ </tr>
+ <tr>
+ <td><code>initsort</code></td>
+ <td> Column to sort initially (<code>"1"</code> to number of columns). </td>
+ <td><span>unspecified</span></td>
+ <td><code>initsort="2"</code></td>
+ </tr>
+ <tr>
+ <td><code>initdirection</code></td>
+ <td> Initial sorting direction for <code>initsort</code>, set to <code>"up"</code> (descending) or <code>"down"</code> (ascending). </td>
+ <td><span>unspecified</span></td>
+ <td><code>initdirection="up"</code></td>
+ </tr>
+ <tr>
+ <td><code>disableallsort</code></td>
+ <td> Disable all sorting, both initsort and header sort. This is mainly used by plugins such as the [[Main/EditTablePlugin]] to disable sorting in a table while editing the table. </td>
+ <td><span>unspecified</span></td>
+ <td><code>disableallsort="on"</code></td>
+ </tr>
+ <tr>
+ <td><code>headerbg</code></td>
+ <td> Header cell background colour. </td>
+ <td><code>"#6b7f93"</code></td>
+ <td><code>headerbg="#999999"</code></td>
+ </tr>
+ <tr>
+ <td><code>headerbgsorted</code></td>
+ <td> Header cell background colour of a sorted column. </td>
+ <td> the value of <code>headerbg</code></td>
+ <td><code>headerbgsorted="#32596c"</code></td>
+ </tr>
+ <tr>
+ <td><code>headercolor</code></td>
+ <td> Header cell text colour. </td>
+ <td><code>"#ffffff"</code></td>
+ <td><code>headercolor="#0000cc"</code></td>
+ </tr>
+ <tr>
+ <td><code>databg</code></td>
+ <td> Data cell background colour, a comma separated list. Specify <code>"none"</code> for no colour, that is to use the colour/background of the page the table is on. </td>
+ <td><code>"#edf4f9,#ffffff"</code></td>
+ <td><code>databg="#f2f2f2,#ffffff"</code></td>
+ </tr>
+ <tr>
+ <td><code>databgsorted</code></td>
+ <td> Data cell background colour of a sorted column; see <code>databg</code>. </td>
+ <td> the values of <code>databg</code></td>
+ <td><code>databgsorted="#d4e8e4,#e5f5ea"</code></td>
+ </tr>
+ <tr>
+ <td><code>datacolor</code></td>
+ <td> Data cell text colour, a comma separated list. </td>
+ <td><span>unspecified</span></td>
+ <td><code>datacolor="#0000CC, #000000"</code></td>
+ </tr>
+ <tr>
+ <td><code>tableborder</code></td>
+ <td> Table border width (pixels). </td>
+ <td><code>"1"</code></td>
+ <td><code>tableborder="2"</code></td>
+ </tr>
+ <tr>
+ <td><code>tableframe</code></td>
+ <td> Table frame, set to <code>"void"</code> (no sides), <code>"above"</code> (the top side only), <code>"below"</code> (the bottom side only), <code>"hsides"</code> (the top and bottom sides only), <code>"lhs"</code> (the left-hand side only), <code>"rhs"</code> (the right-hand side only), <code>"vsides"</code> (the right and left sides only), <code>"box"</code> (all four sides), <code>"border"</code> (all four sides). </td>
+ <td><span>unspecified</span></td>
+ <td><code>tableframe="hsides"</code></td>
+ </tr>
+ <tr>
+ <td><code>tablerules</code></td>
+ <td> Table rules, set to <code>"none"</code> (no rules), <code>"groups"</code> (rules will appear between row groups and column groups only), <code>"rows"</code> (rules will appear between rows only), <code>"cols"</code> (rules will appear between columns only), <code>"all"</code> (rules will appear between all rows and columns). </td>
+ <td><span>unspecified</span></td>
+ <td><code>tablerules="rows"</code></td>
+ </tr>
+ <tr>
+ <td><code>cellpadding</code></td>
+ <td> Cell padding (pixels). </td>
+ <td><code>"0"</code></td>
+ <td><code>cellpadding="0"</code></td>
+ </tr>
+ <tr>
+ <td><code>cellspacing</code></td>
+ <td> Cell spacing (pixels). </td>
+ <td><code>"0"</code></td>
+ <td><code>cellspacing="3"</code></td>
+ </tr>
+ <tr>
+ <td><code>cellborder</code></td>
+ <td> Cell border width (pixels). </td>
+ <td><span>unspecified</span></td>
+ <td><code>cellborder="0"</code></td>
+ </tr>
+ <tr>
+ <td><code>valign</code></td>
+ <td> Vertical alignment of cells and headers, set to <code>"top"</code>, <code>"middle"</code>, <code>"bottom"</code> or <code>"baseline"</code>. </td>
+ <td><span>unspecified</span></td>
+ <td><code>valign="top"</code></td>
+ </tr>
+ <tr>
+ <td><code>headervalign</code></td>
+ <td> Vertical alignment of header cells; overrides <code>valign</code>. </td>
+ <td><span>unspecified</span></td>
+ <td><code>headervalign="top"</code></td>
+ </tr>
+ <tr>
+ <td><code>datavalign</code></td>
+ <td> Vertical alignment of data cells; overrides <code>valign</code>. </td>
+ <td><span>unspecified</span></td>
+ <td><code>datavalign="top"</code></td>
+ </tr>
+ <tr>
+ <td><code>headeralign</code></td>
+ <td> Header cell alignment, one value for all columns, or a comma separated list for different alignment of individual columns. Set to <code>"left"</code>, <code>"center"</code>, <code>"right"</code> or <code>"justify"</code>. Overrides individual cell settings. </td>
+ <td><span>unspecified</span></td>
+ <td><code>headeralign="left,right"</code></td>
+ </tr>
+ <tr>
+ <td><code>dataalign</code></td>
+ <td> Data cell alignment, one value for all columns, or a comma separated list for different alignment of individual columns. Set to <code>"left"</code>, <code>"center"</code>, <code>"right"</code> or <code>"justify"</code>. Overrides individual cell settings. </td>
+ <td><span>unspecified</span></td>
+ <td><code>dataalign="center"</code></td>
+ </tr>
+ <tr>
+ <td><code>tablewidth</code></td>
+ <td> Table width: Percentage of window width, or absolute pixel value. </td>
+ <td><span>unspecified</span></td>
+ <td><code>tablewidth="100%"</code></td>
+ </tr>
+ <tr>
+ <td><code>columnwidths</code></td>
+ <td> Column widths: Comma delimited list of column widths, percentage or absolute pixel value. </td>
+ <td><span>unspecified</span></td>
+ <td><code>columnwidths="80%,20%"</code></td>
+ </tr>
+ <tr>
+ <td><code>headerrows</code></td>
+ <td> Number of header rows to exclude from sort. (will be rendered in a HTML <code>thead</code> section) </td>
+ <td><code>"1"</code></td>
+ <td><code>headerrows="1"</code></td>
+ </tr>
+ <tr>
+ <td><code>footerrows</code></td>
+ <td> Number of footer rows to exclude from sort. (will be rendered in a HTML <code>tfoot</code> section) </td>
+ <td><code>"0"</code></td>
+ <td><code>footerrows="1"</code></td>
+ </tr>
+ <tr>
+ <td><code>id</code></td>
+ <td> Unique table identifier string, used for targeting a table with CSS. </td>
+ <td><code>tableN</code> (where N is the table order number on the page) </td>
+ <td><code>id="userTable"</code></td>
+ </tr>
+ <tr>
+ <td><code>summary</code></td>
+ <td> Table summary used by screenreaders: A summary of what the table presents. It should provide an orientation for someone who listens to the table. </td>
+ <td><span>unspecified</span></td>
+ <td><code>summary="List of subscribed users"</code></td>
+ </tr>
+ <tr>
+ <td><code>caption</code></td>
+ <td> Table caption: A title that will be displayed just above the table. </td>
+ <td><span>unspecified</span></td>
+ <td><code>caption="Users"</code></td>
+ </tr>
+</table>
+
+- Example:%BR% `%TABLE{ tableborder="0" cellpadding="4" cellspacing="3" cellborder="0" }%` %BR% `| *A1* | *B1* |` %BR% `| A2 | B2 |`
+- Related: See [[TablePlugin]] for more details
- Syntax: `%TEAL% teal text %ENDCOLOR%`
- Expands to: %TEAL% teal text %ENDCOLOR%
- **_Note:_** `%<color>%` text must end with `%ENDCOLOR%`. If you want to switch from one color to another one you first need to end the active color with `%ENDCOLOR%`, e.g. write `%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%`.
-- Related: [[ENDCOLOR|Main/TWikiVariables#VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
+- Related: [[ENDCOLOR|Main/VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
### <a name="TOC -- table of contents of curr"></a> TOC -- table of contents of current topic
- Syntax: `%TOC%`
-- Related: [[TOC{"Topic"}|Main/WebHome#VarTOC2]]
+- Related: [[TOC{"Topic"}|Main/VarTOC2]]
</tr>
</table>
- Example: `%TOC{depth="2"}%`
-- Example: `%TOC{"TWikiDocumentation" web="TWiki" title="Contents:"}%`
+- Example: `%TOC{"TWikiDocumentation" web="%SYSTEMWEB%" title="Contents:"}%`
- Example: see TWiki:Sandbox.TestTopicInclude
- %T% Hint: TOC will generate links to the headings, so when a reader clicks on a heading it will jump straight where that heading is anchored in the text. If you have two headings with exactly the same text, then their anchors will also be identical and they won't be able to jump to them. To make the anchors unique, you can add an invisible HTML comment to the text of the heading. This will be hidden in normal view, but will force the anchors to be different. For example, `---+ Heading <!--5-->`.
-- Related: [[TOC|Main/WebHome#VarTOC]]
+- Related: [[TOC|Main/VarTOC]]
- `%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.
- Syntax: `%TOPIC%`
- Expands to: `%INCLUDINGTOPIC%`, renders as [[%INCLUDINGTOPIC%|Main/INCLUDINGTOPIC]]
-- Related: [[BASETOPIC|Main/WebHome#VarBASETOPIC]], [[INCLUDINGTOPIC|Main/WebHome#VarINCLUDINGTOPIC]], [[TOPICLIST|Main/WebHome#VarTOPICLIST]], [[WEB|Main/WebHome#VarWEB]]
+- Related: [[BASETOPIC|Main/VarBASETOPIC]], [[INCLUDINGTOPIC|Main/VarINCLUDINGTOPIC]], [[TOPICLIST|Main/VarTOPICLIST]], [[WEB|Main/VarWEB]]
### <a name="TOPICLIST{"format"} -- topic ind"></a> TOPICLIST\{"format"\} -- topic index of a web
-- List of all topics in a web. The "format" defines the format of one topic item. It may include variables: The `$name` variable gets expanded to the topic name, `$qname` to double quoted name, `$marker` to `marker` parameter where topic matches `selection`, and `$web` to the name of the web.
+- List of all topics in a web. The "format" defines the format of one topic item. It may include variables: The `$topic` variable 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]].
- Syntax: `%TOPICLIST{"format" ...}%`
- Supported parameters: <table border="1" cellpadding="0" cellspacing="0">
<tr>
</tr>
<tr>
<td><code>"format"</code></td>
- <td> Format of one line, may include <code>$web</code> (name of web), <code>$name</code> (name of the topic), <code>$qname</code> (name of topic in double quotes), <code>$marker</code> (which expands to <code>marker</code> for the item matching <code>selection</code> only) </td>
- <td><code>"$name"</code></td>
+ <td> Format of one line, may include <code>$web</code> (name of web), <code>$topic</code> (name of the topic), <code>$marker</code> (which expands to <code>marker</code> for the item matching <code>selection</code> only) </td>
+ <td><code>"$topic"</code></td>
</tr>
<tr>
<td><code>format="format"</code></td>
<td> (Alternative to above) </td>
- <td><code>"$name"</code></td>
+ <td><code>"$topic"</code></td>
</tr>
<tr>
<td><code>separator=", "</code></td>
<td> Current web </td>
</tr>
</table>
-- Example: `%TOPICLIST{" * $web.$name"}%` creates a bullet list of all topics
+- Example: `%TOPICLIST{" * $web.$topic"}%` creates a bullet list of all topics
- Example: `%TOPICLIST{separator=", "}%` creates a comma separated list of all topics
-- Example: `%TOPICLIST{" <option>$name</option>"}%` creates an option list (for drop down menus)
-- Example: `<select>%TOPICLIST{" <option $marker value='$name'>$name</option>" separator=" " selection="%TOPIC%"}%</select>` creates an option list of web topics with the current topic selected
-- Related: [[SEARCH|Main/WebHome#VarSEARCH]], [[WEBLIST|Main/WebHome#VarWEBLIST]]
+- Example: `%TOPICLIST{" <option>$topic</option>"}%` creates an option list (for drop down menus)
+- Example: `<select>%TOPICLIST{" <option $marker value='$topic'>$topic</option>" separator=" " selection="%TOPIC%"}%</select>` creates an option list of web topics with the current topic selected
+- Related: [[SEARCH|Main/VarSEARCH]], [[WEBLIST|Main/VarWEBLIST]]
<a name="VarTWIKIWEB"></a>
-### <a name="TWIKIWEB -- name of TWiki docume"></a> TWIKIWEB -- name of TWiki documentation web
+### <a name="TWIKIWEB -- synonym forSYSTEMWEB"></a> TWIKIWEB -- synonym for [[SYSTEMWEB|Main/VarSYSTEMWEB]]
-- The web containing all documentation and site-wide preference settings for %WIKITOOLNAME%
-- Syntax: `%TWIKIWEB%`
-- Expands to: `TWiki`
-- Related: [[MAINWEB|Main/WebHome#VarMAINWEB]]
+- Deprecated. Please use `%SYSTEMWEB%` instead.
- Type: Preference variable - [[TWikiRenderingShortcut]].
- Current value: U = %U%
-- Related: [[H|Main/WebHome#VarH]], [[I|Main/WebHome#VarI]], [[ICON|Main/WebHome#VarICON]], [[M|Main/WebHome#VarM]], [[N|Main/WebHome#VarN]], [[P|Main/WebHome#VarP]], [[Q|Main/WebHome#VarQ]], [[S|Main/WebHome#VarS]], [[T|Main/WebHome#VarT]], [[X|Main/WebHome#VarX]], [[Y|Main/WebHome#VarY]]
+- Related: [[H|Main/VarH]], [[I|Main/VarI]], [[ICON|Main/VarICON]], [[M|Main/VarM]], [[N|Main/VarN]], [[P|Main/VarP]], [[Q|Main/VarQ]], [[S|Main/VarS]], [[T|Main/VarT]], [[X|Main/VarX]], [[Y|Main/VarY]]
</tr>
<tr>
<td><code>encode="entity"</code></td>
- <td> Encode special characters into HTML entities. See [[Main/WebHome#VarENCODE]] for more details. </td>
+ <td> Encode special characters into HTML entities. See [[Main/VarENCODE]] for more details. </td>
<td> no encoding </td>
</tr>
<tr>
</tr>
</table>
- Example: `%URLPARAM{"skin"}%` returns `print` for a `.../view/%WEB%/%INCLUDINGTOPIC%?skin=print` URL
-- **_%X% Note:_** URL parameters passed into HTML form fields must be entity [[ENCODEd|Main/WebHome#VarENCODE]].
+- **_%X% Note:_** URL parameters passed into HTML form fields must be entity [[ENCODEd|Main/VarENCODE]].
- **_%X% Note:_** Double quotes in URL parameters must be escaped when passed into other TWiki variables.%BR% Example: `%SEARCH{ "%URLPARAM{ "search" encode="quotes" }%" noheader="on" }%`
- **_%X% Note:_** When used in a template topic, this variable will be expanded when the template is used to create a new topic. See [[TWikiTemplates#TemplateTopicsVars]] for details.
- **_%X% Note:_** There is a risk that this variable could be misused for cross-site scripting.
-- Related: [[ENCODE|Main/WebHome#VarENCODE]], [[SEARCH|Main/WebHome#VarSEARCH]], [[FormattedSearch]], [[QUERYSTRING|Main/WebHome#VarQUERYSTRING]]
+- Related: [[ENCODE|Main/VarENCODE]], [[SEARCH|Main/VarSEARCH]], [[FormattedSearch]], [[QUERYSTRING|Main/VarQUERYSTRING]]
+
+**_Note_** If you have `%URLPARAM{` in the value of a URL parameter, it will be modified to `%<nop>URLPARAM{`. This is to prevent an infinite loop during expansion.
- Syntax: `%USERINFO%`
- Expands to: `admin, Main.admin, ` (comma-separated list of the username, wikiusername, and emails)
-- With formatted output, using tokens `$emails`, `$username`, `$wikiname`, `$wikiusername`, and `$groups`:
+- With formatted output, using tokens `$emails`, `$username`, `$wikiname`, `$wikiusername`, `$groups` and `$admin` ($admin returns 'true' or 'false'):
- Example: `%USERINFO{ format="$username is really $wikiname" }%`
- Expands to: `admin is really admin`
- Retrieve information about another user:
- Example: `%USERINFO{ "TWikiGuest" format="$username is really $wikiname" }%`
- Expands to: ``
- **_Note:_** The parameter should be the wikiname of a user. You can only get information about another user if the `{AntiSpam}{HideUserDetails}` configuration option is not enabled, or if you are an admin. _(User details are hidden in this TWiki)_
-- Related: [[USERNAME|Main/WebHome#VarUSERNAME]], [[WIKINAME|Main/WebHome#VarWIKINAME]], [[WIKIUSERNAME|Main/WebHome#VarWIKIUSERNAME]], [[TWikiUserAuthentication]], [[ChangeEmailAddress]]
+- Related: [[USERNAME|Main/VarUSERNAME]], [[WIKINAME|Main/VarWIKINAME]], [[WIKIUSERNAME|Main/VarWIKIUSERNAME]], [[TWikiUserAuthentication]], [[ChangeEmailAddress]]
### <a name="USERNAME -- your login username"></a> USERNAME -- your login username
-- TWiki makes names available in three formats: USERNAME like `jsmith`, WIKINAME like `JohnSmith` and WIKIUSERNAME like `Main.JohnSmith`. Un-authenticated users are all [[TWikiGuest]].
+- TWiki makes names available in three formats: USERNAME like `jsmith`, WIKINAME like `JohnSmith` and WIKIUSERNAME like `%USERSWEB%.JohnSmith`. Un-authenticated users are all %USERSWEB%.TWikiGuest.
- Syntax: `%USERNAME%`
- Expands to: `admin`
- **_%X% Note:_** When used in a template topic, this variable will be expanded when the template is used to create a new topic. See [[TWikiTemplates#TemplateTopicsVars]] for details.
-- Related: [[REMOTE_USER|Main/WebHome#VarREMOTEUSER]], [[USERINFO|Main/WebHome#VarUSERINFO]], [[WIKINAME|Main/WebHome#VarWIKINAME]], [[WIKIUSERNAME|Main/WebHome#VarWIKIUSERNAME]], [[TWikiUserAuthentication]]
+- Related: [[REMOTE_USER|Main/VarREMOTEUSER]], [[USERINFO|Main/VarUSERINFO]], [[WIKINAME|Main/VarWIKINAME]], [[WIKIUSERNAME|Main/VarWIKIUSERNAME]], [[TWikiUserAuthentication]]
--- /dev/null
+<a name="VarUSERSWEB"></a>
+
+### <a name="USERSWEB -- name of users web"></a> USERSWEB -- name of users web
+
+- The web containing individual user topics, %USERSWEB%.TWikiGroups, and customised site-wide preferences.
+- Syntax: `%USERSWEB%`
+- Expands to: `%USERSWEB%`
+- Related: [[SYSTEMWEB|Main/VarSYSTEMWEB]]
-<a name="VarVAR"></a>
+Status: 500 Content-type: text/html
-### <a name="VAR{"NAME" web="Web"} -- get a p"></a> VAR\{"NAME" web="Web"\} -- get a preference value from another web
+# Software error:
-- Syntax: `%VAR{"NAME" web="Web"}%`
-- Example: To get `%WEBBGCOLOR%` of the Main web write `%VAR{"WEBBGCOLOR" web="Main"}%`, which expands to ==
-- Related: [[WEBPREFSTOPIC|Main/WebHome#VarWEBPREFSTOPIC]]
+ Can't use an undefined value as an ARRAY reference at /tmp/TWiki/lib/TWiki/Prefs.pm line 246.
+
+For help, please send mail to this site's webmaster, giving this error message and the time and date of the error.
- The vertical bar variable can be used in TWiki tables.
- Type: Preference variable - [[TWikiRenderingShortcut]].
- Current value: VBAR = %VBAR%
-- Related: [[BR|Main/WebHome#VarBR]], [[BULLET|Main/WebHome#VarBULLET]], [[BB|Main/WebHome#VarBB]], [[BB2|Main/WebHome#VarBB2]], [[BB3|Main/WebHome#VarBB3]], [[BB4|Main/WebHome#VarBB4]]
+- Related: [[BR|Main/VarBR]], [[BULLET|Main/VarBULLET]], [[BB|Main/VarBB]], [[BB2|Main/VarBB2]], [[BB3|Main/VarBB3]], [[BB4|Main/VarBB4]], [[CARET|Main/VarCARET]]
- `%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.
- Syntax: `%WEB%`
- Expands to: `%WEB%`
-- Related: [[BASEWEB|Main/WebHome#VarBASEWEB]], [[INCLUDINGWEB|Main/WebHome#VarINCLUDINGWEB]], [[TOPIC|Main/WebHome#VarTOPIC]]
+- Related: [[BASEWEB|Main/VarBASEWEB]], [[INCLUDINGWEB|Main/VarINCLUDINGWEB]], [[TOPIC|Main/VarTOPIC]]
<td><code>"$n"</code> (new line) </td>
</tr>
<tr>
+ <td><code>web=""</code></td>
+ <td> if you specify <code>$web</code> in format, it will be replaced with this </td>
+ <td><code>""</code></td>
+ </tr>
+ <tr>
<td><code>webs="public"</code></td>
<td> Comma separated list of webs, <code>public</code> expands to all non-hidden.%BR% <strong><em>NOTE:</em></strong> Administrators will see all webs, not just the public ones </td>
<td><code>"public"</code></td>
<tr>
<td><code>selection="%WEB%"</code></td>
<td> Current value to be selected in list </td>
- <td><code>section="%WEB%"</code></td>
+ <td><code>selection="%WEB%"</code></td>
+ </tr>
+ <tr>
+ <td><code>subwebs="Sandbox"</code></td>
+ <td> show webs that are a sub-web of this one (recursivly) </td>
+ <td><code>""</code></td>
</tr>
</table>
- Example: `%WEBLIST{" * [[$name.WebHome]]"}%` - creates a bullet list of all webs.
- Example: `<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.
-- Related: [[TOPICLIST|Main/WebHome#VarTOPICLIST]], [[SEARCH|Main/WebHome#VarSEARCH]]
+- Related: [[TOPICLIST|Main/VarTOPICLIST]], [[SEARCH|Main/VarSEARCH]]
- Syntax: `%WEBPREFSTOPIC%`
- Expands to: `WebPreferences`, renders as [[WebPreferences]]
-- Related: [[HOMETOPIC|Main/WebHome#VarHOMETOPIC]], [[WIKIPREFSTOPIC|Main/WebHome#VarWIKIPREFSTOPIC]], [[VAR|Main/WebHome#VarVAR]]
+- Related: [[HOMETOPIC|Main/VarHOMETOPIC]], [[WIKIPREFSTOPIC|Main/VarWIKIPREFSTOPIC]], [[VAR|Main/VarVAR]]
- Syntax: `%WHITE% white text %ENDCOLOR%`
- Expands to: <span>%WHITE% white text %ENDCOLOR%</span> (shown with a gray background here)
- **_Note:_** `%<color>%` text must end with `%ENDCOLOR%`. If you want to switch from one color to another one you first need to end the active color with `%ENDCOLOR%`, e.g. write `%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%`.
-- Related: [[ENDCOLOR|Main/TWikiVariables#VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
+- Related: [[ENDCOLOR|Main/VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
- Expands to `%WIKIHOMEURL%`
- Defined in [[TWikiPreferences]] and normally per default set to `%SCRIPTURLPATH{"view"}%`
- **_%X% Note:_** For the top bar logo URL use `%WIKILOGOURL%` defined in [[WebPreferences]] instead.
-- Related: [[WIKITOOLNAME|Main/VarWIKITOOLNAME]]
+- Related: [[WIKITOOLNAME|Main/VarVarWIKITOOLNAME]]
### <a name="WIKINAME -- your Wiki username"></a> WIKINAME -- your Wiki username
-- The [[WikiName]] is the same as `%USERNAME%` if not defined in the [[TWikiUsers]] topic
+- The [[WikiName]] is the same as `%USERNAME%` if not defined in the %USERSWEB%.TWikiUsers topic
- Syntax: `%WIKINAME%`
- Expands to: `admin`
- **_%X% Note:_** When used in a template topic, this variable will be expanded when the template is used to create new topic. See [[TWikiTemplates#TemplateTopicsVars]] for details.
-- Related: [[REMOTE_USER|Main/WebHome#VarREMOTEUSER]], [[USERINFO|Main/WebHome#VarUSERINFO]], [[USERNAME|Main/WebHome#VarUSERNAME]], [[WIKIUSERNAME|Main/WebHome#VarWIKIUSERNAME]], [[WIKIUSERSTOPIC|Main/WebHome#VarWIKIUSERSTOPIC]]
+- Related: [[REMOTE_USER|Main/VarREMOTEUSER]], [[USERINFO|Main/VarUSERINFO]], [[USERNAME|Main/VarUSERNAME]], [[WIKIUSERNAME|Main/VarWIKIUSERNAME]], [[WIKIUSERSTOPIC|Main/VarWIKIUSERSTOPIC]]
- Syntax: `%WIKIPREFSTOPIC%`
- Expands to: `TWikiPreferences`, renders as [[TWikiPreferences]]
-- Related: [[HOMETOPIC|Main/WebHome#VarHOMETOPIC]], [[WEBPREFSTOPIC|Main/WebHome#VarWEBPREFSTOPIC]]
+- Related: [[HOMETOPIC|Main/VarHOMETOPIC]], [[WEBPREFSTOPIC|Main/VarWEBPREFSTOPIC]]
- Syntax: `%WIKITOOLNAME%`
- Expands to: `%WIKITOOLNAME%`
-- Related: [[WIKIHOMEURL|Main/WebHome#VarWIKIHOMEURL]], [[WIKIVERSION|Main/WebHome#VarWIKIVERSION]]
+- Related: [[WIKIHOMEURL|Main/VarWIKIHOMEURL]], [[WIKIVERSION|Main/VarWIKIVERSION]]
### <a name="WIKIUSERNAME -- your Wiki userna"></a> WIKIUSERNAME -- your Wiki username with web prefix
-- Your %WIKINAME% with Main web prefix, useful to point to your %WIKITOOLNAME% home page
+- Your %WIKINAME% with %USERSWEB% web prefix, useful to point to your %WIKITOOLNAME% home page
- Syntax: `%WIKIUSERNAME%`
- Expands to: `Main.admin`, renders as Main.admin
- **_%X% Note:_** When used in a template topic, this variable will be expanded when the template is used to create a new topic. See [[TWikiTemplates#TemplateTopicsVars]] for details
-- Related: [[REMOTE_USER|Main/WebHome#VarREMOTEUSER]], [[USERINFO|Main/WebHome#VarUSERINFO]], [[USERNAME|Main/WebHome#VarUSERNAME]], [[WIKINAME|Main/WebHome#VarWIKINAME]]
+- Related: [[REMOTE_USER|Main/VarREMOTEUSER]], [[USERINFO|Main/VarUSERINFO]], [[USERNAME|Main/VarUSERNAME]], [[WIKINAME|Main/VarWIKINAME]]
### <a name="WIKIUSERSTOPIC -- name of topic"></a><a name="WIKIUSERSTOPIC -- name of topic "></a> WIKIUSERSTOPIC -- name of topic listing all registers users
- Syntax: `%WIKIUSERSTOPIC%`
-- Expands to: `TWikiUsers`, with Main prefix renders as [[TWikiUsers]]
-- Related: [[WIKIUSERNAME|Main/WebHome#VarWIKIUSERNAME]]
+- Expands to: `TWikiUsers`, with %USERSWEB% prefix renders as %USERSWEB%.TWikiUsers
+- Related: [[WIKIUSERNAME|Main/VarWIKIUSERNAME]]
- Syntax: `%WIKIVERSION%`
- Expands to: `TWiki-4.1.2, Sat, 03 Mar 2007, build 13046`
-- Related: [[PLUGINVERSION|Main/WebHome#VarPLUGINVERSION]], [[WIKITOOLNAME|Main/WebHome#VarWIKITOOLNAME]]
+- Related: [[PLUGINVERSION|Main/VarPLUGINVERSION]], [[WIKITOOLNAME|Main/VarWIKITOOLNAME]]
- Type: Preference variable - [[TWikiRenderingShortcut]].
- Current value: X = %X%
-- Related: [[H|Main/WebHome#VarH]], [[I|Main/WebHome#VarI]], [[ICON|Main/WebHome#VarICON]], [[M|Main/WebHome#VarM]], [[N|Main/WebHome#VarN]], [[P|Main/WebHome#VarP]], [[Q|Main/WebHome#VarQ]], [[S|Main/WebHome#VarS]], [[T|Main/WebHome#VarT]], [[U|Main/WebHome#VarU]], [[Y|Main/WebHome#VarY]]
+- Related: [[H|Main/VarH]], [[I|Main/VarI]], [[ICON|Main/VarICON]], [[M|Main/VarM]], [[N|Main/VarN]], [[P|Main/VarP]], [[Q|Main/VarQ]], [[S|Main/VarS]], [[T|Main/VarT]], [[U|Main/VarU]], [[Y|Main/VarY]]
- Type: Preference variable - [[TWikiRenderingShortcut]].
- Current value: Y = %Y%
-- Related: [[H|Main/WebHome#VarH]], [[I|Main/WebHome#VarI]], [[ICON|Main/WebHome#VarICON]], [[M|Main/WebHome#VarM]], [[N|Main/WebHome#VarN]], [[P|Main/WebHome#VarP]], [[Q|Main/WebHome#VarQ]], [[S|Main/WebHome#VarS]], [[T|Main/WebHome#VarT]], [[U|Main/WebHome#VarU]], [[X|Main/WebHome#VarX]]
+- Related: [[H|Main/VarH]], [[I|Main/VarI]], [[ICON|Main/VarICON]], [[M|Main/VarM]], [[N|Main/VarN]], [[P|Main/VarP]], [[Q|Main/VarQ]], [[S|Main/VarS]], [[T|Main/VarT]], [[U|Main/VarU]], [[X|Main/VarX]]
- Syntax: `%YELLOW% yellow text %ENDCOLOR%`
- Expands to: %YELLOW% yellow text %ENDCOLOR%
- **_Note:_** `%<color>%` text must end with `%ENDCOLOR%`. If you want to switch from one color to another one you first need to end the active color with `%ENDCOLOR%`, e.g. write `%RED% some text %ENDCOLOR% %GREEN% more text %ENDCOLOR%`.
-- Related: [[ENDCOLOR|Main/TWikiVariables#VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
+- Related: [[ENDCOLOR|Main/VarENDCOLOR]], [[TWikiPreferences|Main/TWikiPreferences#RenderingShortcuts]], [[StandardColors]]
<title><nop>%WIKITOOLNAME%'s <nop>%INCLUDINGWEB% web</title>
<subtitle>(the description of the web, plain text with no markup and no wikiwords). TWiki is an Enterprise Collaboration Platform.</subtitle>
- %INCLUDE{"%TWIKIWEB%.WebAtomBase"}% <!--
+ %INCLUDE{"%SYSTEMWEB%.WebAtomBase"}% <!--
* Set SKIN = rss
-->
**_Note for System Administrators:_** Notification is supported by an add-on to the TWiki 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 %INCLUDINGWEB%.WebRss (for RSS 1.0 feeds) or %INCLUDINGWEB%.WebAtom (for ATOM 1.0 feeds). Learn more at [[WebRssBase]] and [[WebAtomBase]], respectively.
+**_Note:_** If you prefer a news feed, point your reader to %INCLUDINGWEB%.WebRss (for RSS 1.0 feeds) or %INCLUDINGWEB%.WebAtom (for ATOM 1.0 feeds). Learn more at %SYSTEMWEB%.WebRssBase and %SYSTEMWEB%.WebAtomBase, respectively.
--- /dev/null
+%TMPL:INCLUDE\{"view"\}%
+
+%TMPL:DEF\{"content"\}%
+
+# <a name="Create New Topic in Main Web"></a> Create New Topic in Main Web
+
+%TMPL:END%
+
+%\{ do not show the following elements \}% %TMPL:DEF\{"topicaction"\}%%TMPL:END% %TMPL:DEF\{"topicinfo"\}%%TMPL:END% %TMPL:DEF\{"toolbar"\}%%TMPL:END% %TMPL:DEF\{"topicpathinfo"\}%%TMPL:END% %TMPL:DEF\{"breadcrumb"\}%%TMPL:END% %TMPL:DEF\{"top:toolbarbuttons"\}%%TMPL:END%
+
+%TMPL:DEF\{"formstartstep"\}%%TMPL:END%
+
+%TMPL:DEF\{"formendstep"\}%%TMPL:END%
+
+%TMPL:DEF\{"topicnamestep"\}%---+++ Topic name:
+
+%TMPL:END%
+
+%TMPL:DEF\{"topicparentstep"\}%---+++ Topic parent:
+
+%TMPL:END%
+
+%TMPL:DEF\{"topictemplatestep"\}%---+++ Use template:
+
+%TMPL:END%
+
+%TMPL:DEF\{"submitstep"\}%
+
+%TMPL:END%
+
+%TMPL:DEF\{"formstart"\}%
+
+<form action="http://www.dementia.org/twiki/edit/Main/" id="newtopicform" name="newtopicform"><input name="onlynewtopic" type="hidden" value="on" />%TMPL:END% <p>
+ </p>
+ <p> %TMPL:DEF{"topicname"}%</p><input id="topic" name="topic" size="40" type="text" />%TMPL:END% <p>
+ </p>
+ <p> %TMPL:DEF{"topicparent"}%</p><input class="twikiInputField" name="topicparent" size="40" type="text" value="" /> <a href="$percntSCRIPTURLPATH{view}$percnt/$percntBASEWEB$percnt/$percntBASETOPIC$percnt?$percntQUERYSTRING$percnt;pickparent=1" id="pickparent">Pick from a list</a>%TMPL:END% <p> %TMPL:DEF{"topictemplate"}%</p><select name="templatetopic"><option value="">Default template</option>
+ <h1>TWiki Installation Error</h1>Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)</select> [[%SYSTEMWEB%/WebTemplateTopics?web=Main]] %TMPL:END% <p> %TMPL:DEF{"submit"}%</p><input id="submit" type="submit" value="Create this topic" />%TMPL:END% <p> %TMPL:DEF{"formend"}%</p>
+</form>
+
+%TMPL:END%
-<div style="float: right; width: 255px; padding: 1em; text-align: center"><a href="http://twiki.org"><img alt="Collaborate with TWiki -- visit TWiki.org" border="0" height="67" src="http://www.dementia.org/twiki//view/TWiki/TWikiLogos/T-logo-235x67-t.gif" style="margin: .3em 0" title="Collaborate with TWiki -- visit TWiki.org" width="235" /></a><br />The official TWiki site is <a href="http://twiki.org"><span>twiki.org</span></a></div>
+<div style="float: right; width: 255px; padding: 1em; text-align: center"><a href="http://twiki.org"><img alt="Collaborate with TWiki -- visit TWiki.org" border="0" height="67" src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiLogos/T-logo-235x67-t.gif" style="margin: .3em 0" title="Collaborate with TWiki -- visit TWiki.org" width="235" /></a><br />The official TWiki site is <a href="http://twiki.org"><span>twiki.org</span></a></div>
# <a name="Welcome to the %WEB% Web"></a><a name=" Welcome to the %WEB% Web"></a> Welcome to the %WEB% Web
_The place to learn about TWiki features and perform TWiki system maintenance._
+This site is running TWiki version **TWiki-4.1.2, Sat, 03 Mar 2007, build 13046**, Plugin API version **1\.11**
+
TWiki is a flexible, powerful, secure, yet simple web-based collaboration platform. Use TWiki to run a project development space, a document management system, a knowledge base or any other groupware tool on either an intranet or on the Internet.
## <a name="TWiki Documentation and Configur"></a> TWiki Documentation and Configuration
- [[Frequently Asked Questions|Main/TWikiFAQ]] - about TWiki
- [[Reference Manual|Main/TWikiReferenceManual]] - documentation for system administrators
- [[Admin Tools|Main/AdminToolsCategory]] - manage the TWiki site
-- [[TWiki-4.1 Release Notes|Main/TWikiReleaseNotes04x01]] - describes what's new in this release
+- [[TWiki-4.2 Release Notes|Main/TWikiReleaseNotes04x02]] - describes what's new in this release
## <a name="%WEB% Web Utilities"></a> %WEB% Web Utilities
- TWiki™, the [[TWiki logo|Main/TWikiLogos]] and the "Collaborate with TWiki" tagline are trademarks of [Peter Thoeny](http://twiki.org/cgi-bin/view/Main/PeterThoeny)
- **_Note_**: Twiki (with a lower case "w") is a robot character from the _Buck Rogers™ in the 25th Century_ TV series. TWiki (with an upper case "W") is not affiliated with the Dille Family Trust, the registered trademark owner of the _Buck Rogers_ name
- TWiki is developed as Free Software under the [[GNU/GPL|Main/GnuGeneralPublicLicense]]
-- This site is running TWiki version **TWiki-4.1.2, Sat, 03 Mar 2007, build 13046**, Plugin API version **1\.11**
- Get the latest version from [TWiki.org downloads](http://TWiki.org/download.html)
- **[[ %INCLUDINGWEB% Web|INCLUDINGWEB/WebHome]]**
-- [[ Users|Main/TWikiUsers]]
-- [[ Groups|Main/TWikiGroups]]
+- [[ $percntICON{"person"}$percnt $percntMAKETEXT{"Users"}$percnt|PercntUSERSWEBPercnt/TWikiUsers]]
+- [[ Groups|USERSWEB/TWikiGroups]]
- [[ Index|Main/WebTopicList]]
- [[ Search|INCLUDINGWEB/WebSearch]]
- [[ Changes|Main/WebChanges]]
- [[ Notifications|Main/WebNotify]]
+- [[ RSS Feed|Main/WebRss]]
- [[ Statistics|Main/WebStatistics]]
- [[ Preferences|Main/WebPreferences]]
- **Webs**
-<div><a href="http://www.dementia.org/twiki/edit/Main/adminLeftBar?templatetopic=TWiki.WebLeftBarPersonalTemplate">Create personal sidebar</a></div>
+<div><a href="http://www.dementia.org/twiki/edit/%USERSWEB%/adminLeftBar?templatetopic=%SYSTEMWEB%.WebLeftBarPersonalTemplate">Create personal sidebar</a></div>
</ul>
<div>
<ul>
- <li><a href="http://www.dementia.org/twiki/edit/Main/adminLeftBar?templatetopic=TWiki.WebLeftBarPersonalTemplate&topicparent=admin">Create personal sidebar</a></li>
+ <li><a href="http://www.dementia.org/twiki/edit/%USERSWEB%/adminLeftBar?templatetopic=%SYSTEMWEB%.WebLeftBarPersonalTemplate&topicparent=admin">Create personal sidebar</a></li>
</ul>
</div>
</div>
-Customise this topic; samples and ideas available at TWiki:TWiki.WebLeftBarCookbook.
-
**My links:**
- [[My home page|Main/Admin]]
-This is a subscription service to be automatically notified by e-mail when topics change in this **%WEB%** web. This is a convenient service, so you do not have to come back and check all the time if something has changed. To subscribe, please add a bullet with your [[WikiName]] in alphabetical order to this list:
+This is a subscription service to be automatically notified by e-mail when topics change in this **%WEB%** web. This is a convenient service, so you do not have to come back and check all the time if something has changed. To subscribe, please add a bullet with your %SYSTEMWEB%.WikiName in alphabetical order to this list:
-- [[TWikiGuest]] - <example@your.company>
+- %USERSWEB%.TWikiGuest - <example@your.company>
-**_Related topics:_** [[WebChangesAlert]], [[TWikiUsers]], [[TWikiRegistration]]
+**_Related topics:_** %SYSTEMWEB%.WebChangesAlert, %USERSWEB%.TWikiUsers, %SYSTEMWEB%.TWikiRegistration
# <a name="%WEB% Web Preferences"></a><a name=" %WEB% Web Preferences"></a> %WEB% Web Preferences
-The following settings are **_web preferences_** of the [[%WEB%|WEB/WebHome]] web. These preferences overwrite the **_site-level preferences_** in [[TWiki.TWikiPreferences|TWiki/TWikiPreferences]] and [[Main.TWikiPreferences|Main/TWikiPreferences]], and can be overwritten by **_user preferences_** (your personal topic, eg: Main.admin in the [[Main|Main/WebHome]] web).
+The following settings are **_web preferences_** of the [[%WEB%|WEB/WebHome]] web. These preferences overwrite the **_site-level preferences_** in [[%SYSTEMWEB%.TWikiPreferences|SYSTEMWEB/TWikiPreferences]] and [[Main.TWikiPreferences|Main/TWikiPreferences]], and can be overwritten by **_user preferences_** (your personal topic, eg: %USERSWEB%.admin in the [[%USERSWEB%|USERSWEB/WebHome]] web).
<div>
<ul>
## <a name="Web Preferences Settings"></a> Web Preferences Settings
-These settings override the defaults for this web only. See [[full list of defaults with explanation|TWiki/TWikiPreferences#DefaultWebPreferences]].
+These settings override the defaults for this web only. See [[full list of defaults with explanation|SYSTEMWEB/TWikiPreferences#DefaultWebPreferences]].
- Web settings:
- Set WEBTOPICLIST = [[Welcome|Main/WelcomeGuest]] | [[Register|Main/TWikiRegistration]] | [[Changes|Main/WebChanges]] | [[Topics|Main/WebTopicList]] | [[Index|Main/WebIndex]] | [[Search|Main/WebSearch]] | Go <input name="topic" size="16" type="text" />
- Set WEBBGCOLOR = #FFD8AA
- - Set WEBHEADERART = 
+ - Set WEBHEADERART = 
- Set SITEMAPLIST = on
- Set SITEMAPWHAT = [[Welcome|WEB/WelcomeGuest]], [[Registration|WEB/TWikiRegistration]], and other %WEB%.StartingPoints; TWiki history & Wiki style; All the docs...
- Set SITEMAPUSETO = ...discover TWiki details, and how to start your own site.
+ - Hide Table of Contents if the topic is included
+ - Set TOC\_HIDE\_IF\_INCLUDED = on
+ - Set default Table of Contents title
+ - Set TOC\_TITLE = On this page:
+ - The first header level to appear in the TOC:
+ - Set TOC\_MIN\_DEPTH = 2
- Default template for **new topics** for this web:
- [[WebTopicEditTemplate]]: Site-level default topic template
-- Comma separated list of **forms** that can be attached to topics in this web. See [[TWikiForms]] for more information.
+- Comma separated list of **forms** that can be attached to topics in this web. See %SYSTEMWEB%.TWikiForms for more information.
- Set WEBFORMS = [[TWikiPreferencesForm]]
-- Users or groups who **_are not_** / **_are_** allowed to **_view_** / **_change_** / **_rename_** topics in the %WEB% web: (See [[TWikiAccessControl]]).
- - #Set DENYWEBVIEW =
- - #Set ALLOWWEBVIEW =
- - #Set DENYWEBCHANGE =
- - Set ALLOWWEBCHANGE = [[TWikiAdminGroup]]
+- Copyright notice for the TWiki web.
+ - Set WEBCOPYRIGHT = <span> [<img src="http://www.dementia.org/twiki//view/%SYSTEMWEB%/TWikiLogos/T-badge-88x31.gif" width="88" height="31" alt="This site is powered by the TWiki collaboration platform" title="This site is powered by the TWiki collaboration platform" />](http://twiki.org/)</span>Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors. <br /> Ideas, requests, problems regarding %WIKITOOLNAME%? [Send feedback](mailto:?subject=%WIKITOOLNAME%%20Feedback%20on%20Main.WebHome)
-- Users or groups allowed to change or rename this %TOPIC% topic: (e.g., [[TWikiAdminGroup]])
- - Set ALLOWTOPICCHANGE = [[TWikiAdminGroup]]
+- Users or groups who **_are not_** / **_are_** allowed to **_view_** / **_change_** / **_rename_** topics in the %WEB% web: (See %SYSTEMWEB%.TWikiAccessControl).
+ - Set ALLOWWEBCHANGE = %USERSWEB%.TWikiAdminGroup
+ - Set ALLOWWEBRENAME = %USERSWEB%.TWikiAdminGroup
+
+- Users or groups allowed to change or rename this %TOPIC% topic: (e.g., %USERSWEB%.WebAdministratorsGroup)
+ - Set ALLOWTOPICCHANGE = %USERSWEB%.TWikiAdminGroup
- Web preferences that are **not** allowed to be overridden by user or topic preferences:
- - Set FINALPREFERENCES = NOSEARCHALL, ATTACHFILESIZELIMIT, WIKIWEBMASTER, WEBCOPYRIGHT, WEBTOPICLIST, DENYWEBVIEW, ALLOWWEBVIEW, DENYWEBCHANGE, ALLOWWEBCHANGE, ALLOWWEBMANAGE, DENYWEBMANAGE
+ - Set FINALPREFERENCES = NOSEARCHALL, ATTACHFILESIZELIMIT, WIKIWEBMASTER, WEBCOPYRIGHT, WEBTOPICLIST, DENYWEBVIEW, ALLOWWEBVIEW, DENYWEBCHANGE, ALLOWWEBCHANGE, ALLOWWEBRENAME, DENYWEBRENAME
- A preference setting is defined by: <br />`3 or 6 spaces * Set NAME = value`<br /> Example:
- Set WEBBGCOLOR = #FFFFC0
- A preferences setting can be disabled with a # sign. Remove the # sign to enable a local customisation. Example:%BR%
- - #Set DENYWEBCHANGE = [[UnknownUser]]
-- Preferences are used as [[TWikiVariables]] by enclosing the name in percent signs. Example:
+ - #Set DENYWEBCHANGE = %USERSWEB%.UnknownUser
+- Preferences are used as %SYSTEMWEB%.TWikiVariables by enclosing the name in percent signs. Example:
- When you write variable `%WEBBGCOLOR%` , it gets expanded to `%WEBBGCOLOR%`
- The sequential order of the preference settings is significant. Define preferences that use other preferences first, i.e. set `WEBCOPYRIGHT` before `WIKIWEBMASTER` since `%WEBCOPYRIGHT%` uses the `%WIKIWEBMASTER%` variable.
- You can introduce your own preferences variables and use them in your topics and templates.
## <a name="Related Topics"></a> Related Topics
-- [[TWiki.TWikiPreferences|TWiki/TWikiPreferences]], [[Main.TWikiPreferences|Main/TWikiPreferences]] - site-level preferences
-- [[TWikiUsers]] - list of user topics. User topics can have optional user preferences
-- [[TWikiVariables]] - list of common `%VARIABLES%`
-- [[TWikiAccessControl]] - explains how to restrict access by users or groups
+- [[%SYSTEMWEB%.TWikiPreferences|SYSTEMWEB/TWikiPreferences]], [[Main.TWikiPreferences|Main/TWikiPreferences]] - site-level preferences
+- %USERSWEB%.TWikiUsers - list of user topics. User topics can have optional user preferences
+- %SYSTEMWEB%.TWikiVariables - list of common `%VARIABLES%`
+- %SYSTEMWEB%.TWikiAccessControl - explains how to restrict access by users or groups
## <a name="Tools"></a> Tools
<title>%WIKITOOLNAME%'s <nop>%INCLUDINGWEB% web</title>
<link>%SCRIPTURL{"view"}%/%INCLUDINGWEB%</link>
<description>(the description of the web). TWiki is a Web-Based Collaboration Platform for the Enterprise.</description>
- %INCLUDE{"TWiki.WebRssBase"}% <!--
+ %INCLUDE{"%SYSTEMWEB%.WebRssBase"}% <!--
* Set SKIN = rss
-->
<a name="twikiSearchForm"></a>
<div>
- <form action="http://www.dementia.org/twiki/view/%INCLUDINGWEB%/%INCLUDINGTOPIC%">
+ <form action="http://www.dementia.org/twiki/view/%INCLUDINGWEB%/%INCLUDINGTOPIC%" id="twikiWebSearchForm">
<table border="0" cellpadding="0" cellspacing="0" id="twikiSearchTable">
<tr>
- <td colspan="2"><input name="search" size="40" type="text" value="" /> <input type="submit" value="Search" /><span> [[INCLUDINGWEB/WebSearchAdvanced]] | [[TWiki/SearchHelp]]</span><div style="padding: 1em 0 0 0">TIP: to search for all topics that contain <code>"SOAP"</code>, <code>"WSDL"</code>, a literal <code>"web service"</code>, but not <code>"shampoo"</code>, write: <code>soap wsdl "web service" -shampoo</code></div>
+ <td colspan="2"><input name="search" size="40" type="text" value="" /> <input type="submit" value="Search" /><span> [[%INCLUDINGWEB%/WebSearchAdvanced?search=;type=word;scope=;web=;nosearch=]] | [[SYSTEMWEB/SearchHelp]]</span><div style="padding: 1em 0 0 0">TIP: to search for all topics that contain <code>"SOAP"</code>, <code>"WSDL"</code>, a literal <code>"web service"</code>, but not <code>"shampoo"</code>, write: <code>soap wsdl "web service" -shampoo</code></div>
</td>
</tr>
<tr>
<th>Search where:</th>
- <td><input checked id="textbody" name="scope" type="radio" value="text" /><label for="textbody"> Text body</label> <input id="topictitle" name="scope" type="radio" value="topic" /><label for="topictitle"> Topic title</label> <input id="both" name="scope" type="radio" value="all" /><label for="both"> Both body and title</label>
+ <td><input id="textbody" name="scope" type="radio" value="text" /><label for="textbody"> Text body</label> <input id="topictitle" name="scope" type="radio" value="topic" /><label for="topictitle"> Topic title</label> <input checked id="both" name="scope" type="radio" value="all" /><label for="both"> Both body and title</label>
<hr /><input id="web" name="web" type="checkbox" /><label for="web"> All public webs</label><span>(otherwise search %INCLUDINGWEB% Web only)</span></td>
</tr>
</table>
</div>
<div><strong>Other search options:</strong><ul>
- <li><img align="top" alt="arrowright" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/arrowright.gif" width="16" /> If you already know the name of the topic, enter the name of the topic into the [[TWiki/GoBox]] at the top </li>
+ <li><img align="top" alt="arrowright" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/arrowright.gif" width="16" /> If you already know the name of the topic, enter the name of the topic into the [[SYSTEMWEB/GoBox]] at the top </li>
<li><img align="top" alt="indexlist" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/indexlist.gif" width="16" /> <a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=\.*">List all topics in the %INCLUDINGWEB% web in alphabetical order</a></li>
<li><img align="top" alt="filter" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/filter.gif" width="16" /> List topics that start with the letter: <a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ea">A</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Eb">B</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ec">C</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ed">D</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ee">E</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ef">F</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Eg">G</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Eh">H</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ei">I</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ej">J</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ek">K</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5El">L</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Em">M</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5En">N</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Eo">O</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ep">P</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Eq">Q</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Er">R</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Es">S</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Et">T</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Eu">U</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ev">V</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ew">W</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ex">X</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ey">Y</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ez">Z</a></li>
<li><img align="top" alt="recentchanges" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/recentchanges.gif" width="16" /> [[INCLUDINGWEB/WebChanges]]</li>
<a name="twikiSearchForm"></a>
<div>
- <form action="http://www.dementia.org/twiki/view/%INCLUDINGWEB%/%INCLUDINGTOPIC%">
+ <form action="http://www.dementia.org/twiki/view/%INCLUDINGWEB%/%INCLUDINGTOPIC%" id="twikiWebSearchForm">
<table border="0" cellpadding="0" cellspacing="0" id="twikiSearchTable">
<tr>
- <td colspan="2"><input name="search" size="40" type="text" value="" /> <input type="submit" value="Search" /><span> [[INCLUDINGWEB/WebSearch]] | [[TWiki/SearchHelp]]</span><div style="padding: 1em 0 0 0">TIP: to search for all topics that contain <code>"SOAP"</code>, <code>"WSDL"</code>, a literal <code>"web service"</code>, but not <code>"shampoo"</code>, write: <code>soap wsdl "web service" -shampoo</code></div>
+ <td colspan="2"><input name="search" size="40" type="text" value="" /> <input type="submit" value="Search" /><span> [[%INCLUDINGWEB%/WebSearchAdvanced?search=;type=word;scope=;web=;nosearch=]] | [[SYSTEMWEB/SearchHelp]]</span><div style="padding: 1em 0 0 0">TIP: to search for all topics that contain <code>"SOAP"</code>, <code>"WSDL"</code>, a literal <code>"web service"</code>, but not <code>"shampoo"</code>, write: <code>soap wsdl "web service" -shampoo</code></div>
</td>
</tr>
<tr>
<th>Search where:</th>
- <td><input checked id="textbody" name="scope" type="radio" value="text" /><label for="textbody"> Text body</label>
+ <td><input id="textbody" name="scope" type="radio" value="text" /><label for="textbody"> Text body</label>
<br /><input id="topictitle" name="scope" type="radio" value="topic" /><label for="topictitle"> Topic title</label>
- <br /><input id="both" name="scope" type="radio" value="all" /><label for="both"> Both body and title</label>
+ <br /><input checked id="both" name="scope" type="radio" value="all" /><label for="both"> Both body and title</label>
<hr /><input id="web" name="web" type="checkbox" /><label for="web"> All public webs</label><span>(otherwise search %INCLUDINGWEB% Web only)</span></td>
</tr>
<tr>
<tr>
<th>Make search:</th>
<td><input id="casesensitive" name="casesensitive" type="checkbox" /><label for="casesensitive"> Case sensitive</label>
- <br /><input id="regex" name="regex" type="checkbox" /><label for="regex"> Regular expression search</label><span>(semicolon <code>;</code> for and) [[TWiki/RegularExpression]]</span></td>
+ <br /><input id="regex" name="regex" type="checkbox" /><label for="regex"> Regular expression search</label><span>(semicolon <code>;</code> for and) [[SYSTEMWEB/RegularExpression]]</span></td>
</tr>
<tr>
<th><b>Don't show:</b></th>
</tr>
<tr>
<th>Do show:</th>
- <td><input id="bookview" name="bookview" type="checkbox" /><label for="bookview"> BookView</label><span>[[TWiki/BookView]]</span></td>
+ <td><input id="bookview" name="bookview" type="checkbox" /><label for="bookview"> BookView</label><span>[[SYSTEMWEB/BookView]]</span></td>
</tr>
<tr>
<th>Limit results to:</th>
</div>
<div><strong>Other search options:</strong><ul>
- <li> If you already know the name of the topic, enter the name of the topic into the [[TWiki/GoBox]] at the top </li>
+ <li> If you already know the name of the topic, enter the name of the topic into the [[SYSTEMWEB/GoBox]] at the top </li>
<li><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=\.*">List all topics in the %INCLUDINGWEB% web in alphabetical order</a></li>
<li> List topics that start with the letter: <a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ea">A</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Eb">B</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ec">C</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ed">D</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ee">E</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ef">F</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Eg">G</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Eh">H</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ei">I</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ej">J</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ek">K</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5El">L</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Em">M</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5En">N</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Eo">O</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ep">P</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Eq">Q</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Er">R</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Es">S</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Et">T</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Eu">U</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ev">V</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ew">W</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ex">X</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ey">Y</a><span> | </span><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&search=%5Ez">Z</a></li>
- <li><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&bookview=on&search=\.*">All topics in BookView</a> <span>([[TWiki/BookView]])</span></li>
+ <li><a href="http://www.dementia.org/twiki/search/%INCLUDINGWEB%/?scope=topic®ex=on&bookview=on&search=\.*">All topics in BookView</a> <span>([[SYSTEMWEB/BookView]])</span></li>
<li>[[INCLUDINGWEB/WebChanges]]</li>
</ul>
</div>
<li>[[INCLUDINGWEB/WebIndex]]: List all %INCLUDINGWEB% topics in alphabetical order. See also the faster [[INCLUDINGWEB/WebTopicList]]</li>
<li>[[INCLUDINGWEB/WebNotify]]: Subscribe to an e-mail alert sent when something changes in the %INCLUDINGWEB% web </li>
<li>[[INCLUDINGWEB/WebStatistics]]: View access statistics of the %INCLUDINGWEB% web </li>
- <li>[[INCLUDINGWEB/WebPreferences]]: Preferences of the %INCLUDINGWEB% web ([[TWiki/TWikiPreferences]] has site-wide preferences) </li>
+ <li>[[INCLUDINGWEB/WebPreferences]]: Preferences of the %INCLUDINGWEB% web ([[SYSTEMWEB/TWikiPreferences]] has site-wide preferences) </li>
</ul>
</form>
----
- The list above provides the [[TWikiSiteTools]] used to navigate, search and maintain a particular web. It is included within other topics using the following directive:
- `%INCLUDE{"%TWIKIWEB%.WebSiteTools"}%`
+ `%INCLUDE{"%SYSTEMWEB%.WebSiteTools"}%`
- [List](http://www.dementia.org/twiki/search/%WEB%?scope=text&web=all®ex=on&search=INCLUDE.*WebSiteTools&casesensitive=on&nosummary=on¬otal=on) all topics which include this WebSiteTools topic.
**_Notes:_**
- Do not edit this topic; it is updated automatically. (You can also [force](http://www.dementia.org/twiki/statistics/%WEB%) an update)
-- [[TWikiDocumentation]] tells you how to enable the automatic updates of the statistics.
+- %SYSTEMWEB%.TWikiDocumentation tells you how to enable the automatic updates of the statistics.
- Suggestion: You could archive this topic once a year and delete the previous year's statistics from the table.
-# <a name="Web template topics"></a><a name=" Web template topics"></a> Web template topics
+# <a name="Topic templates in %WEB% Web"></a><a name=" Topic templates in %WEB% Web"></a> Topic templates in %WEB% Web
-**Template topics define the default text for new topics.**
+**A topic template defines the initial content of a newly created topic.**
Available templates in %WEB% Web:
-<table border="0" cellpadding="0" cellspacing="0" style="width: 100%; margin-top: 11px">
+<table border="0" cellpadding="0" cellspacing="0" style="width: 100%; margin-top: 12px">
<tr>
- <td valign="middle"><a href="%WEBLOGOURL%"><img alt="%WEBLOGOALT%" border="0" src="%WEBLOGOIMG%" /></a></td>
+ <td valign="middle"><span id="twikiLogo"><a href="%WEBLOGOURL%"><img alt="%WEBLOGOALT%" border="0" src="%WEBLOGOIMG%" style="border: none" /></a></span></td>
<td align="right" valign="top">
<ul>
<li>
- <form action="http://www.dementia.org/twiki/view/Main/WebHome" name="jumpForm"><input id="jumpFormField" name="topic" onblur="setDefaultText(this);" onfocus="clearDefaultandCSS(this);" size="14" type="text" value="Jump" /></form>
+ <form action="http://www.dementia.org/twiki/view/Main/WebHome" name="jumpForm"><input id="jumpFormField" name="topic" size="18" type="text" value="" /><noscript> <input name="submit" size="5" type="submit" value="Jump" /> </noscript>
+ </form>
</li>
<li>
- <form action="http://www.dementia.org/twiki/view/%INCLUDINGWEB%/WebSearch" name="quickSearchForm"><input name="search" onblur="setDefaultText(this);" onfocus="clearDefaultandCSS(this);" size="14" type="text" value="Search" /></form>
+ <form action="http://www.dementia.org/twiki/view/%INCLUDINGWEB%/WebSearch" name="quickSearchForm"><input id="quickSearchBox" name="search" size="18" type="text" value="" /><input name="scope" type="hidden" value="all" /><input name="web" type="hidden" value="Main" /><noscript> <input name="submit" size="5" type="submit" value="Search" /> </noscript>
+ </form>
</li>
<li>
</li>
-# <a name="Create New Topic in Main Web"></a> Create New Topic in Main Web
+# <a name="'Create New Topic' page has move"></a> 'Create New Topic' page has moved
-<form action="http://www.dementia.org/twiki/edit/Main/" id="newtopic" name="newtopic" onsubmit="return canSubmit(this,true);"><input name="onlywikiname" type="hidden" /><input name="onlynewtopic" type="hidden" value="on" /><div>
- <div>
- <h3><a name="Topic name:"></a> Topic name: </h3>
- <p>
- </p><input id="topic" name="topic" onblur="canSubmit(this.form,true);" onchange="canSubmit(this.form,false);" onkeyup="canSubmit(this.form,false);" size="40" tabindex="10" type="text" /> <span id="webTopicCreatorFeedback"></span><p>
- </p><input id="nonwikiword" name="nonwikiword" onchange="canSubmit(this.form,false);" onmouseup="canSubmit(this.form,false);" tabindex="11" type="checkbox" /><label for="nonwikiword">Allow non WikiWord for the new topic name</label>
- <br /><span>It's usually best to choose a <a href="TWiki" onclick="return launchWindow('TWiki','WikiWord')" rel="nofollow" target="WikiWord">WikiWord</a> for the new topic name, otherwise automatic linking may not work. Characters not allowed in topic names, such as spaces will automatically be removed.</span></div>
- <div>
- <h3><a name="Topic parent:"></a> Topic parent: </h3>
- <p>
- </p><select name="topicparent" size="10" tabindex="12"><p>
- </p>
- <option value="">(no parent, orphaned topic)</option></select></div>
- <div>
- <h3><a name="Use template:"></a> Use template: </h3>
- <p>
- </p><select name="templatetopic"><option value="">Default template</option>
- <h1>TWiki Installation Error</h1>Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)</select> [[TWiki/WebTemplateTopics?web=Main]]</div>
- <div>
- <p>
- </p><input id="submit" tabindex="13" type="submit" value="Create this topic" /></div>
- </div>
+**[[Continue to create the new page|Main/WebHome?create=on&newtopic=&topicparent=&template=WebCreateNewTopic]]**
+
+<div>
+ <h3><a name="TWiki admins"></a> TWiki admins </h3>
+ <p> Please replace all web's WebTopicCreator topic contents with this text: </p>
<p>
</p>
-</form>
-
-%BR%
-
-<div><img align="top" alt="info" border="0" height="16" src="http://www.dementia.org/twiki//view/Main/WebHome/info.gif" width="16" /> Once you have created the topic, consider adding links in related topics to the new topic so that there are more ways people can discover it. </div>
+ <textarea rows="3" style="width: 99%; background: #ffe">
+<!-- <ul>
+<li> Local VIEW_TEMPLATE = WebCreateNewTopic
+</li></ul>
+-->
+</textarea>
+ <p> All WebTopicCreator topic on this site: </p>
+ <h1><a name="TWiki Installation Error"></a> TWiki Installation Error </h1>Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags) </div>
-%RED% **WARNING:** %ENDCOLOR% This topic name is not recommended because it will not be linked automatically. See [[WikiWord]] for details
+$percntINCLUDE\{$quot$percntSYSTEMWEB$percnt.$percntWebTopicNonWikiTemplate$percnt$quot section=$quotnonwikiwordwarning$quot\}$percnt
<table border="0" cellpadding="0" cellspacing="0" id="twikiSearchTable">
<tr>
<td>
- <form action="http://www.dementia.org/twiki/view/Main/WebHome" name="jumpAgain"><strong>Did you spell the [[TWiki/WikiWord]] correctly?</strong> Remember, a WikiWord is case sensitive. %BR% <input name="topic" size="36" type="text" value="WebHome" /> <input type="submit" value="Jump to topic" /></form>
+ <form action="http://www.dementia.org/twiki/view/Main/WebHome" name="jumpAgain"><strong>Did you spell the %SYSTEMWEB%.WikiWord correctly?</strong> Remember, a WikiWord is case sensitive. %BR% <input name="topic" size="36" type="text" value="WebHome" /> <input type="submit" value="Jump" /></form>
</td>
</tr>
</table>
### <a name="Do you wish to navigate quickly"></a><a name="Do you wish to navigate quickly "></a> Do you wish to navigate quickly to a similar topic?
-Similar topics in this web (if any):%BR% <img src="http://www.dementia.org/twiki//view/Main/WebHome/arrowbright.gif" width="16" height="16" alt="arrowbright" /> [[List more similar topic in this web|Main/WebSearch?scope=topic;search=WebHome]] %BR% <img src="http://www.dementia.org/twiki//view/Main/WebHome/arrowbright.gif" width="16" height="16" alt="arrowbright" /> [[Search similar topics in all public webs|Main/WebSearch?scope=topic;web=all;search=WebHome]]
-
# <a name="TWiki Installation Error"></a> TWiki Installation Error
Incorrect format of searchformat template (missing sections? There should be 4 %SPLIT% tags)
+Similar topics in this web (if any):%BR% <img src="http://www.dementia.org/twiki//view/Main/WebHome/arrowbright.gif" width="16" height="16" alt="arrowbright" /> [[List more similar topic in this web|Main/WebSearch?scope=topic;search=WebHome]] %BR% <img src="http://www.dementia.org/twiki//view/Main/WebHome/arrowbright.gif" width="16" height="16" alt="arrowbright" /> [[Search similar topics in all public webs|Main/WebSearch?scope=topic;web=all;search=WebHome]]
+
### <a name="Do you wish to create the topic"></a><a name="Do you wish to create the topic "></a> Do you wish to create the topic 'WebHome'?
-<img src="http://www.dementia.org/twiki//view/Main/WebHome/arrowbright.gif" width="16" height="16" alt="arrowbright" /> [[Create 'WebHome'|Main/%TOPIC%?create=on&newtopic=WebHome]]
+<img src="http://www.dementia.org/twiki//view/Main/WebHome/arrowbright.gif" width="16" height="16" alt="arrowbright" /> [[Create 'WebHome'|Main/WebHome?create=on&newtopic=WebHome&template=WebCreateNewTopic&topicparent=]]
For example, Tim Berners-Lee's WikiName is [[TimBernersLee]].
-%X% Your name is also a potentially valid [[WikiWord]] when used within a topic. However the home pages of registered users on this site are stored in the **Main** web. When you sign your username in a topic, prefix it with `Main.` (including the dot). That is, write <code>**Main.admin**</code> to link to Main.admin, your personal home page in the Main web. For convenience, your signature is also provided for copying and pasting when editing a topic.
+%X% Your name is also a potentially valid [[WikiWord]] when used within a topic. However the home pages of registered users on this site are stored in the **%USERSWEB%** web. When you sign your username in a topic, prefix it with `%USERSWEB%.` (including the dot). That is, write <code>**%USERSWEB%.admin**</code> to link to %USERSWEB%.admin, your personal home page in the %USERSWEB% web. For convenience, your signature is also provided for copying and pasting when editing a topic.
-%Y% Though rarely used in common practice, you can use the special <code>**%MAINWEB%**</code> [[variable|Main/TWikiVariables]] prefix for user names, for example, <code>**%MAINWEB%.admin**</code>.
+%Y% Though rarely used in common practice, you can use the special <code>**%USERSWEB%**</code> [[variable|Main/TWikiVariables]] prefix for user names, for example, <code>**%USERSWEB%.admin**</code>.
## <a name="Wiki Technology and TWiki"></a> Wiki Technology and TWiki
+- Book: Wikis for Dummies; by Dan Woods and Peter Thoeny; Whiley; ISBN:9780470043998
+
- Book: The Wiki Way, Quick Collaboration on the Web; by Bo Leuf and Ward Cunningham; Addison-Wesley Pub Co; ISBN:020171499X
- Book: Wiki: Web Collaboration; by Anja Ebersbach, Markus Glaser, Richard Heigl; Springer; ISBN:3540259953. The book is about TWiki and MediaWiki; [Free eBook](http://www.springerlink.com/content/978-3-540-29267-8/) is available; German version is "[WikiTools: Kooperation im Web](http://www.wiki-tools.de/)".
- If you enter a [[WikiWord]] for a topic that doesn't exist, it'll appear highlighted, with question mark at the end, prompting you (or someone else) to start off the new topic by clicking the **?** - [[NewTopic]] (click the **?**, but don't save, to preserve the example!).
-- When entering WikiName signatures - like, admin - include "Main." as a prefix, since all TWiki member pages are in the Main web: `Main.YourName`.
+- When entering WikiName signatures - like, admin - include "%USERSWEB%." as a prefix, since all TWiki member pages are in the %USERSWEB% web: `%USERSWEB%.YourName`.
- For an external link, type the full URL: `http://twiki.org/`.
- **bullet list** 3 spaces, asterisk, 1 space: ` * your text`
- **headings** 3 dashes, 1 to 6 pluses, 1 space: `---++ Your Heading`
- **italic** put word/phrase in underscores: `_your words_`
-- **links** use topic name or URL: `WebHome`, `http://yahoo.com`, or `[[http://yahoo.com/][link to Yahoo]]`
+- **site links** use topic name: `WebHome` or `[[WebHome][Our homepage]]`
+- **external links** `http://yahoo.com` or `[[http://yahoo.com/][link to Yahoo]]`
- **monospaced** put word/phrase in equal signs: `=your words=`
- **paragraphs** separate with blank line
-- [[More formatting help|TWiki/TextFormattingRules]] and [[hints on good style|TWiki/GoodStyle]]
+- [[More formatting help|%SYSTEMWEB%/TextFormattingRules]] and [[hints on good style|%SYSTEMWEB%/GoodStyle]]
----
- Uppercase letter(s)
- Optional lowercase or uppercase letter(s) or number(s)
+WikiWord syntax in [[Extended Backus.Naur form|Main/Wikipedia:Extended_Backus_Naur_Form]] (EBNF):
+
+ wikiWord = upperLetters , lowerNumLetters , upperLetters , { alphaNum } ;
+ upperLetters = upperCase , { upperCase } ;
+ lowerNumLetters = lowerNum , { lowerNum } ;
+ alphaNum = upperCase | lowerCase | digit ;
+ lowerNum = lowerCase | digit ;
+ lowerCase = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i"
+ | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r"
+ | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z" ;
+ upperCase = "A" | "B" | "C" | "D" | "E" | "F" | "G" | "H" | "I"
+ | "J" | "K" | "L" | "M" | "N" | "O" | "P" | "Q" | "R"
+ | "S" | "T" | "U" | "V" | "W" | "X" | "Y" | "Z" ;
+ digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
+
## <a name="Good examples of _WikiWords"></a> Good examples of WikiWords
- [[WikiWord]]
- To write a custom **link label**, use bracket notation: `[[TWikiAccessControl][access control]]` - this becomes: [[access control|Main/TWikiAccessControl]]
- To link to a topic in **another web**, write: `Sandbox.WebSearch` - this becomes: [[WebSearch]]
+- To link to a topic in **another subweb** write: `Sandbox.Subweb.WebSearch`.
- To show the web name in the link use bracket notation: `[[Sandbox.WebHome]]` - this becomes: [[Sandbox.WebHome|Sandbox/WebHome]]
- To link to a topic on **another Wiki site**, use: `TWiki:Main/WebHome` - this becomes: TWiki:Main/WebHome (sites are defined in the [[InterwikiPlugin]])
-- To link to a part on the **same page**, write a "#" followed by the name of an anchor. The anchor is a "#" followed by a name which must be a WikiName. Example `#MyAnchor`. You can also link to an anchor on another page: `TWiki.WebHome#MyAnchor`.
-- To link to a header on the **same page**, write a "#" followed by the header text, with spaces replaced by underscores (and `!` removed): `[[#Good_examples_of_WikiWords]]` becomes: [[#Good_examples_of_WikiWords|Main/WebHome#Good_examples_of_WikiWords]]. You can also link to a header on another page: `TWiki.WebHome#Disclaimer` becomes: [[WebHome#Disclaimer]].
+- To link to a part on the **same page**, write a "#" followed by the name of an anchor. The anchor is a "#" followed by a name which must be a WikiName. Example `#MyAnchor`. You can also link to an anchor on another page: `%SYSTEMWEB%.WebHome#MyAnchor`.
+- To link to a header on the **same page**, write a "#" followed by the header text, with spaces replaced by underscores (and `!` removed): `[[#Good_examples_of_WikiWords]]` becomes: [[#Good_examples_of_WikiWords|Main/WebHome#Good_examples_of_WikiWords]]. You can also link to a header on another page: `%SYSTEMWEB%.WebHome#Disclaimer` becomes: %SYSTEMWEB%.WebHome#Disclaimer.
## <a name="Hints"></a> Hints
- Turn acronyms into WikiWords, i.e. take `FaqIndex` for a "FAQ index" topic.
- It is possible to turn off the auto-linking of WikiWords and to rely only on the bracket notation. See NOAUTOLINK setting in [[TWikiPreferences#Default_Web_Preferences]].
- %X% When linking to a WebHome topic _in another web_, the link will be rendered as the name of the web, e.g. `Sandbox.WebHome` becomes [[Sandbox|Sandbox/WebHome]].
+- %X% Dots (.) are used as seperators between webs, subwebs, and topics. It is not possible to use dots in topic names. TWiki does not attempt to guess if a dot could be part of a topic name.
**_Related Topics:_** [[WikiSyntax]], [[TextFormattingRules]]
+
+-- **_Contributors:_** TWiki:Main.PeterThoeny, TWiki:Main.ArthurClemens, TWiki:Main.CrawfordCurrie
<li><a href="#What's in the package"> What's in the package</a></li>
<li><a href="#How it works"> How it works</a></li>
<li><a href="#Using the translators from Perl"> Using the translators from Perl scripts</a></li>
- <li><a href="#Integrating a Wysiwyg Editor"> Integrating a Wysiwyg Editor</a><ul>
- <li><a href="#Getting content in the edit temp"> Getting content in the edit template</a></li>
+ <li><a href="#Integrating a HTML Editor"> Integrating a HTML Editor</a><ul>
+ <li><a href="#Generating content directly in t"> Generating content directly in the standard edit template</a></li>
+ <li><a href="#Generating content directly in a"> Generating content directly in a specialised edit template</a></li>
<li><a href="#Fetching content from a URL"> Fetching content from a URL</a></li>
</ul>
</li>
- <li><a href="#Handling Saves"> Handling Saves</a><ul>
+ <li><a href="#Other techniques"> Other techniques</a><ul>
+ <li><a href="#Asynchronous saves"> Asynchronous saves</a></li>
<li><a href="#Handling Attachments"> Handling Attachments</a></li>
+ <li><a href="#REST handlers"> REST handlers</a></li>
</ul>
</li>
</ul>
The plugin works by translating the topic text into HTML when someone edits a topic. The HTML is then fed to the WYSIWYG editor. On save, the edited HTML is run through the reverse translation before saving to the topic. TWiki syntax is used in preference to HTML in the stored topic wherever possible, though HTML may be used if the translator can't find a suitable TML equivalent..
-The default rendering that TWiki uses to generate HTML for display in browsers is 'lossy' - information in the TWiki syntax is lost in the HTML output, and a round-trip (recovering the original TWiki syntax from the HTML) is impossible. To solve this problem the plugin instead uses its own translation of TWiki syntax to pure XHTML. The generated XHTML is annotated with CSS classes that support the accurate recovery of the original TWiki syntax.
+The default rendering that TWiki uses to generate HTML for display in browsers is 'lossy' - information in the TWiki syntax is lost in the HTML output, and a round-trip (recovering the original TWiki syntax from the HTML) is impossible. To solve this problem the plugin instead uses its own translation of TWiki syntax to XHTML. The generated XHTML is annotated with CSS classes that support the accurate recovery of the original TWiki syntax.
_Before you ask the obvious question, yes, the translator **could** be used to replace the TWiki rendering pipeline for generating HTML pages. In fact, the translator is taken almost directly from the implementation of the rendering pipeline for the TWiki-4 release_
-Translation of the HTML back to TWiki syntax uses the CPAN:HTML::Parser. This parser is used in preference to a more modern XML parser, because the HTML may not generate fully compliant XHTML. A strict parser would risk losing content. CPAN:HTML::Parser is better at handling malformed HTML.
+Translation of the HTML back to TWiki syntax uses the CPAN:HTML::Parser. This parser is used in preference to a more modern XML parser, because the WYSIWYG editor may not generate fully compliant XHTML. A strict parser would risk losing content. CPAN:HTML::Parser is better at handling malformed HTML.
-There is also the advantage that the translator can be used to import HTML from other sources - for example, existing web pages. Due to the simple nature of TWiki syntax and the potential complexity of web pages, this translation is often lossy - i.e there will be HTML features that can be entered by editors that will be lost in this translation step. This is especially noticeable with HTML tables.
+There is also the advantage that the translator can be used to **import** HTML from other sources - for example, existing web pages. Due to the simple nature of TWiki syntax and the potential complexity of web pages, this translation is often lossy - i.e there will be HTML features that can be entered by editors that will be lost in this translation step. This is especially noticeable with HTML tables.
### <a name="Using the translators from Perl"></a><a name="Using the translators from Perl "></a> Using the translators from Perl scripts
Both translators can be used directly from Perl scripts, for example to build your own stand-alone translators.
-A stand-alone convertor script for HTML to TWiki is included in the installation. It can be found in the top-level `tools` directory and is called `html2tml.pl`.
+A stand-alone convertor script for HTML to TWiki is included in the installation. It can be found in `tools/html2tml.pl`.
-### <a name="Integrating a Wysiwyg Editor"></a> Integrating a Wysiwyg Editor
+### <a name="Integrating a HTML Editor"></a> Integrating a HTML Editor
-The plugin can be used to generate HTML for an editor in two ways; first, by generating the HTML for the content-to-be-edited directly in the edit template, and second, through a URL that can be used to fetch the content-to-be-edited from the server.
+The plugin can be used to integrate an HTML editor in a number of different ways.
-#### <a name="Getting content in the edit temp"></a> Getting content in the edit template
+1. The HTML for the content-to-be-edited can be generated directly in the standard edit template.
+2. The HTML for the content-to-be-edited can be generated directly in a specialised edit template.
+3. A URL can be used to fetch the content-to-be-edited from the server, for use in an IFRAME.
+4. REST handlers can be called from Javacript to convert content.
-This is the scenario used by the standard TWiki text editor, except that the text is pre-converted to HTML before inclusion in the template.
+#### <a name="Generating content directly in t"></a> Generating content directly in the standard edit template
-The flow of control is as follows:
+This is the technique used by WYSIWYG editors that can sit on top of HTML textareas, such as TinyMCE. The topic content is pre-converted to HTML before inclusion in the standard edit template. These editors use plugins that have a `beforeEditHandler` and an `afterEditHandler`. These handlers are responsible for the conversion of topic text to HTML, and post-conversion of HTML back to TML.
1. User hits "edit".
-2. The `beforeEditHandler` filters the edit, blocking any attempt to edit restricted content
-3. The `edit` template containing the JS editor is instantiated. The following variables are available for expansion in the template:
+2. Editor-specific plugin `beforeEditHandler` converts topic content to HTML by calling `TWiki::Plugins::WysiwygPlugin::TranslateTML2HTML`.
+3. User edits and saves
+4. Editor-specific plugin `afterEditHandler` converts HTML back to TML by calling `TWiki::Plugins::WysiwygPlugin::TranslateHTML2TML`.
+
+- WysiwygPlugin should **not** be enabled in `configure`.
+- `WYSIWYGPLUGIN_WYSIWYGSKIN` should **not** be set.
+- Your plugin should set the `textareas_hijacked` context id, to signal to skins to suppress their textarea manipulation functions.
+
+This is the recommended integration technique, if your editor can support it.
+
+#### <a name="Generating content directly in a"></a> Generating content directly in a specialised edit template
+
+This technique is useful when the editor requires the topic content in a variety of different formats at the same time. In this scenario the editor uses a custom edit template. The WYSIWYG content is made available for instantiation in that template in a number of different formats. `WYSIWYGPLUGIN_WYSIWYGSKIN` **must** be set for this to work.
+
+The flow of control is as follows:
+
+1. User hits "edit" with the skin (or cover) set the same as `WYSIWYGPLUGIN_WYSIWYGSKIN`.
+2. The WysiwygPlugin `beforeEditHandler` determines if the topic is WYSIWYG editable, and vetos the edit if not by redirecting to the standard edit skin. the edit
+3. The `edit` template containing the JS editor is instantiated.
+4. The following variables are available for expansion in the template:
- `%WYSIWYG_TEXT%` expands to the HTML of the content-to-be-edited. This is suitable for use in a `textarea`.
- `%JAVASCRIPT_TEXT%` expands to the HTML of the content-to-be-edited in a javascript constant.
+5. User edits and saves
+6. The `afterEditHandler` in the WyswiygPlugin sees that `wysiwyg_edit` is set, which triggers the conversion back to TML.
-`WYSIWYGPLUGIN_WYSIWYGSKIN` **must** be set for this to work.
+- The HTML form in the edit template **must** include an `<input` called `wysiwyg_edit` and set it to 1, to trigger the conversion from HTML back to TML.
+- `WYSIWYGPLUGIN_WYSIWYGSKIN` must be set to the name of the skin used for WYSIWYG editing. This is usually the name of the editor e.g. `kupu`.
#### <a name="Fetching content from a URL"></a> Fetching content from a URL
-In this scenario, the edit template is generated **without** the content-to-be-edited. The content is retrieved from the server using a URL e.g. from an `IFRAME` or using a `XmlHttpRequest`.
+In this scenario, the edit template is generated **without** the content-to-be-edited. The content is retrieved from the server using a URL e.g. from an `IFRAME`.
The flow of control is as follows:
-1. User hits "edit".
-2. If the current skin = `WYWIWYGPLUGIN_WYWIWYGSKIN`, the `beforeEditHandler` filters the edit, blocking any attempt to edit restricted content.
-3. The `edit` template containing the JS editor is instantiated.
-4. JS editor invokes content URL to obtain the HTML document to be edited
+1. As _Generating content directly in a specialised edit template_
+2. As _Generating content directly in a specialised edit template_
+3. As _Generating content directly in a specialised edit template_
+4. When the document loads in the browser, the JS editor invokes a content URL (using an `IFRAME` or a `XmlHttpRequest`) to obtain the HTML document to be edited
- The content URL is just a TWiki `view` URL with the `wysiwyg_edit` parameter set.
- - The plugin recognises the `wysiwyg_edit` parameter and uses the [[TML2HTML]] translator to prepare the text, which is then returned as `text/plain` to the browser.
- - Two TWiki variables, `%OWEB%` and %OTOPIC%=, should be used in the content URL to refer to the source topic for the content.
+ - The WysiwygPlugin recognises the `wysiwyg_edit` parameter and uses the [[TML2HTML]] translator to prepare the text, which is then returned as `text/plain` to the browser.
+ - Two TWiki variables, `%OWEB%` and %OTOPIC%=, can be used in the content URL in the edit template to refer to the source topic for the content.
+5. After edit handling is as for _Generating content directly in a specialised edit template_
+
+### <a name="Other techniques"></a> Other techniques
-### <a name="Handling Saves"></a> Handling Saves
+#### <a name="Asynchronous saves"></a> Asynchronous saves
-Saves are invoked by the editor POSTing to the TWiki `save` script with the `wysiwyg_edit` parameter set to `1`. This parameter tells the `beforeSaveHandler` in the plugin to convert the HTML back to TML. See [[TWikiScripts]] for details of the other parameters to the `save` script.
+Editors can use `XmlHttpRequest` to perform saves, by POSTing to the TWiki `save` script with the `wysiwyg_edit` parameter set to `1`. This parameter tells the `beforeSaveHandler` in the WysiwygPlugin to convert the content back to TML. See [[TWikiScripts]] for details of the other parameters to the `save` script.
Once the save script has completed it responds with a redirect, either to an Oops page if the save failed, or to the appropriate post-save URL (usually a `view`). The editor must be ready to handle this redirect.
#### <a name="Handling Attachments"></a> Handling Attachments
-Attachment uploads can be handled by URL requests from the editor to the TWiki `upload` script. The `upload` script normally redirects to the containing topic; a behaviour that you usually don't want in an editor! There are two ways to handle this:
+Attachment uploads can be handled by URL requests from the editor template to the TWiki `upload` script. The `upload` script normally redirects to the containing topic; a behaviour that you usually don't want in an editor! There are two ways to handle this:
- If the uploads are done in an `IFRAME` or via `XmlHttpRequest`, then the 302 redirect at the end of the upload can simply be ignored.
- You can pass `noredirect` to the `upload` script to suppress the redirect. In this case you will get a `text/plain` response of `OK` followed by a message if everything went well, or an error message if it did not.
-## <a name="Plugin Installation Instructions"></a> Plugin Installation Instructions
-
-You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.
-
-Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.
+#### <a name="REST handlers"></a> REST handlers
-- If you have TWiki 4.1 or later, and Perl 5.8, you can install from the `configure` interface (Go to Plugins->Find More Extensions)
- - The webserver user has to have permission to write to all areas of your installation for this to work.
-- If you have a permanent connection to the internet (and Perl 5.8), you are recommended to use the automatic installer script
- - Just download the `WysiwygPlugin_installer` perl script and run it.
-- **Notes:**
- - The installer script will:
- - Automatically resolve dependencies,
- - Copy files into the right places in your local install (even if you have renamed data directories),
- - check in new versions of any installed files that have existing RCS histories files in your existing install (such as topics).
- - If the $TWIKI\_PACKAGES environment variable is set to point to a directory, the installer will try to get archives from there. Otherwise it will try to download from twiki.org or cpan.org, as appropriate.
- - (Developers only: the script will look for twikiplugins/WysiwygPlugin/WysiwygPlugin.tgz before downloading from TWiki.org)
- - If you don't have a permanent connection, you can still use the automatic installer, by downloading all required TWiki archives to a local directory.
- - Point the environment variable `$TWIKI_PACKAGES` to this directory, and the installer script will look there first for required TWiki packages.
- - `$TWIKI_PACKAGES` is actually a path; you can list several directories separated by :
- - If you are behind a firewall that blocks access to CPAN, you can build a local CPAN mini-mirror, as described at [http://twiki.org/cgi-bin/view/Codev/BuildingDakar#CPAN\_local\_minimirror](http://twiki.org/cgi-bin/view/Codev/BuildingDakar#CPAN_local_minimirror)
-- If you don't want to use the installer script, or have problems on your platform (e.g. you don't have Perl 5.8), then you can still install manually:
- 1. Download and unpack one of the `.zip` or `.tgz` archives to a temporary directory.
- 2. Manually copy the contents across to the relevant places in your TWiki installation.
- 3. Check in any installed files that have existing `,v` files in your existing install (take care **not** to lock the files when you check in)
- 4. Manually edit LocalSite.cfg to set any configuration variables.
- 5. Run `configure` and enable the module, if it is a plugin.
- 6. Repeat from step 1 for any missing dependencies.
+If you are confident in Javascript you can use REST handlers with `XmlHttpRequest` to convert content from TML to HTML and back again.
-## <a name="Plugin Configuration Settings"></a> Plugin Configuration Settings
+The plugin defines the following REST handlers:
-### <a name="Translator control"></a> Translator control
+`.../rest/WysiwygPlugin/html2tml?topic=Web.Topic;text=htmltexttotranslate`
-For any of the following controls to work, you must tell %TOPIC% the name of the skin being used to invoke the Wysiwyg editor, for example `kupu` or `wikiwyg`.
+Converts the HTML text to TML. `topic` **must** be specified.
-- Set WYSIWYGSKIN =
+`.../rest/WysiwygPlugin/tml2html?topic=Web.Topic;text=tmltexttotranslate`
-Note that is can be set differently in different areas by defining `WYSWIYGPLUGIN_WYSIWYGSKIN` locally (e.g. in WebPreferences).
+Converts the TML text to HTML. `topic` **must** be specified. The response is a `text/plain` page of converted content.
-The **global** TWiki Variable `WYSIWYG_EXCLUDE` can be set to make the plugin sensitive to what is in a topic before allowing it to be edited. You can set it up to refuse to edit if
+## <a name="Plugin Installation Instructions"></a> Plugin Installation Instructions
-- some or all of HTML tags (e.g. `<br />` or `<div>`), or
-- simple variables (e.g. `%VAR%`) or
-- calls (e.g. `%VARIABLE{...}%`)
-- PRE blocks (`<pre>`)
-- HTML comments (`<!--` ... `-->`)
+You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server where TWiki is running.
-are used in the topic. If the plugin detects an excluded construct in the topic, it will redirect to the default editor. Comma-separated list of one or more of `html`, `variables`, `calls`, `pre` or `comments` e.g.
+Like many other TWiki extensions, this module is shipped with a fully automatic installer script written using the BuildContrib.
-- Set WYSIWYG\_EXCLUDE = calls,html
+- If you have TWiki 4.2 or later, you can install from the `configure` interface (Go to Plugins->Find More Extensions)
+ - See the [installation supplement](http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement) on TWiki.org for more information.
+- If you have any problems, then you can still install manually from the command-line:
+ 1. Download one of the `.zip` or `.tgz` archives
+ 2. Unpack the archive in the root directory of your TWiki installation.
+ 3. Run the installer script ( `perl <module>_installer` )
+ 4. Run `configure` and enable the module, if it is a plugin.
+ 5. Repeat for any missing dependencies.
+- If you are **still** having problems, then instead of running the installer script:
+ 1. Make sure that the file permissions allow the webserver user to access all files.
+ 2. Check in any installed files that have existing `,v` files in your existing install (take care **not** to lock the files when you check in)
+ 3. Manually edit LocalSite.cfg to set any configuration variables.
+
+<div class="twikiAlert">%X% WARNING: SYSTEMWEB is not defined in this TWiki. Please add these definitions to your [[Main/TWikiPreferences]], if they are not already there:<br /><pre> * Set SYSTEMWEB = %TWIKIWEB%<br /> * Set USERSWEB = %MAINWEB%</pre></div>
-Set `WYSIWYG_EXCLUDE` in [[TWikiPreferences]], or in [[WebPreferences]] for each web.
+## <a name="Plugin Configuration Settings"></a> Plugin Configuration Settings
-If you excluded `calls` in `WYSIWYG_EXCLUDE`, you can still define a subset of TWiki variables that do **not** block edits. this is done in the **global** preference variable `WYSIWYG_EDITABLE_CALLS`, which should be a list of TWiki variable names separated by vertical bars, with no spaces, e.g:
+### <a name="Translator control"></a> Translator control
-- Set WYSIWYG\_EDITABLE\_CALLS = COMMENT|CALENDAR|INCLUDE
+**Implementors note** if you are using your own before/after edit handlers, you can call `TWiki::Plugins::WysiwygPlugin::isWysiwygEditable()` to check these controls.
## <a name="Known issues"></a> Known issues
## <a name="Plugin Info"></a> Plugin Info
+This plugin is brought to you by a [WikiRing [](http://wikiring.com)](http://wikiring.com) partner - working together to improve your wiki experience!
+
+Many thanks to the following sponsors for supporting this work:
+
+- [ILOG](http://ilog.fr)
+- [Carrier Corporation](http://www.carrier.com)
+- [TWIKI.NET](http://twiki.net)
+
<table border="1" cellpadding="0" cellspacing="0">
<tr>
<td align="right"> Plugin Authors: </td>
</tr>
<tr>
<td align="right"> Plugin Version: </td>
- <td> 12422 </td>
+ <td> 16174 (22 Jan 2008) </td>
</tr>
<tr>
- <td align="right"> Change History: </td>
+ <td align="right"> Change History: </td>
<td> </td>
</tr>
<tr>
- <td align="right"> 12422 </td>
- <td> Added JAVASCRIPT_TEXT to support editors that require topic text in a JS var </td>
- </tr>
- <tr>
- <td align="right"> 12161 </td>
- <td> Added support for embedded editable HTML in the edit template </td>
- </tr>
- <tr>
- <td align="right"> 12119 </td>
- <td> Split into [[Main/WysiwygPlugin]] and [[Main/KupuContrib]]</td>
- </tr>
- <tr>
- <td align="right"> 11538 </td>
- <td> Minor doc updates, minor fixes to spacing in lists, integrated Koen Marten's template topic patch </td>
- </tr>
- <tr>
- <td align="right"> 9671 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item2025" rel="nofollow">Item2025</a> corrected handling of SPAN and FONT tags used for colour changes </td>
- </tr>
- <tr>
- <td align="right"> 9566 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1890" rel="nofollow">Item1890</a> doc update </td>
- </tr>
- <tr>
- <td align="right"> 9565 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1890" rel="nofollow">Item1890</a> <a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1041" rel="nofollow">Item1041</a> <a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item944" rel="nofollow">Item944</a> Much more aggressive cleanup of HTML pasted in from external sources. Excessively verbose HTML (e.g. from Outlook) was causing apparent infinite looing behaviour. </td>
- </tr>
- <tr>
- <td align="right"> 8867 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1176" rel="nofollow">Item1176</a> commented out Cairo version of header handler </td>
- </tr>
- <tr>
- <td align="right"> 8780 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1625" rel="nofollow">Item1625</a> disable expansion of twiki variables in urls where there are other twiki variables that can't be expanded </td>
- </tr>
- <tr>
- <td align="right"> 8779 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1530" rel="nofollow">Item1530</a> support for templatetopic when editing new topics </td>
- </tr>
- <tr>
- <td align="right"> 8592 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1532" rel="nofollow">Item1532</a> [[Main/WysiwygPlugin]]: Added two more do-not-edit-if-topic-contains parameters, pre+comments </td>
- </tr>
- <tr>
- <td align="right"> 8590 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1532" rel="nofollow">Item1532</a> [[Main/WysiwygPlugin]]: Kenneths suggestion on proper handling of HTML comments (incl. change to kupu) </td>
- </tr>
- <tr>
- <td align="right"> 8572 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1529" rel="nofollow">Item1529</a> evil, evil. The XMLSerializer in IE isn't happy serializing the DOM. I have no idea why. Kupu manages to get away with this because it passes the DOM through the XML validator, which I had to disable because it strips comments. So, for now, the IE implementation will strip comments - but at least you can save again </td>
- </tr>
- <tr>
- <td align="right"> 8538 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1501" rel="nofollow">Item1501</a> table handling was a bit spazzy. Several problems fixed. </td>
- </tr>
- <tr>
- <td align="right"> 8535 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1518" rel="nofollow">Item1518</a> moved icon and string lists into topics, updated screenshot </td>
- </tr>
- <tr>
- <td align="right"> 8531 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1392" rel="nofollow">Item1392</a> reversed the sense of the navigate-away condition, again </td>
- </tr>
- <tr>
- <td align="right"> 8466 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1486" rel="nofollow">Item1486</a> added WYSIWYG_EXCLUDE to allow exclusion of 'uneditable' content </td>
- </tr>
- <tr>
- <td align="right"> 8463 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1486" rel="nofollow">Item1486</a> was stripping comments, wrongly. Had to disable the kupu filters completely, they just do too much damage. </td>
- </tr>
- <tr>
- <td align="right"> 8401 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1457" rel="nofollow">Item1457</a> corrected problem with bullet list at top of topic </td>
- </tr>
- <tr>
- <td align="right"> 8388 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1445" rel="nofollow">Item1445</a> fix for a javascript error, introduced by previous fix </td>
- </tr>
- <tr>
- <td align="right"> 8387 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1445" rel="nofollow">Item1445</a> small usability improvements </td>
- </tr>
- <tr>
- <td align="right"> 8334 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item663" rel="nofollow">Item663</a> TWiki.org doc merge: Fix incorrect link to kupu website </td>
- </tr>
- <tr>
- <td align="right"> 8327 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1411" rel="nofollow">Item1411</a> handle case of the result of a TWiki variable being nopped </td>
- </tr>
- <tr>
- <td align="right"> 8312 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1317" rel="nofollow">Item1317</a> wrong result returned from generation function when expanding HTML embedded in verbatim block </td>
- </tr>
- <tr>
- <td align="right"> 8301 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1397" rel="nofollow">Item1397</a> removed excess space after sqaub links </td>
- </tr>
- <tr>
- <td align="right"> 8300 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1231" rel="nofollow">Item1231</a> added %SPAN% to indicate a spanned-over cell in the editor. Improved handling of HTML in verbatim tags by inserting line breaks is the tag type calls for it, before removing the HTML. </td>
- </tr>
- <tr>
- <td align="right"> 8276 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1215" rel="nofollow">Item1215</a> added WYSIWYG_ICONS and WYSIWYG_TAGS to support user customisation of icon images and twiki variables that can be inserted </td>
- </tr>
- <tr>
- <td align="right"> 8274 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1314" rel="nofollow">Item1314</a> debugging in case the hang happens again; and made sure to default the editor just in case </td>
- </tr>
- <tr>
- <td align="right"> 8273 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1315" rel="nofollow">Item1315</a> short forms must be terminated by one of the same characters that terminate wikiwords </td>
- </tr>
- <tr>
- <td align="right"> 8272 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1391" rel="nofollow">Item1391</a> added special interpretation of IMG tags to expand selected TWiki variables within SRC attributes </td>
- </tr>
- <tr>
- <td align="right"> 8271 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1340" rel="nofollow">Item1340</a> refined handling of NOP to cover abbrevs </td>
- </tr>
- <tr>
- <td align="right"> 8270 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1311" rel="nofollow">Item1311</a> removed excess space inserted in headings </td>
- </tr>
- <tr>
- <td align="right"> 8269 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1339" rel="nofollow">Item1339</a> changed from using arbitrary attribute for notoc to a new CSS class. Arbitrary attributes are stripped by Kupu before save. </td>
- </tr>
- <tr>
- <td align="right"> 8268 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1344" rel="nofollow">Item1344</a> strip ^Ms inserted by Sarissa during serialisation on IE </td>
- </tr>
- <tr>
- <td align="right"> 8267 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1394" rel="nofollow">Item1394</a> still can't get text styles to work properly in IE; but I am now firmly of the opinion that the fault lies with the browser, and not with Kupu. </td>
- </tr>
- <tr>
- <td align="right"> 8232 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1341" rel="nofollow">Item1341</a> added appropriate CSS class </td>
- </tr>
- <tr>
- <td align="right"> 8152 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1313" rel="nofollow">Item1313</a> added caveat about editing complex HTML and mixed HTML-TML </td>
- </tr>
- <tr>
- <td align="right"> 8151 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1334" rel="nofollow">Item1334</a> headers not handled properly in Cairo version </td>
- </tr>
- <tr>
- <td align="right"> 8108 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1318" rel="nofollow">Item1318</a> corrected table/list parser for tables embedded in bulleted lists </td>
- </tr>
- <tr>
- <td align="right"> 8106 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1310" rel="nofollow">Item1310</a> support for <nop/> </td>
- </tr>
- <tr>
- <td align="right"> 8105 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1317" rel="nofollow">Item1317</a> support for limited case of nopped variable </td>
- </tr>
- <tr>
- <td align="right"> 8104 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1320" rel="nofollow">Item1320</a> corrected interpretation of relative URL path in [[]] </td>
- </tr>
- <tr>
- <td align="right"> 8091 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1259" rel="nofollow">Item1259</a> changed comment handling; rather than trying to create HTML, which gets munged, create an HTML comment. This will only be editable by switching to source view, but hey, it's supposed to be WYSIWYG. Note that this also means that comments in pasted HTML should be retained now </td>
- </tr>
- <tr>
- <td align="right"> 8063 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1042" rel="nofollow">Item1042</a> spec of SCRIPTURL changed </td>
- </tr>
- <tr>
- <td align="right"> 7904 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1189" rel="nofollow">Item1189</a> reverting accidental checkin of experimental code </td>
- </tr>
- <tr>
- <td align="right"> 7903 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1189" rel="nofollow">Item1189</a> filter whitelist is not good enough; need to generate B and I nodes. templates/ pub/TWiki/WysiwygPlugin </td>
- </tr>
- <tr>
- <td align="right"> 7902 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1189" rel="nofollow">Item1189</a> it took bloody ages to track down, but finally discovered that bold and italic were being filtered out of spans by Kupu 1.3.2.... too smart for it's own good. So added them to the filter whitelist, and it works again. </td>
- </tr>
- <tr>
- <td align="right"> 7873 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1189" rel="nofollow">Item1189</a> added pre save filter to try and find where the attributes are disappearing to in FF </td>
- </tr>
- <tr>
- <td align="right"> 7872 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1187" rel="nofollow">Item1187</a> for lack of an s on an RE, the nation was lost (well, the multi-line comment actually). Thanks Kenneth! </td>
- </tr>
- <tr>
- <td align="right"> 7871 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item859" rel="nofollow">Item859</a> solved issue with non-display of inserted images. Was due to the use of an onSubmit handler to close the dialog, rather than an onLoad handler triggered when the IFRAME that contains the result is loaded. </td>
- </tr>
- <tr>
- <td align="right"> 7869 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1172" rel="nofollow">Item1172</a> had to rewrite big chunk of the table popup to get it working with 1.3.2 </td>
- </tr>
- <tr>
- <td align="right"> 7858 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1151" rel="nofollow">Item1151</a> rewrote link handlings stuff to leverage browser better </td>
- </tr>
- <tr>
- <td align="right"> 7854 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1175" rel="nofollow">Item1175</a> escape wikiwords within squabs </td>
- </tr>
- <tr>
- <td align="right"> 7815 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1158" rel="nofollow">Item1158</a> works for Cairo now as well </td>
- </tr>
- <tr>
- <td align="right"> 7814 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1158" rel="nofollow">Item1158</a> first implementation of AJAX interface to allow selectoin of topics from other webs </td>
- </tr>
- <tr>
- <td align="right"> 7812 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1154" rel="nofollow">Item1154</a> removed non-existent scull.gif </td>
- </tr>
- <tr>
- <td align="right"> 7811 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1155" rel="nofollow">Item1155</a> added extra recursion block, as Item1155 suggests it is needed </td>
- </tr>
- <tr>
- <td align="right"> 7801 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1042" rel="nofollow">Item1042</a> All sorts of clever tricks to handle expansion/compression of a subset of TWiki variables when they are used in URLs. Not a complete solution, but better than it was. </td>
- </tr>
- <tr>
- <td align="right"> 7799 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1024" rel="nofollow">Item1024</a> caught out by recursive call to beforeCommonTagsHandler in Cairo (nasty) </td>
- </tr>
- <tr>
- <td align="right"> 7798 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1042" rel="nofollow">Item1042</a> whoops, broke \t conversion in Cairo </td>
- </tr>
- <tr>
- <td align="right"> 7789 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1140" rel="nofollow">Item1140</a> testcase for 1140 </td>
- </tr>
- <tr>
- <td align="right"> 7788 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1140" rel="nofollow">Item1140</a> fix rewriting of img src urls (and updated MANIFEST for Kupu1.3.2) </td>
- </tr>
- <tr>
- <td align="right"> 7786 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1042" rel="nofollow">Item1042</a> extensive improvements to variable and URL recognition and conversion </td>
- </tr>
- <tr>
- <td align="right"> 7766 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item856" rel="nofollow">Item856</a> added doc on EDIT_SKIN to the plugin </td>
- </tr>
- <tr>
- <td align="right"> 7712 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1074" rel="nofollow">Item1074</a> upgrade to Kupu 1.3.2 complete (at last) </td>
- </tr>
- <tr>
- <td align="right"> 7710 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1074" rel="nofollow">Item1074</a> Fixed source edit mode </td>
- </tr>
- <tr>
- <td align="right"> 7709 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1074" rel="nofollow">Item1074</a> tidied up broken toolbar. There are still known issues </td>
- </tr>
- <tr>
- <td align="right"> 7700 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1074" rel="nofollow">Item1074</a> first pass at moving to Kupu 1.3.2. </td>
- </tr>
- <tr>
- <td align="right"> 7673 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1037" rel="nofollow">Item1037</a> insert wikiword only if selection is zero length </td>
- </tr>
- <tr>
- <td align="right"> 7672 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item977" rel="nofollow">Item977</a> changed to remove dangerous Cairo-based assumption, and use context ids instead </td>
- </tr>
- <tr>
- <td align="right"> 7630 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item1025" rel="nofollow">Item1025</a> added 'escape clause' for old handlers implemented to support old TWiki releases without warnings </td>
- </tr>
- <tr>
- <td align="right"> 7506 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item941" rel="nofollow">Item941</a> Eliminated the last of the dynamic globals to try and solve saving problem. Can;t test with mod_perl, but is fine with speedycgi AFAICT </td>
- </tr>
- <tr>
- <td align="right"> 7456 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item873" rel="nofollow">Item873</a> minor issue; replace br with \n in pre </td>
- </tr>
- <tr>
- <td align="right"> 7455 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item873" rel="nofollow">Item873</a> obvious problem parsing closing pre tag on same line as open tag </td>
- </tr>
- <tr>
- <td align="right"> 7453 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item710" rel="nofollow">Item710</a> Handling HTML comments </td>
- </tr>
- <tr>
- <td align="right"> 7452 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item876" rel="nofollow">Item876</a> Item945: Item876: spacing around table cells, correct handling of variables. Had to compromise on handling [[]] but I think it's for the best. </td>
- </tr>
- <tr>
- <td align="right"> 7430 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item871" rel="nofollow">Item871</a> made sure that brackets are generated for non-wikiwords </td>
- </tr>
- <tr>
- <td align="right"> 7425 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item928" rel="nofollow">Item928</a> removed special interpretation of mailto links </td>
- </tr>
- <tr>
- <td align="right"> 7424 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item866" rel="nofollow">Item866</a> extended URL parsing to handle MAINWEB and TWIKIWEB twiki variables, in the same hacky way as the core. </td>
- </tr>
- <tr>
- <td align="right"> 7416 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item870" rel="nofollow">Item870</a> a couple of corner-cases for correct handling of twiki variables </td>
- </tr>
- <tr>
- <td align="right"> 7401 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item899" rel="nofollow">Item899</a> changed list generation to use spaces instead of tabs </td>
- </tr>
- <tr>
- <td align="right"> 7265 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item180" rel="nofollow">Item180</a> removed pointless, outdated dependency check from [[Main/DateFieldPlugin]]</td>
- </tr>
- <tr>
- <td align="right"> 6935 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item622" rel="nofollow">Item622</a> reverted 3 specs to tabs in Set lines in plugins topics for kompatterbility with Kigh-roe </td>
- </tr>
- <tr>
- <td align="right"> 6905 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item622" rel="nofollow">Item622</a> tabs -> 3 spacesto avoid confusing the users </td>
- </tr>
- <tr>
- <td align="right"> 6850 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item638" rel="nofollow">Item638</a> added instruction to run configure to all install docs (I hope) </td>
- </tr>
- <tr>
- <td align="right"> 6827 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item569" rel="nofollow">Item569</a> added default RELEASE to everything that had a version, and removed a load of dead code that was getting in the way </td>
- </tr>
- <tr>
- <td align="right"> 6758 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item569" rel="nofollow">Item569</a> computed version numbers for plugins from the repository rev they were built from. </td>
- </tr>
- <tr>
- <td align="right"> 6504 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item436" rel="nofollow">Item436</a> incremented vernos of all changed plugins </td>
- </tr>
- <tr>
- <td align="right"> 6485 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item429" rel="nofollow">Item429</a> trying to make access controls clearer </td>
- </tr>
- <tr>
- <td align="right"> 6401 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item340" rel="nofollow">Item340</a> re-initialisation bug found by [[Main/ColasNahaboo]] when using mod_perl; fixed by correctly re-initialising the parse stack for each run of the convertor </td>
- </tr>
- <tr>
- <td align="right"> 6284 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item340" rel="nofollow">Item340</a> Release 0.16 of [[Main/WysiwygPlugin]]</td>
- </tr>
- <tr>
- <td align="right"> 6279 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item340" rel="nofollow">Item340</a> bugfixes for release 0.16 of [[Main/WysiwygPlugin]]</td>
- </tr>
- <tr>
- <td align="right"> 6261 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item335" rel="nofollow">Item335</a> Switched PNGs to indexed mode, as transparency doesn't work on IE for RGB images </td>
- </tr>
- <tr>
- <td align="right"> 6238 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item332" rel="nofollow">Item332</a> Added context identifier to [[Main/WysiwygPlugin]], and a button to the pattern view template. If [[Main/WysiwygPlugin]] is enabled, then the button will appear. Neat, huh? </td>
- </tr>
- <tr>
- <td align="right"> 6195 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item196" rel="nofollow">Item196</a> getting plugin test suites to pass. Doesn't mean the plugins actually work, just that the test suites run (which is a good indicator) </td>
- </tr>
- <tr>
- <td align="right"> 6174 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item168" rel="nofollow">Item168</a> checkpoint checking for 0.16 </td>
- </tr>
- <tr>
- <td align="right"> 6151 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item186" rel="nofollow">Item186</a> more minor updates </td>
- </tr>
- <tr>
- <td align="right"> 6150 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item168" rel="nofollow">Item168</a> new icons, and a couple of bugfixes, to [[Main/WysiwygPlugin]]</td>
- </tr>
- <tr>
- <td align="right"> 6092 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item196" rel="nofollow">Item196</a> more plugin and contrib fixes for develop; mainly just moving tests around and making sure they all pass. </td>
- </tr>
- <tr>
- <td align="right"> 6067 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item138" rel="nofollow">Item138</a> had to change to using beforeCommonTagsHandler and also escape % signs to prevent TWiki from rendering internal tags (as reported by Colas) </td>
- </tr>
- <tr>
- <td align="right"> 5979 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item168" rel="nofollow">Item168</a> corrected stupid error on IE; added screenshot </td>
- </tr>
- <tr>
- <td align="right"> 5977 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item168" rel="nofollow">Item168</a> release 0.13 </td>
- </tr>
- <tr>
- <td align="right"> 5948 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item168" rel="nofollow">Item168</a> nearly ready for 0.13 </td>
- </tr>
- <tr>
- <td align="right"> 5937 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item168" rel="nofollow">Item168</a> corrected images, twikified all images </td>
- </tr>
- <tr>
- <td align="right"> 5936 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item168" rel="nofollow">Item168</a> the import from cvs has screwed images </td>
- </tr>
- <tr>
- <td align="right"> 5934 </td>
- <td><a href="http://develop.twiki.org/~develop/cgi-bin/view/Bugs/Item168" rel="nofollow">Item168</a> twikified icon images, and renamed some images to be more intention-revealing </td>
+ <td align="right"> 20 Dec 2007 </td>
+ <td> TWikibug:Item5022: made TT font size same as verbatim. Had to add a new style to do it, as TMCE didn't want to play with TT or CODE tags. TWikibug:Item5138: post-conversion of 8-bit entities to characters to aid searching etc. </td>
</tr>
<tr>
- <td align="right"> 5739 </td>
- <td> 0.12 beta release </td>
+ <td> 19 Dec 2007 </td>
+ <td> TWikibug:Item4836: make the parser tolerant of META, so pasting OO docs works TWikibug:Item4969: autoclose BR and HR tags TWikibug:Item5132: fixed IMG tags TWikibug:Item5076: fixed line-sensitive TML embedded in tables </td>
</tr>
<tr>
- <td align="right"> 5730 </td>
- <td> V0.11 </td>
+ <td align="right"> 8 Nov 2007 </td>
+ <td> TWikibug:Item4923: fixed blocking of table conversion due to empty attributes TWikibug:Item4936: An em embedded in an em was getting eaten TWikibug:Item4817: added typewriter text button TWikibug:Item4850: added font colour controls TWikibug:Item4645: added REST handlers for upload and fetching lists of attachments </td>
</tr>
<tr>
- <td align="right"> 5714 </td>
- <td> Tidied up installer, documentation. Release 0.10 </td>
+ <td align="right"> 2 Nov 2007 </td>
+ <td> TWikibug:Item4903: corrected over-enthusiastive interpretation of ! as an escape </td>
</tr>
<tr>
- <td align="right"> 5712 </td>
- <td> pre-release 0.06 </td>
+ <td align="right"> 21 Oct 2007 </td>
+ <td> TWikibug:Item4788: fixed unbalanced protect, which could cause loss of protected status TWikibug:Item4811: noautolink <strong>looks</strong> like an HTML construct but in fact is not; the tag is infact an "on-off" switch and does not imply any HTML structure, so cannot be converted to a DIV or a span, so has to be removed. TWikibug:Item4747: added <sticky> to try to overcome limitations in translation TWikibug:Item4831: added increased flexibility in deciding what HTML get converted to TML, and what does not. Analysed all the HTML4 tags to establish initial settings. TWikibug:Item4847: don't call non-existent function with older HTML::Parser releases TWikibug:Item4844: Saving a table from IE didn't convert it back to TML TWikibug:Item4855: table rows generated from TWiki variables were being eaten </td>
</tr>
<tr>
- <td align="right"> 5706 </td>
- <td> Version 0.05 </td>
+ <td align="right"> 6 Oct 2007 </td>
+ <td> TWikibug:Item4700: fixed colspans TWikibug:Item4701: removed extra line between %TABLE and the table TWikibug:Item4705: fixed spacing around literal and verbatim blocks TWikibug:Item4706: merge adjacent verbatim blocks separated only by whitespace TWikibug:Item4712: fixed eating of noautolink and literal TWikibug:Item4763: list items spanning multiple lines fixed TWikibug:Item4867: released tml2html </td>
</tr>
<tr>
- <td align="right"> 5705 </td>
- <td> Checkpoint checking - version 0.03 </td>
+ <td align="right"> 17 Sep 2007 </td>
+ <td> TWikibug:Item4647: TWikibug:Item4652: problems related to DIV fixed. TWikibug:Item4653: fixed multi-line twiki variables </td>
</tr>
<tr>
- <td align="right"> 5702 </td>
- <td> cvsrmtee old files </td>
+ <td align="right"> 16 Sep 2007 </td>
+ <td> TWikibug:Item4630: polished up the way the secret string is done, to ensure synch between perl and JS. Item4622: added UTF-8 handling steps that fixup malformed UTF8 strings before presenting them to the editor (saves Moz) and stops the editor passing them back to TWiki (saves IE). Removed extra entity decoding steps that were causing problems. TWikibug:Item4629: fixed issues with verbatim, highlighted by previous mangling of this topic </td>
</tr>
<tr>
- <td align="right"> 5701 </td>
- <td> Check in for prototype release </td>
+ <td align="right"> 13 Sep 2007 </td>
+ <td> TWikibug:Item4613 cleaned up spurious message when navigating away TWikibug:Item4615 fixed incorrect rendering of emphasis next to br </td>
</tr>
<tr>
- <td align="right"> 5700 </td>
- <td> Check in for prototype release </td>
+ <td align="right"> 12 Sep 2007 </td>
+ <td> TWikibug:Item4604 Fixes to REST handler, and add ability to trigger [[Main/HTML2TML]] conversion from a content comment alone (required for some editors) TWikibug:Item4588 fixes to conversion of double-character emphases </td>
</tr>
<tr>
- <td align="right"> 5699 </td>
- <td> Checkpoint </td>
+ <td align="right"> 7 Sep 2007 </td>
+ <td> TWikibug:Item4503 excess empty lines TWikibug:Item4486 no toc headers with unofficial syntax TWikibug:Item4560: empty lines lost TWikibug:Item4566: corrupted table on save TWikibug:Item4550 section tags being eaten </td>
</tr>
<tr>
- <td align="right"> 5698 </td>
- <td> Most of the toolboxes are working again </td>
+ <td align="right"> 4 Sep 2007 </td>
+ <td> TWikibug:Item4534 TWikibug:Item4535 fixed </td>
</tr>
<tr>
- <td align="right"> 5693 </td>
- <td> Initial commit; doesn't do much except run tests </td>
+ <td colspan="2"> See Subversion logs for earlier revisions </td>
</tr>
<tr>
<td align="right"> Dependencies: </td>
--- /dev/null
+# <a name="Settings for _WysiwygPlugin that"></a> Settings for [[WysiwygPlugin]] that are common to most editor integrations
+
+The **global** TWiki Variable `WYSIWYG_EXCLUDE` can be set to make the plugin sensitive to what is in a topic, before allowing it to be edited. You can set it up to veto an edit if the topic contains:
+
+- `html` - HTML tags (e.g. `<div>`, not including <br>), or
+- `variables` - simple variables (e.g. `%VAR%`) or
+- `calls` - TWiki variables with parameters e.g. `%VARIABLE{...}%`
+- `pre` blocks (`<pre>`)
+- HTML `comments` (`<!--` ... `-->`)
+
+If the plugin detects an excluded construct in the topic, it will refuse to allow the edit and will redirect to the default editor.
+
+If you excluded `calls` in `WYSIWYG_EXCLUDE`, you can still define a subset of TWiki variables that do **not** block edits. this is done in the **global** TWiki variable `WYSIWYG_EDITABLE_CALLS`, which should be a list of TWiki variable names separated by vertical bars, with no spaces, e.g: `* Set WYSIWYG_EDITABLE_CALLS = COMMENT|CALENDAR|INCLUDE`
+
+You should set `WYSIWYG_EXCLUDE` and `WYSIWYG_EDITABLE_CALLS` in [[TWikiPreferences]], or in [[WebPreferences]] for each web.
+
+You can define the global variable `WYSIWYGPLUGIN_STICKYBITS` to stop the plugin from ever trying to convert specific HTML tags into HTML when certain specific attributes are present on the tag. This is most useful when you have styling or alignment information in tags that must be preserved.
+
+This variable is used to tell the translator which attributes, when present on a tag, make it "stick" i.e. block conversion. For example, setting it to `table=background,lang;tr=valign` will stop the translator from trying to handle any `table` tag that has `background` or `lang` attributes, and any `tr` tag that has a `valign` attribute.
+
+You can use perl regular expressions to match tag and attribute names, so `.*=id,on.*` will ensure that any tag with an `on*` event handler is kept as HTML.
+
+The default setting for this variable is:
+
+ .*=id,lang,title,dir,on.*;
+ A=accesskey,coords,shape,target;
+ BDO=dir;
+ BR=clear;
+ COL=char,charoff,span,valign,width;
+ COLGROUP=align,char,charoff,span,valign,width;
+ DIR=compact;
+ DIV=align;
+ DL=compact;
+ FONT=size,face;
+ H\d=align;
+ HR=align,noshade,size,width;
+ LEGEND=accesskey,align;
+ LI=type,value;
+ OL=compact,start,type;
+ P=align;
+ PARAM=name,type,value,valuetype;
+ PRE=width;
+ Q=cite;
+ TABLE=align,bgcolor,border,cellpadding,cellspacing,frame,rules,summary,width;
+ TBODY=align,char,charoff,valign;
+ TD=abbr,align,axis,bgcolor,char,charoff,colspan,headers,height,nowrap,rowspan,scope,valign,width;
+ TFOOT=align,char,charoff,valign;
+ TH=abbr,align,axis,bgcolor,char,charoff,colspan,height,nowrap,rowspan,scope,valign,width,headers;
+ THEAD=align,char,charoff,valign;
+ TR=bgcolor,char,charoff,valign;
+ UL=compact,type
+
+If you edit using the plain-text editor, you can use the <sticky>..</sticky> tags to delimit HTML (or TML) that you do **not** want to be WYSIWYG edited.
- <span>You are currently in the %INCLUDINGWEB% web. The color code for this web is this background, so you know where you are.</span>
-- If you are not familiar with the %WIKITOOLNAME% collaboration platform, please visit [[WelcomeGuest]] first.
+- If you are not familiar with the %WIKITOOLNAME% collaboration platform, please visit %SYSTEMWEB%.WelcomeGuest first.
----
- The description above briefly explains how a background color corresponds to a particular web. It can be included within other topics using the following directive:
- `%INCLUDE{"%TWIKIWEB%.YouAreHere"}%`
+ `%INCLUDE{"%SYSTEMWEB%.YouAreHere"}%`
- [List](http://www.dementia.org/twiki/search/%WEB%?scope=text®ex=on&web=all&search=INCLUDE.*YouAreHere&casesensitive=on&nosummary=on¬otal=on) all topics which include this topic.
git://git.openafs.org / openafs-wiki.git / commitdiff